bittime-docs.github.io

Public Rest API for Bittime (2022-12-30)

General API Information

LIMITS

Endpoint security type

Security Type Description
NONE Endpoint can be accessed freely.
TRADE Endpoint requires sending a valid API-Key and signature.
MARKET_DATA Endpoint requires sending a valid API-Key.

SIGNED (TRADE and USER_DATA) Endpoint security

Timing security

Serious trading is about timing. Networks can be unstable and unreliable, which can lead to requests taking varying amounts of time to reach the servers. With recvWindow, you can specify that the request must be processed within a certain number of milliseconds or be rejected by the server.

It recommended to use a small recvWindow of 5000 or less!

SIGNED Endpoint Examples for POST /api/v1/order

Here is a step-by-step example of how to send a vaild signed payload from the Linux command line using echo, openssl, and curl.

Key Value
apiKey vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A
secretKey NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j
Parameter Value
symbol LTCBTC
side BUY
type LIMIT
timeInForce GTC
quantity 1
price 0.1
recvWindow 5000
timestamp 1499827319559

Example 1: As a query string

Example 2: As a request body

Public API Endpoints

Terminology

ENUM definitions

Symbol status:

Order status:

Order types:

Order side:

Time in force:

Kline/Candlestick chart intervals:

m -> minutes; h -> hours; d -> days; w -> weeks; M -> months

Rate limiters (rateLimitType)

Rate limit intervals

Error Codes

Http status 200

Http status code desc
200 -2013 Could not find order information for given order ID.
200 -2017 Could not find net-value for given symbol.

Http status ‘4xx’

Http status code desc
412 -1102 Mandatory parameter is missing or illegal.
412 -1121 Invalid symbol name given.
401 -1022 Invalid signature or Invalid timestamp or Unauthorized for API.
412 -1111 Invalid volume or price or address given.
406 -2010 Order placement or cancellation or withdrawal rejected.
405 -1020 Method not supported.

Http status ‘5xx’

Http status code desc
500 -1016 Service unavailable
503 503 Service unavailable

General endpoints

Test connectivity

GET /api/v1/ping

Test connectivity to the Rest API.

Weight: 1

Parameters: NONE

Response:

{}

Check server time

GET /api/v1/time

Test connectivity to the Rest API and get the current server time.

Weight: 1

Parameters: NONE

Response:

{
  "serverTime":1672225177210
}

Exchange information (Some fields not support. only reserved)

GET /api/v1/exchangeInfo

Current exchange trading rules and symbol information

Weight: 1

Parameters: NONE

Response:

