JSON

Market Data API

Overview.

All market data messages are delivered on subscriptions via a web socket. The instrument reference data messages are delivered as a query reply. A subscription key consists of a stream (message type) and a symbol's pattern, which supports the “” wildcard (BTCUSDT, BTC, “*”, etc). The wildcard allows to subscribe for a range of instruments by a single subscription key. All message timestamps have the nanoseconds resolution. All active client's subscriptions are cancelled on a client's web socket disconnection. The web socket server sends a ping frame every 10 seconds. If the web socket server does not receive a pong frame within 30 seconds, the web socket connection is closed. The unsolicited pong frames are allowed. For the instrument reference data subscription normally only in a single reply is sent.

Subscription request.

A subscription request can send only a single subscription key.

Examples:

{
  "msg" : "Subscription",
  "ts" : 1669032206385873,
  "seqn" : 177,
  "op" : "sub",
  "reqId" : 1,
  "stream" : "BestBidAsk",
  "pattern" : "BTC*"
}

{
  "msg" : "Subscription",
  "ts" : 1669032206385873,
  "seqn" : 177,
  "op" : "unsub",
  "stream" : "OrderbookSnapshot",
  "pattern" : "BTC*",
  "depth" : 10
}

Name Type Mandatory Description
msg string Y Message type: “Subscription”
ts timestamp [usec] Y Client's timestamp (microseconds)
seqn int64 Y Client's sequence number (max: 16 digits)
op string Y Operation: “sub”, “unsub”
reqId int32 N Subscription request id
stream string Y Stream name
pattern string Y Symbol's pattern
interval int32 N Interval (Kline subscription only), available intervals [sec]: 1, 60, 300, 900, 1800, 3600, 14400, 86400
depth int32 N Order book snapshot depth (OrderbookSnapshot subscription only): 5, 10, 20

Subscription reply.

A subscription reply may indicate the success or error.

Examples:

{
  "msg" : "SubscriptionReply",
  "ts" : 1669032206385873,
  "seqn" : 277,
  "reqId" : 1,
  "op" : "sub",
  "stream" : "OrderbookSnapshot",
  "pattern" : "BTCU*",
  "depth" : 20,
  "result" : "success”
}

{
  "msg" : "SubscriptionReply",
  "ts" : 1669032206385873,
  "seqn" : 277,
  "op" : "unsub",
  "stream" : "Kline",
  "pattern" : "BTCUS",
  "interval" : 3600,
  "result" : "error",
  "errCode" : 48,
  "errMessage" : "Invalid subscription: pattern=BTCUS"
}
Name Type Mandatory Description
msg string Y Message type: “SubscriptionReply”
ts timestamp [usec] Y Message generation timestamp (microseconds)
seqn int64 Y Exchange sequence number (max: 16 digits)
op string Y Operation: “sub”, “unsub”
reqId int32 N Subscription request id
pattern string Y Symbol's pattern
interval int32 N Interval (Kline subscription only), available intervals [sec]: 1, 60, 300, 900, 1800, 3600, 14400, 86400
depth int32 N Order book snapshot depth (OrderbookSnapshot subscription only): 5, 10, 20
status string Y Operation status: “success”, “error”
errCode int32 N Error code
errMessage string N Error message

Best bid/ask message.

This is a snapshot message. Missing bid/ask side indicates a single sided book.

Examples:

{
  "msg" : "BestBidAsk",
  "ts" : 1669026845496043,
  "streamSeqn" : 10167,
  "seqn" : 16716,
  "symbol" : "BTCUSDT",
  "bidPrice" : "17567.34",
  "bidQty" : "5.76345",
  "askPrice" : "17567.44",
  "askQty" : "4.18456"
}

Name Type Mandatory Description
msg string Y Message name: “BestBidAsk”
ts timestamp [usec] Y Message generation timestamp (microseconds)
streamSeqn int64 N Market data stream sequence number (max: 16 digits)
seqn int64 Y Exchange sequence number (max: 16 digits)
symbol string Y Symbol
bidPrice price N Best bid price
bidQty quantity N Best bid quantity
askPrice price N Best ask price
askQty quantity N Best ask quantity

