NAV Navbar
javascript python

Introduction

API Clients

// Shrimpy API Javascript Library
// https://github.com/shrimpy-dev/shrimpy-node
# Shrimpy API Python Library
# https://github.com/shrimpy-dev/shrimpy-python

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.

Official API Clients are currently available for:

Unofficial API Clients from our Users:

Pricing

There are two types of credits that Shrimpy Developers can purchase to access the Developer API.

User credits are used to access any endpoints that require a user guid in the URL path. For example, to rebalance an users portfolio we use the endpoint:

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

Since the URL contains users/701e0d16-1e9e-42c9-b6a1-4cada1f395b8 in the url, it requires user credits to be accessed. Endpoints that require user credits are also detailed in their individual sections. Credit usage is determined using "Active Users". See Users for more information.

Data credits are used to access the historical endpoints to retrieve historical order book or trade data. The Historical-Instruments endpoint is free to use, so that users can determine if the data they require is vended by Shrimpy.

All Real-time market data REST endpoints are free to user for all users. Real-time data from websockets require a paid subscription plan.

Rate Limits

There are separate rate limits for both public and private endpoints. The rate limits are as follows:

If you exceed the rate limit, a status of 429 will be returned. Repeatedly violating rate limits will result in an automatic IP ban.

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

Example of Signing a Request

var crypto = require('crypto');

// This is base64 encoded
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');
import hmac
import hashlib
import time
import base64
import json
import requests


# public API key (not base64 encoded)
api_key = '56bd007fa71b63...'

# private API key (base64 encoded)
secret = '6991cf4c9b51...'

nonce = int(time.time() *  1000)
base_url = 'https://dev-api.shrimpy.io'
request_path = "/v1/users/70e3a52a-4fda-464d-b4af-029f55cbd9be/accounts/123/rebalance_period"

body = json.dumps({ "rebalancePeriod": 24 })
method = "POST"
prehash_string = ''.join([request_path, method, str(nonce), (body or '')])

secret_key = base64.b64decode(secret)
prehash_string = prehash_string.encode('ascii')

signature = hmac.new(secret_key, prehash_string, hashlib.sha256)
signature_b64 = base64.b64encode(signature.digest()).decode('utf-8')

headers = {
    'Content-Type': 'application/json',
    'DEV-SHRIMPY-API-KEY': api_key,
    'DEV-SHRIMPY-API-NONCE': str(nonce),
    'DEV-SHRIMPY-API-SIGNATURE': signature_b64
}

r  = requests.post(
    base_url + request_path,
    data=body,
    headers=headers
)

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

The Public endpoints provide free access to general information. They do not require credits to be used.

API Keys are not required to use Public endpoints. However, requests that do not specify an API key in the header will be rate limited to 10 requests per minute per IP.

See Rate Limits for more details.

Cost: Free!

Get Supported Exchanges

Example Code

const supportedExchanges = await client.getSupportedExchanges();
supported_exchanges = client.get_supported_exchanges()

Request

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

Response

[
    {
        "exchange": "coinbasepro",
        "bestCaseFee": 0,
        "worstCaseFee": 0.003,
        "icon": "https://assets.shrimpy.io/exchanges/coinbasepro.png"
    },
    {
        "exchange": "kucoin",
        "bestCaseFee": 0.000125,
        "worstCaseFee": 0.001,
        "icon": "https://assets.shrimpy.io/exchanges/kucoin.png"
    },
    {
        "exchange": "bittrex",
        "bestCaseFee": 0.0025,
        "worstCaseFee": 0.0025,
        "icon": "https://assets.shrimpy.io/exchanges/bittrex.png"
    },
    {
        "exchange": "bittrexinternational",
        "bestCaseFee": 0.0025,
        "worstCaseFee": 0.0025,
        "icon": "https://assets.shrimpy.io/exchanges/bittrexinternational.png"
    },    
    ...
]

This endpoint retrieves all Shrimpy supported exchanges and some basic information about each.

HTTP Request

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

Response

List of Exchange Info types.

Exchange Info Fields

Field Type Description
exchange string A unique identifier for the exchange that is used with other Shrimpy endpoints. This is typically the lowercase name of the exchange without spaces.
bestCaseFee number The lowest possible fee on the exchange. Fees are typically lower based on your trading volume, if you are using an exchange-specific discount token, and if you are the maker. A negative fee means you receive a rebate. All fee values are scalar values associated with percentages. For example, 0.001 means "0.1%".
worstCaseFee number The highest possible fee on the exchange. All fee values are scalar values associated with percentages. For example, 0.001 means "0.1%".
icon string A url for a 32x32px icon associated with the exchange.

Get Exchange Assets

Example Code

const exchangeAssets = await client.getExchangeAssets(
    'coinbasepro' // exchange
);
exchange_assets = client.get_exchange_assets('coinbasepro')

Request

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

Response

[
  {
    "id": 38,
    "name": "Bitcoin",
    "symbol": "BTC",
    "tradingSymbol": "BTC"
  },
  {
    "id": 229,
    "name": "Litecoin",
    "symbol": "LTC",
    "tradingSymbol": "LTC"
  },
  ...
]

This endpoint retrieves exchange asset information for a particular exchange.

As a convenience, Shrimpy hosts a logo for each asset according to the table below:

Resolution Url
32x32 https://assets.shrimpy.io/cryptoicons/png/<id>.png
128x128 https://assets.shrimpy.io/cryptoicons/png128/<id>.png

HTTP Request

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

Response

List of Exchange Asset types.

Exchange Asset Fields

Field Type Description
id integer A cross-exchange unique identifier for the asset that is generated by Shrimpy.
name string A human-readable name for the asset. This name may change if the asset is rebranded.
symbol string The commonly used symbol for the asset. E.g. XLM for Stellar or BTC for Bitcoin.
tradingSymbol string The symbol for the asset that is used on the associated exchange. The tradingSymbol will usually match the symbol, but not always. E.g. STR for Stellar on Poloniex or XBT for Bitcoin on Kraken.

Get Trading Pairs

Example Code

const tradingPairs = await client.getTradingPairs(
    'coinbasepro' // exchange
);
trading_pairs = client.get_trading_pairs('coinbasepro')

Request

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

Response

[
  {
    "baseTradingSymbol": "LTC",
    "quoteTradingSymbol": "BTC"
  },
  {
    "baseTradingSymbol": "BTC",
    "quoteTradingSymbol": "USD"
  },
  ...
]

This endpoint retrieves a list of active trading pairs for a particular exchange. The symbols will match the tradingSymbol from Get Exchange Assets as well as the symbol used by the exchange.

See also: Get Exchange Assets.

HTTP Request

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

Response

List of Trading Pair types.

Trading Pair Fields

Field Type Description
baseTradingSymbol string The base symbol for this trading pair used by the exchange.
quoteTradingSymbol string The quote symbol for this trading pair used by the exchange.

Market Data

Get Ticker

Example Code

const ticker = await client.getTicker(
    'kucoin' // exchange
);
ticker = client.get_ticker('kucoin')

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

Get Order Books

Example Code

const orderBooks = await client.getOrderBooks(
    'bittrex',  // exchange
    'XLM',      // baseSymbol
    'BTC',      // quoteSymbol
    10          // limit
);
orderbooks = client.get_orderbooks(
    'bittrex',  # exchange
    'XLM',      # base_symbol
    'BTC',      # quote_symbol
    10          # limit
)

Request

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

Response

[{
  "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"
        },
        ...
      ]
    }
  }]
}]

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/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 base symbol for the market
quoteSymbol string The quote symbol 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)

Get Candles

Example Code

const candles = await client.getCandles(
    'bittrex',  // exchange
    'XLM',      // baseTradingSymbol
    'BTC',      // quoteTradingSymbol
    '15m'       // interval
);
candles = client.get_candles(
    'bittrex',  # exchange
    'XLM',      # base_trading_symbol
    'BTC',      # quote_trading_symbol
    '15m'       # interval
)

Request

