NAV Navbar

Introduction

Welcome to the Shrimpy Developer API documentation. These documents outline how to use the Developer Shrimpy API to add Shrimpy functionality to your application. If you are looking for an API to manage your personal Shrimpy account, please see the Shrimpy API.

There is a rate limit of 1000 requests per minute for Master API Keys. User API Keys have a rate limit of 60 requests per minute. If you exceed the rate limit, a status of 429 will be returned. Repeatedly violating rate limits will result in an automatic IP ban.

Visit the Shrimpy Developer API github page here.

Authentication

Generating an API Key

Example API Keys

{
    "apiKey": "12326758a39a720e15d064cab3c1f0a9332d107de453bd41926bb3acd565059e",
    "secretKey": "6991cf4c9b518293429db0df6085d1731074bed8abccd7f0279a52fac5b0c1a8a2f6d28e11a50fbb1c6575d1407e637f9ad7c73fbddfa87c5d418fd58971f829",
}

Shrimpy uses API keys to allow access to the API. After creating a key you will have 2 pieces of information which you must remember:

All requests to endpoints must be signed using the described authentication scheme. See Creating a Request

Creating a Request

Example Request Headers

Content-Type: application/json
DEV-SHRIMPY-API-KEY: 12326758a39a720e15d064cab3c1f0a9332d107de453bd41926bb3acd565059e
DEV-SHRIMPY-API-NONCE: 1544920259394
DEV-SHRIMPY-API-SIGNATURE: 0heLxSWpa5r4JSiW1PXPkKGdUNWEGneAgSYcGZy9ezk=

All requests must contain the following headers:

All request bodies should have content type application/json and be valid JSON.

Signing a Request

NodeJS Example of Signing a Request

var crypto = require('crypto');

var secret = '6991cf4c9b51...';

var nonce = Date.now();
var requestPath = "/v1/users/70e3a52a-4fda-464d-b4af-029f55cbd9be/accounts/123/rebalance_period";

var body = JSON.stringify({
    rebalancePeriod: 24
});

var method = "POST";

// create the prehash string by concatenating required parts
var prehashString = requestPath + method + nonce + body;

// decode the base64 secret
var key = Buffer(secret, 'base64');

// create a sha256 hmac with the secret
var hmac = crypto.createHmac('sha256', key);

// hash the prehash string and base64 encode the result
return hmac.update(prehashString).digest('base64');

The DEV-SHRIMPY-API-SIGNATURE header is generated by creating a sha256 HMAC using the base64-decoded secret key on the prehash string requestPath + method + nonce + body (where + represents string concatenation) and base64-encoding the output. The nonce value is the same as the DEV-SHRIMPY-API-NONCE header.

The requestPath should include the query string, if present.

The method should be UPPER CASE. E.g. GET or POST

The body is the reqest body string or omitted if there is no request body (typically for GET requests).

Public

Get Supported Exchanges

GET https://dev-api.shrimpy.io/v1/exchanges

Response

[
  "binance",
  "bittrex",
  "kucoin",
  "coinbasepro",
  "poloniex",
  "kraken",
  "bibox",
  "gemini",
  "huobi",
  "huobiglobal",
  "hitbtc"
]

This endpoint retrieves all Shrimpy supported exchanges.

HTTP Request

GET https://dev-api.shrimpy.io/v1/exchanges

Response

List of supported exchanges as lowercase strings.

Get Ticker

Request

GET https://dev-api.shrimpy.io/v1/exchanges/kucoin/ticker

Response

[
  {
    "name": "Bitcoin",
    "symbol": "BTC",
    "priceUsd": "3700.0089335",
    "priceBtc": "1",
    "percentChange24hUsd": "4.191224354581092",
    "lastUpdated": "2018-12-19T22:51:13.000Z"
  },
  {
    "name": "Ethereum",
    "symbol": "ETH",
    "priceUsd": "100.114205389399",
    "priceBtc": "0.027057825",
    "percentChange24hUsd": "5.432113558652999",
    "lastUpdated": "2018-12-19T22:51:13.000Z"
  },
  ...
]

This endpoint retrieves all Shrimpy supported exchange assets for a particular exchange along with pricing information. The pricing information is updated once per minute.

See the Ticker type for more information

HTTP Request

GET https://dev-api.shrimpy.io/v1/exchanges/<exchange>/ticker

URL Parameters

Parameter Type Description
exchange string See Get Supported Exchanges for the list of supported exchanges

Response

List of Ticker types.

Ticker Fields

Field Type Description
name string The name of the asset
symbol string The symbol of the asset on the exchange
priceUsd Decimal or null The latest price in United States Dollars
priceBtc Decimal or null The latest price in Bitcoin
percentChange24hUsd Decimal or null The change in USD price in the last 24 hours
lastUpdated Date or null The time the latest ticker data was retrieved

Users

The Users endpoints are used to manage Shrimpy users on behalf of your users. The expectation is that there is a one-to-one relationship between users on your application and users that you have created via this API. Each enabled user costs 1 credit per 30 days.

See also: User API Keys Endpoints, Accounts Endpoints, Trading Endpoints.

List Users

Request

GET https://dev-api.shrimpy.io/v1/users

Response

[
    {
        "id": "701e0d16-1e9e-42c9-b6a1-4cada1f395b8",
        "isEnabled": true,
        "expirationDate": "2019-01-12T21:09:25.000Z",
        "name": ""
    },
    {
        "id": "70e3a52a-4fda-464d-b4af-029f55cbd9be",
        "isEnabled": false,
        "expirationDate": null,
        "name": ""
    }
]

This endpoint retrieves all users that have been created.

See also: Creating a User, User.

HTTP Request

GET https://dev-api.shrimpy.io/v1/users

Response

List of User types.

User Fields

Field Type Description
id UUID The unique identifier of the user.
isEnabled boolean True if the user is currently enabled.
expirationDate Date or null The date the user will expire.
name string The optional name associated with the user.

Get a User

Request

GET https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8

Response

{
    "id": "701e0d16-1e9e-42c9-b6a1-4cada1f395b8",
    "isEnabled": true,
    "expirationDate": "2019-01-12T21:09:25.000Z",
    "name": ""
}

This endpoint returns the current status of a user.

See also: Creating a User, User.

HTTP Request

GET https://dev-api.shrimpy.io/v1/users/<userId>

URL Parameters

Parameter Type Description
userId UUID The id of the user to retrieve

Response

The requested User.

User Fields

Field Type Description
id UUID The unique identifier of the user.
isEnabled boolean True if the user is currently enabled.
expirationDate Date or null The date the user will expire.
name string The optional name associated with the user.

Creating a User

Request

POST https://dev-api.shrimpy.io/v1/users

Request Body (optional)

{
    "name": "customnameforthisuser"
}

Response:

{
    "id": "701e0d16-1e9e-42c9-b6a1-4cada1f395b8"
}

This endpoint creates a new user. New users are disabled by default.

See also: Enabling a User, User.

HTTP Request

POST https://dev-api.shrimpy.io/v1/users

