Skip to content

Market Data APIs

All requests should be made using the POST HTTP method.

For example:

curl -X POST https://market-data.testnet.grvt.io/lite/v1/instrument -d '{"i":"BTC_USDT_Perp"}'

Get Instrument

Retrieves a single instrument from GRVT.

FULL ENDPOINT: full/v1/instrument
LITE ENDPOINT: lite/v1/instrument
GetInstrumentRequest

Fetch a single instrument by supplying the asset or instrument name

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]
instrument_name in string The readable name of the instrument
GetInstrumentResponse
Name Lite Type Description
results r Instrument The instrument matching the request asset
Instrument
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]
instrument_name in string The readable name of the instrument
venues v [Venue] Venues that this instrument can be traded at
settlement_period sp InstrumentSettlementPeriod The settlement period of the instrument
underlying_decimals ud int8 The smallest denomination of the underlying asset supported by GRVT (+3 represents 0.001, -3 represents 1000, 0 represents 1)
quote_decimals qd int8 The smallest denomination of the quote asset supported by GRVT (+3 represents 0.001, -3 represents 1000, 0 represents 1)
tick_size ts uint64 The size of a single tick, expressed in quote asset decimal units
min_size ms uint64 The minimum contract size, expressed in underlying asset decimal units
min_block_trade_size mb uint64 The minimum block trade size, expressed in underlying asset decimal units
create_time ct Timestamp Creation time in unix nanoseconds
Venue

The list of Trading Venues that are supported on the GRVT exchange
Venue:

  • ORDERBOOK = 1: the trade is cleared on the orderbook venue
  • RFQ = 2: the trade is cleared on the RFQ venue
  • AXE = 3: the trade is cleared on the AXE venue

InstrumentSettlementPeriod

InstrumentSettlementPeriod:

  • PERPETUAL = 1: Instrument settles through perpetual hourly funding cycles
  • DAILY = 2: Instrument settles at an expiry date, marked as a daily instrument
  • WEEKLY = 3: Instrument settles at an expiry date, marked as a weekly instrument
  • MONTHLY = 4: Instrument settles at an expiry date, marked as a monthly instrument
  • QUARTERLY = 5: Instrument settles at an expiry date, marked as a quarterly instrument

Example

{
    "instrument": "BTC_USDT_Perp",
}

Example

{
    "results": {
        "instrument": "BTC_USDT_Perp",
        "instrument_name": "BTC_USDT_Perp",
        "venues": ["ORDERBOOK", "RFQ"],
        "settlement_period": "PERPETUAL",
        "underlying_decimals": 9,
        "quote_decimals": 6,
        "tick_size": 100000, // 0.1 USDT (6 quote decimals)
        "min_size": 1000, // 0.00001 BTC (9 underlying decimals)
        "min_block_size": 5000000000, // 5 BTC (9 underlying decimals)
        "create_time": "1631250800103000"
    }
}
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.

Get Instruments

Retrieves a list of instruments from GRVT based on supplied filters.

FULL ENDPOINT: full/v1/instruments
LITE ENDPOINT: lite/v1/instruments
GetInstrumentsRequest
Name Lite Type Description
kind k [Kind] The kind filter to apply. If nil, this defaults to all kinds. Otherwise, only entries matching the filter will be returned
underlying u [Currency] The underlying filter to apply. If nil, this defaults to all underlyings. Otherwise, only entries matching the filter will be returned
quote q [Currency] The quote filter to apply. If nil, this defaults to all quotes. Otherwise, only entries matching the filter will be returned
is_active ia bool Request for active instruments only
limit l int32 The limit to query for. Defaults to 500; Max 100000
Kind

The list of asset kinds that are supported on the GRVT exchange
Kind:

  • PERPETUAL = 1: the perpetual asset kind
  • FUTURE = 2: the future asset kind
  • CALL = 3: the call option asset kind
  • PUT = 4: the put option asset kind

Currency

The list of Currencies that are supported on the GRVT exchange
Currency:

  • USDC = 2: the USDC token
  • USDT = 3: the USDT token
  • ETH = 4: the ETH token
  • BTC = 5: the BTC token