GET https://dev-api.shrimpy.io/v1/exchanges/coinbasepro/candles?quoteTradingSymbol=BTC&baseTradingSymbol=XLM&interval=1H 

Response

[
  {
    "open": "0.0000157300000000",
    "high": "0.0000157800000000",
    "low": "0.0000155800000000",
    "close": "0.0000157100000000",
    "volume": "219444.0000000000000000",
    "quoteVolume": 3.44176145,
    "btcVolume": 3.44176145,
    "usdVolume": 27437.297915762,
    "time": "2019-05-24T23:00:00.000Z"
  },
  {
    "open": "0.0000157100000000",
    "high": "0.0000157500000000",
    "low": "0.0000156900000000",
    "close": "0.0000157300000000",
    "volume": "1603.0000000000000000",
    "quoteVolume": 0.02520959,
    "btcVolume": 0.02520959,
    "usdVolume": 201.98615317277,
    "time": "2019-05-25T00:00:00.000Z"
  },
  ...
]

This endpoint retrieves live candlestick data. The candlestick data is typically used to plot a candlestick or OHLCV chart.

When retrieving candlestick data for plotting, first call the endpoint without specifying a startTime. This will return data associated with the most recent 1000 candlesticks. Subsequently, periodically call the endpoint specifying the startTime as the time associated with the most recent candlestick. Note that the last or most recent candlestick is for the current, not-yet-committed frame.

All times are in returned in UTC. See the Candlestick type for more information.

HTTP Request

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

URL Parameters

Parameter Type Description
exchange string The exchange for which to retrieve candlestick data. See Get Supported Exchanges for the list of supported exchanges

Query String Parameters

Parameter Type Description
baseTradingSymbol string The base symbol of a pair on the exchange. (e.g. XLM for a XLM-BTC pair)
quoteTradingSymbol string The quote symbol of a pair on the exchange. (e.g. BTC for a XLM-BTC pair)
interval string The interval must be one of the following values: 1m, 5m, 15m, 1h, 6h, or 1d) These values correspond to intervals representing one minute, five minutes, fifteen minutes, one hour, six hours, and one day, respectively.
startTime (optional) Date Optionally only return data on or after the supplied startTime (inclusive).

Response

List of Candlestick types.

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 active user costs 1 credit per 30 days. Users are marked as "Active" if you perform any of the following actions:

Users are immediately marked as active users on creation.

Endpoints that are contain the user object substring in their URL will mark users as "Active" on success. For example,

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

This means that while using the APIs does not directly incur cost, our system will aggregate all the users that are marked as "Active" in the background.

If you exceed your subscription, you will be asked to upgrade within a grace period of 2 weeks. If you do not upgrade your usage tier and continue to make API calls above your limit, any api calls for new users will fail. However, you will still be able to make API calls for users that were previously active within the subscription limit.

We also have a very helpful blog article, see Here for more information.

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

List Users

Example Code

const users = await client.getUsers();
users = client.list_users()

Request

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

Response

[
    {
        "id": "701e0d16-1e9e-42c9-b6a1-4cada1f395b8",
        "isEnabled": null,
        "expirationDate": "2019-01-12T21:09:25.000Z",
        "name": ""
    },
    {
        "id": "70e3a52a-4fda-464d-b4af-029f55cbd9be",
        "isEnabled": null,
        "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 null This key has been disabled and is not meant for use. It simply exists for backwards compatibility at this time.
expirationDate Date or null The date the user will expire.
name string The optional name associated with the user.

Get a User

Example Code

const user = await client.getUser(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8' //userId
);
user = client.get_user(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8' # user_id
)

Request

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

Response

{
    "id": "701e0d16-1e9e-42c9-b6a1-4cada1f395b8",
    "isEnabled": null,
    "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

Example Code

const userId = await client.createUser();
create_user_response = client.create_user(
    'mycustomname' # (optional) name
)
user_id = create_user_response['id']

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.

This endpoint will mark an User as Active for billing purposes.

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

Example Code

await client.setUserName(
    'mycustomname' // name
);
client.name_user(
    'mycustomname' # name
)

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.

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

Example Code

const publicKeys = await client.getApiKeys(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8' //userId
);
public_user_keys = client.get_api_keys(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8' # user_id
)

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

Example Code

const apiKeys = await client.createApiKeys(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8' // userId
);
user_api_keys = client.create_api_keys(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8' # user_id
)

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

Example Code

const apiKeys = await client.deleteApiKeys(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8',                            // userId
    '51ac18b7d208f59b3c88acbb1ecefe6ba6be6ea4edc07e7a2450307ddc27ab80' // publicKey
);
client.delete_api_keys(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8',                            # user_id
    '51ac18b7d208f59b3c88acbb1ecefe6ba6be6ea4edc07e7a2450307ddc27ab80' # public_key
)

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

Example Code

const permissions = await client.getPermissions(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8',                            // userId
    '51ac18b7d208f59b3c88acbb1ecefe6ba6be6ea4edc07e7a2450307ddc27ab80' // publicKey
);
permissions = client.get_api_key_permissions(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8',                            # user_id
    '51ac18b7d208f59b3c88acbb1ecefe6ba6be6ea4edc07e7a2450307ddc27ab80' # public_key
)

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

Example Code

await client.setPermissions(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8',                             // userId
    '51ac18b7d208f59b3c88acbb1ecefe6ba6be6ea4edc07e7a2450307ddc27ab80', // publicKey
    true,                                                               // enable account methods
    false                                                               // enable trading methods
);
client.set_api_key_permissions(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8',                             # user_id
    '51ac18b7d208f59b3c88acbb1ecefe6ba6be6ea4edc07e7a2450307ddc27ab80', # public_key
    True,                                                               # enable account methods
    False                                                               # enable trading methods
)

Request

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

Request Body

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

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

Example Code

const accounts = await client.getAccounts(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8' // userId
);
accounts = client.list_accounts(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8' # user_id
)

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

Example Code

const account = await client.getAccount(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', // userId
    123                                     // accountId
);
account = client.get_account(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', # user_id
    123                                     # exchange_account_id
)

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.

Example Code

const accountId = await client.createAccount(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8',                             // userId
    'binance',                                                          // exchange
    'GOelL5FT6TklPxAzICIQK25aqct52T2lHoKvtcwsFla5sbVXmeePqVJaoXmXI6Qd', // publicKey (a.k.a. apiKey)
    'SelUuFq1sF2zGd97Lmfbb4ghITeziKo9IvM5NltjEdffatRN1N5vfHXIU6dsqRQw'  // privateKey (a.k.a. secretKey
);
link_account_response = client.link_account(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8',                             # user_id
    'binance',                                                          # exchange
    'GOelL5FT6TklPxAzICIQK25aqct52T2lHoKvtcwsFla5sbVXmeePqVJaoXmXI6Qd', # public_key (a.k.a. apiKey)
    'SelUuFq1sF2zGd97Lmfbb4ghITeziKo9IvM5NltjEdffatRN1N5vfHXIU6dsqRQw', # private_key (a.k.a. secretKey
    # 'mypassphrase'  (optional) passphrase - required for exchanges with passphrases like CoinbasePro
)
account_id = link_account_response['id']

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.

Example Code

await client.deleteAccount(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', // userId
    456                                     // accountId
);
client.unlink_account(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', # user_id
    456                                     # account_id
)

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

Example Code

const IpAddresses = await client.getIpWhitelistAddresses(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8' // userId
);
ip_addresses = client.get_ip_whitelist_addresses(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8' # user_id
)

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.

Creating a Trade

Example Code

const tradeId = await client.createTrade(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', // userId
    123,                                    // accountId
    'BTC',                                  // fromSymbol
    'ETH',                                  // toSymbol
    new Decimal('0.01')                     // amount of fromSymbol
);
create_trade_response = client.create_trade(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', # user_id
    123,                                    # account_id
    'BTC',                                  # from_symbol
    'ETH',                                  # to_symbol
    '0.01'                                  # amount of from_symbol
)
trade_id = create_trade_response['id']

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.
smartRouting (optional) boolean Trade through whichever pairs give the best rate, not just directly or BTC. smartRouting defaults to false.
maxSpreadPercent (optional) Decimal The maximum allowed spread when trading to and from the assets. The trade will be aborted if the spread crosses this threshold. The maxSpreadPercent defaults to 10%.
maxSlippagePercent (optional) Decimal The maximum allowed slippage when trading to and from the assets. The trade will be aborted if the price decreases by more than this percentage during the trade. The maxSlippagePercent defaults to 10%.

Response

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

Get Trade Status

Example Code

const trade = await client.getTrade(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', // userId
    123,                                    // exchangeAccountId
    '72dff099-54c0-4a32-b046-5c19d4f55758'  // tradeId
);
trade = client.get_trade_status(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', # user_id
    123,                                    # exchange_account_id
    '72dff099-54c0-4a32-b046-5c19d4f55758'  # trade_id
)

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": "97230bce-08d1-4a1c-a1dc-675ee2e1bd04",
        "fromSymbol": "KCS",
        "toSymbol": "BTC",
        "amount": "20",
        "status": "completed",
        "success": true,
        "errorCode": 0,
        "errorMessage": "",
        "exchangeApiErrors": [],
        "smartRouting": false,
        "maxSpreadPercent": "10",
        "maxSlippagePercent": "10",
        "triggeredMaxSpread": false,
        "triggeredMaxSlippage": false
    },
    "changes": [
        {
            "symbol": "KCS",
            "nativeValue": "-20",
            "btcValue": -0.0028169,
            "usdValue": -20.05604616757
        },
        {
            "symbol": "BTC",
            "nativeValue": "0.0028134",
            "btcValue": 0.0028169,
            "usdValue": 20.05604616757
        }
    ],
    "fills": [
        {
            "baseAmount": "20",
            "baseSymbol": "KCS",
            "btcValue": 0.0028169,
            "price": "0.00014067",
            "quoteAmount": "0.0028134",
            "quoteSymbol": "BTC",
            "side": "SELL",
            "usdValue": 20.05604616757
        }
    ]
}

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.
fills Trade Fill[] The orders that were filled as a result of the trade.

List Active Trades

Example Code

const activeTrades = await client.getActiveTrades(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', // userId
    123,                                    // exchangeAccountId
);
active_trades = client.list_active_trades(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', # user_id
    123,                                    # exchange_account_id
)

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": [],
        "smartRouting": false,
        "maxSpreadPercent": "10",
        "maxSlippagePercent": "10",
        "triggeredMaxSpread": false,
        "triggeredMaxSlippage": false
    },
    {
        "id": "72dff099-54c0-4a32-b046-5c19d4f55758",
        "fromSymbol": "USDT",
        "toSymbol": "BTC",
        "amount": "15.27",
        "status": "started",
        "success": false,
        "errorCode": 0,
        "errorMessage": "",
        "exchangeApiErrors": [],
        "smartRouting": false,
        "maxSpreadPercent": "10",
        "maxSlippagePercent": "10",
        "triggeredMaxSpread": false,
        "triggeredMaxSlippage": false
    }
]

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.
smartRouting boolean Whether or not smart routing was enabled for this trade. Smart routing means the trade will use whichever pairs give the best rate, not just the direct pair or BTC pairs.
maxSpreadPercent Decimal The maximum allowed spread when trading to and from the assets. The trade will be aborted if the spread crosses this threshold.
maxSlippagePercent Decimal The maximum allowed slippage when trading to and from the assets. The trade will be aborted if the price decreases by more than this percentage during the trade.
triggeredMaxSpread boolean Whether or not the maximum spread threshold was reached.
triggeredMaxSlippage boolean Whether or not the maximum slippage threshold was reached.

