NAV Navbar

Introduction

Welcome to the Shrimpy API documentation. This API is for the management and automation of your personal Shrimpy account. If you are developing an application and would like to integrate trading capabilities, please use the Shrimpy Developer API.

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

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 private endpoints must be signed using the described authentication scheme. See Creating a Request

Creating a Request

Example Request Headers

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

All requests must contain the following headers:

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

Signing a Request

NodeJS Example of Signing a Request

var crypto = require('crypto');

var secret = '6991cf4c9b51...';

var nonce = Date.now();
var pathname = "/v1/accounts/123/portfolios/create";

var body = JSON.stringify({
    name: 'My Portfolio',
    rebalancePeriod: 24,
    strategy: {
        isDynamic: false,
        allocations: [
            {
                symbol: "BTC",
                percent: "50"
            },
            {
                symbol: "ETH",
                percent: "50"
            }
        ]
    }
});

var method = "POST";

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

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

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

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

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

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

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

Public

Get Ticker

Request

GET https://api.shrimpy.io/v1/<exchange>/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://api.shrimpy.io/v1/<exchange>/ticker

URL Parameters

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

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

Accounts

List Accounts

Request

GET https://api.shrimpy.io/v1/accounts

Response

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

This endpoint retrieves all linked exchange accounts. See the Account type for more information.

HTTP Request

GET https://api.shrimpy.io/v1/accounts

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.

Get an Account

Request

GET https://api.shrimpy.io/v1/accounts/<exchangeAccountId>

Response

{
    "id": true,
    "exchange": "Kucoin",
    "isRebalancing": true,
}

This endpoint returns the current status of a linked exchange account. See the Account type for more information.

HTTP Request

GET https://api.shrimpy.io/v1/accounts/<exchangeAccountId>

URL Parameters

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

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.

Get Balance

Request

GET https://api.shrimpy.io/v1/accounts/<exchangeAccountId>/balance

Response

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

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

HTTP Request

GET https://api.shrimpy.io/v1/accounts/<exchangeAccountId>/balance

URL Parameters

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

Response

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

Rebalancing an Account

Request

POST https://api.shrimpy.io/v1/accounts/<exchangeAccountId>/rebalance

Response:

{
    "success": true
}

This endpoint queues a rebalance for the specified exchange account. It is equivalent to pressing the "Rebalance Now" button on the dashboard. See Creating a Portfolio and Activating a Portfolio for more information.

HTTP Request

POST https://api.shrimpy.io/v1/accounts/<exchangeAccountId>/rebalance

URL Parameters

Parameter Type Description
exchangeAccountId integer The exchange account id of the account to be rebalanced.

Portfolios

Get All Portfolios

Request

GET https://api.shrimpy.io/v1/accounts/<exchangeAccountId>/portfolios

Response

[
    {
        "id": 123,
        "name": "Bitcoin and Ethereum",
        "rebalancePeriod": 24,
        "active": true,
        "strategy": {
            "isDynamic": false,
            "allocations": [
                {
                    "symbol": "BTC",
                    "percent": "50"
                },
                {
                    "symbol": "ETH",
                    "percent": "50"
                }
            ]
        },
        "strategyTrigger": "interval",
        "rebalanceThreshold": "0",
        "maxSpread": "10",
        "maxSlippage": "10"
    },
    {
        "id": 456,
        "name": "Tether",
        "rebalancePeriod": 24,
        "active": false,
        "strategy": {
            "isDynamic": false,
            "allocations": [
                {
                    "symbol": "USDT",
                    "percent": "100"
                }
            ]
        },
        "strategyTrigger": "interval",
        "rebalanceThreshold": "0",
        "maxSpread": "10",
        "maxSlippage": "10"
    }
]

This endpoint retrieves all saved portfolios for an exchange account. See the Portfolio type for more information.

HTTP Request

GET https://api.shrimpy.io/v1/accounts/<exchangeAccountId>/portfolios

URL Parameters

Parameter Type Description
exchangeAccountId integer The exchange account id of the account to be rebalanced.

Creating a Portfolio

Request

POST https://api.shrimpy.io/v1/accounts/<exchangeAccountId>/portfolios/create

Request Body

{
    "name": "Bitcoin and Ethereum",
    "rebalancePeriod": 24,
    "strategy": {
        "isDynamic": false,
        "allocations": [
            {
                "symbol": "BTC",
                "percent": "50"
            },
            {
                "symbol": "ETH",
                "percent": "50"
            }
        ]
    },
    "strategyTrigger": "interval",
    "rebalanceThreshold": "0",
    "maxSpread": "10",
    "maxSlippage": "10"
}

Response

{
    "portfolioId": 12345
}

This endpoint creates a new portfolio for an exchange account.

HTTP Request

POST https://api.shrimpy.io/v1/accounts/<exchangeAccountId>/portfolios/create

URL Parameters

Parameter Type Description
exchangeAccountId integer The exchange account id of the account that should have the newly created portfolio

Body Parameters