Response

Field Type Description
id UUID The id of the newly created user. This id is used in future requests for this user.

Naming a User

Request

POST https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/name

Request Body

{
    "name": "customnameforthisuser"
}

Response:

{
    "success": true
}

This endpoint names an existing user. The name cannot be longer than 255 characters and does not change any Shrimpy behavior.

See also: Creating a User, Disabling a User, User.

HTTP Request

POST https://dev-api.shrimpy.io/v1/users/<userId>/name

URL Parameters

Parameter Type Description
userId UUID The id of the user to name

Body Parameters

Parameter Type Description
name string The name to associate with the user.

Enabling a User

Request

POST https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/enable

Response:

{
    "success": true
}

This endpoint enables an existing user. Each enabled user costs 1 credit per 30 days. Users must be enabled before using certain Trading Endpoints.

See also: Creating a User, Disabling a User, User.

HTTP Request

POST https://dev-api.shrimpy.io/v1/users/<userId>/enable

URL Parameters

Parameter Type Description
userId UUID The id of the user to enable

Disabling a User

Request

POST https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/disable

Response:

{
    "success": true
}

This endpoint disables an existing user.

See also: Enabling a User, User.

HTTP Request

POST https://dev-api.shrimpy.io/v1/users/<userId>/disable

URL Parameters

Parameter Type Description
userId UUID The id of the user to disable

User API Keys

API Keys can be created for each user. These API Keys are referred to as "User API Keys" to differentiate them from Master API Keys. User API Keys can only manage the user they are assocaited with.

For example, if you are building a mobile app, you could generate API Keys for a user and store that user's API keys on their device. The device can then manage their account by using the Shrimpy Developer API.

See also: Users Endpoints, Accounts Endpoints, Trading Endpoints.

Get API Keys

Request

GET https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/keys

Response:

[
    "fbdf44529a68a7de8338c05f0e455f64584f185bcd21fc13874ba62ff96cf366"
]

This endpoint will retrieve existing public keys for a particular user.

See also: Create API Keys.

HTTP Request

GET https://dev-api.shrimpy.io/v1/users/<userId>/keys

URL Parameters

Parameter Type Description
userId UUID The id of the user for which to retrieve existing User API Keys.

Response

List of created user public keys.

Create API Keys

Request

POST https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/keys

Response:

{
    "publicKey": "51ac18b7d208f59b3c88acbb1ecefe6ba6be6ea4edc07e7a2450307ddc27ab80",
    "privateKey": "85c977ef4070f1deee70192ba7fd5a6caf534f891e4918cfffec11cd6b625e77db4f80347cb436bcaa8882231bacb02f0798a696f101fdd1ef268d66fc63c213"
}

This endpoint will create new User API keys for a particular user. By default new User API Keys have no permissions. User API Keys have a rate limit of 60 requests per minute.

See also: Set API Key Permissions, Delete API Keys.

HTTP Request

POST https://dev-api.shrimpy.io/v1/users/<userId>/keys

URL Parameters

Parameter Type Description
userId UUID The id of the user for which to create api keys.

Response

Field Type Description
publicKey string The public key of the newly created User API Key.
privateKey string The private key of the newly created User API Key.

Delete API Keys

Request

DELETE https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/keys/51ac18b7d208f59b3c88acbb1ecefe6ba6be6ea4edc07e7a2450307ddc27ab80

Response:

{
    "success": true
}

This endpoint will delete User API Keys for a particular user. Any application or device using the API keys will no longer function.

See also: Create API Keys.

HTTP Request

DELETE https://dev-api.shrimpy.io/v1/users/<userId>/keys/<publicKey>

URL Parameters

Parameter Type Description
userId UUID The id of the user for which to create api keys.
publicKey string The public key of the api key pair to delete.

Get API Key Permissions

Request

GET https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/keys/51ac18b7d208f59b3c88acbb1ecefe6ba6be6ea4edc07e7a2450307ddc27ab80/permissions

Response:

{
    "account": true,
    "trade": false
}

This endpoint will retrieve api key permissions for a user's API Keys.

See also: Set API Key Permissions, Create API Keys.

HTTP Request

GET https://dev-api.shrimpy.io/v1/users/<userId>/keys/<publicKey>/permissions

URL Parameters

Parameter Type Description
userId UUID The id of the user for which to create api keys.
publicKey string The public key of the User API Key permissions to be checked.

Response

Field Type Description
account boolean True if this User API Key can use Accounts Endpoints
trade boolean True if this User API Key can use Trading Endpoints

Set API Key Permissions

Request

POST https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/keys/51ac18b7d208f59b3c88acbb1ecefe6ba6be6ea4edc07e7a2450307ddc27ab80/permissions

Response:

{
    "success": true,
}

This endpoint will set api key permissions for a user's api keys.

See also: Get API Key Permissions, Create API Keys.

HTTP Request

POST https://dev-api.shrimpy.io/v1/users/<userId>/keys/<publicKey>/permissions

URL Parameters

Parameter Type Description
userId UUID The id of the user for which to create api keys.
publicKey string The public key of the User API Key permissions to be set.

Body Parameters

Parameter Type Description
account boolean True if this User API Key can use Accounts Endpoints
trade boolean True if this User API Key can use Trading Endpoints

Accounts

The Accounts endpoints are used to manage your users' exchange account connections. Each user has a limit of 20 linked exchange accounts.

Linking an Exchange Account must be done in order to use the Trading Endpoints to trade or rebalance.

List Accounts

Request

GET https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/accounts

Response

[
    {
        "id": 123,
        "exchange": "Kucoin",
        "isRebalancing": true,
        "exchangeApiErrors": []
    },
    {
        "id": 456,
        "exchange": "Binance",
        "isRebalancing": false,
        "exchangeApiErrors": []
    }
]

This endpoint retrieves all linked exchange accounts.

See also: Link an Exchange Account, Account

HTTP Request

GET https://dev-api.shrimpy.io/v1/users/<userId>/accounts

URL Parameters

Parameter Type Description
userId UUID The id of the user

Response

List of Account types.

Account Fields

Field Type Description
id integer The unique identifier of the exchange account.
exchange string The name of the linked exchange.
isRebalancing boolean True if the account is rebalancing.
exchangeApiErrors Exchange Api Error[] A list of errors received from the exchange that relate to the user's exchange API keys. This list is generally empty and a non-empty list usually indicates an issue that the user needs to resolve. For example, this list will be non-empty if the user deletes their API keys from the exchange, or has invalid API permission on the exchange.

Get an Account

Request

GET https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/accounts/123

Response

{
    "id": 123,
    "exchange": "Kucoin",
    "isRebalancing": true,
    "exchangeApiErrors": []
}

This endpoint returns the current status of a linked exchange account.

See also: Link an Exchange Account, Account, Get Balance

HTTP Request

GET https://dev-api.shrimpy.io/v1/users/<userId>/accounts/<exchangeAccountId>

URL Parameters

Parameter Type Description
userId UUID The id of the user
exchangeAccountId integer The exchange account id of the account to retrieve