Balances

Get Balance

Example Code

const balance = await client.getBalance(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', // userId
    123                                     // accountId
);
balance = client.get_balance(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', # user_id
    123                                     # account_id
)

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 detailed balance data for an exchange account. By default, the most recent balance is returned. 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

Query String Parameters

Parameter Type Description
date (optional) Date If supplied, balance data that is nearest to the date will be returned.
If not supplied, the most recent balance data is returned.

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.

Get Total Balance History

Example Code

const totalBalanceHistory = await client.getTotalBalanceHistory(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', // userId
    123                                     // accountId
);
total_balance_history = client.get_total_balance_history(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', # user_id
    123                                     # account_id
)

Request

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

Response

[
  {
    "date": "2018-05-04T23:13:36.000Z",
    "usdValue": 5450.848215924849,
    "btcValue": 0.5591789264332345
  },
  {
    "date": "2018-05-04T23:28:16.000Z",
    "usdValue": 5431.690471169028,
    "btcValue": 0.5593913976487155
  },
  ...
]

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

HTTP Request

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

URL Parameters

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

Query String Parameters

Parameter Type Description
startTime (optional) Date Optionally only return data on or after the supplied startTime (inclusive)
endTime (optional) Date Optionally only return data on or before the supplied endTime (inclusive)

Response

List of TotalBalanceHistoryItem

Asset Management

Rebalancing

Example Code

await client.rebalance(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', // userId
    123                                     // accountId
);
client.rebalance(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', # user_id
    123                                     # account_id
)

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

Example Code

const rebalancePeriodHours = await client.getRebalancePeriod(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', // userId
    123                                     // accountId
);
rebalance_period_hours = client.get_rebalance_period(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', # user_id
    123                                     # account_id
)

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

Example Code

await client.setRebalancePeriod(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', // userId
    123,                                    // accountId
    24                                      // rebalancePeriod in hours
);
client.set_rebalance_period(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', # user_id
    123,                                    # account_id
    24                                      # rebalance_period in hours
)

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

Example Code

const strategy = await client.getStrategy(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', // userId
    123                                     // accountId
);
strategy = client.get_strategy(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', # user_id
    123                                     # account_id
)

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

Example Code