Trade message.

Individual trade tick message.

Example:

{
  "msg" : "Trade",
  "ts" : 1669030387918824,
  "streamSeqn" : 170167,
  "seqn" : 180444,
  "symbol" : "BTCUSDT",
  "tradeId" : "6690303879188244",
  "tradePrice" : "17567.34",
  "tradeQty" : "1.23978",
  "makerBuyer" : true
}
Name Type Mandatory Description
msg string Y Message name: “Trade”
ts timestamp [usec] Y Message generation timestamp (microseconds)
streamSeqn int64 N Market data stream sequence number (max: 16 digits)
seqn int64 Y Exchange sequence number (max: 16 digits)
symbol string Y Symbol
tradeId int64 Y Unique trade id (max: 16 digits)
tradePrice price Y Trade price
tradeQty quantity Y Trade quantity
makerBuyer boolean Y Maker is a buyer flag

Orderbook snapshot message.

Orderbook snapshot tick message. Supported depths: 5, 10 and 20, which must be specified in the subscription request's “depth” field.

Price level snapshot value: [price, quantity, number of orders].

Examples:

{
  "msg" : "OrderbookSnapshot",
  "ts" : 1669030575242078,
  "streamSeqn" : 170167,
  "seqn" : 189282,
  "symbol" : "BTCUSDT",
  "bids" : [
    ["17567.34","2.01235",4],
    ["17567.25","1.45169",2],
    ...
    ["17239.11","0.95432",6]
  ],
  "asks" : [
    ["17567.56","6.34985",3],
    ["17567.67","1.45169",7],
    ...
    ["17611.11","0.78911",4]
  ]
}

{
  "msg" : "OrderbookSnapshot",
  "ts" : 1669030575242078,
  "streamSeqn" : 170167,
  "seqn" : 189282,
  "symbol" : "BTCUSDT",
  "bids" : [],
  "asks" : []
}
Name Type Mandatory Description
msg string Y Message name: “OrderbookSnapshot”
ts timestamp [usec] Y Message generation timestamp (microseconds)
streamSeqn int64 N Market data stream sequence number (max: 16 digits)
seqn int64 Y Exchange sequence number (max: 16 digits)
symbol string Y Symbol
bids sequence of price levels N Full bid (all price levels) order book
asks sequence of price levels N Full ask (all price levels) order book

Orderbook update message.

Orderbook update (delta) tick message. A snapshot message may be delivered as a sequence of updates reconstructing a whole book, which is indicated via the snapshot flag.

Price level update value: [update command (“n” (new), “c” (change), “d” (delete)), level, price, quantity, number of orders].

Examples:

{
  "msg" : "OrderbookUpdate",
  "ts" : 1669031373575253,
  "streamSeqn" : 170167,
  "seqn" : 226768,
  "symbol" : "BTCUSDT",
  "bids" : [
    ["c", 3, "17567.34","2.01235",4],
    ["d", 1, "0.","0.",0],
    ["n", 5, "17511.16","0.12",1]
  ],
  "asks" : [
    ["d", 0, "0.","0.",0],
    ["n", 2, "17614.77","1.67",1],
    ["c", 1, "17601.56","0.98",2]
  ]
}

{
  "msg" : "OrderbookUpdate",
  "ts" : 1669031373575253,
  "streamSeqn" : 170167,
  "seqn" : 226768,
  "symbol" : "BTCUSDT",
  "bids" : [],
  "asks" : [],
  "snapshot" : true
}