Response

The requested Account.

Account Fields

Field Type Description
id integer The unique identifier of the exchange account.
exchange string The name of the linked exchange.
isRebalancing boolean True if the account is rebalancing.
exchangeApiErrors Exchange Api Error[] A list of errors received from the exchange that relate to the user's exchange API keys. This list is generally empty and a non-empty list usually indicates an issue that the user needs to resolve. For example, this list will be non-empty if the user deletes their API keys from the exchange, or has invalid API permission on the exchange.

Request

POST https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/accounts

Request Body

{
    "exchange": "binance",
    "publicKey": "GOelL5FT6TklPxAzICIQK25aqct52T2lHoKvtcwsFla5sbVXmeePqVJaoXmXI6Qd",
    "privateKey": "SelUuFq1sF2zGd97Lmfbb4ghITeziKo9IvM5NltjEdffatRN1N5vfHXIU6dsqRQw",
}

Response

{
    "id": 1234
}

This endpoint links a new exchange account for a user. The id of the newly linked exchange is returned in the response. Once an exchange account has been linked, the Trading Endpoints can be used to rebalance and trade.

See also: Unlink an Exchange Account, Account, Trading Endpoints.

HTTP Request

POST https://dev-api.shrimpy.io/v1/users/<userId>/accounts

URL Parameters

Parameter Type Description
userId UUID The id of the user

Body Parameters

Parameter Type Description
exchange string See Get Supported Exchanges for the list of supported exchanges
publicKey string The public key of the exchange api key pair. Some exchanges refer to this as the "API Key".
privateKey string The private key of the exchange api key pair. Some exchanges refer to this as the "Secret Key".
passphrase (optional) string The passphrase associated with the exchange api keys. This is only required for some exchanges, such as Coinbase Pro.

Response

Field Type Description
id integer The id of the newly linked exchange account.

Request

DELETE https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/accounts/456

Response

{
    "success": true
}

This endpoint unlinks an exchange account for a user. The exchange api keys are immediately deleted, thus the account can no longer be used with the Trading Endpoints.

See also: Link an Exchange Account, Account, Trading Endpoints.

HTTP Request

DELETE https://dev-api.shrimpy.io/v1/users/<userId>/accounts/<exchangeAccountId>

URL Parameters

Parameter Type Description
userId UUID The id of the user
exchangeAccountId integer The exchange account id of the exchange account to be unlinked

Get Ip Whitelist Addresses

Request

GET https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/whitelist

Response

[
  "18.235.147.140",
  "34.204.140.11",
  "100.24.133.187",
  "52.21.196.129"
]

This endpoint retrieves the provisioned IP addresses for this user. All exchange requests for this user will be sent from the returned IP addresses. Thus, these IP addresses can be provided to the user to provide to the exchange if they desire to enable IP whitelisting for their exchange API keys.

HTTP Request

GET https://dev-api.shrimpy.io/v1/users/<userId>/whitelist

URL Parameters

Parameter Type Description
userId UUID The id of the user

Response

The list of ip addresses that have been provisioned for this user.

Trading

The Trading endpoints are used to manage a particular exchange account. Certain endpoints require that the user has been enabled and has not expired.

To link an exchange account, see the Accounts Endpoints. To enabled a user, see Enabling a User.

Get Balance

Request

GET https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/accounts/123/balance

Response

{
  "retrievedAt": "2019-01-09T19:17:33.000Z",
  "balances": [
    {
      "symbol": "KCS",
      "nativeValue": 2306,
      "btcValue": 0.33486579,
      "usdValue": 1327.8775274784
    },
    {
      "symbol": "ETH",
      "nativeValue": 4.0e-8,
      "btcValue": 1.4960564e-9,
      "usdValue": 5.9324652822859e-6
    }
  ]
}

This endpoint retrieves the most recent balance for an exchange account. Balance is retrieved from the exchange every 15 minutes for each account, as well as immediately after rebalance operations and trade operations.

HTTP Request

GET https://dev-api.shrimpy.io/v1/users/<userId>/accounts/<exchangeAccountId>/balance

URL Parameters

Parameter Type Description
userId UUID The id of the user
exchangeAccountId integer The exchange account id of the exchange account to retrieve balance data

Response

Field Type Description
retrievedAt Date or null The date the data was retrieved, or null if no balance data has been retrieved yet.
balances Balance[] An array of balance information. This array will be empty if no balance data has been retrieved yet.

Rebalancing

Request

POST https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/accounts/123/rebalance

Response:

{
    "success": true
}

This endpoint queues a rebalance for the specified exchange account. When the rebalance occurs, trades will be made so that the linked exchange accounts assets match the current strategy. That is, any assets that are overallocated will be sold and any assets that are underallocated will be purchased. Learn more about rebalancing.

See also: Set the Rebalance Period, Set the Strategy, Allocating.

HTTP Request

POST https://dev-api.shrimpy.io/v1/users/<userId>/accounts/<exchangeAccountId>/rebalance

URL Parameters

Parameter Type Description
userId UUID The id of the user
exchangeAccountId integer The exchange account id of the exchange account to be rebalanced

Get the Rebalance Period

Request

GET https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/accounts/123/rebalance_period

Response:

{
    "rebalancePeriod": 24
}

This endpoint gets the current rebalance period for the specified exchange account. A rebalance period of 0 means to never automatically rebalance.

See also: Rebalancing, Set the Rebalance Period, Set the Strategy.

HTTP Request

GET https://dev-api.shrimpy.io/v1/users/<userId>/accounts/<exchangeAccountId>/rebalance_period

URL Parameters

Parameter Type Description
userId UUID The id of the user
exchangeAccountId integer The exchange account id of the exchange account to be rebalanced

Response

Field Type Description
rebalancePeriod integer The rebalance period in hours, or 0 to never automatically rebalance.

Set the Rebalance Period

Request

POST https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/accounts/123/rebalance_period

Request Body

{
    "rebalancePeriod": 24
}

Response:

{
    "success": true
}

This endpoint sets the rebalance period for the specified exchange account. The next rebalance will be scheduled from the current time. For example, it is currently 4PM and a rebalance period of 24 hours is set, the next rebalance operation will occur at 4PM tomorrow.

See also: Rebalancing, Get the Rebalance Period, Set the Strategy.

HTTP Request

POST https://dev-api.shrimpy.io/v1/users/<userId>/accounts/<exchangeAccountId>/rebalance_period

URL Parameters

Parameter Type Description
userId UUID The id of the user
exchangeAccountId integer The exchange account id of the exchange account to be rebalanced

Body Parameters

Parameter Type Description
rebalancePeriod integer The rebalance period in hours, or 0 to never automatically rebalance.

Get the Strategy

Request

GET https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/accounts/123/strategy

Response:

{
    "isDynamic": false,
    "allocations": [
        {
            "symbol": "USDT",
            "percent": "100"
        }
    ]
}

This endpoint retrieves the strategy for the exchange account.

See also: Strategy, Set the Strategy, Clear the Strategy, Rebalancing.