await client.setStrategy(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8',   // userId
    123,                                      // accountId
    {
        isDynamic: false,
        allocations: [
            { symbol: 'BTC', percent: '50' },
            { symbol: 'ETH', percent: '50' }
        ]
    }                                         // strategy
);
client.set_strategy(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8',   # user_id
    123,                                      # account_id
    {
        'isDynamic': False,
        'allocations': [
            { 'symbol': 'BTC', 'percent': '50' },
            { 'symbol': 'ETH', 'percent': '50' }
        ]
    }                                         # 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

Example Code

await client.clearStrategy(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8',   // userId
    123                                       // accountId
);
client.clear_strategy(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8',   # user_id
    123                                       # account_id
)

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

Example Code

await client.allocate(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8',    // userId
    123,                                       // accountId
    {
        isDynamic: false,
        allocations: [
            { symbol: 'USDT', percent: '100' }
        ]
    }                                          // strategy
);
client.allocate(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8',    # user_id
    123,                                       # account_id
    {
        'isDynamic': False,
        'allocations': [
            { 'symbol': 'USDT', 'percent': '100' }
        ]
    }                                          # strategy
)

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.

Limit Orders

Place a Limit Order

Example Code

const orderId = await client.createOrder(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', // userId
    123,                                    // accountId
    'ETH',                                  // baseSymbol
    'BTC',                                  // quoteSymbol
    new Decimal('0.01'),                    // quantity of baseSymbol
    new Decimal('0.026'),                   // price
    'SELL',                                 // side
    'IOC',                                  // timeInForce
);
place_limit_order_response = client.place_limit_order(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', # user_id
    123,                                    # account_id
    'ETH',                                  # base_symbol
    'BTC',                                  # quote_symbol
    '0.01',                                 # quantity of base_symbol
    '0.026',                                # price
    'SELL',                                 # side
    'IOC',                                  # time_in_force
)
limit_order_id = place_limit_order_response['id']

Request

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

Request Body

{
    "baseSymbol": "ETH",
    "quoteSymbol": "BTC",
    "quantity": "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)
quantity Decimal The quantity 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

Example Code

const order = await client.getOrder(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', // userId
    123,                                    // accountId
    '8c2a9401-eb5b-48eb-9ae2-e9e02c174058'  // orderId
);
order = client.get_limit_order_status(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', # user_id
    123,                                    # account_id
    '8c2a9401-eb5b-48eb-9ae2-e9e02c174058'  # order_id
)

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. For streaming completed limit orders, see the Websocket Orders Channel docs.

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

Example Code

const orders = await client.getOrders(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', // userId
    123                                     // accountId
);
orders = client.list_open_orders(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', # user_id
    123                                     # account_id
)

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

Example Code

const order = await client.cancelOrder(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', // userId
    123,                                    // accountId
    '8c2a9401-eb5b-48eb-9ae2-e9e02c174058'  // orderId
);
order = client.cancel_limit_order(
    '701e0d16-1e9e-42c9-b6a1-4cada1f395b8', # user_id
    123,                                    # account_id
    '8c2a9401-eb5b-48eb-9ae2-e9e02c174058'  # order_id
)

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

Websocket

The websocket feed provides access to real-time order book information across exchanges. Any websocket compliant client may be able to subscribe to the data vended from the websocket feed. Websocket channels require authentication via a Token from the REST API to be accessed. See the Get Token section for more information.

General Details

All websocket messages adhere to the following standards:

Connections are rate limited to the following restrictions:

Connecting

Example Connection Url

wss://ws-feed.shrimpy.io?token=3f823368132fb12f72de8f35a5834e691559c2ec22141facc175d8530a014f668e569cc5aeb1188b993acb1c2e0215d16fe51f8b91de2a003227476ef7fb9634

You must request a token before creating a websocket connection. See Get Token for information on requesting a token. A new token must be supplied each time you create a websocket connection. After connecting, you can subscribe and unsubcribe without sending a new token. The token is only used to create the connection.

Get Token

Request

GET https://dev-api.shrimpy.io/v1/ws/token

Response

{
  "token": "3f823368132fb12f72de8f35a5834e691559c2ec22141facc175d8530a014f668e569cc5aeb1188b993acb1c2e0215d16fe51f8b91de2a003227476ef7fb9634",
}

A new token is required for each connection to the websocket. Each token can only be used a single time and is only valid for 1 hour. The validity of the token is only checked when creating a connection, which means that the connection must be opened within 1 hour, but can stay open for longer than 1 hour.

Although this endpoint does not cost any data credits, you will receive an error if you do not have any available data credits.

Ping

Ping Message

{
     "type": "ping",
     "data": 1534667234
}

Client Response

{
     "type": "pong",
     "data": 1534667234
}

Every minute, the server will emit a ping message to connected clients. Clients are required to respond to this message with the data matching the data sent by the server. Sending any other data will not refresh the ping interval and will result in disconnection from the server.

Client connections are terminated if no valid ping is received for over 3 minutes.

Field Type Description
type string The type of the ping message. Possible values are "ping" or "pong"
data long A number of data type long.

Subscribing and Unsubscribing

Subscribe Example

{
    "type": "subscribe",
    "exchange": "coinbasepro",
    "pair": "ltc-btc",
    "channel": "bbo"
}

Unsubscribe Example

{
    "type": "unsubscribe",
    "exchange": "coinbasepro",
    "pair": "ltc-btc",
    "channel": "bbo"
}

The websocket feed supports two types of requests, namely subscribe and unsubscribe. Clients may subscribe to 100 individual channels, but may only subscribe a single time to each individual channel. For example, clients may subscribe to the order book for LTC-BTC and ETH-BTC for CoinbasePro, but may not subscribe to LTC-BTC twice for CoinbasePro.

Clients must subscribe to a channel to begin receiving updates. Once a client subscribes to a channel, the channel updates will immediately start being sent to the client.

Users must follow the format to the right to subscribe to order book data for an asset pair on an exchange.

Websocket Request

Field Type Description
type string The type of subscription request, possible values are "subscribe" or "unsubscribe"
exchange string The name of the exchange
pair string The shrimpy name for the asset pair from the Trading Pairs endpoint. Case insensitive. The pair should be formatted as {BASE}-{QUOTE}
channel string The name of the channel. Clients can subscribe to either the "bbo" (Best-Bid-Offer), "orderbook", "trade" or "orders" channels. Case insensitive.

Error Handling

Error Example

{
    "type": "error",
    "code": 2153,
    "message": "The maximum 100 connections per IP has been exceeded"
}

Errors will be returned if the client does not conform to the standards mentioned in this document. Errors can be identified by examining the "code" field of the response and referencing the different codes here.

Websocket Error

Field Type Description
type string The type of the websocket message, "error" in this case.
code integer An integer code that can be used to uniquely identify the error. See Websocket Error Codes for details.
message string A message string that provides detailed information about the error.

Websocket Error Codes

Error Code Description
2151 The websocket message request from the client contains invalid json.
2152 The websocket message request from the client does not conform to proper syntax.
2153 The IP address has exceeded the maximum connection count.
2154 No ping was received from the client and the connection will be closed.
2155 The client is already subscribed to this channel.
2156 The given message does not have a valid type.
2157 The given trading pair is invalid.
2158 The Pong data is invalid.
2159 The client does not surface IP information.
2160 The server did not receive a Ping.
2161 The server has rejected the connection due to an internal error
2162 The client has exceeded the maximum subscription count
2163 The client is missing a websocket token
2164 The client provided an invalid token

BBO Channel

BBO Subscription

{
    "type": "subscribe",
    "exchange": "coinbasepro",
    "pair": "ltc-btc",
    "channel": "bbo"
}

Update Format

{
    "exchange": "coinbasepro",
    "pair": "ltc-btc",
    "channel": "bbo",
    "sequence": 0,
    "content": {
        "asks": [
            {
                "price": "59.782355",
                "quantity": "3.456722"
            }
        ],
        "bids": [
            {
                "price": "58.782355",
                "quantity": "3.456722"
            }
        ]
    }
}

The BBO channel (Best-Bid-Offer) provides the best bid and ask prices for the given pair. Each update after the subscription will simply provide the best bid and ask prices along with their respective quantities. Updates are published every time the best bid or ask changes on the book.

Field Type Description
exchange string The name of the exchange
pair string The shrimpy name for the asset pair from the Trading Pairs endpoint. Case insensitive.
channel string The name of the channel, in this case "bbo". Case insensitive.
content Order Book Content The bid/ask data for the given pair and exchange.

Cost

6 Data Credit/subscription/hour. For Example, if you subscribe to 100 channels for 10 minutes, it will cost 100 data credits.

Order Book Channel

Order Book Subscription

{
    "type": "subscribe",
    "exchange": "coinbasepro",
    "pair": "ltc-btc",
    "channel": "orderbook"
}

Snapshot Format

{
    "exchange": "coinbasepro",
    "pair": "ltc-btc",
    "channel": "orderbook",
    "snapshot": true,
    "sequence": 6784322,
    "content": {
        "asks": [
            {
                "price": "59.782355",
                "quantity": "3.456722"
            },
            {
                "price": "60.782355",
                "quantity": "3.456722"
            },
            ...
        ],
        "bids": [
            {
                "price": "58.782355",
                "quantity": "3.456722"
            },
            {
                "price": "56.782355",
                "quantity": "3.456722"
            },
            ...
        ]
    }
}

Update Format

{
    "exchange": "coinbasepro",
    "pair": "ltc-btc",
    "channel": "orderbook",
    "snapshot": false,
    "content": {
        "sequence": 6784322,
        "asks": [
            {
                "price": "59.782355",
                "quantity": "3.456722"
            },
            {
                "price": "60.782355",
                "quantity": "3.456722"
            },
            ...
        ],
        "bids": [
            {
                "price": "58.782355",
                "quantity": "3.456722"
            },
            {
                "price": "56.782355",
                "quantity": "3.456722"
            },
            ...
        ]
    }
}

The order book channel provides the full order book for the given pair and exchange. Once subscribed, the first update will be the initial order book snapshot. The snapshot will be followed by order book updates. Updates includes the full list of bid/ask data. If the quantity of the price level for a bid or ask is 0, you must remove that price from your local order book.

Each update contains an incrementing sequence number with the exception of the initial order book snapshot. Each subsequent update increments the sequence number by 1. To ensure order book accuracy, updates must be applied in the increasing order of sequence number, starting with the sequence number of the snapshot. If a sequence number is missed, all updates and sequence numbers must be discarded and clients must attempt to re-connect to the server.

Field Type Description
exchange string The name of the exchange
pair string The shrimpy name for the asset pair from the Trading Pairs endpoint. Case insensitive.
channel string The name of the channel. In this case, "orderbook". Case insensitive.
content Order Book Content The full order book data for the given pair and exchange.

Cost

6 Data Credit/subscription/hour. For Example, if you subscribe to 100 channels for 10 minutes, it will cost 100 data credits.

Trade Channel

Trade Subscription

{
    "type": "subscribe",
    "exchange": "coinbasepro",
    "pair": "ltc-btc",
    "channel": "trade"
}

Update Format

{
    "exchange": "coinbasepro",
    "pair": "ltc-btc",
    "channel": "trade",
    "snapshot": false,
    "sequence": 0,
    "content": [
        {
            "id": 138368370,
            "price": "0.0130650000000000",
            "quantity": "2.0300000000000000",
            "time": "2019-05-31T20:25:14.000Z",
            "btcValue": 0.02652195,
            "usdValue": 224.16218805254,
            "takerSide": "buyer"
        },
        {
            "id": 138368371,
            "price": "0.0130650000000000",
            "quantity": "1.0000000000000000",
            "time": "2019-05-31T20:25:14.000Z",
            "btcValue": 0.013065,
            "usdValue": 110.42472317859,
            "takerSide": "seller"
        },
        ...
    ]
}

The Trade channel provides the executed trades the given pair. Each update after the subscription will simply provide the executed trade along with their respective quantities. Updates are published every time a trade is executed on the exchange for the given pair.

Field Type Description
exchange string The name of the exchange
pair string The shrimpy name for the asset pair from the Trading Pairs endpoint. Case insensitive.
channel string The name of the channel, in this case "trade". Case insensitive.
snapshot boolean Ignore. Always false.
sequence number Ignore. Always 0.
content Trade Content The trade data for the given pair and exchange.

Cost

6 Data Credit/subscription/hour. For Example, if you subscribe to 100 channels for 10 minutes, it will cost 100 data credits.

Orders Channel

Orders Subscription

{
    "type": "subscribe",
    "channel": "orders"
}

Update Format

{
    "channel": "orders",
    "content": [
        "3d9299c4-c20c-4112-9029-3eb62df64f95",
        "7f095bb8-a15d-47fc-a575-d352d0e8de6b",
        ...
    ]
}

The Orders channel provides a stream for users to get all limit orders across all exchanges that have been completed by Shrimpy in real-time. Updates are simple lists of order ids and are posted every time an order is completed by Shrimpy. The orders included in this stream are only the limit orders that have been placed via the Shrimpy developer platform. See Limit Orders for details on how to place a limit order.

Field Type Description
channel string The name of the channel, in this case "orders". Case insensitive.
content Orders Channel Content The list of completed order ids.

Cost

6 Data Credit/subscription/hour. For Example, if you subscribe to 100 channels for 10 minutes, it will cost 100 data credits.

Analytics

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

Get Backtest Assets

Example Code

const backtestAssets = await client.getBacktestAssets(
    'kucoin' // exchange
);
backtest_assets = client.get_backtest_assets(
    'kucoin' # exchange
)

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

Example Code

const backtestResults = await client.runBacktest(
    'binance',                                       // exchange
    10,                                              // rebalancePeriod in hours
    new Decimal(0.1),                                // fee in percent
    new Date("2018-05-19T00:00:00.000Z"),            // startTime
    new Date("2018-11-02T00:00:00.000Z"),            // endTime
    new Decimal(5000),                               // initialValue in USD
    [
        { symbol: "BTC", percent: new Decimal(50) },
        { symbol: "ETH", percent: new Decimal(50) }
    ]                                                // allocations
);
backtest_results = client.run_backtest(
    'binance',                                       # exchange
    10,                                              # rebalance_period in hours
    '0.1',                                           # fee in percent
    '2018-05-19T00:00:00.000Z',                      # start_time
    '2018-11-02T00:00:00.000Z',                      # end_time
    '5000',                                          # initial_value in USD
    [
        { 'symbol': "BTC", 'percent': '50' },
        { 'symbol': "ETH", 'percent': '50' }
    ]                                                # allocations
)

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

Insights

The Insights endpoints are used to retrieve aggregate information about Shrimpy user assets.

Get Asset Dominance

Example Code

const assetDominance = await client.getAssetDominance();
asset_dominance = client.get_asset_dominance()

Request

GET https://dev-api.shrimpy.io/v1/insights/asset_dominance

Response

[
  {
    "id": 1
    "change7d": "-0.06754437"
    "change24h": "0.05776859"
    "change30d": "-0.14742836"
    "percent": "1.09964191"
  },
  {
    "id": 2
    "change7d": "0.00091775"
    "change24h": "-0.00009564"
    "change30d": "-0.00521552"
    "percent": "0.002849"
  },
  ...
]

This endpoint retrieves aggregate information about asset percentage dominance of linked exchange accounts. The dominance is the average percent of asset across all portfolios. For example, if there are two users, one with 100% Bitcoin and one with 0% Bitcoin, the asset dominance for Bitcoin would be 50%. The sum of all asset dominance percentages will be 100%.

HTTP Request

GET https://dev-api.shrimpy.io/v1/insights/asset_dominance

Response

List of Asset Insight types.

Get Asset Popularity

Example Code

const assetPopularity = await client.getAssetPopularity();
asset_popularity = client.get_asset_popularity()

Request

GET https://dev-api.shrimpy.io/v1/insights/asset_popularity

Response

[
  {
    "id": 1,
    "change7d": "0.21649781",
    "change24h": "0.74325753",
    "change30d": "-2.35559691",
    "percent": "14.7008547"
  },
  {
    "id": 2,
    "change7d": "0.01835511",
    "change24h": "-0.00191276",
    "change30d": "-0.10431026",
    "percent": "0.05698006"
  },
  ...
]

This endpoint retrieves aggregate information about asset percentage popularity of linked exchange accounts. The popularity of an asset is calculated based on the percentage of portfolios that contain the asset. For example, if there are two users, one with 50% Bitcoin and one with 5% Bitcoin, the asset popularity for Bitcoin would be 100% because 100% of portfolios contain Bitcoin.

HTTP Request

GET https://dev-api.shrimpy.io/v1/insights/asset_popularity

Response

List of Asset Insight types.

Historical

The Historical Data endpoints are used to retrieve historical data such as order books and trades.

Historical endpoints are billed against your balance of Data credits. The Historical Order Book and Trade endpoints each cost a certain number of data credits, detailed in their individual section.

Developers can use the Historical Instruments endpoint free of charge for querying purposes.

Get Historical Candles

Example Code

const candles = await client.getHistoricalCandles(
    'bittrex',
    'LTC',
    'BTC',
    new Date('2019-09-01'),
    new Date('2019-09-02'),
    100,
    '15m'
);
candles = client.get_historical_candles(
    'Bittrex',
    'LTC',
    'BTC',
    '2019-05-19T00:00:00.000Z',
    '2019-05-20T00:00:00.000Z',
    100,
    '15m'
)

Request

GET https://dev-api.shrimpy.io/v1/historical/candles

Response

[
    {
        "open": "0.0000157100000000",
        "high": "0.0000157500000000",
        "low": "0.0000156900000000",
        "close": "0.0000157300000000",
        "volume": "1603.0000000000000000",
        "quoteVolume": 0.02520959,
        "time": "2019-05-25T00:00:00.000Z"
    },
    ...
]

This endpoint retrieves historical candlestick (ohlcv) data based on the exchange, start and end times, and currency pair passed in. Data is returned as lists of Historical-Candlestick objects as demonstrated in the examples.

HTTP Request

GET https://dev-api.shrimpy.io/v1/historical/candles

Query String Parameters

Parameter Type Description
exchange string The exchange for which to retrieve historical ohlcv data
baseTradingSymbol string The base trading symbol that is used by the exchange.
quoteTradingSymbol string The quote trading symbol that is used by the exchange.
startTime Date The starting time in ISO 8601
endTime Date The ending time in ISO 8601
limit number The amount of items to return. Must be an integer from 1 to 1000.
interval string The interval must be one of the following values: 1m, 5m, 15m, 1h, 6h, or 1d) These values correspond to intervals representing one minute, five minutes, fifteen minutes, one hour, six hours, and one day, respectively.

Response

List of Historical Candlestick types.

Cost

10 Data Credit/datapoint. For Example, if you query 100 data points from the API, it will cost 1000 data credits.

Get Historical Count

Example Code

const count = await client.getHistoricalCount(
    'trade',
    'binance',
    'BTC',
    'USDT',
    new Date('2019-05-01'),
    new Date('2019-05-02')
);
trades = client.get_historical_count(
    'trade',
    'binance',
    'BTC',
    'USDT',
    '2019-05-01T00:00:00.000Z',
    '2019-05-02T00:00:00.000Z'
)

Request

GET https://dev-api.shrimpy.io/v1/historical/count?type=trade&exchange=binance&quoteTradingSymbol=USDT&baseTradingSymbol=BTC&startTime=2019-05-01T00:00:00Z&endTime=2019-05-02T00:00:00Z

Response

{
  "count": 165012
}

This endpoint retrieves that number of datapoints available based on the type, exchange, start and end times, and currency pair passed in.

HTTP Request

GET https://dev-api.shrimpy.io/v1/historical/count

Query String Parameters

Parameter Type Description
type string Etiher trade or orderbook.
exchange string The exchange for which to retrieve historical trade data
baseTradingSymbol string The base trading symbol that is used by the exchange.
quoteTradingSymbol string The quote trading symbol that is used by the exchange.
startTime Date The starting time in ISO 8601. This time must be rounded to the nearest hour (i.e. minutes and seconds must be 0)
endTime Date The ending time in ISO 8601. This time must be rounded to the nearest hour (i.e. minutes and seconds must be 0)

Response

Field Type Description
count integer The number of datapoints available based on the supplied information. Note that order books, this will be correspond to the number of order book snapshots, not the number of individual orders.

Get Historical Instruments

Example Code

const instruments = await client.getHistoricalInstruments();
const bittrexInstruments = await client.getHistoricalInstruments('Bittrex');
instruments = client.get_historical_instruments()
bittrex_instruments = client.get_historical_instruments('Bittrex')

Request

GET https://dev-api.shrimpy.io/v1/historical/instruments?exchange=Bittrex

Response

[
    {
        "exchange":"bittrex",
        "baseTradingSymbol":"LTC",
        "quoteTradingSymbol":"BTC",
        "orderBookStartTime":"2016-09-14T13:00:00.000Z",
        "orderBookEndTime":"2019-09-07T23:00:00.000Z",
        "tradeStartTime":"2016-09-12T23:00:00.000Z",
        "tradeEndTime":"2019-09-09T16:00:00.000Z"
    }
    ...
    {
        "exchange":"kucoin",
        "baseTradingSymbol":"LTC",
        "quoteTradingSymbol":"BTC",
        "orderBookStartTime":"2019-04-09T11:00:00.000Z",
        "orderBookEndTime":"2019-08-31T23:00:00.000Z",
        "tradeStartTime":"2019-04-09T10:00:00.000Z",
        "tradeEndTime":"2019-09-03T23:00:00.000Z"
    }
]

This endpoint retrieves the supported historical instruments on the Developer API and their available historical order book and trade data ranges.

HTTP Request

GET https://dev-api.shrimpy.io/v1/historical/instruments

Query String Parameters

Parameter Type Description
exchange (optional) string If provided, only trading pairs that are available on exchange will be returned
baseTradingSymbol (optional) string If provided, only trading pairs with a matching base trading symbol will be returned
quoteTradingSymbol (optional) string If provided, only trading pairs with a matching quote trading symbol will be returned

Response

List of Historical Instrument types.

Get Historical Orderbooks

Example Code

const historicalOrderbooks = await client.getHistoricalOrderbooks(
    'bittrex',
    'LTC',
    'BTC',
    new Date('2019-09-01'),
    new Date('2019-09-02'),
    100
);
historical_orderbooks = client.get_historical_orderbooks(
    'Bittrex',
    'LTC',
    'BTC',
    '2019-05-19T00:00:00.000Z',
    '2019-05-20T00:00:00.000Z',
    100
)

Request

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

Response

[
    {
        "time": "2019-05-19T00:03:02.000Z",
        "asks": [
            {
                "price": 564.002,
                "size": 2354346
            },
            ...
            {
                "price": 564.002,
                "size": 2354346
            }
        ],
        "bids": [
            {
                "price": 564.002,
                "size": 2354346
            },
            ...
            {
                "price": 564.002,
                "size": 2354346
            }
        ]
    },
    {
        "time": "2019-05-19T00:05:02.000Z",
        "asks": [
            {
                "price": 564.002,
                "size": 2354346
            },
            ...
            {
                "price": 564.002,
                "size": 2354346
            }
        ],
        "bids": [
            {
                "price": 564.002,
                "size": 2354346
            },
            ...
            {
                "price": 564.002,
                "size": 2354346
            }
        ]
    },
    ...
    {
        "time": "2019-05-19T00:07:02.000Z",
        "asks": [
            {
                "price": 564.002,
                "size": 2354346
            },
            ...
            {
                "price": 564.002,
                "size": 2354346
            }
        ],
        "bids": [
            {
                "price": 564.002,
                "size": 2354346
            },
            ...
            {
                "price": 564.002,
                "size": 2354346
            }
        ]
    },
]

This endpoint retrieves historical orderbooks based on the exchange, start and end times, and currency pair passed in. Data is returned as lists of Historical Order Books objects as demonstrated in the examples. Historical Order Book Snapshots are taken roughly every minute.

HTTP Request

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

Query String Parameters

Parameter Type Description
exchange string The exchange for which to retrieve historical depth data
baseTradingSymbol string The base trading symbol that is used by the exchange.
quoteTradingSymbol string The quote trading symbol that is used by the exchange.
startTime Date The starting time in ISO 8601
endTime Date The ending time in ISO 8601
limit number The amount of items to return. Must be an integer from 1 to 1000.

Response

List of Historical Order Book types.

Cost

10 Data Credits/datapoint. For Example, if you query 100 data points from the API, it will cost 1000 data credits.

Get Historical Trades

Example Code

const trades = await client.getHistoricalTrades(
    'bittrex',
    'LTC',
    'BTC',
    new Date('2019-09-01'),
    new Date('2019-09-02'),
    100
);
trades = client.get_historical_trades(
    'Bittrex',
    'LTC',
    'BTC',
    '2019-05-19T00:00:00.000Z',
    '2019-05-20T00:00:00.000Z',
    100
)

Request

GET https://dev-api.shrimpy.io/v1/historical/trades

Response

[
    {
        "time": "2016-09-06T13:01:34.000Z",
        "size": "1891.1316431",
        "price": "0.00002585",
        "takerSide": "buyer"
    },
    {
        "time": "2016-09-06T13:01:35.000Z",
        "size": "35200",
        "price": "0.00002594",
        "takerSide": "buyer"
    },
    ...
    {
        "time": "2016-09-06T13:01:36.000Z",
        "size": "6000",
        "price": "0.00002596",
        "takerSide": "seller"
    }
]

This endpoint retrieves historical trades based on the exchange, start and end times, and currency pair passed in. Data is returned as lists of Historical-Trade objects as demonstrated in the examples.

HTTP Request

GET https://dev-api.shrimpy.io/v1/historical/trades

Query String Parameters

Parameter Type Description
exchange string The exchange for which to retrieve historical trade data
baseTradingSymbol string The base trading symbol that is used by the exchange.
quoteTradingSymbol string The quote trading symbol that is used by the exchange.
startTime Date The starting time in ISO 8601
endTime Date The ending time in ISO 8601
limit number The amount of items to return. Must be an integer from 1 to 10000.

Response

List of Historical Trade types.

Cost

1 Data Credit/datapoint. For Example, if you query 100 data points from the API, it will cost 100 data credits. Note that this is different than the pricing for the order book data points.

Management

The API Management endpoints can be used to query information related to your API usage and API status.

Get API Management Status

Example Code

const status = await client.getStatus();
status = client.get_status()

Request

GET https://dev-api.shrimpy.io/v1/management/status

Response

{
    "apiKeyAccepted":true,
    "apiNonceAccepted":true,
    "apiSignatureAccepted":true,
    "ipAccepted":true,
    "requestsRemaining":999
}

This endpoint returns API status information. This endpoint is helpful for providing information to debug sending requests to Shrimpy.

HTTP Request

GET https://dev-api.shrimpy.io/v1/management/status

Response

Field Type Description
apiKeyAccepted boolean True if the API Key is valid and accepted by Shrimpy. False otherwise.
apiNonceAccepted boolean True if the API Nonce is valid and accepted by Shrimpy. False otherwise.
apiSignatureAccepted boolean True if the API signature is valid and accepted by Shrimpy. False otherwise.
ipAccepted boolean True if the IP the request is sent from is within the whitelist for this request. False otherwise.
requestsRemaining integer The amount of requests remaining for use in the current minute

Get API Management Usage

Example Code

const usage = await client.getUsage();
usage = client.get_usage()

Request

GET https://dev-api.shrimpy.io/v1/management/usage

Response

{
    "usedUserCredits":0,
    "maxUserCredits":100,
    "usedDataCredits":16100,
    "maxDataCredits":1000000
}

This endpoint returns API usage information related to your subscription. See Pricing for more details on credits.

HTTP Request

GET https://dev-api.shrimpy.io/v1/management/usage

Response

Field Type Description
usedUserCredits integer The amount of user credits used from your subscription for the current billing period
maxUserCredits integer The total amount of user credits available in your subscription
usedDataCredits integer The amount of data credits used from your subscription for the current billing period
maxDataCredits integer The total amount of data credits available in your subscription

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)