{
  "timezone": "UTC",
  "serverTime": 1508631584636,
  "rateLimits": [
          {
              "id": "general",
              "type": [
                  "IP"
              ],
              "replenishRate": 1200,
              "burstCapacity": 1200,
              "timeCount": 1,
              "timeUnit": "MINUTES",
              "refreshType": "FIRST_REQUEST",
              "weight": 1,
              "dynamicWeight": false,
              "overrideLevel": false,
              "dynamicWeightType": null
          },// That means only allow 1200 weight in 1 minute per IP.
          {
              "id": "orders_ip_seconds",
              "type": [
                  "IP"
              ],
              "replenishRate": 100,
              "burstCapacity": 100,
              "timeCount": 60,
              "timeUnit": "SECONDS",
              "refreshType": "FIRST_REQUEST",
              "weight": 1,
              "dynamicWeight": false,
              "overrideLevel": true,
              "dynamicWeightType": null
          },// That means only allow 100 weight for order endpoints in 60 seconds per IP.
          {
              "id": "orders_user_seconds",
              "type": [
                  "USER"
              ],
              "replenishRate": 100,
              "burstCapacity": 100,
              "timeCount": 60,
              "timeUnit": "SECONDS",
              "refreshType": "FIRST_REQUEST",
              "weight": 1,
              "dynamicWeight": false,
              "overrideLevel": true,
              "dynamicWeightType": null
          },// That means only allow 100 weight for order endpoints in 60 seconds per User.
          {
              "id": "withdraw_days",
              "type": [
                  "USER"
              ],
              "replenishRate": 1000,
              "burstCapacity": 1000,
              "timeCount": 1,
              "timeUnit": "DAYS",
              "refreshType": "FIRST_REQUEST",
              "weight": 1,
              "dynamicWeight": false,
              "overrideLevel": false,
              "dynamicWeightType": null
          },// That means only allow 1000 weight for withdraw endpoints in 1 day per User.
          {
              "id": "withdraw_read_hours",
              "type": [
                  "USER"
              ],
              "replenishRate": 3000,
              "burstCapacity": 3000,
              "timeCount": 1,
              "timeUnit": "HOURS",
              "refreshType": "FIRST_REQUEST",
              "weight": 1,
              "dynamicWeight": false,
              "overrideLevel": false,
              "dynamicWeightType": null
          } // That means only allow 3000 weight for withdraw read endpoints in 1 hour per User.
      ],
  "exchangeFilters": [],
  "symbols": [{
    "symbol": "ETHBTC",
    "status": "TRADING",
    "baseAsset": "ETH",
    "baseAssetPrecision": 8,
    "quoteAsset": "BTC",
    "quotePrecision": 8,
    "orderTypes": ["LIMIT", "MARKET"],
    "icebergAllowed": false,
    "filters": [{
                        "filterType": "PRICE_FILTER",
                        "minPrice": "0.666", // price >= minPrice
                        "maxPrice": "66.600",// price <= maxPrice
                        "tickSize": "0.01",  // price % tickSize == 0
                        "priceScale": 2
                    },
                    {
                        "filterType": "PERCENT_PRICE_BY_SIDE",
                        "bidMultiplierUp": "1.3",    // Order price <= bidMultiplierUp * lastPrice
                        "bidMultiplierDown": "0.1",  // Order price >= bidMultiplierDown * lastPrice
                        "askMultiplierUp": "10.0",   // Order Price <= askMultiplierUp * lastPrice
                        "askMultiplierDown": "0.7",  // Order Price >= askMultiplierDown * lastPrice
                        "avgPriceMins": "1"
                    },
                    {
                        "filterType": "LOT_SIZE",
                        "minQty": "0.1",  // quantity >= minQty
                        "minVal": "10.0", // quantity * lastPrice >= minVal
                        "maxQty": "999999999999999", // quantity <= maxQty
                        "stepSize": "0.01", // (quantity-minQty) % stepSize == 0
                        "volumeScale": 2
                    }]
  }],
  "coins": [{
    "coin":"btr",
    "coinFulName":"Bittime Coin",
    "enableWithdraw":true,
    "enableDeposit":true,
    "chains":["ERC20","BEP20"],
    "withdrawFee":"161.0",
    "minWithdraw":"1961.067474",
    "maxWithdraw":"88888888"
  }]
}

Market Data endpoints

Order book

GET /api/v1/depth

Weight: Adjusted based on the limit:

Limit Weight
5, 10, 20, 50, 100 1
500 5
1000 10

Parameters:

Name Type Mandatory Description
symbol STRING YES  
limit INT NO Default 100; max 1000. Valid limits:[5, 10, 20, 50, 100, 500, 1000]

Caution: setting limit=0 can return a lot of data.

Response:

{
  "lastUpdateId": 1027024,
  "bids": [
    [
      "4.00000000",     // PRICE
      "431.00000000",   // QTY
      []                // Ignore.
    ]
  ],
  "asks": [
    [
      "4.00000200",
      "12.00000000",
      []
    ]
  ]
}

Recent trades list

GET /api/v1/trades

Get recent trades (up to last 1000).

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES  
limit INT NO Default 100; max 1000.

Response:

[
  {
    "id": 28457,
    "price": "4.00000100",
    "qty": "12.00000000",
    "time": 1499865549590,
    "isBuyerMaker": true, 
    "isBestMatch": true 
  }
]

Old trade lookup (MARKET_DATA)

GET /api/v1/historicalTrades

Get older trades.

Weight: 5

Parameters:

Name Type Mandatory Description
symbol STRING YES  
limit INT NO Default 100; max 1000.
fromId LONG NO TradeId to fetch from. Default gets most recent trades.

Response:

[
  {
    "id": 28457,
    "price": "4.00000100",
    "qty": "12.00000000",
    "time": 1499865549590,
    "isBuyerMaker": true,
    "isBestMatch": true  
  }
]

