Skip to content

Market Data Websocket

Request Format

Subscription to the following streams all follow this payload format:

{
    "stream": streamName,
    "feed": [feed1, feed2], // feed3, feed4, ...
    "method": "subscribe",
    "is_full": true
}

streamName is listed below each of the streams.

feed is an array of of instruments that you would like to subscribe to, combined with stream specific options ("Feed Selector") joined together by -. For example, BTC_USDT_Perp@500 for the mini.s stream denotes "BTC_USDT_Perp" at a rate of 500ms; BTC_USDT_Perp@500-10-10 for the book.s stream denotes "BTC_USDT_Perp" at a rate of 500ms, with a depth of 10 and an aggregation of 10.

is_full is a boolean that denotes whether a "full" stream or "lite" stream will be returned.

Response Format

The response format for each of the streams is as follows:

{
    "stream": streamName,
    "subs": [feed1, feed2], // feed3, feed4, ...
    "unsubs": [feed5, feed6], // feed7, feed8, ...
}

streamName is the name of the stream that was specified in the request.

subs is an array of instruments that have been successfully subscribed to the stream. Example, ['BTC_USDT_Perp', 'ETH_USDT_Perp'].

unsubs is an array of instruments that have been unsubscribed from the stream as a result of the subscription. This can happen as an example of subscribing to the same instruments at a different frequency -- instruments of the same type will be unsubscribed from the previous frequency.

MiniTicker Snapshot Stream

Subscribes to a mini ticker feed for a single instrument. To experience higher publishing rates, please use the mini.d channel. Unlike the mini.d channel which publishes an initial snapshot, then only streams deltas after, the mini.s channel publishes full snapshots at each feed.

Stream Name: mini.s
Feed Selector Example: BTC_USDT_Perp@500

Gravity reserves the rights to degrade publishing rate if system is overwhelmed

MiniTicker Feed Selector
Name Lite Type Description
instrument i string The readable name of the instrument. For Perpetual: ETH_USDT_Perp [Underlying Quote Perp]
For Future: BTC_USDT_Fut_20Oct23 [Underlying Quote Fut DateFormat]
For Call: ETH_USDT_Call_20Oct23_4123 [Underlying Quote Call DateFormat StrikePrice]
For Put: ETH_USDT_Put_20Oct23_4123 [Underlying Quote Put DateFormat StrikePrice]
rate r uint32 The minimal rate at which we publish feeds (in milliseconds)
Delta (raw, 50, 100, 200, 500, 1000, 5000)
Snapshot (200, 500, 1000, 5000)
MiniTicker Data Schema
Name Lite Type Description
stream s string Stream name
sequence_number sn uint64 A running sequence number that determines global message order within the specific stream
feed f MiniTicker A mini ticker matching the request filter
MiniTicker
Name Lite Type Description
event_time et Timestamp Time at which the event was emitted in unix nanoseconds
instrument i string The readable name of the instrument. For Perpetual: ETH_USDT_Perp [Underlying Quote Perp]
For Future: BTC_USDT_Fut_20Oct23 [Underlying Quote Fut DateFormat]
For Call: ETH_USDT_Call_20Oct23_4123 [Underlying Quote Call DateFormat StrikePrice]
For Put: ETH_USDT_Put_20Oct23_4123 [Underlying Quote Put DateFormat StrikePrice]
mark_price mp uint64 The mark price of the instrument, expressed in 9 decimals
index_price ip uint64 The index price of the instrument, expressed in 9 decimals
last_price lp uint64 The last traded price of the instrument (also close price), expressed in 9 decimals
last_size ls uint64 The number of assets traded in the last trade, expressed in underlying asset decimal units
mid_price mp1 uint64 The mid price of the instrument, expressed in 9 decimals
best_bid_price bb uint64 The best bid price of the instrument, expressed in 9 decimals
best_bid_size bb1 uint64 The number of assets offered on the best bid price of the instrument, expressed in underlying asset decimal units
best_ask_price ba uint64 The best ask price of the instrument, expressed in 9 decimals
best_ask_size ba1 uint64 The number of assets offered on the best ask price of the instrument, expressed in underlying asset decimal units

Example

// Example 1
{
    "stream": "mini.s",
    "sequence_number": 1234,
    "feed": {
        "event_time": "1631250820000000",
        "instrument": "BTC_USDT_Perp",
        "mark_price": "34796400000", // 34796.40 USDT
        "index_price": "34796380000", // 34796.38 USDT
        "last_price": "34796430000", // 34796.43 USDT
        "last_size": "4500000000", // 4.5 BTC
        "mid_price": "34796380000", // 34796.38 USDT
        "best_bid_price": "34796560000", // 34796.56 USDT
        "best_bid_size": "76500000000", // 76.5 BTC
        "best_bid_num_orders": 46, // 46 orders at best bid level
        "best_ask_price": "34796200000", // 34796.20 USDT
        "best_ask_size": "34500000000", // 34.5 BTC
        "best_ask_num_orders": 24, // 24 orders at best bid level
    }
}
Code Number Description
INVALID_INSTRUMENT 1001 The instrument supplied is not supported by our exchange
INVALID_RATE 1007 The rate specified is invalid
Generic System Errors

We Adopt the GRPC error code system.

Failed API calls always return an error code. In some APIs, API level error codes will also be returned.

{
    "code": 3,
    "msg":"INVALID_ARGUMENT",
    "api_code": 1001,
    "api_msg": "INVALID_TIME_IN_FORCE"
}
Code Number Description
OK 0 Not an error; returned on success.
CANCELLED 1 The operation was cancelled, typically by the caller.
UNKNOWN 2 Unknown error. For example, this error may be returned when a Status value received from another address space belongs to an error space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error.
INVALID_ARGUMENT 3 The client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name).
DEADLINE_EXCEEDED 4 The deadline expired before the operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long
NOT_FOUND 5 Some requested entity (e.g., file or directory) was not found. Note to server developers: if a request is denied for an entire class of users, such as gradual feature rollout or undocumented allowlist, NOT_FOUND may be used. If a request is denied for some users within a class of users, such as user-based access control, PERMISSION_DENIED must be used.
ALREADY_EXISTS 6 The entity that a client attempted to create (e.g., file or directory) already exists.
PERMISSION_DENIED 7 The caller does not have permission to execute the specified operation. PERMISSION_DENIED must not be used for rejections caused by exhausting some resource (use RESOURCE_EXHAUSTED instead for those errors). PERMISSION_DENIED must not be used if the caller can not be identified (use UNAUTHENTICATED instead for those errors). This error code does not imply the request is valid or the requested entity exists or satisfies other pre-conditions.
RESOURCE_EXHAUSTED 8 Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
FAILED_PRECONDITION 9 The operation was rejected because the system is not in a state required for the operation's execution. For example, the directory to be deleted is non-empty, an rmdir operation is applied to a non-directory, etc. Service implementors can use the following guidelines to decide between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE: (a) Use UNAVAILABLE if the client can retry just the failing call. (b) Use ABORTED if the client should retry at a higher level (e.g., when a client-specified test-and-set fails, indicating the client should restart a read-modify-write sequence). (c) Use FAILED_PRECONDITION if the client should not retry until the system state has been explicitly fixed. E.g., if an "rmdir" fails because the directory is non-empty, FAILED_PRECONDITION should be returned since the client should not retry unless the files are deleted from the directory.
ABORTED 10 The operation was aborted, typically due to a concurrency issue such as a sequencer check failure or transaction abort. See the guidelines above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.
OUT_OF_RANGE 11 The operation was attempted past the valid range. E.g., seeking or reading past end-of-file. Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generate INVALID_ARGUMENT if asked to read at an offset that is not in the range [0,2^32-1], but it will generate OUT_OF_RANGE if asked to read from an offset past the current file size. There is a fair bit of overlap between FAILED_PRECONDITION and OUT_OF_RANGE. We recommend using OUT_OF_RANGE (the more specific error) when it applies so that callers who are iterating through a space can easily look for an OUT_OF_RANGE error to detect when they are done.
UNIMPLEMENTED 12 The operation is not implemented or is not supported/enabled in this service.
INTERNAL 13 Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors.
UNAVAILABLE 14 The service is currently unavailable. This is most likely a transient condition, which can be corrected by retrying with a backoff. Note that it is not always safe to retry non-idempotent operations.
DATA_LOSS 15 Unrecoverable data loss or corruption.
UNAUTHENTICATED 16 The request does not have valid authentication credentials for the operation.

