Navbar
shell

Introduction

bitsian is a trading platform to help make advanced crypto traders more profitable by saving you time and giving you control, putting all of your crypto exchanges in one place for trade execution and position management.

bitsian provides REST API and websocket to check balance, trade and get market data of various exchanges.

Development Guide

Base URL

The base url for rest endpoints is https://api.bitsian.io/api
Websocket base url is wss://api.bitsian.io/bitsian-feed

CORS

bitsian API supports cross-origin HTTP requests which is commonly referred as CORS. This means that you can call API resources using Javascript from any browser.

Pagination

By default, 20 results are returned initially for some GET requests. To paginate through data, following parameters are used.

PARAMETERS

Parameter Default Description
page 1 Page needed
pageSize 20 Number of results per request

Authentication

Getting key

Once you have an account, you can raise a request for API entitlement to use services of bitsian using API Keys. After admin's approval, you can create keys and do API operations with us. You can create multiple API keys with different scope for your application, but API keys with same scopes are not allowed.

Creating request

All REST requests must contain the following headers:

Signing message

The BITSIAN-API-SIGN header is generated by creating a sha256 HMAC using the secret key on the prehash_string.

prehash_string = timestamp + method + requestPath + body (where + represents string concatenation)

NOTE:

Request Rate Limit

The access limit for REST API is applied per user (User may have multiple API keys, Sum of requests from all API keys is applied for rate limits). The request rate limit for each user is 10 requests per 10 seconds ((i.e) average of 1 request per second ). User API access is suspended according to number of violations made. For first 2 violations, suspension is done for 10 seconds. For next 2 violations, suspension is done for 24 hours. For any violation more than that,the user's API keys are made inactive.

Bad Request

Any request with invalid headers and parameters are considered bad request. Initial 2 bad requests are only permitted. Next 2 bad requests will result in API key access suspension for 24 hours. For any bad requests more, API key is made inactive.

Error Codes

HTTP error status codes

Error Code Meaning
400 Bad Request -- Invalid request format.
401 Unauthorized -- Invalid API key.
403 Forbidden -- The request is forbidden.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access resource with an invalid method.
415 Unsupported Media Type -- You need to use: application/json..
429 Too Many Requests -- Access limit breached.
500 Internal Server Error -- We had a problem with our server. Try again later.

System error codes

Error code Message
4001 Authorization failed. Headers missing
4002 Invalid passphrase
4003 Invalid signature
4004 Gateway Timeout. Timestamp differs from the server time by more than 15 seconds.
4005 Action is forbidden for this Ip
4006 Action is forbidden for this API key
4007 API limit exceeded
4008 Expected parameters missing
10xx Errors occurred on processing of request (ex: Validation error)

REST

Market data

Exchanges

curl -X GET "https://api.bitsian.io/exchange"
  -H "BITSIAN-API-KEY: your_api_key"
  -H "BITSIAN-API-SIGN: signaure"
  -H "BITSIAN-API-TIMESTAMP: timestamp_in_milliseconds"
  -H "BITSIAN-API-PASSPHRASE: your_passphrase"

Response

{
    "data": [
        {
            "exchangeId": 1,
            "exchangeName": "BINANCE",
            "websiteLink": "www.binance.com",
            "countryOfOrigin": "Malta"
        },
        {
            "exchangeId": 2,
            "exchangeName": "BITTREX",
            "websiteLink": "https://bittrex.com/",
            "countryOfOrigin": "United States"
        }
    ]
}

GET /exchange

Returns the list of exchanges supported in bitsian.

Response : Exchange



















Currencies

curl -X GET "https://api.bitsian.io/currency"
  -H "BITSIAN-API-KEY: your_api_key"
  -H "BITSIAN-API-SIGN: signaure"
  -H "BITSIAN-API-TIMESTAMP: timestamp_in_milliseconds"
  -H "BITSIAN-API-PASSPHRASE: your_passphrase"

Response

{
    "data": [
        {
            "currencySymbol": "BTC",
            "currencyName": "Bitcoin",
            "currencyId": 1
        },
        {
            "currencySymbol": "ETH",
            "currencyName": "Ethereum",
            "currencyId": 2
        },
        {
            "currencySymbol": "XRP",
            "currencyName": "RippleX",
            "currencyId": 3
        }
    ]
}

GET /currency

Returns the list of currencies available in bitsian with id

Response: Currency





















Products