Parameter Type Description
name string The name of the portfolio
rebalancePeriod integer The rebalance period in hours, or 0 to never automatically rebalance. Note that this must be 0 if strategyTrigger is "threshold".
strategy Strategy The portfolio strategy
strategyTrigger string The trigger type of the portfolio. Either "interval" or "threshold". threshold means that the rebalanceThreshold will be used and the rebalancePeriod will be ignored. interval means that the rebalancePeriod will be used and the rebalanceThreshold will be ignored.
rebalanceThreshold Decimal The percent deviation at which a rebalance operation will be triggered. See Threshold Based Rebalancing for more information.
maxSpread Decimal The maximum allowed spread when trading. If a pair has a spread larger than this threshold, it will stop being traded.
maxSlippage Decimal The maximum allowed slippage when trading. If a pair has its price decrease by more than this percentage, it will stop being traded.

Update a Portfolio

Request

POST https://api.shrimpy.io/v1/accounts/<exchangeAccountId>/portfolios/<portfolioId>/update

Request Body

{
    "name": "Bitcoin and Ethereum",
    "rebalancePeriod": 24,
    "strategy": {
        "isDynamic": false,
        "allocations": [
            {
                "symbol": "BTC",
                "percent": "50"
            },
            {
                "symbol": "ETH",
                "percent": "50"
            }
        ]
    },
    "strategyTrigger": "interval",
    "rebalanceThreshold": "0",
    "maxSpread": "10",
    "maxSlippage": "10"
}

Response

{
    "success": true
}

This endpoint updates an existing portfolio.

HTTP Request

POST https://api.shrimpy.io/v1/accounts/<exchangeAccountId>/portfolios/<portfolioId>/update

URL Parameters

Parameter Type Description
exchangeAccountId integer The exchange account id of the account that has the portfolio to be updated
portfolioId integer The portfolio id to be updated

Body Parameters

Parameter Type Description
name string The name of the portfolio
rebalancePeriod integer The rebalance period in hours, or 0 to never automatically rebalance. Note that this must be 0 if strategyTrigger is "threshold".
strategy Strategy The portfolio strategy
strategyTrigger string The trigger type of the portfolio. Either "interval" or "threshold". threshold means that the rebalanceThreshold will be used and the rebalancePeriod will be ignored. interval means that the rebalancePeriod will be used and the rebalanceThreshold will be ignored.
rebalanceThreshold Decimal The percent deviation at which a rebalance operation will be triggered. See Threshold Based Rebalancing for more information.
maxSpread Decimal The maximum allowed spread when trading. If a pair has a spread larger than this threshold, it will stop being traded.
maxSlippage Decimal The maximum allowed slippage when trading. If a pair has its price decrease by more than this percentage, it will stop being traded.

Activating a Portfolio

Request

POST https://api.shrimpy.io/v1/accounts/<exchangeAccountId>/portfolios/<portfolioId>/activate

Response

{
    "success": true
}

This endpoint activates an existing portfolio. All rebalance operations use the currently active portfolio. There must always be one active portfolio per account. Activating one portfolio will deactivate any other active portfolio for that account.

HTTP Request

POST https://api.shrimpy.io/v1/accounts/<exchangeAccountId>/portfolios/<portfolioId>/activate

URL Parameters

Parameter Type Description
exchangeAccountId integer The exchange account id of the account that has the portfolio to be activated
portfolioId integer The portfolio id to be activated

Types

Account

Example

{
    "id": 123,
    "exchange": "Kucoin",
    "isRebalancing": true,
}

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.

Allocation

Example

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

An allocation specifies an exchange asset and a percentage. It is a component of the 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)

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.

Date

Dates are returned as strings in ISO format (ISO 8601). For example: "2018-12-19T22:51:13.000Z"

Decimal

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 portfolio id and rebalancePeriod) are unquoted.

Dynamic Strategy

Example1

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

Example2

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

Example3

{
    "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

Portfolio

Example

{
    "id": 123,
    "active": false,
    "name": "Bitcoin and Ethereum",
    "rebalancePeriod": 24,
    "strategy": {
        "isDynamic": false,
        "allocations": [
            {
                "symbol": "BTC",
                "percent": "50"
            },
            {
                "symbol": "ETH",
                "percent": "50"
            }
        ]
    },
    "strategyTrigger": "interval",
    "rebalanceThreshold": "0",
    "maxSpread": "10",
    "maxSlippage": "10"
}

A portfolio is made up of a Strategy, a rebalance period, and a name. Each account can only have one active account at time. See Activating a Portfolio for more information.

Portfolio Fields

Field Type Description
id integer The unique identifier of the portfolio
name string The name of the portfolio
rebalancePeriod integer The rebalance period in hours, or 0 to stop rebalancing on a regular interval.
active boolean True if this portfolio is the currently active portfolio for the account
strategy Strategy The portfolio's strategy
strategyTrigger string The trigger type of the portfolio. Either "interval" or "threshold". threshold means that the rebalanceThreshold will be used and the rebalancePeriod will be ignored. interval means that the rebalancePeriod will be used and the rebalanceThreshold will be ignored.
rebalanceThreshold Decimal The percent deviation at which a rebalance operation will be triggered. See Threshold Based Rebalancing for more information.
maxSpread Decimal The maximum allowed spread when trading. If a pair has a spread larger than this threshold, it will stop being traded.
maxSlippage Decimal The maximum allowed slippage when trading. If a pair has its price decrease by more than this percentage, it will stop being traded.

Static Strategy

Example

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

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

Static Strategy Fields

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

Strategy

Examples: See Static Strategy or Dynamic Strategy

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

Strategy Fields

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

Ticker

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

Example

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

Ticker Fields

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