MiniTicker Delta Stream

Subscribes to a ticker feed for a single instrument, with raw (zero delay) publishing rates. This channel is the most performant way to consume ticker updates. It submits an initial snapshot with the current ticker state, then submits a delta feed after. Use the Ticker snapshot feed for a more convenient (but less performant) consumption experience.

The Delta feed will work as follows:

  • Fields will only be published they changed since the last feed
  • For optional fields, an explicit field = null will be published to unset the field
  • If fields are missing, assume that they have not been updated
Stream Name: mini.d
Feed Selector Example: BTC_USDT_Perp@500

Gravity reserves the rights to degrade publishing rate if system is overwhelmed

MiniTicker Feed Selector
Name Lite Type Description
instrument i string The readable name of the instrument. For Perpetual: ETH_USDT_Perp [Underlying Quote Perp]
For Future: BTC_USDT_Fut_20Oct23 [Underlying Quote Fut DateFormat]
For Call: ETH_USDT_Call_20Oct23_4123 [Underlying Quote Call DateFormat StrikePrice]
For Put: ETH_USDT_Put_20Oct23_4123 [Underlying Quote Put DateFormat StrikePrice]
rate r uint32 The minimal rate at which we publish feeds (in milliseconds)
Delta (raw, 50, 100, 200, 500, 1000, 5000)
Snapshot (200, 500, 1000, 5000)
MiniTicker Data Schema
Name Lite Type Description
stream s string Stream name
sequence_number sn uint64 A running sequence number that determines global message order within the specific stream
feed f MiniTicker A mini ticker matching the request filter
MiniTicker
Name Lite Type Description
event_time et Timestamp Time at which the event was emitted in unix nanoseconds
instrument i string The readable name of the instrument. For Perpetual: ETH_USDT_Perp [Underlying Quote Perp]
For Future: BTC_USDT_Fut_20Oct23 [Underlying Quote Fut DateFormat]
For Call: ETH_USDT_Call_20Oct23_4123 [Underlying Quote Call DateFormat StrikePrice]
For Put: ETH_USDT_Put_20Oct23_4123 [Underlying Quote Put DateFormat StrikePrice]
mark_price mp uint64 The mark price of the instrument, expressed in 9 decimals
index_price ip uint64 The index price of the instrument, expressed in 9 decimals
last_price lp uint64 The last traded price of the instrument (also close price), expressed in 9 decimals
last_size ls uint64 The number of assets traded in the last trade, expressed in underlying asset decimal units
mid_price mp1 uint64 The mid price of the instrument, expressed in 9 decimals
best_bid_price bb uint64 The best bid price of the instrument, expressed in 9 decimals
best_bid_size bb1 uint64 The number of assets offered on the best bid price of the instrument, expressed in underlying asset decimal units
best_ask_price ba uint64 The best ask price of the instrument, expressed in 9 decimals
best_ask_size ba1 uint64 The number of assets offered on the best ask price of the instrument, expressed in underlying asset decimal units

Example

// Example 1
{
    "stream": "mini.d",
    "sequence_number": 1234,
    "feed": {
        "event_time": "1631250820000000",
        "instrument": "BTC_USDT_Perp",
        "mark_price": "34796400000", // 34796.40 USDT
        "index_price": "34796380000", // 34796.38 USDT
        "last_price": "34796430000", // 34796.43 USDT
        "last_size": "4500000000", // 4.5 BTC
        "mid_price": "34796380000", // 34796.38 USDT
        "best_bid_price": "34796560000", // 34796.56 USDT
        "best_bid_size": "76500000000", // 76.5 BTC
        "best_bid_num_orders": 46, // 46 orders at best bid level
        "best_ask_price": "34796200000", // 34796.20 USDT
        "best_ask_size": "34500000000", // 34.5 BTC
        "best_ask_num_orders": 24, // 24 orders at best bid level
    }
}
Code Number Description
INVALID_INSTRUMENT 1001 The instrument supplied is not supported by our exchange
INVALID_RATE 1007 The rate specified is invalid
Generic System Errors

We Adopt the GRPC error code system.

Failed API calls always return an error code. In some APIs, API level error codes will also be returned.

{
    "code": 3,
    "msg":"INVALID_ARGUMENT",
    "api_code": 1001,
    "api_msg": "INVALID_TIME_IN_FORCE"
}
Code Number Description
OK 0 Not an error; returned on success.
CANCELLED 1 The operation was cancelled, typically by the caller.
UNKNOWN 2 Unknown error. For example, this error may be returned when a Status value received from another address space belongs to an error space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error.
INVALID_ARGUMENT 3 The client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name).
DEADLINE_EXCEEDED 4 The deadline expired before the operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long
NOT_FOUND 5 Some requested entity (e.g., file or directory) was not found. Note to server developers: if a request is denied for an entire class of users, such as gradual feature rollout or undocumented allowlist, NOT_FOUND may be used. If a request is denied for some users within a class of users, such as user-based access control, PERMISSION_DENIED must be used.
ALREADY_EXISTS 6 The entity that a client attempted to create (e.g., file or directory) already exists.
PERMISSION_DENIED 7 The caller does not have permission to execute the specified operation. PERMISSION_DENIED must not be used for rejections caused by exhausting some resource (use RESOURCE_EXHAUSTED instead for those errors). PERMISSION_DENIED must not be used if the caller can not be identified (use UNAUTHENTICATED instead for those errors). This error code does not imply the request is valid or the requested entity exists or satisfies other pre-conditions.
RESOURCE_EXHAUSTED 8 Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
FAILED_PRECONDITION 9 The operation was rejected because the system is not in a state required for the operation's execution. For example, the directory to be deleted is non-empty, an rmdir operation is applied to a non-directory, etc. Service implementors can use the following guidelines to decide between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE: (a) Use UNAVAILABLE if the client can retry just the failing call. (b) Use ABORTED if the client should retry at a higher level (e.g., when a client-specified test-and-set fails, indicating the client should restart a read-modify-write sequence). (c) Use FAILED_PRECONDITION if the client should not retry until the system state has been explicitly fixed. E.g., if an "rmdir" fails because the directory is non-empty, FAILED_PRECONDITION should be returned since the client should not retry unless the files are deleted from the directory.
ABORTED 10 The operation was aborted, typically due to a concurrency issue such as a sequencer check failure or transaction abort. See the guidelines above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.
OUT_OF_RANGE 11 The operation was attempted past the valid range. E.g., seeking or reading past end-of-file. Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generate INVALID_ARGUMENT if asked to read at an offset that is not in the range [0,2^32-1], but it will generate OUT_OF_RANGE if asked to read from an offset past the current file size. There is a fair bit of overlap between FAILED_PRECONDITION and OUT_OF_RANGE. We recommend using OUT_OF_RANGE (the more specific error) when it applies so that callers who are iterating through a space can easily look for an OUT_OF_RANGE error to detect when they are done.
UNIMPLEMENTED 12 The operation is not implemented or is not supported/enabled in this service.
INTERNAL 13 Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors.
UNAVAILABLE 14 The service is currently unavailable. This is most likely a transient condition, which can be corrected by retrying with a backoff. Note that it is not always safe to retry non-idempotent operations.
DATA_LOSS 15 Unrecoverable data loss or corruption.
UNAUTHENTICATED 16 The request does not have valid authentication credentials for the operation.