curl -X GET "https://api.bitsian.io/product?exchangeId=2"
  -H "BITSIAN-API-KEY: your_api_key"
  -H "BITSIAN-API-SIGN: signaure"
  -H "BITSIAN-API-TIMESTAMP: timestamp_in_milliseconds"
  -H "BITSIAN-API-PASSPHRASE: your_passphrase"

Response

{
    "data": [
        {
            "exchangeProductId": 1,
            "productName": "LTC-BTC",
            "productSymbol": "BTC-LTC",
            "baseCurrencySymbol": "LTC",
            "quoteCurrencySymbol": "BTC",
            "exchangeId": 2,
            "exchangeName": "BITTREX"
        },
        {
            "exchangeProductId": 2,
            "productName": "DOGE-BTC",
            "productSymbol": "BTC-DOGE",
            "baseCurrencySymbol": "DOGE",
            "quoteCurrencySymbol": "BTC",
            "exchangeId": 2,
            "exchangeName": "BITTREX"
        }
    ]
}

GET /product

Returns the list of products available against the exchange.

Parameters:

Name Type Required Description
exchangeId Integer required exchange Identifier of the required exchange

Response: Product

Account

Account Balance

curl -X GET "https://api.bitsian.io/balance"
  -H "BITSIAN-API-KEY: your_api_key"
  -H "BITSIAN-API-SIGN: signaure"
  -H "BITSIAN-API-TIMESTAMP: timestamp_in_milliseconds"
  -H "BITSIAN-API-PASSPHRASE: your_passphrase"

Response

{
    "data": [
        {
            "exchangeId": 2,
            "currencyId": 13,
            "availableBalance": 0.02652544,
            "realizedBalance": 0.02652544,
            "currencySymbol": "BCH",
            "exchangeName": "BITTREX"
        },
        {
            "exchangeId": 2,
            "currencyId": 1,
            "availableBalance": 0.00788285,
            "realizedBalance": 0.00788285,
            "currencySymbol": "BTC",
            "exchangeName": "BITTREX"
        }
    ]
}

GET /balance

Get balances of the account in the registered exchanges. This endpoint requires balance scope.

Results are paginated. See the Pagination section for retrieving additional entries after the first page.

Parameters:

Name Type Required Description
exchangeId Integer optional exchange identifier
currencyId Integer optional currency identifier

Response: Balance

Trade

Create new order

curl -X POST "https://api.bitsian.io/orders"
  -H "BITSIAN-API-KEY: your_api_key"
  -H "BITSIAN-API-SIGN: signaure"
  -H "BITSIAN-API-TIMESTAMP: timestamp_in_milliseconds"
  -H "BITSIAN-API-PASSPHRASE: your_passphrase"
  -d '{
      "currencyPair": "LTC-USD",
      "exchangeId": 2,
      "orderSide": "buy",
      "orderType": "limit",
      "price": 57.0,
      "quantity": 0.1,
      "tifType": "gtc"
    }'

Response

{
    "data": [
        {
            "orderId": "9ddd7e26-d770-47b2-9eb8-2f43571719b0",
            "currencyPair": "LTC-USD",
            "baseCurrencyId": "7",
            "quantity": "0.1",
            "quoteCurrencyId": "3622",
            "price": "57.0",
            "orderType": "limit",
            "tifType": "gtc",
            "status": "Working",
            "exchangeName": "BITTREX",
            "exchangeId": "2",
            "exchangeOrderId": "261eee9b-0f19-4a8a-90a9-4b3b3767dbe5",
            "orderPlacedVia": "BITSIAN",
            "fillPercentage": null,
            "executedPrice": null,
            "feeSide": "QUOTE",
            "fee": "0.0",
            "statusDescription": null,
            "amountFilled": "0.0",
            "createdTime": "2019-11-01 11:51:22",
            "updateTime": null
        }
     ]
}

POST /orders

Users can place two types of orders: limit and market. Orders can be placed if the user has sufficient funds in the exchange.

Parameters :

Name Type Required Description
orderSide String required BUY (or) SELL
orderType String required market (or) limit
currencyPair String required currency pair (baseCurrencySymbol-quoteCurrencySymbol)
exchangeId Integer required exchange to place the order
price Decimal optional price per base currency (required for limit order}
quantity Decimal required quantity of base currency to buy or sell
tifType String optional Time in force type (Only if the exchange specified supports it)

TIME IN FORCE

Time in Force is a special instruction used when placing a trade to indicate how long an order will remain active before it is executed or expired. Supported tifType varies according to the exchanges. It is supported only if the specified exchange supports it.

Response: Order











Cancel order