Name Type Mandatory Description
msg string Y Message name: “OrderbookUpdate”
ts timestamp [usec] Y Message generation timestamp (microseconds)
streamSeqn int64 N Market data stream sequence number (max: 16 digits)
seqn int64 Y Exchange sequence number (max: 16 digits)
symbol string Y Symbol
bids sequence of price level updates N Bid order book updates sequence
asks Sequence of price level updates N Ask order book updates sequence
snapshot boolean N Bid and ask books message in a snapshot sequence
snapshotFirst boolean N First snapshot message in a snapshot sequence
snapshotLast boolean N Last snapshot message in a snapshot sequence

State message.

Market/instrument state message. May indicate a whole market or individual instrument state.

Examples:

{
  "msg" : "State",
  "ts" : 1669032206998413,
  "streamSeqn" : 170167,
  "seqn" : 265985,
  "marketState" : "halted"
}

{
  "msg" : "State",
  "ts" : 1669032206998413,
  "streamSeqn" : 170167,
  "seqn" : 265985,
  "symbol" : "BTCUSDT",
  "instrumentState" : "disabled"
}
Name Type Mandatory Description
msg string Y Message name: “State”
ts timestamp [usec] Y Message generation timestamp (microseconds)
streamSeqn int64 N Market data stream sequence number (max: 16 digits)
seqn int64 Y Exchange sequence number (max: 16 digits)
symbol string N Symbol
marketState market state N Market state
instrumentState instrument state N Instrument state

Ticker message.

24 hours sliding window ticker message. The interval is 1 sec.

Example:

{
  "msg" : "Ticker",
  "ts" : 1669032206998413,
  "streamSeqn" : 170167,
  "seqn" : 265977,
  "interval" : 1,
  "symbol" : "BTCUSDT",
  "openPrice" : "20201.15",
  "lastPrice" : "20202.34",
  "highPrice" : "20205.87",
  "lowPrice" : "20199.98",
  "vwap" : "20202.78",
  "numTrades" : 53197,
  "volume" : "3909.78543",
  "quoteVolume" : "4760.48",
  "avgQty" : "0.19852",
  "lastQty" : "3.00329"
}
Name Type Mandatory Description
msg string Y Message name: “Ticker”
ts timestamp [usec] Y Message generation timestamp (microseconds)
streamSeqn int64 N Market data stream sequence number (max: 16 digits)
seqn int64 Y Exchange sequence number (max: 16 digits)
interval int32 Y Message generation interval [secs]
symbol string Y Symbol
openPrice price Y Open traded price
LastPrice price Y Last/close traded price
highPrice price Y Highest traded price
lowPrice price Y Lowest traded price
vwap price Y Volume weighed average price
numTrades int32 Y Number of trades
volume quantity Y Total traded volume
quoteVolume price Y Total traded quote volume
avgQty quantity N Average traded quantity
lastQty quantity N Last trades quantity

Top Trading Stats message.

24 hours sliding window top stats. The interval is 1 minute.

Example:

{
  "msg": "TopTradingStats",
  "ts": 1684416420000000,
  "streamSeqn": 6,
  "seqn": 7,
  "topGainerSymbol": "BTCUSDC",
  "topGainerRelative": "1.3",
  "topLoserSymbol": "ETHUSDC",
  "topLoserRelative": "-0.5",
  "symbol": "BTCUSDC",
  "volume": "100.0"
}
Name Type Mandatory Description
msg string Y Message name: “TopTradingStats”
ts timestamp [usec] Y Message generation timestamp (microseconds)
streamSeqn int64 N Market data stream sequence number (max: 16 digits)
seqn int64 Y Exchange sequence number (max: 16 digits)
topGainerSymbol string Y Best relative increase symbol
topGainerRelative relation Y Best relative increase value
topLoserSymbol string Y Worst relative increase symbol
topLoserRelative relation Y Worst relative increase value
symbol string Y Symbol for top volume
volume quantity Y Top volume, traded in USD

Kline/candlestick message.

Supported intervals: 1 sec, 1 min, 5 mins, 15 mins, 30 mins, 1 hour, 4 hours and 1 day, which must be specified in the subscription request's "interval" field.