Asset Insight

Example 1

{
    "id": 1,
    "percent": "14.7008547"
    "change24h": "0.74325753",
    "change7d": "0.21649781",
    "change30d": "-2.35559691"
}

Example 2

{
    "id": 833,
    "percent": "0",
    "change24h": "0",
    "change7d": "-0.03894081",
    "change30d": null
}

An Asset Insight contains information about a particular asset. The meaning of the information will vary based on the endpoint that was called. In all cases, the percent change is an absolute change. For example, if an asset's percentage goes from 5% to 15% in 24 hours, the change24h will be 10%.

Asset Insight Fields

Field Type Description
id integer A cross-exchange unique identifier for the asset. See Get Exchange Assets for more information.
percent Decimal The current percentage value for this insight.
change24h Decimal or null The percent change for this insight over the last 24 hours.
change7d Decimal or null The percent change for this insight over the last 7 days.
change30d Decimal or null The percent change for this insight over the last 30 days.

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.

Candlestick

Example

{
    "open": "0.0000157100000000",
    "high": "0.0000157500000000",
    "low": "0.0000156900000000",
    "close": "0.0000157300000000",
    "volume": "1603.0000000000000000",
    "quoteVolume": 0.02520959,
    "btcVolume": 0.02520959,
    "usdVolume": 201.98615317277,
    "time": "2019-05-25T00:00:00.000Z"
}