Ticker Snapshot Stream

Subscribes to a ticker feed for a single instrument. To experience higher publishing rates, please use the ticker.d channel. Unlike the ticker.d channel which publishes an initial snapshot, then only streams deltas after, the ticker.s channel publishes full snapshots at each feed.

Stream Name: ticker.s
Feed Selector Example: BTC_USDT_Perp@500

Gravity reserves the rights to degrade publishing rate if system is overwhelmed

Ticker Feed Selector
Name Lite Type Description
instrument i string The readable name of the instrument. For Perpetual: ETH_USDT_Perp [Underlying Quote Perp]
For Future: BTC_USDT_Fut_20Oct23 [Underlying Quote Fut DateFormat]
For Call: ETH_USDT_Call_20Oct23_4123 [Underlying Quote Call DateFormat StrikePrice]
For Put: ETH_USDT_Put_20Oct23_4123 [Underlying Quote Put DateFormat StrikePrice]
rate r uint32 The minimal rate at which we publish feeds (in milliseconds)
Delta (100, 200, 500, 1000, 5000)
Snapshot (500, 1000, 5000)
Ticker Data Schema
Name Lite Type Description
stream s string Stream name
sequence_number sn uint64 A running sequence number that determines global message order within the specific stream
feed f Ticker A ticker matching the request filter
Ticker

Derived data such as the below, will not be included by default:
- 24 hour volume (buyVolume + sellVolume)
- 24 hour taker buy/sell ratio (buyVolume / sellVolume)
- 24 hour average trade price (volumeQ / volumeU)
- 24 hour average trade volume (volume / trades)
- 24 hour percentage change (24hStatChange / 24hStat)
- 48 hour statistics (2 * 24hStat - 24hStatChange)

To query for an extended ticker payload, leverage the greeks and the derived flags.
Ticker extensions are currently under design to offer you more convenience.
These flags are only supported on the Ticker Snapshot WS endpoint, and on the Ticker API endpoint.

Name Lite Type Description
event_time et Timestamp Time at which the event was emitted in unix nanoseconds
instrument i string The readable name of the instrument. For Perpetual: ETH_USDT_Perp [Underlying Quote Perp]
For Future: BTC_USDT_Fut_20Oct23 [Underlying Quote Fut DateFormat]
For Call: ETH_USDT_Call_20Oct23_4123 [Underlying Quote Call DateFormat StrikePrice]
For Put: ETH_USDT_Put_20Oct23_4123 [Underlying Quote Put DateFormat StrikePrice]
mark_price mp uint64 The mark price of the instrument, expressed in 9 decimals
index_price ip uint64 The index price of the instrument, expressed in 9 decimals
last_price lp uint64 The last traded price of the instrument (also close price), expressed in 9 decimals
last_size ls uint64 The number of assets traded in the last trade, expressed in underlying asset decimal units
mid_price mp1 uint64 The mid price of the instrument, expressed in 9 decimals
best_bid_price bb uint64 The best bid price of the instrument, expressed in 9 decimals
best_bid_size bb1 uint64 The number of assets offered on the best bid price of the instrument, expressed in underlying asset decimal units
best_ask_price ba uint64 The best ask price of the instrument, expressed in 9 decimals
best_ask_size ba1 uint64 The number of assets offered on the best ask price of the instrument, expressed in underlying asset decimal units
funding_rate_curr fr int32 The current funding rate of the instrument, expressed in centibeeps (1/100th of a basis point)
funding_rate_avg fr1 int32 The average funding rate of the instrument (over last 8h), expressed in centibeeps (1/100th of a basis point)
interest_rate ir int32 The interest rate of the underlying, expressed in centibeeps (1/100th of a basis point)
forward_price fp uint64 [Options] The forward price of the option, expressed in 9 decimals
buy_volume_u bv uint64 The 24 hour taker buy volume of the instrument, expressed in underlying asset decimal units
sell_volume_u sv uint64 The 24 hour taker sell volume of the instrument, expressed in underlying asset decimal units
buy_volume_q bv1 uint64 The 24 hour taker buy volume of the instrument, expressed in quote asset decimal units
sell_volume_q sv1 uint64 The 24 hour taker sell volume of the instrument, expressed in quote asset decimal units
high_price hp uint64 The 24 hour highest traded price of the instrument, expressed in 9 decimals
low_price lp1 uint64 The 24 hour lowest traded price of the instrument, expressed in 9 decimals
open_price op uint64 The 24 hour first traded price of the instrument, expressed in 9 decimals
open_interest oi uint64 The open interest in the instrument, expressed in underlying asset decimal units
long_short_ratio ls1 float32 The ratio of accounts that are net long vs net short on this instrument

Example

// Example 1
{
    "stream": "ticker.s",
    "sequence_number": 1234,
    "feed": {
        "event_time": "1631250820000000",
        "instrument": "BTC_USDT_Perp",
        "mark_price": "34796400000", // 34796.40 USDT
        "index_price": "34796380000", // 34796.38 USDT
        "last_price": "34796430000", // 34796.43 USDT
        "last_size": "4500000000", // 4.5 BTC
        "mid_price": "34796380000", // 34796.38 USDT
        "best_bid_price": "34796560000", // 34796.56 USDT
        "best_bid_size": "76500000000", // 76.5 BTC
        "best_bid_num_orders": 46, // 46 orders at best bid level
        "best_ask_price": "34796200000", // 34796.20 USDT
        "best_ask_size": "34500000000", // 34.5 BTC
        "best_ask_num_orders": 24, // 24 orders at best bid level
        "volume": "5934500000000", // 5934.5 BTC traded in last 24 hours
        "volume_change": -0.07, // 7% fall in 24 hour trading volume
        "quote_volume": "206496862523000", // 206,496,862.52 USDT traded in last 24 hours
        "quote_volume_change": 0.03, // 3% rise in 24 hour quote trading volume
        "taker_buy_trades": 2353, // 2353 taker buy trades in last 24 hours
        "taker_buy_trades_change": 0.08,
        "maker_buy_trades": 1858, // 1858 maker buy trades in last 24 hours
        "maker_buy_trades_change": -0.02,
        "high_price": "34996380000", // 34996.38 USDT
        "low_price": "34496380000", // 34496.38 USDT
        "next_funding_rate": "5200000", // 5.2 USDT
        "next_funding_at": "1631250820000000",
        "open_interest": "5934500000000", // 5934.5 BTC of open interest
        "num_trades": 4211,
        "num_trades_change": 0.14,
        "taker_buy_sell_ratio": 0.5587746379,
        "taker_buy_sell_ratio_change": 0.32,
        "avg_price": 34796000088, // 34796.00 USDT
        "avg_price_change": -0.1,
        "avg_volume": 1409285205, // 1.41 BTC
        "avg_volume_change": -0.23,
    }
}
Code Number Description
INVALID_INSTRUMENT 1001 The instrument supplied is not supported by our exchange
INVALID_RATE 1007 The rate specified is invalid
Generic System Errors

We Adopt the GRPC error code system.

Failed API calls always return an error code. In some APIs, API level error codes will also be returned.