Example:

{
  "msg" : "Kline",
  "ts" : 1669032206998413,
  "streamSeqn" : 170167,
  "seqn" : 265977,
  "startTs" : 1669032206000000,
  "endTs" :   1669032207000000,
  "interval" : 60,
  "symbol" : "BTCUSDT",
  "openPrice" : "20201.15",
  "lastPrice" : "20202.34",
  "highPrice" : "20205.87",
  "lowPrice" : "20199.98",
  "numTrades" : 53197,
  "volume" : "3909.78543",
  "quoteVolume" : "4760.48"
}
Name Type Mandatory Description
msg string Y Message name: “Kline”
ts timestamp [usec] Y Message generation timestamp (microseconds)
streamSeqn int64 N Market data stream sequence number (max: 16 digits)
seqn int64 Y Exchange sequence number (max: 16 digits)
startTs timestamp [usec] Y Start of interval timestamp (microseconds)
endTs timestamp [usec] Y End of interval timestamp (microseconds)
interval int32 Y Interval [secs]
symbol string Y Symbol
openPrice price N Open traded price
LastPrice price N Last/close traded price
highPrice price N Highest traded price
lowPrice price N Lowest traded price
numTrades int32 N Number of trades
volume quantity N Total traded volume
quoteVolume price N Total traded quote volume

TotalValueLocked message.

Total value locked message is sent each 5 minutes. It's calculated as deposited-assets - withdrawn-assets. If no withdrawals happened during last 5 minutes, update won't be sent.

Example:

{
  "msg" : "TotalValueLocked",
  "ts" : 1669032206998413,
  "streamSeqn" : 170167,
  "seqn" : 265977,
  "asset" : "BTC",
  "volume" : "2.53747423",
  "volumeNotional" : "110160.12998926"
}
Name Type Mandatory Description
msg string Y Message name: “TotalValueLocked”
ts timestamp [usec] Y Message generation timestamp (microseconds)
streamSeqn int64 N Market data stream sequence number (max: 16 digits)
seqn int64 Y Exchange sequence number (max: 16 digits)
asset string Y Asset short name
volume quantity N Total asset volume in trading engine
volumeNotional price N Total asset volume in USD based on last traded price

Kline/candlestick query.

Supported intervals: 1 sec, 1 min, 5 mins, 15 mins, 30 mins, 1 hour, 4 hours and 1 day.

Example:

{
  "msg" : "KlineQuery",
  "ts" : 1669032206998413,
  "seqn" : 177,
  "startTs" : 1669032206000000,
  "endTs" :   1669032207000000,
  "interval" : 60,
  "symbol" : "BTCUSDT",
  "limit" : 600
}
Name Type Mandatory Description
msg string Y Message name: “KlineQuery”
ts timestamp [usec] Y Message generation timestamp (microseconds)
seqn int64 Y Client's sequence number (max: 16 digits)
startTs timestamp [usec] Y Start of interval timestamp (microseconds)
endTs timestamp [usec] N End of interval timestamp (microseconds)
interval int32 Y Interval [secs]
symbol string Y Symbol
limit int32 N Max number of replies. Max=1000, default=500

Kline/candlestick query reply.

Supported intervals: 1 sec, 1 min, 5 mins, 15 mins, 30 mins, 1 hour, 4 hours and 1 day.

Example:

{
  "msg" : "KlineQueryReply",
  "ts" : 1669031373575253,
  "seqn" : 277,
  "symbol" : "BTCUSDT",
  "interval" : 60,
  "startTs" : 1618930720000000,
  "endTs" : 1618930730000000,
  "limit" : 100,
  "klines" : [
    {
      "startTs" : 1669032206000000,
      "endTs" :   1669032207000000,
      "openPrice" : "20201.15",
      "lastPrice" : "20202.34",
      "highPrice" : "20205.87",
      "lowPrice" : "20199.98",
      "numTrades" : 53197,
      "volume" : "3909.78543",
      "quoteVolume" : "4760.48"
    },
    ...
    {
      ...
    }
  ]
}