HTTP Request

GET https://dev-api.shrimpy.io/v1/users/<userId>/accounts/<exchangeAccountId>/strategy

URL Parameters

Parameter Type Description
userId UUID The id of the user
exchangeAccountId integer The exchange account id of the exchange account

Response

The user's current Strategy.

Set the Strategy

Request

POST https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/accounts/123/strategy

Request Body

{
    "isDynamic": false,
    "allocations": [
        {
            "symbol": "BTC",
            "percent": "50"
        },
        {
            "symbol": "ETH",
            "percent": "50"
        }
    ]
}

Response:

{
    "success": true
}

This endpoint sets the strategy for the exchange account. All future rebalance operations will use the new strategy.

See also: Strategy, Clear the Strategy, Rebalancing, Set the Rebalance Period.

HTTP Request

POST https://dev-api.shrimpy.io/v1/users/<userId>/accounts/<exchangeAccountId>/strategy

URL Parameters

Parameter Type Description
userId UUID The id of the user
exchangeAccountId integer The exchange account id of the exchange account

Body Parameters

The body should be a strategy object. See the Strategy type for more information.

Clear the Strategy

Request

DELETE https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/accounts/123/strategy

Response:

{
    "success": true
}

This endpoint clears the strategy for the exchange account. It will also clear the rebalance period. After calling this endpoint, no rebalance operations will occur for the user's exchange account until a new strategy is set and a rebalance is requested.

See also: Strategy, Set the Strategy, Get the Strategy, Set the Rebalance Period.

HTTP Request

DELETE https://dev-api.shrimpy.io/v1/users/<userId>/accounts/<exchangeAccountId>/strategy

URL Parameters

Parameter Type Description
userId UUID The id of the user
exchangeAccountId integer The exchange account id of the exchange account

Allocating

Request

POST https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/accounts/123/allocate

Request Body

{
    "isDynamic": false,
    "allocations": [
        {
            "symbol": "USDT",
            "percent": "100"
        }
    ]
}

Response:

{
    "success": true
}

This endpoint sets the strategy for the exchange account and queues a rebalance operation. See Set the Strategy and Rebalancing for more information.

HTTP Request

POST https://dev-api.shrimpy.io/v1/users/<userId>/accounts/<exchangeAccountId>/allocate

URL Parameters

Parameter Type Description
userId UUID The id of the user
exchangeAccountId integer The exchange account id of the exchange account to be rebalanced

Body Parameters

The body should be a strategy object. See the Strategy type for more information.

Place a Limit Order

Request

POST https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/accounts/123/orders

Request Body

{
    "baseSymbol": "ETH",
    "quoteSymbol": "BTC",
    "amount": "0.5",
    "price": "0.0344",
    "side": "BUY",
    "timeInForce": "IOC"
}

Response:

{
    "id": "72dff099-54c0-4a32-b046-5c19d4f55758"
}

This endpoint creates and queues a limit order operation. The limit order operation will attempt to place the specified limit order on the linked exchange.

See also: Get Limit Order Status, Cancel a Limit Order, List Open Orders

HTTP Request

POST https://dev-api.shrimpy.io/v1/users/<userId>/accounts/<exchangeAccountId>/orders

URL Parameters

Parameter Type Description
userId UUID The id of the user
exchangeAccountId integer The id of the exchange account for which to create a trade.

Body Parameters