A candlestick object contains information about trades that executed over a particular time frame. This information can be useful when illustrating movements in price over time.

Candlestick Fields

Field Type Description
open Decimal The price of the first trade in the time frame
high Decimal The highest price of any trade in the time frame
low Decimal The lowest price of any trade in the time frame
close Decimal The price of the last trade in the time frame
volume Decimal The total amount of baseAsset traded in the time frame. (e.g. XLM for a XLM-BTC pair)
quoteVolume number The total volume in quoteAsset traded in the time frame.
btcVolume number The total volume in Bitcoin traded in the time frame. This volume is estimated using exchange rates available on the exchange at the time of each trade.
usdVolume number The total volume in United States Dollars traded in the time frame. This volume is estimated using exchange rates available on the exchange at the time of each trade.
time Date The start time of the time frame, in UTC. The duration of the time frame will depend on the interval associated with the candlestick.

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,
    "isSquareRootWeight": false
}

Example 2

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

Example 3

{
    "isDynamic": true,
    "excludedSymbols": [],
    "topAssetCount": 20,
    "minPercent": "3",
    "maxPercent": "100",
    "isEqualWeight": false,
    "isSquareRootWeight": 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 to assign equal percentages to each asset in the dynamic strategy
isSquareRootWeight boolean Whether or not to assign percentages based on the square root of the market cap of each asset in the dynamic strategy. isEqualWeight and isSquareRootWeight cannot both be true.

The weighting of the dynamic strategy can is determined by the isEqualWeight and isSquareRootWeight fields according to the table below.

isEqualWeight = false isEqualWeight = true
isSquareRootWeight = false Market Cap Weight Equal Weights
isSquareRootWeight = true Square Root Market Cap Weight N/A. Invalid

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 Asset

Example 1

{
    "id":38,
    "name":"Bitcoin",
    "symbol":"BTC",
    "tradingSymbol":"BTC"
}

Example 2

{
    "id":356,
    "name":"Stellar",
    "symbol":"XLM",
    "tradingSymbol":"STR"
}

An exchange asset represents a single asset on a particular exchange.

Exchange Asset Fields

Field Type Description
id integer A cross-exchange unique identifier for the asset that is generated by Shrimpy.
name string A human-readable name for the asset. This name may change if the asset is rebranded.
symbol string The commonly used symbol for the asset. E.g. XLM for Stellar or BTC for Bitcoin.
tradingSymbol string The symbol for the asset that is used on the associated exchange. The tradingSymbol will usually match the symbol, but not always. E.g. STR for Stellar on Poloniex or XBT for Bitcoin on Kraken.

Exchange Info

Example

{
    "exchange": "coinbasepro",
    "bestCaseFee": 0,
    "worstCaseFee": 0.003,
    "icon": "https://assets.shrimpy.io/exchanges/coinbasepro.png"
}

The exchange info type contains basic information about a particular exchange.

Exchange Info Fields

Field Type Description
exchange string A unique identifier for the exchange. This is typically the lowercase name of the exchange without spaces.
bestCaseFee number The lowest possible fee on the exchange. Fees are typically lower based on your trading volume, if you are using an exchange-specific discount token, and if you are the maker. A negative fee means you receive a rebate. All fee values are scalar values associated with percentages. For example, 0.001 means "0.1%".
worstCaseFee number The highest possible fee on the exchange. All fee values are scalar values associated with percentages. For example, 0.001 means "0.1%".
icon string A url for a 32x32px icon associated with the exchange.

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.

Historical Candlestick

Example

{
    "open": "0.0000157100000000",
    "high": "0.0000157500000000",
    "low": "0.0000156900000000",
    "close": "0.0000157300000000",
    "volume": "1603.0000000000000000",
    "quoteVolume": 0.02520959,
    "time": "2019-05-25T00:00:00.000Z"
}

A candlestick object contains information about trades that executed over a particular time frame. This information can be useful when illustrating movements in price over time.

Historical Candlestick Fields

Field Type Description
open Decimal The price of the first trade in the time frame
high Decimal The highest price of any trade in the time frame
low Decimal The lowest price of any trade in the time frame
close Decimal The price of the last trade in the time frame
volume Decimal The total amount of baseAsset traded in the time frame. (e.g. XLM for a XLM-BTC pair)
quoteVolume number The total volume in quoteAsset traded in the time frame.
time Date The start time of the time frame, in UTC. The duration of the time frame will depend on the interval associated with the candlestick.

Historical Instrument

Example

{
    "exchange":"bittrex",
    "baseTradingSymbol":"LTC",
    "quoteTradingSymbol":"BTC",
    "orderBookStartTime":"2019-04-09T11:00:00.000Z",
    "orderBookEndTime":"2019-08-31T23:00:00.000Z",
    "tradeStartTime":"2019-04-09T10:00:00.000Z",
    "tradeEndTime":"2019-09-03T23:00:00.000Z"
}

The historical instrument object contains information related to the available date ranges for order book and trade historical data.

Historical Instrument Fields

Parameter Type Description
exchange string The name of the exchange that contains the trading pair
baseTradingSymbol string The base trading symbol of the trading pair
quoteTradingSymbol string The quote trading symbol of the trading pair
orderBookStartTime Date The start time of first datapoint for this instrument
orderBookEndTime Date The end time of last datapoint for this instrument
tradeStartTime Date The start time of first datapoint for this instrument
tradeEndTime Date The end time of last datapoint for this instrument

Historical Trade

Example

{
    "time": "2016-09-06T13:01:35.000Z",
    "size": "35200",
    "price": "0.00002594",
    "takerSide": "buyer"
}

The historical trade object contains trade information such as price and size for a historical datapoint. See Get Historical Trades for more details.

Historical Trade Fields

Field Type Description
time Date The time the trade was recorded
size Decimal The size of the trade order
price Decimal The price of the trade order
takerSide string Can be either 'buyer', 'seller' or 'unknown'.

Historical Order Book

Example

{
    "time": "",
    "asks": [
        {
            "price": 564.002,
            "size": 2.354346
        },
        ...
        {
            "price": 564.002,
            "size": 15.4322
        }
    ],
    "bids": [
        {
            "price": 564.002,
            "size": 23543.46
        },
        ...
        {
            "price": 564.002,
            "size": 23.54346
        }
    ]
}

The historical order book object is a snapshot of the order book at a specific point in time.

Historical Order Book Fields

Field Type Description
time Date The id of the limit order
asks Historical Order Book Item[] The best asks for the market. (ascending order)
bids Historical Order Book Item[] The best bids for the market. (descending order)

Historical Order Book Item

Example

{
    "price": 564.002,
    "size": 23.54346
}

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

Field Type Description
price Decimal The price of the order
size Decimal The size of the order (in base_symbol units)

Limit Order

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": []
}