{
    "code": 3,
    "msg":"INVALID_ARGUMENT",
    "api_code": 1001,
    "api_msg": "INVALID_TIME_IN_FORCE"
}
Code Number Description
OK 0 Not an error; returned on success.
CANCELLED 1 The operation was cancelled, typically by the caller.
UNKNOWN 2 Unknown error. For example, this error may be returned when a Status value received from another address space belongs to an error space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error.
INVALID_ARGUMENT 3 The client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name).
DEADLINE_EXCEEDED 4 The deadline expired before the operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long
NOT_FOUND 5 Some requested entity (e.g., file or directory) was not found. Note to server developers: if a request is denied for an entire class of users, such as gradual feature rollout or undocumented allowlist, NOT_FOUND may be used. If a request is denied for some users within a class of users, such as user-based access control, PERMISSION_DENIED must be used.
ALREADY_EXISTS 6 The entity that a client attempted to create (e.g., file or directory) already exists.
PERMISSION_DENIED 7 The caller does not have permission to execute the specified operation. PERMISSION_DENIED must not be used for rejections caused by exhausting some resource (use RESOURCE_EXHAUSTED instead for those errors). PERMISSION_DENIED must not be used if the caller can not be identified (use UNAUTHENTICATED instead for those errors). This error code does not imply the request is valid or the requested entity exists or satisfies other pre-conditions.
RESOURCE_EXHAUSTED 8 Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
FAILED_PRECONDITION 9 The operation was rejected because the system is not in a state required for the operation's execution. For example, the directory to be deleted is non-empty, an rmdir operation is applied to a non-directory, etc. Service implementors can use the following guidelines to decide between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE: (a) Use UNAVAILABLE if the client can retry just the failing call. (b) Use ABORTED if the client should retry at a higher level (e.g., when a client-specified test-and-set fails, indicating the client should restart a read-modify-write sequence). (c) Use FAILED_PRECONDITION if the client should not retry until the system state has been explicitly fixed. E.g., if an "rmdir" fails because the directory is non-empty, FAILED_PRECONDITION should be returned since the client should not retry unless the files are deleted from the directory.
ABORTED 10 The operation was aborted, typically due to a concurrency issue such as a sequencer check failure or transaction abort. See the guidelines above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.
OUT_OF_RANGE 11 The operation was attempted past the valid range. E.g., seeking or reading past end-of-file. Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generate INVALID_ARGUMENT if asked to read at an offset that is not in the range [0,2^32-1], but it will generate OUT_OF_RANGE if asked to read from an offset past the current file size. There is a fair bit of overlap between FAILED_PRECONDITION and OUT_OF_RANGE. We recommend using OUT_OF_RANGE (the more specific error) when it applies so that callers who are iterating through a space can easily look for an OUT_OF_RANGE error to detect when they are done.
UNIMPLEMENTED 12 The operation is not implemented or is not supported/enabled in this service.
INTERNAL 13 Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors.
UNAVAILABLE 14 The service is currently unavailable. This is most likely a transient condition, which can be corrected by retrying with a backoff. Note that it is not always safe to retry non-idempotent operations.
DATA_LOSS 15 Unrecoverable data loss or corruption.
UNAUTHENTICATED 16 The request does not have valid authentication credentials for the operation.

Ticker Delta Stream

Subscribes to a ticker feed for a single instrument, with raw (zero delay) publishing rates. This channel is the most performant way to consume ticker updates. It submits an initial snapshot with the current ticker state, then submits a delta feed after. Use the Ticker snapshot feed for a more convenient (but less performant) consumption experience.

The Delta feed will work as follows:

  • Fields will only be published they changed since the last feed
  • For optional fields, an explicit field = null will be published to unset the field
  • If fields are missing, assume that they have not been updated
Stream Name: ticker.d
Feed Selector Example: BTC_USDT_Perp@500

Gravity reserves the rights to degrade publishing rate if system is overwhelmed

Ticker Feed Selector
Name Lite Type Description
instrument i string The readable name of the instrument. For Perpetual: ETH_USDT_Perp [Underlying Quote Perp]
For Future: BTC_USDT_Fut_20Oct23 [Underlying Quote Fut DateFormat]
For Call: ETH_USDT_Call_20Oct23_4123 [Underlying Quote Call DateFormat StrikePrice]
For Put: ETH_USDT_Put_20Oct23_4123 [Underlying Quote Put DateFormat StrikePrice]
rate r uint32 The minimal rate at which we publish feeds (in milliseconds)
Delta (100, 200, 500, 1000, 5000)
Snapshot (500, 1000, 5000)
Ticker Data Schema
Name Lite Type Description
stream s string Stream name
sequence_number sn uint64 A running sequence number that determines global message order within the specific stream
feed f Ticker A ticker matching the request filter
Ticker

Derived data such as the below, will not be included by default:
- 24 hour volume (buyVolume + sellVolume)
- 24 hour taker buy/sell ratio (buyVolume / sellVolume)
- 24 hour average trade price (volumeQ / volumeU)
- 24 hour average trade volume (volume / trades)
- 24 hour percentage change (24hStatChange / 24hStat)
- 48 hour statistics (2 * 24hStat - 24hStatChange)

To query for an extended ticker payload, leverage the greeks and the derived flags.
Ticker extensions are currently under design to offer you more convenience.
These flags are only supported on the Ticker Snapshot WS endpoint, and on the Ticker API endpoint.

Name Lite Type Description
event_time et Timestamp Time at which the event was emitted in unix nanoseconds
instrument i string The readable name of the instrument. For Perpetual: ETH_USDT_Perp [Underlying Quote Perp]
For Future: BTC_USDT_Fut_20Oct23 [Underlying Quote Fut DateFormat]
For Call: ETH_USDT_Call_20Oct23_4123 [Underlying Quote Call DateFormat StrikePrice]
For Put: ETH_USDT_Put_20Oct23_4123 [Underlying Quote Put DateFormat StrikePrice]
mark_price mp uint64 The mark price of the instrument, expressed in 9 decimals
index_price ip uint64 The index price of the instrument, expressed in 9 decimals
last_price lp uint64 The last traded price of the instrument (also close price), expressed in 9 decimals
last_size ls uint64 The number of assets traded in the last trade, expressed in underlying asset decimal units
mid_price mp1 uint64 The mid price of the instrument, expressed in 9 decimals
best_bid_price bb uint64 The best bid price of the instrument, expressed in 9 decimals
best_bid_size bb1 uint64 The number of assets offered on the best bid price of the instrument, expressed in underlying asset decimal units
best_ask_price ba uint64 The best ask price of the instrument, expressed in 9 decimals
best_ask_size ba1 uint64 The number of assets offered on the best ask price of the instrument, expressed in underlying asset decimal units
funding_rate_curr fr int32 The current funding rate of the instrument, expressed in centibeeps (1/100th of a basis point)
funding_rate_avg fr1 int32 The average funding rate of the instrument (over last 8h), expressed in centibeeps (1/100th of a basis point)
interest_rate ir int32 The interest rate of the underlying, expressed in centibeeps (1/100th of a basis point)
forward_price fp uint64 [Options] The forward price of the option, expressed in 9 decimals
buy_volume_u bv uint64 The 24 hour taker buy volume of the instrument, expressed in underlying asset decimal units
sell_volume_u sv uint64 The 24 hour taker sell volume of the instrument, expressed in underlying asset decimal units
buy_volume_q bv1 uint64 The 24 hour taker buy volume of the instrument, expressed in quote asset decimal units
sell_volume_q sv1 uint64 The 24 hour taker sell volume of the instrument, expressed in quote asset decimal units
high_price hp uint64 The 24 hour highest traded price of the instrument, expressed in 9 decimals
low_price lp1 uint64 The 24 hour lowest traded price of the instrument, expressed in 9 decimals
open_price op uint64 The 24 hour first traded price of the instrument, expressed in 9 decimals
open_interest oi uint64 The open interest in the instrument, expressed in underlying asset decimal units
long_short_ratio ls1 float32 The ratio of accounts that are net long vs net short on this instrument

Example