Compressed/Aggregate trades list

GET /api/v1/aggTrades

Get compressed, aggregate trades. Trades that fill at the time, from the same order, with the same price will have the quantity aggregated.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES  
fromId LONG NO ID to get aggregate trades from INCLUSIVE.
startTime LONG NO Timestamp in ms to get aggregate trades from INCLUSIVE.
endTime LONG NO Timestamp in ms to get aggregate trades until EXCLUSIVE.
limit INT NO Default 100; max 1000.

Response:

[
  {
    "a": 26129,         // Aggregate tradeId
    "p": "0.01633102",  // Price
    "q": "4.70443515",  // Quantity
    "f": 27781,         // First tradeId
    "l": 27781,         // Last tradeId
    "T": 1498793709153, // Timestamp
    "m": true,          // Was the buyer the maker?
    "M": true           // Was the trade the best price match?
  }
]

24hr ticker price change statistics

GET /api/v1/ticker/24hr

24 hour price change statistics. Careful when accessing this with no symbol.

Weight: 1 for a single symbol; 40 when the symbol parameter is omitted

Parameters:

Name Type Mandatory Description
symbol STRING NO  

24 hour price change statistics. Careful when accessing this with no symbol. Weight: 1 for a single symbol; 40 when the symbol parameter is omitted

Response:

{
  "symbol": "BNBBTC",
  "priceChange": "-94.99999800",
  "priceChangePercent": "-95.960",
  "weightedAvgPrice": "0.29628482",
  "prevClosePrice": "0.10002000",
  "lastPrice": "4.00000200",
  "lastQty": "200.00000000",
  "bidPrice": "4.00000000",
  "askPrice": "4.00000200",
  "openPrice": "99.00000000",
  "highPrice": "100.00000000",
  "lowPrice": "0.10000000",
  "volume": "8913.30000000",
  "quoteVolume": "15.30000000",
  "openTime": 1499783499040,
  "closeTime": 1499869899040,
  "firstId": 28385,   // First tradeId
  "lastId": 28460,    // Last tradeId
  "count": 76         // Trade count
}

OR

[
  {
    "symbol": "BNBBTC",
    "priceChange": "-94.99999800",
    "priceChangePercent": "-95.960",
    "weightedAvgPrice": "0.29628482",
    "prevClosePrice": "0.10002000",
    "lastPrice": "4.00000200",
    "lastQty": "200.00000000",
    "bidPrice": "4.00000000",
    "askPrice": "4.00000200",
    "openPrice": "99.00000000",
    "highPrice": "100.00000000",
    "lowPrice": "0.10000000",
    "volume": "8913.30000000",
    "quoteVolume": "15.30000000",
    "openTime": 1499783499040,
    "closeTime": 1499869899040,
    "firstId": 28385,   // First tradeId
    "lastId": 28460,    // Last tradeId
    "count": 76         // Trade count
  }
]

Symbol price ticker

GET /api/v1/ticker/price

Latest price for a symbol or symbols.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES  

Response:

{
  "symbol": "LTCBTC",
  "price": "4.00000200"
}

Symbol order book ticker

GET /api/v1/ticker/bookTicker

Best price/qty on the order book for a symbol or symbols.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES  

Response:

{
  "symbol": "LTCBTC",
  "bidPrice": "4.00000000",
  "bidQty": "431.00000000",
  "askPrice": "4.00000200",
  "askQty": "9.00000000"
}

Account endpoints

New order (TRADE)

POST /api/v1/order  (HMAC SHA256)