GetInstrumentsResponse
Name Lite Type Description
results r [Instrument] The instruments matching the request filter
Instrument
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]
instrument_name in string The readable name of the instrument
venues v [Venue] Venues that this instrument can be traded at
settlement_period sp InstrumentSettlementPeriod The settlement period of the instrument
underlying_decimals ud int8 The smallest denomination of the underlying asset supported by GRVT (+3 represents 0.001, -3 represents 1000, 0 represents 1)
quote_decimals qd int8 The smallest denomination of the quote asset supported by GRVT (+3 represents 0.001, -3 represents 1000, 0 represents 1)
tick_size ts uint64 The size of a single tick, expressed in quote asset decimal units
min_size ms uint64 The minimum contract size, expressed in underlying asset decimal units
min_block_trade_size mb uint64 The minimum block trade size, expressed in underlying asset decimal units
create_time ct Timestamp Creation time in unix nanoseconds
Venue

The list of Trading Venues that are supported on the GRVT exchange
Venue:

  • ORDERBOOK = 1: the trade is cleared on the orderbook venue
  • RFQ = 2: the trade is cleared on the RFQ venue
  • AXE = 3: the trade is cleared on the AXE venue

InstrumentSettlementPeriod

InstrumentSettlementPeriod:

  • PERPETUAL = 1: Instrument settles through perpetual hourly funding cycles
  • DAILY = 2: Instrument settles at an expiry date, marked as a daily instrument
  • WEEKLY = 3: Instrument settles at an expiry date, marked as a weekly instrument
  • MONTHLY = 4: Instrument settles at an expiry date, marked as a monthly instrument
  • QUARTERLY = 5: Instrument settles at an expiry date, marked as a quarterly instrument

Example

{
    "kind": ["PERPETUAL", "FUTURE"],
    "underlying": ["BTC"],
    "quote": ["USDT"],
    "is_active": true
}

Example

{
    "results": [
        {
            "instrument": "BTC_USDT_Perp",
            "instrument_name": "BTC_USDT_Perp",
            "venues": ["ORDERBOOK", "RFQ"],
            "settlement_period": "PERPETUAL",
            "underlying_decimals": 9,
            "quote_decimals": 6,
            "tick_size": 100000, // 0.1 USDT (6 quote decimals)
            "min_size": 1000, // 0.00001 BTC (9 underlying decimals)
            "min_block_size": 5000000000, // 5 BTC (9 underlying decimals)
            "create_time": "1631250800103000"
        }
    ]
}

Mini Ticker

Retrieves a single mini ticker value for a single instrument. Please do not use this to repeatedly poll for data -- a websocket subscription is much more performant, and useful.

FULL ENDPOINT: full/v1/mini
LITE ENDPOINT: lite/v1/mini
MiniTickerRequest
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]
MiniTickerResponse
Name Lite Type Description
results r MiniTicker The mini ticker matching the request asset
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

{
    "instrument": "BTC_USDT_Perp"
}

Example