// Example 1
{
    "stream": "ticker.d",
    "sequence_number": 1234,
    "feed": {
        "event_time": "1631250820000000",
        "instrument": "BTC_USDT_Perp",
        "mark_price": "34796400000", // 34796.40 USDT
        "index_price": "34796380000", // 34796.38 USDT
        "last_price": "34796430000", // 34796.43 USDT
        "last_size": "4500000000", // 4.5 BTC
        "mid_price": "34796380000", // 34796.38 USDT
        "best_bid_price": "34796560000", // 34796.56 USDT
        "best_bid_size": "76500000000", // 76.5 BTC
        "best_bid_num_orders": 46, // 46 orders at best bid level
        "best_ask_price": "34796200000", // 34796.20 USDT
        "best_ask_size": "34500000000", // 34.5 BTC
        "best_ask_num_orders": 24, // 24 orders at best bid level
        "volume": "5934500000000", // 5934.5 BTC traded in last 24 hours
        "volume_change": -0.07, // 7% fall in 24 hour trading volume
        "quote_volume": "206496862523000", // 206,496,862.52 USDT traded in last 24 hours
        "quote_volume_change": 0.03, // 3% rise in 24 hour quote trading volume
        "taker_buy_trades": 2353, // 2353 taker buy trades in last 24 hours
        "taker_buy_trades_change": 0.08,
        "maker_buy_trades": 1858, // 1858 maker buy trades in last 24 hours
        "maker_buy_trades_change": -0.02,
        "high_price": "34996380000", // 34996.38 USDT
        "low_price": "34496380000", // 34496.38 USDT
        "next_funding_rate": "5200000", // 5.2 USDT
        "next_funding_at": "1631250820000000",
        "open_interest": "5934500000000", // 5934.5 BTC of open interest
        "num_trades": 4211,
        "num_trades_change": 0.14,
        "taker_buy_sell_ratio": 0.5587746379,
        "taker_buy_sell_ratio_change": 0.32,
        "avg_price": 34796000088, // 34796.00 USDT
        "avg_price_change": -0.1,
        "avg_volume": 1409285205, // 1.41 BTC
        "avg_volume_change": -0.23,
    }
}
Code Number Description
INVALID_INSTRUMENT 1001 The instrument supplied is not supported by our exchange
INVALID_RATE 1007 The rate specified is invalid
Generic System Errors

We Adopt the GRPC error code system.

Failed API calls always return an error code. In some APIs, API level error codes will also be returned.

{
    "code": 3,
    "msg":"INVALID_ARGUMENT",
    "api_code": 1001,
    "api_msg": "INVALID_TIME_IN_FORCE"
}
Code Number Description
OK 0 Not an error; returned on success.
CANCELLED 1 The operation was cancelled, typically by the caller.
UNKNOWN 2 Unknown error. For example, this error may be returned when a Status value received from another address space belongs to an error space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error.
INVALID_ARGUMENT 3 The client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name).
DEADLINE_EXCEEDED 4 The deadline expired before the operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long
NOT_FOUND 5 Some requested entity (e.g., file or directory) was not found. Note to server developers: if a request is denied for an entire class of users, such as gradual feature rollout or undocumented allowlist, NOT_FOUND may be used. If a request is denied for some users within a class of users, such as user-based access control, PERMISSION_DENIED must be used.
ALREADY_EXISTS 6 The entity that a client attempted to create (e.g., file or directory) already exists.
PERMISSION_DENIED 7 The caller does not have permission to execute the specified operation. PERMISSION_DENIED must not be used for rejections caused by exhausting some resource (use RESOURCE_EXHAUSTED instead for those errors). PERMISSION_DENIED must not be used if the caller can not be identified (use UNAUTHENTICATED instead for those errors). This error code does not imply the request is valid or the requested entity exists or satisfies other pre-conditions.
RESOURCE_EXHAUSTED 8 Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
FAILED_PRECONDITION 9 The operation was rejected because the system is not in a state required for the operation's execution. For example, the directory to be deleted is non-empty, an rmdir operation is applied to a non-directory, etc. Service implementors can use the following guidelines to decide between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE: (a) Use UNAVAILABLE if the client can retry just the failing call. (b) Use ABORTED if the client should retry at a higher level (e.g., when a client-specified test-and-set fails, indicating the client should restart a read-modify-write sequence). (c) Use FAILED_PRECONDITION if the client should not retry until the system state has been explicitly fixed. E.g., if an "rmdir" fails because the directory is non-empty, FAILED_PRECONDITION should be returned since the client should not retry unless the files are deleted from the directory.
ABORTED 10 The operation was aborted, typically due to a concurrency issue such as a sequencer check failure or transaction abort. See the guidelines above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.
OUT_OF_RANGE 11 The operation was attempted past the valid range. E.g., seeking or reading past end-of-file. Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generate INVALID_ARGUMENT if asked to read at an offset that is not in the range [0,2^32-1], but it will generate OUT_OF_RANGE if asked to read from an offset past the current file size. There is a fair bit of overlap between FAILED_PRECONDITION and OUT_OF_RANGE. We recommend using OUT_OF_RANGE (the more specific error) when it applies so that callers who are iterating through a space can easily look for an OUT_OF_RANGE error to detect when they are done.
UNIMPLEMENTED 12 The operation is not implemented or is not supported/enabled in this service.
INTERNAL 13 Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors.
UNAVAILABLE 14 The service is currently unavailable. This is most likely a transient condition, which can be corrected by retrying with a backoff. Note that it is not always safe to retry non-idempotent operations.
DATA_LOSS 15 Unrecoverable data loss or corruption.
UNAUTHENTICATED 16 The request does not have valid authentication credentials for the operation.

Orderbook Snapshot Stream

Subscribes to aggregated book updates for a single instrument, with a maximum depth of 50 levels. To query for deeper depths, and experience higher publishing rates, please use the book.d channel. Unlike the book.d channel which publishes an initial snapshot, then only streams deltas after, the book.s channel publishes full snapshots at each feed.

Stream Name: book.s
Feed Selector Example: BTC_USDT_Perp@500-10-10
Orderbook Feed Selector
Name Lite Type Description
instrument i string The readable name of the instrument. For Perpetual: ETH_USDT_Perp [Underlying Quote Perp]
For Future: BTC_USDT_Fut_20Oct23 [Underlying Quote Fut DateFormat]
For Call: ETH_USDT_Call_20Oct23_4123 [Underlying Quote Call DateFormat StrikePrice]
For Put: ETH_USDT_Put_20Oct23_4123 [Underlying Quote Put DateFormat StrikePrice]
rate r uint32 The minimal rate at which we publish feeds (in milliseconds)
Delta (100, 200, 500, 1000, 5000)
Snapshot (500, 1000, 5000)
depth d uint32 Depth of the order book to be retrieved (API/Snapshot max is 100, Delta max is 1000)
aggregate a uint32 The number of levels to aggregate into one level (1 = no aggregation, 10/100/1000 = aggregate 10/100/1000 levels into 1)
Orderbook Data Schema
Name Lite Type Description
stream s string Stream name
sequence_number sn uint64 A running sequence number that determines global message order within the specific stream
feed f OrderbookLevels An orderbook levels object matching the request filter
OrderbookLevels
Name Lite Type Description
event_time et Timestamp Time at which the event was emitted in unix nanoseconds
instrument i string The readable name of the instrument. For Perpetual: ETH_USDT_Perp [Underlying Quote Perp]
For Future: BTC_USDT_Fut_20Oct23 [Underlying Quote Fut DateFormat]
For Call: ETH_USDT_Call_20Oct23_4123 [Underlying Quote Call DateFormat StrikePrice]
For Put: ETH_USDT_Put_20Oct23_4123 [Underlying Quote Put DateFormat StrikePrice]
bids b [OrderbookLevel] The list of best bids up till query depth
asks a [OrderbookLevel] The list of best asks up till query depth
OrderbookLevel
Name Lite Type Description
price p uint64 The price of the level, expressed in 9 decimals
size s uint64 The number of assets offered, expressed in underlying asset decimal units
num_orders no uint32 The number of open orders at this level

Example