curl -X POST "https://api.bitsian.io/orders/9ddd7e26-d770-47b2-9eb8-2f43571719b0/cancel"
  -H "BITSIAN-API-KEY: your_api_key"
  -H "BITSIAN-API-SIGN: signaure"
  -H "BITSIAN-API-TIMESTAMP: timestamp_in_milliseconds"
  -H "BITSIAN-API-PASSPHRASE: your_passphrase"

Response

{
    "data": [
        {
            "orderId": "9ddd7e26-d770-47b2-9eb8-2f43571719b0",
            "currencyPair": "LTC-USD",
            "baseCurrencyId": "7",
            "quantity": "0.1",
            "quoteCurrencyId": "3622",
            "price": "57.0",
            "orderType": "limit",
            "tifType": "gtc",
            "status": "Cancelled",
            "exchangeName": "BITTREX",
            "exchangeId": "2",
            "exchangeOrderId": "261eee9b-0f19-4a8a-90a9-4b3b3767dbe5",
            "orderPlacedVia": "BITSIAN",
            "fillPercentage": null,
            "executedPrice": null,
            "feeSide": "QUOTE",
            "fee": "0.0",
            "statusDescription": null,
            "amountFilled": "0.0",
            "createdTime": "2019-11-01 11:51:22",
            "updateTime": null
        }
     ]
}

POST /orders/{orderId}/cancel

An active order can be cancelled using the orderId here. This endpoint requires trade scope

Name Type Required Description
orderId String required unique order identifier

Response : Order

























View order

curl -X GET "https://api.bitsian.io/orders
  -H "BITSIAN-API-KEY: your_api_key"
  -H "BITSIAN-API-SIGN: signaure"
  -H "BITSIAN-API-TIMESTAMP: timestamp_in_milliseconds"
  -H "BITSIAN-API-PASSPHRASE: your_passphrase"

curl -X GET "https://api.bitsian.io/orders/9ddd7e26-d770-47b2-9eb8-2f43571719b0
  -H "BITSIAN-API-KEY: your_api_key"
  -H "BITSIAN-API-SIGN: signaure"
  -H "BITSIAN-API-TIMESTAMP: timestamp_in_milliseconds"
  -H "BITSIAN-API-PASSPHRASE: your_passphrase"

Response

{
    "data": [
        {
            "orderId": "9ddd7e26-d770-47b2-9eb8-2f43571719b0",
            "currencyPair": "LTC-USD",
            "baseCurrencyId": "7",
            "quantity": "0.1",
            "quoteCurrencyId": "3622",
            "price": "57.0",
            "orderType": "limit",
            "tifType": "gtc",
            "status": "Cancelled",
            "exchangeName": "BITTREX",
            "exchangeId": "2",
            "exchangeOrderId": "261eee9b-0f19-4a8a-90a9-4b3b3767dbe5",
            "orderPlacedVia": "BITSIAN",
            "fillPercentage": null,
            "executedPrice": null,
            "feeSide": "QUOTE",
            "fee": "0.0",
            "statusDescription": null,
            "amountFilled": "0.0",
            "createdTime": "2019-11-01 11:51:22",
            "updateTime": null
        }
     ]
}

Get all orders

GET /orders

Gets list of all orders. This endpoint requires trade scope.

Name Type Required Description
resolution String optional open (or) closed

Results are paginated and sorted to show the latest orders first. See the Pagination section for retrieving additional entries after the first page.

Response : Order

Get order by id

GET /orders/{orderId}

Gets details of order by orderId. This endpoint requires trade scope

Name Type Required Description
orderId String required unique order identifier

Response : Order

Responses

Exchange

Name Type Description
exchangeId Integer Unique exchange identifier
exchangeName String Name of the exchange
websiteLink String Link for the exchange
countryOfOrigin String Country of origin of the exchange

Currency

Name Type Description
currencyId Integer Unique currency identifier
currencySymbol String Unique currency symbol
currencyName String Unique currency name

Product

Name Type Description
exchangeProductId Integer Unique product identifier
productName String Name of product
productSymbol String Symbol of product
baseCurrencySymbol String Symbol of baseCurrency
quoteCurrencySymbol String Symbol of quoteCurrency
exchangeId Integer Unique exchange identifier
exchangeName String Name of the exchange

Balance

Name Type Description
exchangeId Integer Unique exchange identifier
currencyId Integer currency identifier
availableBalance Decimal available balance of the currency for the exchange
realizedBalance Decimal realized balance of the currency for the exhange
currencySymbol String Symbol of the currency
exchangeName String Name of the exchange

Order