{
  "msg" : "KlineQueryReply",
  "ts" : 1618930734676777,
  "seqn" : 277,
  "symbol" : "BTCUSDT",
  "interval" : 60,
  "startTs" : 1618930720000000,
  "endTs" : 1618930730000000,
  "limit" : 100,
  "errCode": 91,
  "errMessage": "Undefined instrument: no symbol matches pattern"
}

Name Type Mandatory Description
msg string Y Message name: “KlineQueryReply”
ts timestamp [usec] Y Message generation timestamp (microseconds)
seqn int64 Y Exchange sequence number (max: 16 digits)
startTs timestamp [usec] Y Start of interval timestamp (microseconds)
endTs timestamp [usec] N End of interval timestamp (microseconds)
interval int32 Y Interval [secs]
symbol string Y Symbol
limit int32 N Max number of replies. Max=1000, default=500
klines array of “Kline” N Array of “Kline” messages. The “ts”, “symbol” and “interval” are not provided in an individual elements of array, because they are equal to the corresponding message values
errCode int32 N Error code
errMessage string N Error message

Last Traded Price query.

Example:

{
  "msg" : "LastTradedPriceQuery",
  "ts" : 1687166942000000,
  "seqn" : 1,
  "pattern" : "BTCUSDC"
}
Name Type Mandatory Description
msg string Y Message name: LastTradedPriceQuery
ts timestamp [usec] Y Message generation timestamp (microseconds)
seqn int64 Y Client's sequence number (max: 16 digits)
pattern string Y Symbol
includeDisabled boolean N Include disabled instruments, False by default.

Last Traded Price query reply.

Example:

{
  "msg" : "LastTradedPriceQueryReply",
  "ts" : 1669031373575253,
  "seqn" : 277,
  "ltps":[["HTDNAUSDC","0.1"],["BNBUSDC","312.6"],["MATICUSDC","0.8623"],
    ["UNIUSDC","5.137"],["ETHUSDC","1820.86"],["HTICPUSDC","5.273"],
    ["SHIBUSDC","0.00000883"],["HTCKBTCBTC","1.0"],["HTCKBTCUSDC","26981.69"],
    ["BTCUSDC","35000.0"]]
}

{
  "msg":"LastTradedPriceQueryReply",
  "ts":1701811711767566,
  "seqn":3,
  "ltps":[["BTCUSDC","50000.0"]]
}

Name Type Mandatory Description
msg string Y Message name: LastTradedPriceQueryReply
ts timestamp [usec] Y Message generation timestamp (microseconds)
seqn int64 Y Exchange sequence number (max: 16 digits)
ltps array of ltps N Array of ltp messages. LTP message is a pair [symbol, price]
errCode int32 N Error code
errMessage string N Error message

Trade query.

Example:

{
  "msg" : "TradeQuery",
  "startTs" : 1704964200003000,
  "symbol" : "BTCUSDC",
  "ts" : 1704967801006000,
  "seqn" : 7
}
Name Type Mandatory Description
msg string Y Message name: TradeQuery
ts timestamp [usec] Y Message generation timestamp (microseconds)
seqn int64 Y Client's sequence number (max: 16 digits)
symbol string Y Symbol
startTs timestamp [usec] N Start of interval timestamp (microseconds)
endTs timestamp [usec] N End of interval timestamp (microseconds)
limit int32 N Max number of trades. Max=1000, default=500

Trade query reply.

Example:

{
  "msg":"TradeQueryReply",
  "ts":1704967801006000,
  "seqn":3,
  "symbol":"BTCUSDC",
  "limit":2,
  "trades":[
    {"msg":"Trade","ts":1704816146215083,"symbol":"BTCUSDC","tradeId":"7048161462150829","tradePrice":"61964.0","tradeQty":"0.00008","makerBuyer":true},
    {"msg":"Trade","ts":1704816146215083,"symbol":"BTCUSDC","tradeId":"7048161462150830","tradePrice":"61964.0","tradeQty":"0.00006","makerBuyer":true}
  ]
}

