The base endpoint is: https://openapi.bittime.com
All endpoints return either a JSON object or array.
All time and timestamp related fields are in milliseconds.
All data timestamp:GMT + 7
HTTP 4XX
return codes are used for for malformed requests;
the issue is on the sender’s side.
HTTP 5XX
return codes are used for internal errors; the issue is on
Bittime’s side.
It is important to NOT treat this as a failure operation; the execution status is
UNKNOWN and could have been a success.
Any endpoint can return an ERROR; the error payload is as follows:
{
"code": -1121,
"msg": "Invalid symbol."
}
Specific error codes and messages defined in another document.
For GET
endpoints, parameters must be sent as a query string
.
For POST
, PUT
, and DELETE
endpoints, the parameters may be sent as a
query string
or in the request body
with content type
application/x-www-form-urlencoded
. You may mix parameters between both the
query string
and request body
if you wish to do so.
Parameters may be sent in any order.
If a parameter sent in both the query string
and request body
, the
query string
parameter will be used.
/api/v1/exchangeInfo
rateLimits
array contains objects related to the exchange’s REQUEST_WEIGHT
and ORDER
rate limits.weight
which determines for the number of requests each endpoint counts for. Heavier endpoints and endpoints that do operations on multiple symbols will have a heavier weight
.rate_limit_p
.X-MBX-APIKEY
header.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. |
TRADE
endpoints are SIGNED
endpoints.SIGNED
endpoints require an additional parameter, signature
, to be
sent in the query string
.HMAC SHA256
signatures. The HMAC SHA256 signature
is a keyed HMAC SHA256
operation.
Use your secretKey
as the key and totalParams
as the value for the HMAC operation.signature
is not case sensitive.totalParams
is defined as the query string
concatenated with the
request body
.A SIGNED
endpoint also requires a parameter, timestamp
, to be sent which
should be the millisecond timestamp of when the request was created and sent.
An additional parameter, recvWindow
, may be sent to specify the number of
milliseconds after timestamp
the request is valid for. If recvWindow
is not sent, it defaults to 5000.
The logic is as follows:
if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow) {
// process request
} else {
// reject request
}
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!
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 |
queryString: symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1499827319559
HMAC SHA256 signature:
[linux]$ echo -n "symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1499827319559" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
(stdin)= c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71
curl command:
(HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://openapi.bittime.com/api/v1/order?symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1499827319559&signature=c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71'
requestBody: {“symbol”:”LTCBTC”,”side”:”BUY”,”type”:”LIMIT”,”timeInForce”:”GTC”,”price”:0.1,”quantity”:1,”timestamp”:1499827319559,”recvWindow”:5000}
HMAC SHA256 signature:
[linux]$ echo -n '{"symbol":"LTCBTC","side":"BUY","type":"LIMIT","timeInForce":"GTC","price":0.1,"quantity":1,"timestamp":1499827319559,"recvWindow":5000}' | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
(stdin)= a96755b9616ffcb19b47f38ee1c8e20bb9ff5ffdd3936ace8f457975fbc91a6a
curl command:
(HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://openapi.bittime.com/api/v1/order?signature=a96755b9616ffcb19b47f38ee1c8e20bb9ff5ffdd3936ace8f457975fbc91a6a' -d '{"symbol":"LTCBTC","side":"BUY","type":"LIMIT","timeInForce":"GTC","price":0.1,"quantity":1,"timestamp":1499827319559,"recvWindow":5000}'
base asset
refers to the asset that is the quantity
of a symbol.quote asset
refers to the asset that is the price
of a symbol.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
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 | 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 | code | desc |
---|---|---|
500 | -1016 | Service unavailable |
503 | 503 | Service unavailable |
GET /api/v1/ping
Test connectivity to the Rest API.
Weight: 1
Parameters: NONE
Response:
{}
GET /api/v1/time
Test connectivity to the Rest API and get the current server time.
Weight: 1
Parameters: NONE
Response:
{
"serverTime":1672225177210
}
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"
}]
}
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",
[]
]
]
}
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
}
]
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
}
]
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?
}
]
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
}
]
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"
}
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"
}
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
}
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
}
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"
}
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
}
]
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:
orderId
is set, it will get orders >= that orderId
. Otherwise most recent orders are returned.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
}
]
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"
}
]
}
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:
fromId
is set, it will get orders >= that fromId
.
Otherwise most recent orders are returned.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
}
]
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 |
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
}
]
}
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"
}
]
}
Example of ping:
{
"ping":"1663815268584" //timestamp
}
Example of pong:
{
"pong":"1663815268584" //It can be any content
}
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"
]
]
}
}
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
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
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
url:
DELETE /poseidon/api/v1/listenKey/{listenKey}
Close out a user data stream.
Response:
{
"msg": "succ",
"code": 200
}
Data Source: Memory
you should send pong message within 10 minutes pong:
{"event":"pong","ts":"1635221621062"}
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 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}
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. |