Send in a new order.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES  
side ENUM YES  
type ENUM YES  
quantity DECIMAL YES  
price DECIMAL NO  
newClientOrderId STRING NO A unique id for the order. Automatically generated if not sent.
stopPrice DECIMAL NO  
icebergQty DECIMAL NO  
recvWindow LONG NO  
timestamp LONG YES  
timeInForce STRING NO Value equals ` POST_ ONLY ‘, supports post only type orders.

Additional mandatory parameters based on type:

Type Additional mandatory parameters
LIMIT quantity, price
MARKET quantity

Additional mandatory parameters based on timeInForce:

Type Additional mandatory parameters
POST_ONLY type=LIMIT

Response :

{
  "symbol": "BTCUSDT",
  "orderId": 28,
  "clientOrderId": "6gCrw2kRUAF9CvJDGP16IP",
  "transactTime": 1507725176595
}

Query order (USER_DATA)

GET /api/v1/order (HMAC SHA256)

Check an order’s status.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES  
orderId LONG YES  
origClientOrderId STRING NO  
recvWindow LONG NO  
timestamp LONG YES  

Response:

{
  "symbol": "LTCBTC",
  "orderId": 1,
  "clientOrderId": "myOrder1",  
  "price": "0.1",
  "origQty": "1.0", 
  "executedQty": "0.0", 
  "cummulativeQuoteQty": "0.0", 
  "status": "NEW",
  "timeInForce": "GTC", 
  "type": "LIMIT",
  "side": "BUY",
  "stopPrice": "0.0",  
  "icebergQty": "0.0", 
  "time": 1499827319559,
  "updateTime": 1499827319559,
  "isWorking": true  
}

Cancel order (TRADE)

DELETE /api/v1/order  (HMAC SHA256)

Cancel an active order.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES  
orderId LONG NO  
origClientOrderId STRING NO  
newClientOrderId STRING NO  
recvWindow LONG NO  
timestamp LONG YES  

Response:

{
  "symbol": "LTCBTC",
  "origClientOrderId": "myOrder1",  
  "orderId": 1,
  "clientOrderId": "cancelMyOrder1"  
}

Current open orders (USER_DATA)

GET /api/v1/openOrders  (HMAC SHA256)

Weight: 1 for a single symbol;

Parameters:

Name Type Mandatory Description
symbol STRING YES  
recvWindow LONG NO  
timestamp LONG YES  

Response:

[
  {
    "symbol": "LTCBTC",
    "orderId": 1,
    "clientOrderId": "myOrder1",
    "price": "0.1",
    "origQty": "1.0",  
    "executedQty": "0.0",  
    "cummulativeQuoteQty": "0.0",  
    "status": "NEW",
    "timeInForce": "GTC",  
    "type": "LIMIT",
    "side": "BUY",
    "stopPrice": "0.0", 
    "icebergQty": "0.0",  
    "time": 1499827319559,
    "updateTime": 1499827319559,
    "isWorking": true  
  }
]

All orders (USER_DATA)

GET /api/v1/allOrders (HMAC SHA256)

Get all account orders; active, canceled, or filled.

Weight: 5 with symbol

Parameters:

Name Type Mandatory Description
symbol STRING YES  
orderId LONG NO  
startTime LONG NO  
endTime LONG NO  
limit INT NO Default 100; max 1000.
recvWindow LONG NO  
timestamp LONG YES  

Notes:

Response:

[
  {
    "symbol": "LTCBTC",
    "orderId": 1,
    "clientOrderId": "myOrder1",
    "price": "0.1",
    "origQty": "1.0",
    "executedQty": "0.0",
    "cummulativeQuoteQty": "0.0",
    "status": "NEW",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "side": "BUY",
    "stopPrice": "0.0",
    "icebergQty": "0.0",
    "time": 1499827319559,
    "updateTime": 1499827319559,
    "isWorking": true
  }
]

Account information (USER_DATA)

GET /api/v1/account (HMAC SHA256)

Get current account information.

Weight: 5

Parameters:

Name Type Mandatory Description
recvWindow LONG NO  
timestamp LONG YES  

Response:

{
  "makerCommission": 15,   
  "takerCommission": 15,  
  "buyerCommission": 0,   
  "sellerCommission": 0,   
  "canTrade": true,   
  "canWithdraw": true,  
  "canDeposit": true,  
  "updateTime": 123456789,
  "balances": [
    {
      "asset": "BTC",
      "free": "4723846.89208129",
      "locked": "0.00000000"
    },
    {
      "asset": "LTC",
      "free": "4763368.68006011",
      "locked": "0.00000000"
    }
  ]
}

Account trade list (USER_DATA)

GET /api/v2/myTrades  (HMAC SHA256)

Get trades for a specific account and symbol.

Weight: 5 with symbol;40 when the symbol parameter is omitted

Parameters:

Name Type Mandatory Description
symbol STRING YES  
startTime LONG NO  
endTime LONG NO  
fromId LONG NO TradeId to fetch from. Default gets most recent trades.
limit INT NO Default 100; max 1000.
recvWindow LONG NO  
timestamp LONG YES  

Notes:

Response:

[
  {
    "symbol": "BNBBTC",
    "id": 28457,
    "orderId": 100234,
    "price": "4.00000100",
    "qty": "12.00000000",
    "commission": "10.10000000",
    "commissionAsset": "BNB",
    "time": 1499865549590,
    "isBuyer": true,
    "isMaker": false,
    "isBestMatch": true    
  }
]

Deposit & Withdraw (Crypto)

Withdraw commit (WITHDRAW_DATA)

POST /api/v1/withdraw/commit

Commit one withdraw request.

Weight: 1

Parameters:

Name Type Mandatory Description
coin STRING YES Coin name without chain name.
amount NUMBER YES How much coins to withdraw.
addressTo STRING YES Which address to withdraw.
chainName STRING YES Which chain to withdraw for this coin.
addressMark STRING NO Mark of address.
addrType STRING NO Type of address.
tag STRING NO Tag for address.

Notes:

This method needs the API withdraw privilege and you MUST set limit IP for this API Key and you MUST set withdraw address white list before.

Response:

{
    "code": 200,
    "msg": "succ",
    "data": {
        "msg": null,
        "amount": 1000,
        "fee": 1,
        "ctime": null,
        "coin": "usdt_erc20",
        "withdrawId": 1156423,
        "addressTo": "0x2edfae3878d7b6db70ce4abed177ab2636f60c83"
    }
}
ErrorCode Description
2 Parameter error
6 Withdraw amount too less
19 Insufficient balance
32 User auth error
110049 Withdraw locked
110050 Withdraw locked
110051 Withdraw locked
110054 Withdraw locked
110055 Withdraw locked
110056 Withdraw locked
110057 Withdraw locked
966000 Ip limit
966001 No privileges
999503 Withdraw fee error
999504 Withdraw limit
999505 Withdraw limit
999508 Withdraw locked
999509 Not deposit found
999512 Withdraw tag error
999513 Withdraw address error
999901 Coin chain error
999902 Account balance error

Withdraw history (WITHDRAW_DATA)

GET /api/v1/withdraw/history

Query withdraw history

Weight: 1

Parameters:

Name Type Mandatory Description
coin STRING YES Coin name without chain name.
status NUMBER NO 0: init 5: finished 6: canceled. Default 0.
offset NUMBER NO Which offset to start. Default 0.
limit NUMBER NO Limit data to query. Default 10. Max 1000.
startTime NUMBER NO Start time to query. Timestamp in ms.
endTime NUMBER NO End time to query. Timestamp in ms.
timestamp LONG YES  

Notes:

The other status means your withdraw request is in a flow.

Response:

{
    "code": 200,
    "msg": "succ",
    "data": [
                {
                    "id": 183745,
                    "symbol": "usdt_erc20",
                    "amount": "8.4000000000000000",
                    "fee": "1.6000000000000000",
                    "payAmount": "0.0000000000000000",
                    "createdAt": 1595336441000,
                    "updatedAt": 1595336576000,
                    "addressFrom": "",
                    "addressTo": "0x2edfae3878d7b6db70ce4abed177ab2636f60c83",
                    "txid": "",
                    "confirmations": 0,
                    "status": 6,
                    "tagType": null
                }
            ]
}

Deposit history (WITHDRAW_DATA)

GET /api/v1/deposit/history

Query deposit history

Weight: 1

Parameters:

Name Type Mandatory Description
coin STRING YES Coin name without chain name.
status NUMBER NO 0: init 1: finished. Default 0.
offset NUMBER NO Which offset to start. Default 0.
limit NUMBER NO Limit data to query. Default 10. Max 1000.
startTime NUMBER NO Start time to query. Timestamp in ms.
endTime NUMBER NO End time to query. Timestamp in ms.
timestamp LONG YES  

Response:

{
    "code": 200,
    "msg": "succ",
    "data": [
                {
                    "symbol": "XRP",
                    "amount": "261.3361000000000000",
                    "fee": "0.0E-15",
                    "createdAt": 1548816979000,
                    "updatedAt": 1548816999000,
                    "addressFrom": "",
                    "addressTo": "raLPjTYeGezfdb6crXZzcC8RkLBEwbBHJ5_18113641",
                    "txid": "86D6EB68A7A28938BCE06BD348F8C07DEF500C5F7FE92069EF8C0551CE0F2C7D",
                    "confirmations": 8,
                    "status": 1,
                    "tagType": "Tag"
                },
                {
                    "symbol": "XRP",
                    "amount": "20.0000000000000000",
                    "fee": "0.0E-15",
                    "createdAt": 1544669393000,
                    "updatedAt": 1544669413000,
                    "addressFrom": "",
                    "addressTo": "raLPjTYeGezfdb6crXZzcC8RkLBEwbBHJ5_18113641",
                    "txid": "515B23E1F9864D3AF7F5B4C4FCBED784BAE861854FAB95F4031922B6AAEFC7AC",
                    "confirmations": 7,
                    "status": 1,
                    "tagType": "Tag"
                }
            ]
}

Market Data Streams WebSocket

Ping/Keep-alive (MARKET_STREAM)

Example of ping:

{
    "ping":"1663815268584"    //timestamp
}

Example of pong:

{
    "pong":"1663815268584"    //It can be any content
}

Live Subscribing/Unsubscribing to streams

Subscribe order book depth

Request:

{
    "event":"${event}",            //sub:Subscribe,unsub:Unsubscribe
    "params":{
        "cb_id":"${cb_id}",        //trading pair,eg: btcusdt
        "channel":"${channel}"    //channel: channel to be subscribed, {cb_id}:placeholder, depth:market_{cb_id}_simple_depth_step0
    }
}

Parameters:

Name Type Mandatory Description
event STRING YES sub:Subscribe,unsub:Unsubscribe
cb_id STRING YES Symbol name
channel STRING YES depth channel will be like market_${cb_id}_simple_depth_step0

Request Example:

{
    "event":"sub",
    "params":{
        "cb_id":"btcusdt",
        "channel":"market_btcusdt_simple_depth_step0"
    }
}

Response:

{
    "channel":"${channel}",
    "cb_id":"${cb_id}",
    "event_rep":"subed",        //subscripted
    "status":"ok",                //success
    "ts":${timestamp}                //timestamp
}

Response Example:

{
    "channel":"market_btcusdt_simple_depth_step0",
    "cb_id":"btcusdt",
    "event_rep":"subed",
    "status":"ok",
    "ts":1663815268584
}

Response of DEPTH message pushing

{
    "ts":1663815268584,         //timestamp
    "channel":"market_btcusdt_simple_depth_step0",
    "tick":{     
        "buys":[    //Buy
            [
                "18619.40",  //Price
                "0.0013"  //Quantity
            ],
            [
                "1000.00",
                "0.0020"
            ]
        ],
        "asks":[    //Sell
            [
                "18620.32",  //Price
                "0.0220"  //Quantity
            ],
            [
                "606500.00",
                "0.0001"
            ]
        ]
    }
}

User Data Streams

Error Codes

Errors consist of two parts: an error code and a message. Codes are universal, but messages can vary.

200 SUCCESS

503 SERVICE_ERROR

-1022 INVALID_API_KEY

-1102 MANDATORY_PARAM_EMPTY_OR_MALFORMED

-1150 INVALID_LISTEN_KEY

ListenKey

CREATE A LISTENKEY (USER_STREAM)

url

POST /poseidon/api/v1/listenKey

Start a new user data stream. The stream will close after 60 minutes unless a keepalive is sent. If the account has an active listenKey, that listenKey will be returned and its validity will be extended for 60 minutes.

Response:

{
  "msg": "succ",
  "code": 200,
  "data":
  {
    "listenKey": "ac3abbc8ac18f7977df42de27ab0c87c1f4ea3919983955d2fb5786468ccdb07"
  }
}

Data Source: Memory

Ping/Keep-alive a ListenKey (USER_STREAM)

url

PUT /poseidon/api/v1/listenKey/{listenKey} Keepalive a user data stream to prevent a time out. User data streams will close after 60 minutes. It’s recommended to send a ping about every 30 minutes.

Response:

{
  "msg": "succ",
  "code": 200
}

Data Source: Memory

Close a ListenKey (USER_STREAM)

url:

DELETE /poseidon/api/v1/listenKey/{listenKey}

Close out a user data stream.

Response:

{
  "msg": "succ",
  "code": 200
}

Data Source: Memory

keep-alive

you should send pong message within 10 minutes pong:

{"event":"pong","ts":"1635221621062"}

Order Update

Orders are updated with the Order Event subscribe:

{"event":"sub","params":{"channel":"user_order_update"}}

response:

sub success :

{"channel":"user_order_update","event_rep":"subed","status":"ok","ts":1623381851178}

order event :

{
  "e": "executionReport",        // Event type
  "I": "209818131719847936",     // Event ID
  "E": 1499405658658,            // Event time
  "u": 123456,                   // UID
  "s": "ETHBTC",                 // Symbol
  "c": "mUvoqJxFIILMdfAW5iGSOW", // Client order ID
  "S": "BUY",                    // Side
  "o": "LIMIT",                  // Order type
  "q": "1.00000000",             // Order quantity
  "p": "0.10264410",             // Order price
  "x": "NEW",                    // order event
  "X": "NEW",                    // Current order status
  "i": 4293153,                  // Order ID
  "l": "0.00000000",             // Last executed quantity
  "L": "0.00000000",             // Last executed price
  "n": "0",                      // Commission amount
  "N": null,                     // Commission asset
  "T": 1499405658657,            // Trade time
  "t": -1,                       // Trade ID
  "O": 1499405658657,            // Order creation time
  "z": "0.00000000",              // Cumulative filled quantity
  "Y": "0.00000000",             // Cumulative transacted amount (i.e. Price * Qty)
  "C": "test",                   // Origin client order id
}

unsubscribe:

{"event":"unsub","params":{"channel":"user_order_update"}}

response:

{"channel":"user_order_update","status":"ok","ts":1623381851178}

example:

subscribe

{"event":"sub","params":{"channel":"user_order_update"}}

unsubscribe

{"event":"unsub","params":{"channel":"user_order_update"}}

balance update

balance are updated with the Balance Event subscribe:

{"event":"sub","params":{"channel":"user_balance_update"}}

response:

{
    "e":"BALANCE",  #event name 
    "x":"OutboundAccountPositionOrderEvent", #event type  
    "E":1635515839203,  #event time 
    "I":208810488108744704,  #event id 
    "i":1635515839203,  # ignore 
    "B":[
        {
            "a":"btr",        # assert name 
            "F":"9999999.9658620755200000",  # balance 
            "T":1635515839000,  # balance update time 
            "f":"2.8125000000000000",  # balance  Delta
            "L":"0.0000000000000000", # lock balance  
            "l":"-2.8125000000000000", # lock balance  Delta 
            "t":1635515839000 #  lock balance  update time 
        },
        {
            "a":"usdt",
            "F":"10000008.8000000000000000",
            "T":1635515839000,
            "f":"10.2600000000000000",
            "L":"0.0000000000000000",
            "l":"-10.2600000000000000",
            "t":1635515839000
        }
    ],
    "u":1090862
}

unsubscribe:

{"event":"unsub","params":{"channel":"user_balance_update"}}

response:

{"channel":"user_balance_update","status":"ok","ts":1623381851178}

Terminology

These terms will be used throughout the documentation, so it is recommended especially for new users to read to help their understanding of the API.

base asset refers to the asset that is the quantity of a symbol. For the symbol BTCUSDT, BTC would be the base asset. quote asset refers to the asset that is the price of a symbol. For the symbol BTCUSDT, USDT would be the quote asset.

ENUM definitions

SPOT balance event :

Event Description
OutboundAccountPositionEvent ignore
OutboundAccountPositionTradeEvent the order has been filled
OutboundAccountPositionOrderEvent The order place or cancel
OutboundAccountPositionTransferEvent ignore
OutboundAccountPositionBonusEvent ignore

order event :

Event Description
1 The order has been created by the user.
2 The order has been canceled by the user.
3 The order has been filled by the engine .
4 The order has been canceled by the engine .

order status :

status Description
0 The order has not been accepted by the engine.
1 The order has been accepted by the engine.
2 The order has been completed.
3 A part of the order has been filled.
4 The order has been canceled by the user.