{
  "msg":"TradeQueryReply",
  "ts":1704967801006000,
  "seqn":1,
  "symbol":"ICPUSDC",
  "startTs":1704964200003000,
  "errCode":59,
  "errMessage":"Invalid query: invalid symbol=ICPUSDC"
}

Name Type Mandatory Description
msg string Y Message name: TradeQueryReply
ts timestamp [usec] Y Message generation timestamp (microseconds)
seqn int64 Y Exchange sequence number (max: 16 digits)
trades array of trades N Array of trade messages
startTs timestamp [usec] N Start of interval timestamp (microseconds)
endTs timestamp [usec] N End of interval timestamp (microseconds)
limit int32 N Max number of trades. Max=1000, default=500
errCode int32 N Error code
errMessage string N Error message

Instruments reference data request.

Provides reference/static data for all instruments.

Example:

{
  "msg": "Symbols",
  "ts": 1670341183180611,
  "seqn" : 177,
  "pattern": "BTC*"
}
Name Type Mandatory Description
msg string Y Message name: “Symbols”
ts timestamp [usec] Y Client's timestamp (microseconds)
seqn int64 Y Client's sequence number (max: 16 digits)
pattern strings Y Symbol's pattern
includeDisabled boolean N Include disabled instruments, False by default.

Instruments reference data reply.

Provides reference/static data for all instruments.

Examples:

{
  "msg": "SymbolsReply",
  "ts": 1670350617040913,
  "seqn" : 277,
  "pattern" : "BTC*",
  "symbols": [
    {
      "symbol": "BTCUSDT",
      "base": "BTC",
      "quote": "USDT",
      "tickSize": "0.01",
      "lotSize": "0.00001",
      "minNotional": "10.0",
      "minQty": "0.00001",
      "maxQty": "100000.0",
      "maxOrders": 200,
      "type": "spot"
    }
  ]
}

{
  "msg": "SymbolsReply",
  "ts": 1670350617040913,
  "seqn" : 277,
  "pattern" : "BU*",
  "errCode": 91,
  "errMessage": "Undefined instrument: no symbol matches pattern"
}
Name Type Mandatory Description
msg string Y Message name: “SymbolsReply”
ts timestamp [usec] Y Message generation timestamp (microseconds)
seqn int64 Y Exchange sequence number (max: 16 digits)
pattern strings Y Symbol's pattern
base string Y Base asset
quote string Y Quote asset
tickSize double Y Tick size
lotSize double Y Lot size
minNotional price Y Min order notional value
maxQty quantity Y Max order quantity
minQty quantity Y Min order quantity
maxOrders int32 Y Max open orders for a client
type instrument type Y Instrument type
errCode int32 N Error code
errMessage string N Error message
enabled boolean N Field not presented for querying only enabled instruments

Error message.

Examples:

{
  "msg" : "Error",
  "ts" : 1618930734676777,
  "seqn" : 277,
  "errCode": 46,
  "errMessage": "Missing mandatory field: symbol",
  "refMsg" : "KlineQuery",
  "refSeqn" : 177
}
Name Type Mandatory Description
msg string Y Message type: “Error”
ts timestamp [usec] Y Message generation timestamp (microseconds)
seqn int64 Y Exchange sequence number (max: 16 digits)
errCode int32 N Error code
errMessage string N Error message
refMsg string N Referenced message type
refSeqn int64 N Referenced client's sequence number (max: 16 digits)

Types.

Instrument type (as string).

Market state (as string).

Instrument state (as string).

Errors

The Kittn API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The kitten requested is hidden for administrators only.
404 Not Found -- The specified kitten could not be found.
405 Method Not Allowed -- You tried to access a kitten with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The kitten requested has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You're requesting too many kittens! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.