{
    "stream": "book.s",
    "sequence_number": 1234,
    "feed": [
        {
            "event_time": "1631250820000000",
            "instrument": "BTC_USDT_Perp",
            "bids": [
                {
                    "price": "34796400000", // 34796.40 USDT
                    "size": "76500000000", // 76.5 BTC
                    "num_orders": 13
                },
                {
                    "price": "34796410000", // 34796.41 USDT
                    "size": "78500000000", // 78.5 BTC
                    "num_orders": 14
                }
                {
                    "price": "34796430000", // 34796.43 USDT
                    "size": "126500000000", // 126.5 BTC
                    "num_orders": 15
                }
            ],
            "asks": [
                {
                    "price": "34796390000", // 34796.39 USDT
                    "size": "79500000000", // 79.5 BTC
                    "num_orders": 14
                },
                {
                    "price": "34796380000", // 34796.38 USDT
                    "size": "96500000000", // 96.5 BTC
                    "num_orders": 12
                }
                {
                    "price": "34796370000", // 34796.37 USDT
                    "size": "134500000000", // 134.5 BTC
                    "num_orders": 17
                }
            ]
        }
    ]
}
Code Number Description
INVALID_INSTRUMENT 1001 The instrument supplied is not supported by our exchange
INVALID_DEPTH 1006 The depth specified is invalid
INVALID_RATE 1007 The rate specified is invalid
Generic System Errors

We Adopt the GRPC error code system.

Failed API calls always return an error code. In some APIs, API level error codes will also be returned.

{
    "code": 3,
    "msg":"INVALID_ARGUMENT",
    "api_code": 1001,
    "api_msg": "INVALID_TIME_IN_FORCE"
}
Code Number Description
OK 0 Not an error; returned on success.
CANCELLED 1 The operation was cancelled, typically by the caller.
UNKNOWN 2 Unknown error. For example, this error may be returned when a Status value received from another address space belongs to an error space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error.
INVALID_ARGUMENT 3 The client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name).
DEADLINE_EXCEEDED 4 The deadline expired before the operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long
NOT_FOUND 5 Some requested entity (e.g., file or directory) was not found. Note to server developers: if a request is denied for an entire class of users, such as gradual feature rollout or undocumented allowlist, NOT_FOUND may be used. If a request is denied for some users within a class of users, such as user-based access control, PERMISSION_DENIED must be used.
ALREADY_EXISTS 6 The entity that a client attempted to create (e.g., file or directory) already exists.
PERMISSION_DENIED 7 The caller does not have permission to execute the specified operation. PERMISSION_DENIED must not be used for rejections caused by exhausting some resource (use RESOURCE_EXHAUSTED instead for those errors). PERMISSION_DENIED must not be used if the caller can not be identified (use UNAUTHENTICATED instead for those errors). This error code does not imply the request is valid or the requested entity exists or satisfies other pre-conditions.
RESOURCE_EXHAUSTED 8 Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
FAILED_PRECONDITION 9 The operation was rejected because the system is not in a state required for the operation's execution. For example, the directory to be deleted is non-empty, an rmdir operation is applied to a non-directory, etc. Service implementors can use the following guidelines to decide between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE: (a) Use UNAVAILABLE if the client can retry just the failing call. (b) Use ABORTED if the client should retry at a higher level (e.g., when a client-specified test-and-set fails, indicating the client should restart a read-modify-write sequence). (c) Use FAILED_PRECONDITION if the client should not retry until the system state has been explicitly fixed. E.g., if an "rmdir" fails because the directory is non-empty, FAILED_PRECONDITION should be returned since the client should not retry unless the files are deleted from the directory.
ABORTED 10 The operation was aborted, typically due to a concurrency issue such as a sequencer check failure or transaction abort. See the guidelines above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.
OUT_OF_RANGE 11 The operation was attempted past the valid range. E.g., seeking or reading past end-of-file. Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generate INVALID_ARGUMENT if asked to read at an offset that is not in the range [0,2^32-1], but it will generate OUT_OF_RANGE if asked to read from an offset past the current file size. There is a fair bit of overlap between FAILED_PRECONDITION and OUT_OF_RANGE. We recommend using OUT_OF_RANGE (the more specific error) when it applies so that callers who are iterating through a space can easily look for an OUT_OF_RANGE error to detect when they are done.
UNIMPLEMENTED 12 The operation is not implemented or is not supported/enabled in this service.
INTERNAL 13 Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors.
UNAVAILABLE 14 The service is currently unavailable. This is most likely a transient condition, which can be corrected by retrying with a backoff. Note that it is not always safe to retry non-idempotent operations.
DATA_LOSS 15 Unrecoverable data loss or corruption.
UNAUTHENTICATED 16 The request does not have valid authentication credentials for the operation.

Orderbook Delta Stream

Subscribes to aggregated book updates for a single instrument, with a maximum depth of 1000 levels. This channel is the most performant way to consume orderbook updates. It submits an initial snapshot with the current orderbook state, then submits a delta feed after. Use the Orderbook snapshot feed for a more convenient (but less performant) consumption experience.

When Orderbook trends upwards/downwards:

  • Incoming levels will be published as soon as price moves
  • Outgoing levels will be published with amount = 0
Stream Name: book.d
Feed Selector Example: BTC_USDT_Perp@500-10-10
Orderbook Feed Selector
Name Lite Type Description
instrument i string The readable name of the instrument. For Perpetual: ETH_USDT_Perp [Underlying Quote Perp]
For Future: BTC_USDT_Fut_20Oct23 [Underlying Quote Fut DateFormat]
For Call: ETH_USDT_Call_20Oct23_4123 [Underlying Quote Call DateFormat StrikePrice]
For Put: ETH_USDT_Put_20Oct23_4123 [Underlying Quote Put DateFormat StrikePrice]
rate r uint32 The minimal rate at which we publish feeds (in milliseconds)
Delta (100, 200, 500, 1000, 5000)
Snapshot (500, 1000, 5000)
depth d uint32 Depth of the order book to be retrieved (API/Snapshot max is 100, Delta max is 1000)
aggregate a uint32 The number of levels to aggregate into one level (1 = no aggregation, 10/100/1000 = aggregate 10/100/1000 levels into 1)
Orderbook Data Schema
Name Lite Type Description
stream s string Stream name
sequence_number sn uint64 A running sequence number that determines global message order within the specific stream
feed f OrderbookLevels An orderbook levels object matching the request filter
OrderbookLevels
Name Lite Type Description
event_time et Timestamp Time at which the event was emitted in unix nanoseconds
instrument i string The readable name of the instrument. For Perpetual: ETH_USDT_Perp [Underlying Quote Perp]
For Future: BTC_USDT_Fut_20Oct23 [Underlying Quote Fut DateFormat]
For Call: ETH_USDT_Call_20Oct23_4123 [Underlying Quote Call DateFormat StrikePrice]
For Put: ETH_USDT_Put_20Oct23_4123 [Underlying Quote Put DateFormat StrikePrice]
bids b [OrderbookLevel] The list of best bids up till query depth
asks a [OrderbookLevel] The list of best asks up till query depth
OrderbookLevel
Name Lite Type Description
price p uint64 The price of the level, expressed in 9 decimals
size s uint64 The number of assets offered, expressed in underlying asset decimal units
num_orders no uint32 The number of open orders at this level

Example

{
    "stream": "book.d",
    "sequence_number": 1234,
    "feed": [
        {
            "event_time": "1631250820000000",
            "instrument": "BTC_USDT_Perp",
            "bids": [
                {
                    "price": "34796400000", // 34796.40 USDT
                    "size": "76500000000", // 76.5 BTC
                    "num_orders": 13
                },
                {
                    "price": "34796410000", // 34796.41 USDT
                    "size": "78500000000", // 78.5 BTC
                    "num_orders": 14
                }
                {
                    "price": "34796430000", // 34796.43 USDT
                    "size": "126500000000", // 126.5 BTC
                    "num_orders": 15
                }
            ],
            "asks": [
                {
                    "price": "34796390000", // 34796.39 USDT
                    "size": "79500000000", // 79.5 BTC
                    "num_orders": 14
                },
                {
                    "price": "34796380000", // 34796.38 USDT
                    "size": "96500000000", // 96.5 BTC
                    "num_orders": 12
                }
                {
                    "price": "34796370000", // 34796.37 USDT
                    "size": "134500000000", // 134.5 BTC
                    "num_orders": 17
                }
            ]
        }
    ]
}
Code Number Description
INVALID_INSTRUMENT 1001 The instrument supplied is not supported by our exchange
INVALID_DEPTH 1006 The depth specified is invalid
INVALID_RATE 1007 The rate specified is invalid
Generic System Errors