The order type contains information about a particular order operation.

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 Content

Example

{
    "sequence": 6784322,
    "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 data type is used exclusively by the websocket api. The order book content contains a sequence number and the bid/ask data for the given pair and exchange. BBO will only include a single bid and ask in the bids/asks arrays. The sequence number is also irrelevant for bbo data and is always set to 0.

Field Type Description
sequence long The sequence number of the update. This is not relevant for BBO data and will always be 0.
asks OrderbookItem[] List of OrderbookItem objects representing asks.
bids OrderbookItem[] List of OrderbookItem objects representing bids.

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)

Orders Channel Content

Example

{
    "content": [
        "58dfd018-b219-4354-9f54-de8ec4ad5cbc",
        "e40e4ec0-a869-4e92-bd02-1199ff971e6a",
        ...
    ]
}

The orders channel content is a list of order ids for orders that have been completed by Shrimpy. Each order id is a string.

Order Channel Content Fields

Field Type Description
content UUID[] The order id of an order completed by Shrimpy

Public Trade

Example

{
    "id": 138368371,
    "price": "0.0130650000000000",
    "quantity": "1.0000000000000000",
    "time": "2019-05-31T20:25:14.000Z",
    "btcValue": 0.013065,
    "usdValue": 110.42472317859,
    "takerSide": "buyer"
}