Name Type Description
orderId String Unique order identifier
currencyPair String currency pair
baseCurrencyId Integer id of base currency
quantity Decimal quantity of base currency
quoteCurrencyId Integer id of quote currency
price Decimal price of base currency
orderType String market (or) limit
tifType String Time in force type
status String order status
exchangeName String Name of exchange
exchangeId Integer exchange identifier
exchangeOrderId String order identifier in exchange
orderPlaceVia String BITSIAN (or) EXCHANGE
fillPercentage Decimal Percentage of filled amount
executedPrice Decimal Price at which the base currency bought or sold
feeSide String BASE (or) QUOTE
fee Decimal amount of fee
statusDescription String Description of the status
amountFilled Decimal amount of quantity filled
createdTime Time Time in yyyy-mm-dd HH:mm:ss
updatedTime Time Time in yyyy-mm-dd HH:mm:ss

Websocket

The websocket feed provides real-time market data updates for orders and trades.

Authentication

Before subscribing order book and trades you must authenticate websocket connection.

To authenticate, you should subscribe to /v1/auth channel with the following parameters in the headers,

NOTE

On authentication failure, following error messages are provided

Payload Description
{"error": "Missing API Key Headers"} Any of required headers is missing
{"error": "Invalid API Key"} API key provided is invalid.
{"error": "Invalid passphrase"} Provided passphrase is invalid for the key
{"error": "Invalid Signature"} Provided signature is invalid

Order Book

Snapshot

{
   "ask": [
   {
       "price": 57.85,
       "qunatity": "11.068",
       "exchange": "KRAKEN"
   },
   {
       "price": 57.87,
       "qunatity": "152.89345228",
       "exchange": "KRAKEN"
   },
    ....
    ....
],
   "bid": [
   {
       "price": 57.77,
       "qunatity": "12.0",
       "exchange": "KRAKEN"
   },
   {
       "price": 57.76,
       "qunatity": "60.0",
       "exchange": "KRAKEN"
   },
    ....
    ....
]
}

L2 updates

{
   "baseCurrency": "ltc",
   "dataType": "Market_Data",
   "buy": [
   [
       57.83,
       57.53068008
   ]
],
   "sell": [
   [
       58.13,
       100
   ],
   [
       58.12,
       53.62622
   ]
],
   "quoteCurrency": "usd",
   "exchange": "COINBASE",
   "dataUniqueIdentifier": "1572434828818"
}

On subscription, a snapshot will be published at the specified depth, following the snapshot, level2 updates will be published.

Aggregated Order Book (All exchanges)

Topic:/v1/productbest/{base}/{quote}

Ex: /v1/productbest/btc/usd




Exchange Order Book ( Individual Exchanges )

Topic:/v1/productbest/{exchange}/{base}/{quote}

Ex: /v1/productbest/kraken/btc/usd

Trade tape

Snapshot Trade


[
   {
       "exchange": "coinbase",
       "priceType": "bid",
       "price": "58.22",
       "quantity": "6.8218E-4",
       "isSynthPair": false,
       "exchangeTimeStamp": "Wed Oct 30 11:53:19 GMT 2019"
   },
   {
       "exchange": "coinbase",
       "priceType": "bid",
       "price": "58.23",
       "quantity": "2.99931782",
       "isSynthPair": false,
       "exchangeTimeStamp": "Wed Oct 30 11:53:19 GMT 2019"
   },
   ....
....
]

Recent Trade


 {
   "quoteCurrency": "usd",
   "timeStamp": "1572436586928",
   "quantiy": "0.00558883",
   "isSynthPair": false,
   "price": "9098.66",
   "dataType": "Trade_Data",
   "exchange": "BITSTAMP",
   "baseCurrency": "btc",
   "tradeId": "99734154",
   "tradeType": "ask"
}

Get a list of Trades for a product.

Aggregated Trade Tape ( All Exchanges )

On subscription, specified depth trades will be published, following that, most recent trade will be published. Topic:/v1/tradetape/{base}/{quote}

Ex: /v1/tradetape/btc/usd





Exchange Trade tape ( Individual Exchanges )

On subscription, last 100 trades will be published, following that, most recent trade will be published.

Topic:/v1/tradetape/{exchange}/{base}/{quote}

Ex: /v1/tradetape/kraken/btc/usd

Unsubscription

var subscription = client.subscribe(...);

  ...

  subscription.unsubscribe();

To unsubscribe a particular topic or channel use STOMP protocol unsubscribe functionality.

The subscribe() method returns an object with an attribute id, that corresponds to the client subscription ID. The unsubscribe() method can be used later on to unsubscribe the client from this destination.

Guide and Code Samples