We Adopt the GRPC error code system.

Failed API calls always return an error code. In some APIs, API level error codes will also be returned.

{
    "code": 3,
    "msg":"INVALID_ARGUMENT",
    "api_code": 1001,
    "api_msg": "INVALID_TIME_IN_FORCE"
}
Code Number Description
OK 0 Not an error; returned on success.
CANCELLED 1 The operation was cancelled, typically by the caller.
UNKNOWN 2 Unknown error. For example, this error may be returned when a Status value received from another address space belongs to an error space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error.
INVALID_ARGUMENT 3 The client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name).
DEADLINE_EXCEEDED 4 The deadline expired before the operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long
NOT_FOUND 5 Some requested entity (e.g., file or directory) was not found. Note to server developers: if a request is denied for an entire class of users, such as gradual feature rollout or undocumented allowlist, NOT_FOUND may be used. If a request is denied for some users within a class of users, such as user-based access control, PERMISSION_DENIED must be used.
ALREADY_EXISTS 6 The entity that a client attempted to create (e.g., file or directory) already exists.
PERMISSION_DENIED 7 The caller does not have permission to execute the specified operation. PERMISSION_DENIED must not be used for rejections caused by exhausting some resource (use RESOURCE_EXHAUSTED instead for those errors). PERMISSION_DENIED must not be used if the caller can not be identified (use UNAUTHENTICATED instead for those errors). This error code does not imply the request is valid or the requested entity exists or satisfies other pre-conditions.
RESOURCE_EXHAUSTED 8 Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
FAILED_PRECONDITION 9 The operation was rejected because the system is not in a state required for the operation's execution. For example, the directory to be deleted is non-empty, an rmdir operation is applied to a non-directory, etc. Service implementors can use the following guidelines to decide between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE: (a) Use UNAVAILABLE if the client can retry just the failing call. (b) Use ABORTED if the client should retry at a higher level (e.g., when a client-specified test-and-set fails, indicating the client should restart a read-modify-write sequence). (c) Use FAILED_PRECONDITION if the client should not retry until the system state has been explicitly fixed. E.g., if an "rmdir" fails because the directory is non-empty, FAILED_PRECONDITION should be returned since the client should not retry unless the files are deleted from the directory.
ABORTED 10 The operation was aborted, typically due to a concurrency issue such as a sequencer check failure or transaction abort. See the guidelines above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.
OUT_OF_RANGE 11 The operation was attempted past the valid range. E.g., seeking or reading past end-of-file. Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generate INVALID_ARGUMENT if asked to read at an offset that is not in the range [0,2^32-1], but it will generate OUT_OF_RANGE if asked to read from an offset past the current file size. There is a fair bit of overlap between FAILED_PRECONDITION and OUT_OF_RANGE. We recommend using OUT_OF_RANGE (the more specific error) when it applies so that callers who are iterating through a space can easily look for an OUT_OF_RANGE error to detect when they are done.
UNIMPLEMENTED 12 The operation is not implemented or is not supported/enabled in this service.
INTERNAL 13 Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors.
UNAVAILABLE 14 The service is currently unavailable. This is most likely a transient condition, which can be corrected by retrying with a backoff. Note that it is not always safe to retry non-idempotent operations.
DATA_LOSS 15 Unrecoverable data loss or corruption.
UNAUTHENTICATED 16 The request does not have valid authentication credentials for the operation.

Recent Trades Stream

Subscribes to a stream of Recent Trades for an instrument.

Stream Name: trade
Feed Selector Example: BTC_USDT_Perp@500
RecentTrades Feed Selector
Name Lite Type Description
instrument i string The readable name of the instrument. For Perpetual: ETH_USDT_Perp [Underlying Quote Perp]
For Future: BTC_USDT_Fut_20Oct23 [Underlying Quote Fut DateFormat]
For Call: ETH_USDT_Call_20Oct23_4123 [Underlying Quote Call DateFormat StrikePrice]
For Put: ETH_USDT_Put_20Oct23_4123 [Underlying Quote Put DateFormat StrikePrice]
limit l int32 The limit to query for. Defaults to 500; Max 1000
RecentTrades Data Schema

Example

{
    "stream": "trade",
    "sequence_number": 1234,
    "feed": [
        {
            "event_time": "1631250820000000",
            "instrument": "BTC_USDT_Perp",
            "is_taker_buyer": true,
            "size": "4500000000", // 4.5 BTC
            "price": "34796430000", // 34796.43 USDT
            "mark_price": "34796400000", // 34796.40 USDT
            "trade_id": 374382,
            "venue": "ORDERBOOK"
        }
    ]
}
Code Number Description
INVALID_INSTRUMENT 1001 The instrument supplied is not supported by our exchange
Generic System Errors

We Adopt the GRPC error code system.

Failed API calls always return an error code. In some APIs, API level error codes will also be returned.

{
    "code": 3,
    "msg":"INVALID_ARGUMENT",
    "api_code": 1001,
    "api_msg": "INVALID_TIME_IN_FORCE"
}
Code Number Description
OK 0 Not an error; returned on success.
CANCELLED 1 The operation was cancelled, typically by the caller.
UNKNOWN 2 Unknown error. For example, this error may be returned when a Status value received from another address space belongs to an error space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error.
INVALID_ARGUMENT 3 The client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name).
DEADLINE_EXCEEDED 4 The deadline expired before the operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long
NOT_FOUND 5 Some requested entity (e.g., file or directory) was not found. Note to server developers: if a request is denied for an entire class of users, such as gradual feature rollout or undocumented allowlist, NOT_FOUND may be used. If a request is denied for some users within a class of users, such as user-based access control, PERMISSION_DENIED must be used.
ALREADY_EXISTS 6 The entity that a client attempted to create (e.g., file or directory) already exists.
PERMISSION_DENIED 7 The caller does not have permission to execute the specified operation. PERMISSION_DENIED must not be used for rejections caused by exhausting some resource (use RESOURCE_EXHAUSTED instead for those errors). PERMISSION_DENIED must not be used if the caller can not be identified (use UNAUTHENTICATED instead for those errors). This error code does not imply the request is valid or the requested entity exists or satisfies other pre-conditions.
RESOURCE_EXHAUSTED 8 Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
FAILED_PRECONDITION 9 The operation was rejected because the system is not in a state required for the operation's execution. For example, the directory to be deleted is non-empty, an rmdir operation is applied to a non-directory, etc. Service implementors can use the following guidelines to decide between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE: (a) Use UNAVAILABLE if the client can retry just the failing call. (b) Use ABORTED if the client should retry at a higher level (e.g., when a client-specified test-and-set fails, indicating the client should restart a read-modify-write sequence). (c) Use FAILED_PRECONDITION if the client should not retry until the system state has been explicitly fixed. E.g., if an "rmdir" fails because the directory is non-empty, FAILED_PRECONDITION should be returned since the client should not retry unless the files are deleted from the directory.
ABORTED 10 The operation was aborted, typically due to a concurrency issue such as a sequencer check failure or transaction abort. See the guidelines above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.
OUT_OF_RANGE 11 The operation was attempted past the valid range. E.g., seeking or reading past end-of-file. Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generate INVALID_ARGUMENT if asked to read at an offset that is not in the range [0,2^32-1], but it will generate OUT_OF_RANGE if asked to read from an offset past the current file size. There is a fair bit of overlap between FAILED_PRECONDITION and OUT_OF_RANGE. We recommend using OUT_OF_RANGE (the more specific error) when it applies so that callers who are iterating through a space can easily look for an OUT_OF_RANGE error to detect when they are done.
UNIMPLEMENTED 12 The operation is not implemented or is not supported/enabled in this service.
INTERNAL 13 Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors.
UNAVAILABLE 14 The service is currently unavailable. This is most likely a transient condition, which can be corrected by retrying with a backoff. Note that it is not always safe to retry non-idempotent operations.
DATA_LOSS 15 Unrecoverable data loss or corruption.
UNAUTHENTICATED 16 The request does not have valid authentication credentials for the operation.