Public Trade Fields

Field Type Description
id number The id of the trade. This is unique across all exchanges
price Decimal The execute price of the trade
quantity Decimal The quantity of the executed trade
time Date The time of the trade
btcValue number The value of the trade in Bitcoin at the time of execution
usdValue number The value of the trade in United States Dollars at the time of execution
takerSide string The side of the trade from the taker's point of view. Either "buyer", "seller" or "unknown".

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

Example

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

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.

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

Total Balance History Item

Example

{
    "date": "2018-05-04T23:13:36.000Z",
    "usdValue": 5450.848215924849,
    "btcValue": 0.5591789264332345
}

The total balance history item contains information about the total value of a single exchange account at a particular point in time.

Total Balance History Item Fields

Field Type Description
date Date The time the total balance history item was collected
usdValue number The total usd value of the account at date.
btcValue number The total btc value of the account at date.

Trade

Example

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

The trade type contains information about a particular trade operation.

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.
smartRouting boolean Whether or not smart routing was enabled for this trade. Smart routing means the trade will use whichever pairs give the best rate, not just the direct pair or BTC pairs.
maxSpreadPercent Decimal The maximum allowed spread when trading to and from the assets. The trade will be aborted if the spread crosses this threshold.
maxSlippagePercent Decimal The maximum allowed slippage when trading to and from the assets. The trade will be aborted if the price decreases by more than this percentage during the trade.
triggeredMaxSpread boolean Whether or not the maximum spread threshold was reached.
triggeredMaxSlippage boolean Whether or not the maximum slippage threshold was reached.

Trade Content

Example

{
    "trades": [
        {
            "id": 138368370,
            "price": "0.0130650000000000",
            "quantity": "2.0300000000000000",
            "time": "2019-05-31T20:25:14.000Z",
            "btcValue": 0.02652195,
            "usdValue": 224.16218805254,
            "takerSide": "buyer"
        },
        {
            "id": 138368371,
            "price": "0.0130650000000000",
            "quantity": "1.0000000000000000",
            "time": "2019-05-31T20:25:14.000Z",
            "btcValue": 0.013065,
            "usdValue": 110.42472317859,
            "takerSide": "seller"
        },
        ...
    ]
}

A trade content object contains a list of trades that were executed recently.

Trade Content Fields

Field Type Description
trades Public Trade[] The list of trades that were executed recently.

Trade Fill

Example

{
    "baseAmount": "20",
    "baseSymbol": "KCS",
    "quoteAmount": "0.0028134",
    "quoteSymbol": "BTC",
    "price": "0.00014067",
    "side": "SELL",
    "btcValue": 0.0028169,
    "usdValue": 20.05604616757
}    

A trade fill object represents a single order that was executed on the exchange.

Trade Fill Fields

Field Type Description
baseAmount Decimal The amount of the base asset that was traded, in units of baseSymbol.
baseSymbol string The symbol of the baseSymbol on the exchange.
quoteAmount Decimal The amount of the quote asset that was traded, in units of quoteSymbol.
quoteSymbol string The symbol of the quoteSymbol on the exchange.
price Decimal The price at which the trade was fill, in units of quoteSymbol.
side string Either BUY or SELL, indicating the direciton of the order on the exchange. BUY means baseSymbol was exchanged for quoteSymbol, while SELL means quoteSymbol was exchanged for baseSymbol.
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.

Trading Pair

Example 1

{
    "baseTradingSymbol": "XLM",
    "quoteTradingSymbol": "BTC"
}

Example 2

{
    "baseTradingSymbol": "STR",
    "quoteTradingSymbol": "BTC"
}

Example 3

{
    "baseTradingSymbol": "LTC",
    "quoteTradingSymbol": "XBT"
}

The trading pair type represents a single trading pair on an exchange. Both symbols will match the symbol used by the exchange.

Trading Pair Fields

Field Type Description
baseTradingSymbol string The base symbol for this trading pair used by the exchange.
quoteTradingSymbol string The quote symbol for this trading pair used by the exchange.

User

Example

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

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.

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"