Parameter Type Description
baseSymbol string The base symbol on the exchange
quoteSymbol string The quote symbol on the exchange (e.g. BTC)
amount Decimal The amount of baseSymbol to buy or sell
price Decimal The price of the order to be placed, in units of quoteSymbol
side string Either "BUY" or "SELL". BUY means to exchange quoteSymbol for baseSymbol, while SELL means to exchange baseSymbol for quoteSymbol.
timeInForce string Either "IOC" or "GTC". IOC (Immediate or Cancel) orders execute immediately and cancel any unfilled portion of the order. GTC (Good 'Til Canceled) orders remain on the exchange until executed or canceled. Shrimpy will place and cancel a GTC order on exchanges that do not natively support IOC orders.

Response

Field Type Description
id UUID The id of the trade. Use this with the Get Limit Order Status endpoint.

Get Limit Order Status

Request

GET https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/accounts/123/orders/e426e9aa-6518-4ba2-afc2-baabb73048c0

Response:

{
  "order": {
    "id": "e426e9aa-6518-4ba2-afc2-baabb73048c0",
    "baseSymbol": "LTC",
    "quoteSymbol": "BTC",
    "amount": "0.1000000000000000",
    "price": "0.0150800000000000",
    "side": "BUY",
    "timeInForce": "GTC",
    "status": "completed",
    "cancelRequested": false,
    "success": true,
    "errorCode": 0,
    "errorMessage": "",
    "exchangeApiErrors": []
  },
  "changes": [
    {
      "symbol": "LTC",
      "nativeValue": "0.1",
      "btcValue": 0.0015062135,
      "usdValue": 6.0405953608968
    },
    {
      "symbol": "BTC",
      "nativeValue": "-0.00151177",
      "btcValue": -0.0015062135,
      "usdValue": -6.0405953608968
    }
  ]
}

This endpoint returns the current status of a limit order operation as well as all balance changes that have occurred as a result of the limit order operation. The balance changes do include trading fees.

See also: Place a Limit Order, Cancel a Limit Order, List Open Orders

HTTP Request

GET https://dev-api.shrimpy.io/v1/users/<userId>/accounts/<exchangeAccountId>/orders/<orderId>

URL Parameters

Parameter Type Description
userId UUID The id of the user
exchangeAccountId integer The id of the exchange account
orderId UUID The id of the limit order

Response

Field Type Description
order Limit Order The status of the limit order
changes Balance Change[] The changes that occurred as a result of the limit order.

List Open Orders

Request

GET https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/accounts/123/orders

Response:

[
  {
    "amount": "0.1000000000000000",
    "price": "0.0123000000000000",
    "cancelRequested": false,
    "errorCode": 0,
    "errorMessage": "",
    "baseSymbol": "LTC",
    "quoteSymbol": "BTC",
    "id": "8046422c-f18c-4ff1-93b9-bedd61e53f80",
    "status": "open",
    "success": false,
    "side": "BUY",
    "timeInForce": "GTC",
    "exchangeApiErrors": []
  },
  {
    "amount": "0.0500000000000000",
    "price": "0.0456000000000000",
    "cancelRequested": false,
    "errorCode": 0,
    "errorMessage": "",
    "baseSymbol": "ETH",
    "quoteSymbol": "BTC",
    "id": "c2776060-20f4-41f6-8598-adfc275ea440",
    "status": "open",
    "success": false,
    "side": "SELL",
    "timeInForce": "GTC",
    "exchangeApiErrors": []
  },
  ...
]

This endpoints returns the current status of all open limit order operations. If an order status is "completed", it will not appear in the list.

See also: Place a Limit Order, Get Limit Order Status, Cancel a Limit Order

HTTP Request

GET https://dev-api.shrimpy.io/v1/users/<userId>/accounts/<exchangeAccountId>/orders

URL Parameters

Parameter Type Description
userId UUID The id of the user
exchangeAccountId integer The id of the exchange account

Response

List of Limit Order types.

Limit Order Fields

Field Type Description
id UUID The id of the limit order
baseSymbol string The exchange symbol of the base asset
quoteSymbol string The exchange symbol of the quote asset (e.g. BTC)
amount Decimal The amount of baseSymbol to buy or sell.
price Decimal The price of the limit order, in units of quoteSymbol.
side string Either "BUY" or "SELL". BUY means to exchange quoteSymbol for baseSymbol, while SELL means to exchange baseSymbol for quoteSymbol.
timeInForce string Either "IOC" or "GTC". IOC (Immediate or Cancel) orders execute immediately and cancel any unfilled portion of the order. GTC orders remain on the exchange until executed or canceled. Shrimpy will place and cancel a GTC order on exchanges that do not natively support IOC orders.
status string The status of the order. Either "queued", "started", "open", "closed", "completed".
cancelRequested boolean Whether or the order was requested to be canceled.
success boolean Whether or not the limit order was successful. This value is false until status is "completed".
errorCode integer The error code if an error occurred, or 0 otherwise. This value is 0 until status is "completed".
errorMessage string The error message if an error occurred, or "" otherwise. This value is "" until status is "completed"
exchangeApiErrors Exchange Api Error[] A list of errors received from the exchange that relate to the user's exchange API keys. This list is generally empty and a non-empty list usually indicates an issue that the user needs to resolve. For example, this list will be non-empty if the user deletes their API keys from the exchange, or has invalid API permission on the exchange.

Cancel a Limit Order

Request

DELETE https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/accounts/123/orders/72dff099-54c0-4a32-b046-5c19d4f55758

Response:

{
    "success": true
}

This endpoint queues a cancel limit order operation. An error will be returned if the order has already been completed or canceled.

See also: See also: Place a Limit Order, Cancel a Limit Order, Get Limit Order Status

HTTP Request

DELETE https://dev-api.shrimpy.io/v1/users/<userId>/accounts/<exchangeAccountId>/orders/<orderId>

URL Parameters

Parameter Type Description
userId UUID The id of the user
exchangeAccountId integer The exchange account id of the exchange account
orderId UUID The id of the limit order to be canceled

Creating a Trade

Request

POST https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/accounts/123/trades

Request Body

{
    "fromSymbol": "BTC",
    "toSymbol": "ETH",
    "amount": "0.01",
}

Response:

{
    "id": "72dff099-54c0-4a32-b046-5c19d4f55758"
}

This endpoint creates and queues a trade operation. The trade operation will attempt to trade the specified amount of fromSymbol to toSymbol at the currently available rate on the exchange. The trading engine will execute the trade as a series of limit orders in order to control slippage and monitor spread.

If the fromSymbol and toSymbol are not a market pair, intermediate trades will be made through an asset that they both share a market pair with, such as Bitcoin. For example, in order to trade from XLM to XRP on KuCoin, trades will be made through the XLM/BTC and XRP/BTC markets because there is no XLM/XRP or XRP/XLM market. Note that it is possible to be left with small amounts of the intermediate asset.

See also: Get Trade Status, List Active Trades, Rebalancing

HTTP Request

POST https://dev-api.shrimpy.io/v1/users/<userId>/accounts/<exchangeAccountId>/trades

URL Parameters

Parameter Type Description
userId UUID The id of the user
exchangeAccountId integer The id of the exchange account for which to create a trade.

Body Parameters

Parameter Type Description
fromSymbol string The symbol on the exchange to sell.
toSymbol string The symbol on the exchange to buy.
amount Decimal The amount of fromSymbol to trade, in units of fromSymbol.

Response

Field Type Description
id UUID The id of the trade. Use this with the Get Trade Status endpoint.

Get Trade Status

Request

GET https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/accounts/123/trades/72dff099-54c0-4a32-b046-5c19d4f55758

Response:

{
    "trade": {
        "id": "72dff099-54c0-4a32-b046-5c19d4f55758"
        "fromSymbol": "USDT"
        "toSymbol": "USDC"
        "amount": 13.0000000000000000
        "status": "completed",
        "success": true,
        "errorCode": 0,
        "errorMessage": "",
        "exchangeApiErrors": []
    },
    "changes": [
        {
            "symbol": "USDT",
            "nativeValue": "-12.9845402",
            "btcValue": -0.00353,
            "usdValue": -12.981680687961756
        },
        {
            "symbol": "USDC",
            "nativeValue": "13.0379491",
            "btcValue": 0.00353,
            "usdValue": 12.981680687961756
        }
    ]
}

This endpoint returns the current status of a trade operation as well as all balance changes that have occurred as a result of the trade operation. The balance changes do include trading fees.

See also: Creating a Trade, List Active Trades

HTTP Request

GET https://dev-api.shrimpy.io/v1/users/<userId>/accounts/<exchangeAccountId>/trades/<tradeId>

URL Parameters

Parameter Type Description
userId UUID The id of the user
exchangeAccountId integer The id of the exchange account
tradeId UUID The id of the trade

Response

Field Type Description
trade Trade The status of the trade
changes Balance Change[] The changes that occurred as a result of the trade.

List Active Trades

Request

GET https://dev-api.shrimpy.io/v1/users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8/accounts/123/trades

Response:

[
    {
        "id": "72dff099-54c0-4a32-b046-5c19d4f55758"
        "fromSymbol": "USDT"
        "toSymbol": "USDC"
        "amount": 13.0000000000000000
        "status": "queued",
        "success": false,
        "errorCode": 0,
        "errorMessage": "",
        "exchangeApiErrors": []
    },
    {
        "id": "72dff099-54c0-4a32-b046-5c19d4f55758",
        "fromSymbol": "USDT",
        "toSymbol": "BTC",
        "amount": "15.27",
        "status": "started",
        "success": false,
        "errorCode": 0,
        "errorMessage": "",
        "exchangeApiErrors": []
    }
]

This endpoints returns the current status of all active trade operations. If a trade status is "completed", it will not appear in the list.

See also: Creating a Trade, Get Trade Status

HTTP Request

GET https://dev-api.shrimpy.io/v1/users/<userId>/accounts/<exchangeAccountId>/trades

URL Parameters

Parameter Type Description
userId UUID The id of the user
exchangeAccountId integer The id of the exchange account

Response

List of Trade types.

Trade Fields

Field Type Description
id UUID The id of the trade
fromSymbol string The exchange symbol of the asset to sell. (e.g. "BTC")
toSymbol string The exchange symbol of the asset to buy. (e.g. "XLM")
amount Decimal The amount of fromSymbol to trade, in units of fromSymbol.
status string The status of the trade. Either "queued", "started", or "completed".
success boolean Whether or not the trade was successful. This value is false until status is "completed".
errorCode integer The error code if an error occurred, or 0 otherwise. This value is 0 until status is "completed".
errorMessage string The error message if an error occurred, or "" otherwise. This value is "" until status is "completed".
exchangeApiErrors Exchange Api Error[] A list of errors received from the exchange that relate to the user's exchange API keys. This list is generally empty and a non-empty list usually indicates an issue that the user needs to resolve. For example, this list will be non-empty if the user deletes their API keys from the exchange, or has invalid API permission on the exchange.

Market

The Market endpoints are used for market data operations, such as retrieving a live orderbook. More operations will be added in the future.

Get Order Books

Request

GET https://dev-api.shrimpy.io/v1/market/orderbooks?exchange=bittrex&baseSymbol=XLM&quoteSymbol=BTC&limit=10

Response

[{
  "baseSymbol": "XLM",
  "quoteSymbol": "BTC",
  "exchanges": [{
    "exchange": "Bittrex",
    "orderBook": {
      "asks": [
        {
          "price": "0.00002585",
          "quantity": "1891.1316431"
        },
        {
          "price": "0.00002594",
          "quantity": "35200"
        },
        ...
      ],
      "bids": [
        {
          "price": "0.00002577",
          "quantity": "774.92250177"
        },
        {
          "price": "0.00002576",
          "quantity": "3509.07031022"
        },
        ...
      ]
    }
  }]
}]

This endpoint retrieves live order book data. Examples of data that can be retrieved in a single call are below

See the Market Order Books type for more information.

HTTP Request

GET https://dev-api.shrimpy.io/v1/market/orderbooks

Query String Parameters

Parameter Type Description
exchange string The exchange for which to retrieve live order book data
OR
A comma separated list of exchanges (e.g. "bittrex,binance")
OR
"all" to retrieve data for all supported exchanges
baseSymbol (optional) string The base symbol. (e.g. XLM for a XLM-BTC market) quantity is in these units.
OR
A comma separated list of baseSymbols (e.g. "XLM,STR,ETH")
If baseSymbol is not supplied, all markets matching the quoteSymbol will be returned.
quoteSymbol (optional) string The quote symbol. (e.g. BTC for a XLM-BTC market)
OR
A comma separated list of quoteSymbols (e.g. "BTC,USDT")
If quoteSymbol is not supplied, all markets matching the baseSymbol will be returned.
limit (optional) integer The maximum number of asks and bids to retrieve. Defaults to 10 if not supplied.
If requesting more than one market, limit cannot be greater than 10.

Response

List of Market Order Books types.

Market Order Books Fields

Field Type Description
baseSymbol string The baseSymbol for the market
quoteSymbol string The quoteSymbol for the market
orderBooks Exchange Order Book[] The order book data for the supplied exchanges

Exchange Order Book Fields

Field Type Description
exchange string The exchange from which data retrieved
orderBook Order Book or null The order book data for a specific market on the exchange.

Order Book Fields

Field Type Description
asks Order Book Item[] The best asks for the market. (ascending order)
bids Order Book Item[] The best bids for the market. (descending order)

Order Book Item Fields

Field Type Description
price Decimal The price of the order.
quantity Decimal The quantity of the order (in baseSymbol units)

Analytics

The Analytics endpoints are used for analytical operations, such as backtesting. More operations will be added in the future.

Get Backtest Assets

Request

GET https://dev-api.shrimpy.io/v1/analytics/backtest/coinbasepro/assets

Response

[
  {
    "symbol": "LTC",
    "endTime": "2018-11-05T23:00:00.000Z",
    "startTime": "2016-09-06T13:00:00.000Z"
  },
  {
    "symbol": "BTC",
    "endTime": "2018-11-10T23:00:00.000Z",
    "startTime": "2015-05-17T01:00:00.000Z"
  },
  ...
]

This endpoint retrieves supported backtestable assets for a particular exchange.

As a convenience, an optional startTime and endTime can be supplied to filter assets that are available over the duration between startTime and endTime.

See the Backtest Asset type for more information.

HTTP Request

GET https://dev-api.shrimpy.io/v1/analytics/backtest/<exchange>/assets

URL Parameters

Parameter Type Description
exchange string Must be one of the following: "binance", "bittrex", "coinbasepro", "kraken", "kucoin", or "poloniex"

Query String Parameters

Parameter Type Description
startTime (optional) Date If provided, only assets that have an earlier startTime will be returned
endTime (optional) Date If provided, only assets that have a later endTime will be returned

Response

List of Backtest Asset types.

Backtest Asset Fields

Field Type Description
symbol string The symbol of the asset on the exchange
startTime Date The oldest data point available for backtesteing
endTime Date The most recent data point available for backtesting

Run Backtest

Request

POST https://dev-api.shrimpy.io/v1/analytics/backtest/binance/run

Request Body

{
    "rebalancePeriod": 24,
    "fee": "0.1",
    "startTime": "2018-05-19T00:00:00.000Z",
    "endTime": "2018-11-02T00:00:00.000Z",
    "initialValue": "5000.0",
    "allocations": [
        { "symbol": "BTC", "percent": "50.0" },
        { "symbol": "ETH", "percent": "50.0" }
    ]
}

Response

{
  "rebalanceData": [
    {
      "time": "2018-05-19T07:00:00.000Z",
      "usdValue": 4999.999999999999
    },
    {
      "time": "2018-05-20T00:59:43.836Z",
      "usdValue": 4995.4975344538725
    },
    ...
  ],
  "holdingData": [
    {
      "time": "2018-05-19T07:00:00.000Z",
      "usdValue": 4999.999999999999
    },
    {
      "time": "2018-05-20T00:59:43.836Z",
      "usdValue": 4995.4975344538725
    },
    ...
  ]
}

This endpoint runs a backtest with the supplied settings. This endpoint has a rate limit of 20 requests per minute.

HTTP Request

POST https://dev-api.shrimpy.io/v1/analytics/backtest/<exchange>/run

URL Parameters

Parameter Type Description
exchange string Must be one of the following: "binance", "bittrex", "coinbasepro", "kraken", "kucoin", or "poloniex"

Body Parameters

Parameter Type Description
rebalancePeriod number The rebalance period in hours, or 0 to never rebalance
fee Decimal The percentage fee to use when simulating trades. The acceptable range is between 0 and 1, with 1 corresponding to a fee of 1%.
startTime Date The starting date of the simulation
endTime Date The ending date of the simulation
initialValue Decimal The intial value of the simulated portfolio in United States Dollars
allocations Allocation The list of allocations to use in the simulation. See Static Strategy for more information

Response

Field Type Description
rebalanceData Backtest Data Point[] Simulated balance data for the duration of the backtest. There will be one data point per day of the backtest.
holdingData Backtest Data Point[] Same as rebalanceData, but the simulation was run without rebalancing. If the rebalancePeriod is 0, holdingData and rebalanceData will match.

Backtest Data Point Fields

Field Type Description
time Date The time of the simulated data point
usdValue number The value of the portfolio in United States Dollars

Types

Account

Example

{
    "id": 123,
    "exchange": "Kucoin",
    "isRebalancing": true,
    "exchangeApiErrors": []
}

The account object contains information about an exchange account that you have linked to your Shrimpy account.

Account Fields

Field Type Description
id integer The unique identifier of the strategy
exchange string The name of the linked exchange
isRebalancing boolean True if the account is rebalancing.
exchangeApiErrors Exchange Api Error[] A list of errors received from the exchange that relate to the user's exchange API keys. This list is generally empty and a non-empty list usually indicates an issue that the user needs to resolve. For example, this list will be non-empty if the user deletes their API keys from the exchange, or has invalid API permission on the exchange.

Allocation

Example

{
    "symbol": "BTC",
    "percent": "50"
}

An allocation specifies an exchange asset and a percentage. It is a component of a Static Strategy.

Allocation Fields

Field Type Description
symbol string The symbol of the asset on the exchange
percent Decimal The percentage (two decimal place precision)

Backtest Asset

Example

{
    "symbol": "BTC",
    "endDate": "2018-11-10T23:00:00.000Z",
    "startDate": "2015-05-17T01:00:00.000Z"
}

A backtest asset represents an asset that can be used in a backtest. It also returns the date range for which the asset can be backtested.

Backtest Asset Fields

Field Type Description
symbol string The symbol of the asset on the exchange
startTime Date The oldest data point available for backtesteing
endTime Date The most recent data point available for backtesting

Backtest Data Point

Example

{
    "time": "2018-05-20T00:59:43.836Z",
    "usdValue": 4995.4975344538725
}

A backtest data point represents the balance of a simulated portfolio at a single point in time.

Backtest Data Point Fields

Field Type Description
time Date The time of the simulated data point
usdValue number The value of the portfolio in United States Dollars

Balance

Example

{
    "symbol": "KCS",
    "nativeValue": 2306.0,
    "btcValue": 0.33486579,
    "usdValue": 1327.8775274784
}

A balance object represents the value of an asset on the exchange.

Balance Fields

Field Type Description
symbol string The symbol of the asset on the exchange
nativeValue number The amount of the asset on the exchange.
btcValue number The value of the asset on the exchange, in Bitcoin. This value is computed when the balance data is collected.
usdValue number The value of the asset on the exchange, in United States Dollars. This value is computed when the balance data is collected.

Balance Change

Example 1

{
    "symbol": "USDC",
    "nativeValue": "13.0379491",
    "btcValue": 0.00353,
    "usdValue": 12.981680687961756
}    

Example 2

{
    "symbol": "USDT",
    "nativeValue": "-12.9845402",
    "btcValue": -0.00353,
    "usdValue": -12.981680687961756
}

A balance object represents a value change of an asset on the exchange. Negative values mean that asset was sold. The type structure is very similar to the Balance type.

Balance Change Fields

Field Type Description
symbol string The exchange symbol of the asset
nativeValue Decimal The amount the asset was changed, in units of symbol.
btcValue number The value of the asset on the exchange, in Bitcoin. This value is computed when the trade is executed.
usdValue number The value of the asset on the exchange, in United States Dollars. This value is computed when the the trade is executed.

Date

Example

"2018-12-19T22:51:13.000Z"

Dates are returned as strings in ISO format (ISO 8601).

Decimal

Example 1

"3628.545"

Example 2

"7.85e-7"

Decimal numbers are returned as strings to preserve full precision across platforms. When making a request, it is recommended that you also convert your numbers to string to avoid truncation and precision errors.

Integer numbers (like exchange account id and rebalancePeriod) are unquoted.

Dynamic Strategy

Example 1

{
    "isDynamic": true,
    "excludedSymbols": [],
    "topAssetCount": 10,
    "minPercent": "0",
    "maxPercent": "100",
    "isEqualWeight": true
}

Example 2

{
    "isDynamic": true,
    "excludedSymbols": ["USDT"],
    "topAssetCount": 10,
    "minPercent": "0",
    "maxPercent": "30",
    "isEqualWeight": false
}

Example 3

{
    "isDynamic": true,
    "excludedSymbols": [],
    "topAssetCount": 20,
    "minPercent": "3",
    "maxPercent": "100",
    "isEqualWeight": false
}

A dynamic strategy's assets and percentages are dependent on the current top market cap assets. Examples of dynamic strategies that can be created are below:

Dynamic Strategy Fields

Field Type Description
excludedSymbols string[] The symbols to ignore when using a dynamic strategy
topAssetCount integer The number of top assets to include in the dynamic strategy
minPercent Decimal The minimum percentage to assign to each asset in the dynamic strategy (two decimal place precision)
maxPercent Decimal The minimum percentage to assign to each asset in the dynamic strategy (two decimal place precision)
isEqualWeight boolean Whether or not equal assign percentages to each asset in the dynamic strategy

Exchange API Error

Example 1

{
  "code": 1002,
  "message": "Invalid API keys"
}

Example 2

{
  "code": 1004,
  "message": "Invalid permission: trade"
}

Example 3

{
  "code": 1004,
  "message": "Invalid permission: balance"
}

An Exchange API Error object represents an issue with user exchange api keys.

Exchange API Error Fields

Field Type Description
code integer The error code associated with the exchange error.
message string A human-readable description of the error.

Error Codes

Code Message Description
1001 Invalid IP whitelist The exchange rejected the request from our API servers due to a user's IP whitelist on the exchange. This can happen if a user enables IP whitelisting on the exchange and fails to whitelist all 4 of the IP addresses provisioned by Shrimpy for the user.
1002 Invalid API keys The API keys are no longer valid. This can happen if the user deletes their exchange API keys from the exchange.
1003 Invalid nonce The exchange rejected a request from our API servers due to the nonce. This can happen on some exchanges if the exchange API keys are shared with another service.
1004 Invalid permission: PERMISSION_TYPE The user has not allowed all required permissions on the exchange. The most common values for PERMISSION_TYPE are "balance" and "trade".

Exchange Order Book

Example

{
  "exchange": "Bittrex",
  "orderBook": {
    "asks": [
      {
        "price": "0.00002585",
        "quantity": "1891.1316431"
      },
      {
        "price": "0.00002594",
        "quantity": "35200"
      },
      ...
    ],
    "bids": [
      {
        "price": "0.00002577",
        "quantity": "774.92250177"
      },
      {
        "price": "0.00002576",
        "quantity": "3509.07031022"
      },
      ...
    ]
  }
}

An exchange order book object contains data for a single currency pair on a single exchange.

Exchange Order Book Fields

Field Type Description
exchange string The exchange from which data retrieved
orderBook Order Book or null The order book data for a specific market on the exchange. Can be null if the currency pair is not supported by the exchange.

Limit Order

The order type contains information about a particular order operation.

Example

{
    "id": "e426e9aa-6518-4ba2-afc2-baabb73048c0",
    "baseSymbol": "LTC",
    "quoteSymbol": "BTC",
    "amount": "0.1000000000000000",
    "price": "0.0150800000000000",
    "side": "BUY",
    "timeInForce": "GTC",
    "status": "completed",
    "cancelRequested": false,
    "success": true,
    "errorCode": 0,
    "errorMessage": "",
    "exchangeApiErrors": []
}

Limit Order Fields

Field Type Description
id UUID The id of the limit order
baseSymbol string The exchange symbol of the base asset
quoteSymbol string The exchange symbol of the quote asset (e.g. BTC)
amount Decimal The amount of baseSymbol to buy or sell.
price Decimal The price of the limit order, in units of quoteSymbol.
side string Either "BUY" or "SELL". BUY means to exchange quoteSymbol for baseSymbol, while SELL means to exchange baseSymbol for quoteSymbol.
timeInForce string Either "IOC" or "GTC". IOC (Immediate or Cancel) orders execute immediately and cancel any unfilled portion of the order. GTC orders remain on the exchange until executed or canceled. Shrimpy will place and cancel a GTC order on exchanges that do not natively support IOC orders.
status string The status of the order. Either "queued", "started", "open", "closed", "completed".
cancelRequested boolean Whether or the order was requested to be canceled.
success boolean Whether or not the limit order was successful. This value is false until status is "completed".
errorCode integer The error code if an error occurred, or 0 otherwise. This value is 0 until status is "completed".
errorMessage string The error message if an error occurred, or "" otherwise. This value is "" until status is "completed"
exchangeApiErrors Exchange Api Error[] A list of errors received from the exchange that relate to the user's exchange API keys. This list is generally empty and a non-empty list usually indicates an issue that the user needs to resolve. For example, this list will be non-empty if the user deletes their API keys from the exchange, or has invalid API permission on the exchange.

Market Order Books

Example

{
  "baseSymbol": "XLM",
  "quoteSymbol": "BTC",
  "orderBooks": [{
    "exchange": "Bittrex",
    "orderBook": {
      "asks": [
        {
          "price": "0.00002585",
          "quantity": "1891.1316431"
        },
        {
          "price": "0.00002594",
          "quantity": "35200"
        },
        ...
      ],
      "bids": [
        {
          "price": "0.00002577",
          "quantity": "774.92250177"
        },
        {
          "price": "0.00002576",
          "quantity": "3509.07031022"
        },
        ...
      ]
    }
  }]
}

A market order book object contains data for a single currency pair on one or more exchanges.

Market Order Book Fields

Field Type Description
baseSymbol string The baseSymbol for the market
quoteSymbol string The quoteSymbol for the market
orderBooks Exchange Order Book[] The order book data for the supplied exchanges

Order Book

Example

{
  "asks": [
    {
      "price": "0.00002585",
      "quantity": "1891.1316431"
    },
    {
      "price": "0.00002594",
      "quantity": "35200"
    },
    ...
  ],
  "bids": [
    {
      "price": "0.00002577",
      "quantity": "774.92250177"
    },
    {
      "price": "0.00002576",
      "quantity": "3509.07031022"
    },
    ...
  ]
}

An order book object represents an order book on an exchange.

Order Book Fields

Field Type Description
asks Order Book Item[] The best asks for the market. (ascending order)
bids Order Book Item[] The best bids for the market. (descending order)

Order Book Item

Example

{
  "price": "0.00002585",
  "quantity": "1891.1316431"
}

An order book item object represents a single order on an exchange.

Order Book Item Fields

Field Type Description
price Decimal The price of the order.
quantity Decimal The quantity of the order (in base_symbol units_)

Static Strategy

Example

{
    "isDynamic": false,
    "allocations": [
    {
        "symbol": "BTC",
        "percent": "50"
    },
    {
        "symbol": "ETH",
        "percent": "50"
    }
}

A Static Strategy is a list of Allocations, where each allocation specifies the asset and what percentage to allocate to it. All percentages must sum to 100%. For example, 50% Bitcoin and 50% Ethereum.

Static Strategy Fields

Field Type Description
isDynamic false Always false for static strategies
allocations Allocations[] The allocations

Strategy

Examples: See Static Strategy or Dynamic Strategy

A strategy is either a Static Strategy or Dynamic Strategy. All strategy objects must include the isDynamic field, the remaining fields depend on the value of isDynamic.

Strategy Fields

Field Type Description
isDynamic boolean True if the strategy is dynamic, false if the strategy is static

Ticker

The ticker type contains public information about a particular asset. The symbol depends on the exchange, so it can vary from exchange to exchange. The price is calculated by taking the average of the latest bid and latest ask.

Example

{
    "name": "Bitcoin",
    "symbol": "BTC",
    "priceUsd": "3700.0089335",
    "priceBtc": "1",
    "percentChange24hUsd": "4.191224354581092",
    "lastUpdated": "2018-12-19T22:51:13.000Z"
}

Ticker Fields

Field Type Description
name string The name of the asset
symbol string The symbol of the asset on the exchange
priceUsd Decimal or null The latest price in United States Dollars
priceBtc Decimal or null The latest price in Bitcoin
percentChange24hUsd Decimal or null The change in USD price in the last 24 hours
lastUpdated Date or null The time the latest ticker data was retrieved

Trade

The trade type contains information about a particular trade operation.

Example

{
    "id": "72dff099-54c0-4a32-b046-5c19d4f55758",
    "fromSymbol": "USDT",
    "toSymbol": "BTC",
    "amount": "15.27",
    "status": "completed",
    "success": true,
    "errorCode": 0,
    "errorMessage": "",
    "exchangeApiErrors": []
}

Trade Fields

Field Type Description
id UUID The id of the trade
fromSymbol string The exchange symbol of the asset to sell. (e.g. "BTC")
toSymbol string The exchange symbol of the asset to buy. (e.g. "XLM")
amount Decimal The amount of fromSymbol to trade, in units of fromSymbol.
status string The status of the trade. Either "queued", "started", or "completed".
success boolean Whether or not the trade was successful. This value is false until status is "completed".
errorCode integer The error code if an error occurred, or 0 otherwise. This value is 0 until status is "completed".
errorMessage string The error message if an error occurred, or "" otherwise. This value is "" until status is "completed".
exchangeApiErrors Exchange Api Error[] A list of errors received from the exchange that relate to the user's exchange API keys. This list is generally empty and a non-empty list usually indicates an issue that the user needs to resolve. For example, this list will be non-empty if the user deletes their API keys from the exchange, or has invalid API permission on the exchange.

User

The user type contains information about a particular user. Users can be enabled and disabled at any time. Trading will continue to work until the expiration date, even if the user is disabled.

Example

{
    "id": "701e0d16-1e9e-42c9-b6a1-4cada1f395b8",
    "isEnabled": true,
    "expirationDate": "2019-01-12T21:09:25.000Z",
    "name": "customnameforthisuser"
}

User Fields

Field Type Description
id UUID The unique identifier of the user.
isEnabled boolean True if the user is currently enabled.
expirationDate Date or null The date the user will expire.
name string The optional name associated with the user.

UUID

UUIDs are returned as strings of 32 hexadecimal digits, displayed in five groups separated by hyphens. For example: "70e3a52a-4fda-464d-b4af-029f55cbd9be"