Trade Candlestick Stream

Historical queries are not yet supported

Subscribes to a stream of Kline/Candlestick updates for an instrument. A Kline is uniquely identified by its open time. A new Kline is published every 250 milliseconds (if it exists).

Stream Name: candle
Feed Selector Example: BTC_USDT_Perp@ci1m-mark
Candlestick Feed Selector
Name Lite Type Description
instrument i string The readable name of the instrument. For Perpetual: ETH_USDT_Perp [Underlying Quote Perp]
For Future: BTC_USDT_Fut_20Oct23 [Underlying Quote Fut DateFormat]
For Call: ETH_USDT_Call_20Oct23_4123 [Underlying Quote Call DateFormat StrikePrice]
For Put: ETH_USDT_Put_20Oct23_4123 [Underlying Quote Put DateFormat StrikePrice]
interval i1 CandlestickInterval The interval of each candlestick
type t CandlestickType The type of candlestick data to retrieve
CandlestickInterval

CandlestickInterval:

  • CI_1_M = 1: 1 minute
  • CI_3_M = 2: 3 minutes
  • CI_5_M = 3: 5 minutes
  • CI_15_M = 4: 15 minutes
  • CI_30_M = 5: 30 minutes
  • CI_1_H = 6: 1 hour
  • CI_2_H = 7: 2 hour
  • CI_4_H = 8: 4 hour
  • CI_6_H = 9: 6 hour
  • CI_8_H = 10: 8 hour
  • CI_12_H = 11: 12 hour
  • CI_1_D = 12: 1 day
  • CI_3_D = 13: 3 days
  • CI_5_D = 14: 5 days
  • CI_1_W = 15: 1 week
  • CI_2_W = 16: 2 weeks
  • CI_3_W = 17: 3 weeks
  • CI_4_W = 18: 4 weeks

CandlestickType

CandlestickType:

  • TRADE = 1: Tracks traded prices
  • MARK = 2: Tracks mark prices
  • INDEX = 3: Tracks index prices
  • MID = 4: Tracks book mid prices

Candlestick Feed Data
Name Lite Type Description
stream s string Stream name
sequence_number sn uint64 A running sequence number that determines global message order within the specific stream
feed f Candlestick A candlestick entry matching the request filters
Candlestick
Name Lite Type Description
open_time ot Timestamp Open time of kline bar in unix nanoseconds
close_time ct Timestamp Close time of kline bar in unix nanosecond
open o uint64 The open price, expressed in base currency resolution units
close c uint64 The close price, expressed in base currency resolution units
high h uint64 The high price, expressed in base currency resolution units
low l uint64 The low price, expressed in base currency resolution units
volume_u vu uint64 The underlying volume transacted, expressed in underlying asset decimal units
volume_q vq uint64 The quote volume transacted, expressed in quote asset decimal units
trades t uint32 The number of trades transacted
instrument i string The readable name of the instrument. For Perpetual: ETH_USDT_Perp [Underlying Quote Perp]
For Future: BTC_USDT_Fut_20Oct23 [Underlying Quote Fut DateFormat]
For Call: ETH_USDT_Call_20Oct23_4123 [Underlying Quote Call DateFormat StrikePrice]
For Put: ETH_USDT_Put_20Oct23_4123 [Underlying Quote Put DateFormat StrikePrice]

Example

{
    "stream": "candle",
    "sequence_number": 1234,
    "feed": {
        "open_time": "1631250810000000",
        "close_time": "1631250820000000",
        "open": "100005",
        "close": "100004",
        "high": "100015",
        "low": "100003",
        "volume": "148976",
        "base_volume": "1520020",
        "trades": 324
    }
}
Code Number Description
INVALID_INSTRUMENT 1001 The instrument supplied is not supported by our exchange
INVALID_INTERVAL 1003 The interval specified is invalid
Generic System Errors

We Adopt the GRPC error code system.

Failed API calls always return an error code. In some APIs, API level error codes will also be returned.

{
    "code": 3,
    "msg":"INVALID_ARGUMENT",
    "api_code": 1001,
    "api_msg": "INVALID_TIME_IN_FORCE"
}
Code Number Description
OK 0 Not an error; returned on success.
CANCELLED 1 The operation was cancelled, typically by the caller.
UNKNOWN 2 Unknown error. For example, this error may be returned when a Status value received from another address space belongs to an error space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error.
INVALID_ARGUMENT 3 The client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name).
DEADLINE_EXCEEDED 4 The deadline expired before the operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long
NOT_FOUND 5 Some requested entity (e.g., file or directory) was not found. Note to server developers: if a request is denied for an entire class of users, such as gradual feature rollout or undocumented allowlist, NOT_FOUND may be used. If a request is denied for some users within a class of users, such as user-based access control, PERMISSION_DENIED must be used.
ALREADY_EXISTS 6 The entity that a client attempted to create (e.g., file or directory) already exists.
PERMISSION_DENIED 7 The caller does not have permission to execute the specified operation. PERMISSION_DENIED must not be used for rejections caused by exhausting some resource (use RESOURCE_EXHAUSTED instead for those errors). PERMISSION_DENIED must not be used if the caller can not be identified (use UNAUTHENTICATED instead for those errors). This error code does not imply the request is valid or the requested entity exists or satisfies other pre-conditions.
RESOURCE_EXHAUSTED 8 Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
FAILED_PRECONDITION 9 The operation was rejected because the system is not in a state required for the operation's execution. For example, the directory to be deleted is non-empty, an rmdir operation is applied to a non-directory, etc. Service implementors can use the following guidelines to decide between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE: (a) Use UNAVAILABLE if the client can retry just the failing call. (b) Use ABORTED if the client should retry at a higher level (e.g., when a client-specified test-and-set fails, indicating the client should restart a read-modify-write sequence). (c) Use FAILED_PRECONDITION if the client should not retry until the system state has been explicitly fixed. E.g., if an "rmdir" fails because the directory is non-empty, FAILED_PRECONDITION should be returned since the client should not retry unless the files are deleted from the directory.
ABORTED 10 The operation was aborted, typically due to a concurrency issue such as a sequencer check failure or transaction abort. See the guidelines above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.
OUT_OF_RANGE 11 The operation was attempted past the valid range. E.g., seeking or reading past end-of-file. Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generate INVALID_ARGUMENT if asked to read at an offset that is not in the range [0,2^32-1], but it will generate OUT_OF_RANGE if asked to read from an offset past the current file size. There is a fair bit of overlap between FAILED_PRECONDITION and OUT_OF_RANGE. We recommend using OUT_OF_RANGE (the more specific error) when it applies so that callers who are iterating through a space can easily look for an OUT_OF_RANGE error to detect when they are done.
UNIMPLEMENTED 12 The operation is not implemented or is not supported/enabled in this service.
INTERNAL 13 Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors.
UNAVAILABLE 14 The service is currently unavailable. This is most likely a transient condition, which can be corrected by retrying with a backoff. Note that it is not always safe to retry non-idempotent operations.
DATA_LOSS 15 Unrecoverable data loss or corruption.
UNAUTHENTICATED 16 The request does not have valid authentication credentials for the operation.