{
    "results": {
        "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
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

Retrieves a single ticker value for a single instrument. Please do not use this to repeatedly poll for data -- a websocket subscription is much more performant, and useful.

FULL ENDPOINT: full/v1/ticker
LITE ENDPOINT: lite/v1/ticker
TickerRequest
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]
TickerResponse
Name Lite Type Description
results r Ticker The mini ticker matching the request asset
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

{
    "instrument": "BTC_USDT_Perp"
}

Example

{
    "results": {
        "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
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

Retrieves aggregated price depth for a single instrument, with a maximum depth of 10 levels. Do not use this to poll for data -- a websocket subscription is much more performant, and useful.

FULL ENDPOINT: full/v1/book
LITE ENDPOINT: lite/v1/book
OrderbookRequest
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]
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)
OrderbookResponse
Name Lite Type Description
results r OrderbookLevels The orderbook levels objects matching the request asset
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

{
    "instrument": "BTC_USDT_Perp",
    "depth": 30,
    "aggregate": 10
}

Example

{
    "results": {
        "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
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.

Public Trades

Retrieves up to 1000 of the most recent public trades in any given instrument. Do not use this to poll for data -- a websocket subscription is much more performant, and useful. This endpoint offers public trading data, use the Trading APIs instead to query for your personalized trade tape.

FULL ENDPOINT: full/v1/trades
LITE ENDPOINT: lite/v1/trades
PublicTradesRequest
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
PublicTradesResponse
Name Lite Type Description
results r [PublicTrade] The public trades matching the request asset
PublicTrade

All private RFQs and Private AXEs will be filtered out from the responses

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]
is_taker_buyer it bool If taker was the buyer on the trade
size s uint64 The number of assets being traded, expressed in underlying asset decimal units
price p uint64 The traded price, expressed in 9 decimals
mark_price mp uint64 The mark price of the instrument at point of trade, expressed in 9 decimals
index_price ip uint64 The index price of the instrument at point of trade, expressed in 9 decimals
interest_rate ir int32 The interest rate of the underlying at point of trade, expressed in centibeeps (1/100th of a basis point)
forward_price fp uint64 [Options] The forward price of the option at point of trade, expressed in 9 decimals
trade_id ti uint64 A trade identifier
venue v Venue The venue where the trade occurred
Venue

The list of Trading Venues that are supported on the GRVT exchange
Venue:

  • ORDERBOOK = 1: the trade is cleared on the orderbook venue
  • RFQ = 2: the trade is cleared on the RFQ venue
  • AXE = 3: the trade is cleared on the AXE venue

Example

{
    "instrument": "BTC_USDT_Perp",
    "limit": 1
}

Example

{
    "results": [
        {
            "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
INVALID_LIMIT 1004 The limit supplied is out of range
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.

Public Trade History

Perform historical lookup of public trades in any given instrument. This endpoint offers public trading data, use the Trading APIs instead to query for your personalized trade tape. Only data from the last three months will be retained.

METHOD: POST
FULL ENDPOINT: full/v1/trade_history
LITE ENDPOINT: lite/v1/trade_history
PublicTradeHistoryRequest
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 uint32 The limit to query for. Defaults to 500; Max 1000
cursor c string The cursor to indicate when to start the query from
PublicTradeHistoryResponse
Name Lite Type Description
results r [PublicTrade] The public trades matching the request asset
PublicTrade

All private RFQs and Private AXEs will be filtered out from the responses

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]
is_taker_buyer it bool If taker was the buyer on the trade
size s uint64 The number of assets being traded, expressed in underlying asset decimal units
price p uint64 The traded price, expressed in 9 decimals
mark_price mp uint64 The mark price of the instrument at point of trade, expressed in 9 decimals
index_price ip uint64 The index price of the instrument at point of trade, expressed in 9 decimals
interest_rate ir int32 The interest rate of the underlying at point of trade, expressed in centibeeps (1/100th of a basis point)
forward_price fp uint64 [Options] The forward price of the option at point of trade, expressed in 9 decimals
trade_id ti uint64 A trade identifier
venue v Venue The venue where the trade occurred
Venue

The list of Trading Venues that are supported on the GRVT exchange
Venue:

  • ORDERBOOK = 1: the trade is cleared on the orderbook venue
  • RFQ = 2: the trade is cleared on the RFQ venue
  • AXE = 3: the trade is cleared on the AXE venue

Example

{
    "instrument": "BTC_USDT_Perp",
    "limit": 1
}

Example

{
    "results": [
        {
            "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": 1 // orderbook
        }
    ]
}
Code Number Description
INVALID_INSTRUMENT 1001 The instrument supplied is not supported by our exchange
INVALID_LIMIT 1004 The limit supplied is out of range
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.

Settlement Price

Lookup the historical settlement price of various pairs.

METHOD: POST
FULL ENDPOINT: full/v1/settlement
LITE ENDPOINT: lite/v1/settlement
SettlementPriceRequest

startTime and endTime are optional parameters. The semantics of these parameters are as follows:

  • If both startTime and endTime are not set, the most recent settlement prices are returned up to limit.
  • If startTime is set and endTime is not set, the settlement prices starting from startTime are returned up to limit.
  • If startTime is not set and endTime is set, the settlement prices ending at endTime are returned up to limit.
  • If both startTime and endTime are set, the settlement prices between startTime and endTime are returned up to limit.

The instrument is also optional. When left empty, all perpetual instruments are returned.

Name Lite Type Description
underlying u Currency The underlying currency to select
quote q Currency The quote currency to select
start_time st Timestamp Start time of kline data in unix nanoseconds
end_time et Timestamp End time of kline data in unix nanoseconds
expiration e int64 The expiration time to select in unix nanoseconds
strike_price sp uint64 The strike price to select
limit l uint32 The limit to query for. Defaults to 30; Max 100
Currency

The list of Currencies that are supported on the GRVT exchange
Currency:

  • USDC = 2: the USDC token
  • USDT = 3: the USDT token
  • ETH = 4: the ETH token
  • BTC = 5: the BTC token

SettlementPriceResponse
Name Lite Type Description
results r [APISettlementPrice] The funding rate result set for given interval
APISettlementPrice
Name Lite Type Description
underlying u Currency The underlying currency of the settlement price
quote q Currency The quote currency of the settlement price
settlement_time st Timestamp The settlement timestamp of the settlement price, expressed in unix nanoseconds
settlement_price sp uint64 The settlement price, expressed in 9 decimals
Currency

The list of Currencies that are supported on the GRVT exchange
Currency:

  • USDC = 2: the USDC token
  • USDT = 3: the USDT token
  • ETH = 4: the ETH token
  • BTC = 5: the BTC token

Example

{
    "instrument": "BTC_USDT_Perp",
    "venue": ["ORDERBOOK"],
    "limit": 1
}

Example

{
    "results": [
        {
            "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": 1 // orderbook
        }
    ]
}
Code Number Description
INVALID_INSTRUMENT 1001 The instrument supplied is not supported by our exchange
INVALID_LIMIT 1004 The limit supplied is out of range
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.

Funding Rate

Lookup the historical funding rate of various pairs.

METHOD: POST
FULL ENDPOINT: full/v1/funding
LITE ENDPOINT: lite/v1/funding
FundingRateRequest

startTime and endTime are optional parameters. The semantics of these parameters are as follows:

  • If both startTime and endTime are not set, the most recent funding rates are returned up to limit.
  • If startTime is set and endTime is not set, the funding rates starting from startTime are returned up to limit.
  • If startTime is not set and endTime is set, the funding rates ending at endTime are returned up to limit.
  • If both startTime and endTime are set, the funding rates between startTime and endTime are returned up to limit.

The instrument is also optional. When left empty, all perpetual instruments are returned.

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]
start_time st uint64 Start time of funding rate in unix nanoseconds
end_time et uint64 End time of funding rate in unix nanoseconds
limit l uint32 The limit to query for. Defaults to 90; Max 300
FundingRateResponse
Name Lite Type Description
results r [FundingRate] The funding rate result set for given interval
FundingRate
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]
funding_rate fr int32 The funding rate of the instrument, expressed in centibeeps
funding_time ft Timestamp The funding timestamp of the funding rate, expressed in unix nanoseconds
mark_price mp uint64 The mark price of the instrument at funding timestamp, expressed in 9 decimals

Example

{
    "instrument": "BTC_USDT_Perp",
    "limit": 1
}

Example

{
    "results": [
        {
            "funding_rate": 5000,
            "funding_time": 1631250820000000,
            "mark_price": "34796400000", // 34796.40 USDT
        }
    ]
}
Code Number Description
INVALID_INSTRUMENT 1001 The instrument supplied is not supported by our exchange
INVALID_LIMIT 1004 The limit supplied is out of range
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.

Candlestick

Kline/Candlestick bars for an instrument. Klines are uniquely identified by their asset, type, interval, and open time.

METHOD: POST
FULL ENDPOINT: full/v1/kline
LITE ENDPOINT: lite/v1/kline
CandlestickRequest

startTime and endTime are optional parameters. The semantics of these parameters are as follows:

  • If both startTime and endTime are not set, the most recent candlesticks are returned up to limit.
  • If startTime is set and endTime is not set, the candlesticks starting from startTime are returned up to limit.
  • If startTime is not set and endTime is set, the candlesticks ending at endTime are returned up to limit.
  • If both startTime and endTime are set, the candlesticks between startTime and endTime are returned up to limit.

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
start_time st uint64 Start time of kline data in unix nanoseconds
end_time et uint64 End time of kline data in unix nanoseconds
limit l uint32 The limit to query for. Defaults to 500; Max 1500
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

CandlestickResponse
Name Lite Type Description
results r [Candlestick] The candlestick result set for given interval
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

{
    "instrument": "BTC_USDT_Perp",
    "interval": 4, // 15m
    "start_time": "1631250800000000",
    "end_time": "1631250830000000",
    "limit": 100
}

Example

{
    "results": [
        {
            "open_time": "1631250810000000",
            "close_time": "1631250820000000",
            "open": "100005",
            "close": "100004",
            "high": "100015",
            "low": "100003",
            "volume": "148976",
            "quote_volume": "1520020",
            "trades": 324
        },
        {
            "open_time": "1631250820000000",
            "close_time": "1631250830000000",
            "open": "100004",
            "close": "100006",
            "high": "10006",
            "low": "100003",
            "volume": "148976",
            "quote_volume": "1520020",
            "trades": 216
        }
    ]
}
Code Number Description
INVALID_INSTRUMENT 1001 The instrument supplied is not supported by our exchange
INVALID_TIME_RANGE 1002 The time range specified is invalid
INVALID_INTERVAL 1003 The interval specified is invalid
INVALID_LIMIT 1004 The limit supplied is out of range
INVALID_CURSOR 1005 The cursor supplied 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.