Skip to content

Trading APIs

All requests should be made using the POST HTTP method.

Order

Create Order

FULL ENDPOINT: full/v1/create_order
LITE ENDPOINT: lite/v1/create_order

ApiCreateOrderRequest

Create an order on the orderbook for this trading account.

Name
Lite		 Type Required
Default		 Description
order
o		 Order True The order to create
Order

Order is a typed payload used throughout the GRVT platform to express all orderbook, RFQ, and liquidation orders.
GRVT orders are capable of expressing both single-legged, and multi-legged orders by default.
This increases the learning curve slightly but reduces overall integration load, since the order payload is used across all GRVT trading venues.
Given GRVT's trustless settlement model, the Order payload also carries the signature, required to trade the order on our ZKSync Hyperchain.

All fields in the Order payload (except id, metadata, and state) are trustlessly enforced on our Hyperchain.
This minimizes the amount of trust users have to offer to GRVT

Name
Lite		 Type Required
Default		 Description
order_id
oi		 string False
0		 [Filled by GRVT Backend] A unique 128-bit identifier for the order, deterministically generated within the GRVT backend
sub_account_id
sa		 string True The subaccount initiating the order
is_market
im		 boolean False
false		 If the order is a market order
Market Orders do not have a limit price, and are always executed according to the maker order price.
Market Orders must always be taker orders
time_in_force
ti		 TimeInForce True Four supported types of orders: GTT, IOC, AON, FOK:

  • PARTIAL EXECUTION = GTT / IOC - allows partial size execution on each leg

  • FULL EXECUTION = AON / FOK - only allows full size execution on all legs

  • TAKER ONLY = IOC / FOK - only allows taker orders

  • MAKER OR TAKER = GTT / AON - allows maker or taker orders

Exchange only supports (GTT, IOC, FOK)
RFQ Maker only supports (GTT, AON), RFQ Taker only supports (FOK)
post_only
po		 boolean False
false		 If True, Order must be a maker order. It has to fill the orderbook instead of match it.
If False, Order can be either a maker or taker order. In this case, order creation is currently subject to a speedbump of 25ms to ensure orders are matched against updated orderbook quotes.
reduce_only
ro		 boolean False
false		 If True, Order must reduce the position size, or be cancelled
legs
l		 [OrderLeg] True The legs present in this order
The legs must be sorted by Asset.Instrument/Underlying/Quote/Expiration/StrikePrice
signature
s		 Signature True The signature approving this order
metadata
m		 OrderMetadata True Order Metadata, ignored by the smart contract, and unsigned by the client
state
s1		 OrderState False
''		 [Filled by GRVT Backend] The current state of the order, ignored by the smart contract, and unsigned by the client
TimeInForce
Must Fill All Can Fill Partial
Must Fill Immediately FOK IOC
Can Fill Till Time AON GTC

Value Description
GOOD_TILL_TIME = 1 GTT - Remains open until it is cancelled, or expired
ALL_OR_NONE = 2 AON - Either fill the whole order or none of it (Block Trades Only)
IMMEDIATE_OR_CANCEL = 3 IOC - Fill the order as much as possible, when hitting the orderbook. Then cancel it
FILL_OR_KILL = 4 FOK - Both AoN and IoC. Either fill the full order when hitting the orderbook, or cancel it
RETAIL_PRICE_IMPROVEMENT = 5 RPI - A GTT + PostOnly maker order, that can only be taken by non-algorithmic UI users.
OrderLeg
Name
Lite		 Type Required
Default		 Description
instrument
i		 string True The instrument to trade in this leg
size
s		 string True The total number of assets to trade in this leg, expressed in base asset decimal units.
limit_price
lp		 string False
0		 The limit price of the order leg, expressed in 9 decimals.
This is the number of quote currency units to pay/receive for this leg.
This should be null/0 if the order is a market order
is_buying_asset
ib		 boolean True Specifies if the order leg is a buy or sell
Signature
Name
Lite		 Type Required
Default		 Description
signer
s		 string True The address (public key) of the wallet signing the payload
r
r		 string True Signature R
s
s1		 string True Signature S
v
v		 integer True Signature V
expiration
e		 string True Timestamp after which this signature expires, expressed in unix nanoseconds. Must be capped at 30 days
nonce
n		 integer True Users can randomly generate this value, used as a signature deconflicting key.
ie. You can send the same exact instruction twice with different nonces.
When the same nonce is used, the same payload will generate the same signature.
Our system will consider the payload a duplicate, and ignore it.
OrderMetadata

Metadata fields are used to support Backend only operations. These operations are not trustless by nature.
Hence, fields in here are never signed, and is never transmitted to the smart contract.

Name
Lite		 Type Required
Default		 Description
client_order_id
co		 string True A unique identifier for the active order within a subaccount, specified by the client
This is used to identify the order in the client's system
This field can be used for order amendment/cancellation, but has no bearing on the smart contract layer
This field will not be propagated to the smart contract, and should not be signed by the client
This value must be unique for all active orders in a subaccount, or amendment/cancellation will not work as expected
Gravity UI will generate a random clientOrderID for each order in the range [0, 2^63 - 1]
To prevent any conflicts, client machines should generate a random clientOrderID in the range [2^63, 2^64 - 1]

When GRVT Backend receives an order with an overlapping clientOrderID, we will reject the order with rejectReason set to overlappingClientOrderId
create_time
ct		 string False
0		 [Filled by GRVT Backend] Time at which the order was received by GRVT in unix nanoseconds
trigger
t		 TriggerOrderMetadata False
``		 Trigger fields are used to support any type of trigger order such as TP/SL
broker
b		 BrokerTag False
``		 Specifies the broker who brokered the order
TriggerOrderMetadata

Contains metadata related to trigger orders, such as Take Profit (TP) or Stop Loss (SL).

Trigger orders are used to automatically execute an order when a predefined price condition is met, allowing traders to implement risk management strategies.


Name
Lite		 Type Required
Default		 Description
trigger_type
tt		 TriggerType True Type of the trigger order. eg: Take Profit, Stop Loss, etc
tpsl
t		 TPSLOrderMetadata True Contains metadata for Take Profit (TP) and Stop Loss (SL) trigger orders.
TriggerType

Defines the type of trigger order used in trading, such as Take Profit or Stop Loss.

Trigger orders allow execution based on pre-defined price conditions rather than immediate market conditions.


Value Description
UNSPECIFIED = 0 Not a trigger order. The order executes normally without any trigger conditions.
TAKE_PROFIT = 1 Take Profit Order - Executes when the price reaches a specified level to secure profits.
STOP_LOSS = 2 Stop Loss Order - Executes when the price reaches a specified level to limit losses.
TPSLOrderMetadata

Contains metadata for Take Profit (TP) and Stop Loss (SL) trigger orders.

### Fields:
- triggerBy: Defines the price type that activates the order (e.g., index price).
- triggerPrice: The price at which the order is triggered, expressed in 9 decimal precision.


Name
Lite		 Type Required
Default		 Description
trigger_by
tb		 TriggerBy True Defines the price type that activates a Take Profit (TP) or Stop Loss (SL) order
trigger_price
tp		 string True The Trigger Price of the order, expressed in 9 decimals.
close_position
cp		 boolean True If True, the order will close the position when the trigger price is reached
TriggerBy

Defines the price type that activates a Take Profit (TP) or Stop Loss (SL) order.

Trigger orders are executed when the selected price type reaches the specified trigger price.Different price types ensure flexibility in executing strategies based on market conditions.


Value Description
UNSPECIFIED = 0 no trigger condition
INDEX = 1 INDEX - Order is activated when the index price reaches the trigger price
LAST = 2 LAST - Order is activated when the last trade price reaches the trigger price
BrokerTag

BrokerTag is a tag for the broker that the order is sent from.

Value Description
UNSPECIFIED = 0
COIN_ROUTES = 1 CoinRoutes
ALERTATRON = 2 Alertatron
ORIGAMI = 3 Origami
OrderState
Name
Lite		 Type Required
Default		 Description
status
s		 OrderStatus True The status of the order
reject_reason
rr		 OrderRejectReason True The reason for rejection or cancellation
book_size
bs		 [string] True The number of assets available for orderbook/RFQ matching. Sorted in same order as Order.Legs
traded_size
ts		 [string] True The total number of assets traded. Sorted in same order as Order.Legs
update_time
ut		 string True Time at which the order was updated by GRVT, expressed in unix nanoseconds
avg_fill_price
af		 [string] True The average fill price of the order. Sorted in same order as Order.Legs
OrderStatus
Value Description
PENDING = 1 Order has been sent to the matching engine and is pending a transition to open/filled/rejected.
OPEN = 2 Order is actively matching on the matching engine, could be unfilled or partially filled.
FILLED = 3 Order is fully filled and hence closed. Taker Orders can transition directly from pending to filled, without going through open.
REJECTED = 4 Order is rejected by matching engine since if fails a particular check (See OrderRejectReason). Once an order is open, it cannot be rejected.
CANCELLED = 5 Order is cancelled by the user using one of the supported APIs (See OrderRejectReason). Before an order is open, it cannot be cancelled.
OrderRejectReason
Value Description
UNSPECIFIED = 0 order is not cancelled or rejected
CLIENT_CANCEL = 1 client called a Cancel API
CLIENT_BULK_CANCEL = 2 client called a Bulk Cancel API
CLIENT_SESSION_END = 3 client called a Session Cancel API, or set the WebSocket connection to 'cancelOrdersOnTerminate'
MARKET_CANCEL = 4 the market order was cancelled after no/partial fill. Lower precedence than other TimeInForce cancel reasons
IOC_CANCEL = 5 the IOC order was cancelled after no/partial fill
AON_CANCEL = 6 the AON order was cancelled as it could not be fully matched
FOK_CANCEL = 7 the FOK order was cancelled as it could not be fully matched
EXPIRED = 8 the order was cancelled as it has expired
FAIL_POST_ONLY = 9 the post-only order could not be posted into the orderbook
FAIL_REDUCE_ONLY = 10 the reduce-only order would have caused position size to increase
MM_PROTECTION = 11 the order was cancelled due to market maker protection trigger
SELF_TRADE_PROTECTION = 12 the order was cancelled due to self-trade protection trigger
SELF_MATCHED_SUBACCOUNT = 13 the order matched with another order from the same sub account
OVERLAPPING_CLIENT_ORDER_ID = 14 an active order on your sub account shares the same clientOrderId
BELOW_MARGIN = 15 the order will bring the sub account below initial margin requirement
LIQUIDATION = 16 the sub account is liquidated (and all open orders are cancelled by Gravity)
INSTRUMENT_INVALID = 17 instrument is invalid or not found on Gravity
INSTRUMENT_DEACTIVATED = 18 instrument is no longer tradable on Gravity. (typically due to a market halt, or instrument expiry)
SYSTEM_FAILOVER = 19 system failover resulting in loss of order state
UNAUTHORISED = 20 the credentials used (userSession/apiKeySession/walletSignature) is not authorised to perform the action
SESSION_KEY_EXPIRED = 21 the session key used to sign the order expired
SUB_ACCOUNT_NOT_FOUND = 22 the subaccount does not exist
NO_TRADE_PERMISSION = 23 the signature used to sign the order has no trade permission
UNSUPPORTED_TIME_IN_FORCE = 24 the order payload does not contain a supported TimeInForce value
MULTI_LEGGED_ORDER = 25 the order has multiple legs, but multiple legs are not supported by this venue
EXCEED_MAX_POSITION_SIZE = 26 the order would have caused the subaccount to exceed the max position size
EXCEED_MAX_SIGNATURE_EXPIRATION = 27 the signature supplied is more than 30 days in the future
MARKET_ORDER_WITH_LIMIT_PRICE = 28 the market order has a limit price set
CLIENT_CANCEL_ON_DISCONNECT_TRIGGERED = 29 client cancel on disconnect triggered
OCO_COUNTER_PART_TRIGGERED = 30 the OCO counter part order was triggered
REDUCE_ONLY_LIMIT = 31 the remaining order size was cancelled because it exceeded current position size
CLIENT_REPLACE = 32 the order was replaced by a client replace request

Query

Full Request 

{
    "order": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "is_market": false,
        "time_in_force": "GOOD_TILL_TIME",
        "post_only": false,
        "reduce_only": false,
        "legs": [{
            "instrument": "BTC_USDT_Perp",
            "size": "10.5",
            "limit_price": "65038.01",
            "is_buying_asset": true
        }],
        "signature": {
            "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "expiration": "1697788800000000000",
            "nonce": 1234567890
        },
        "metadata": {
            "client_order_id": "23042",
            "create_time": "1697788800000000000",
            "trigger": {
                "trigger_type": "TAKE_PROFIT",
                "tpsl": {
                    "trigger_by": "LAST",
                    "trigger_price": "65038.10",
                    "close_position": false
                }
            },
            "broker": "BROKER_CODE"
        }
    }
}
Lite Request 
{
    "o": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "im": false,
        "ti": "GOOD_TILL_TIME",
        "po": false,
        "ro": false,
        "l": [{
            "i": "BTC_USDT_Perp",
            "s": "10.5",
            "lp": "65038.01",
            "ib": true
        }],
        "s": {
            "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "e": "1697788800000000000",
            "n": 1234567890
        },
        "m": {
            "co": "23042",
            "ct": "1697788800000000000",
            "t": {
                "tt": "TAKE_PROFIT",
                "t": {
                    "tb": "LAST",
                    "tp": "65038.10",
                    "cp": false
                }
            },
            "b": "BROKER_CODE"
        }
    }
}

ApiCreateOrderResponse

Name
Lite		 Type Required
Default		 Description
result
r		 Order True The created order
Order

Order is a typed payload used throughout the GRVT platform to express all orderbook, RFQ, and liquidation orders.
GRVT orders are capable of expressing both single-legged, and multi-legged orders by default.
This increases the learning curve slightly but reduces overall integration load, since the order payload is used across all GRVT trading venues.
Given GRVT's trustless settlement model, the Order payload also carries the signature, required to trade the order on our ZKSync Hyperchain.

All fields in the Order payload (except id, metadata, and state) are trustlessly enforced on our Hyperchain.
This minimizes the amount of trust users have to offer to GRVT

Name
Lite		 Type Required
Default		 Description
order_id
oi		 string False
0		 [Filled by GRVT Backend] A unique 128-bit identifier for the order, deterministically generated within the GRVT backend
sub_account_id
sa		 string True The subaccount initiating the order
is_market
im		 boolean False
false		 If the order is a market order
Market Orders do not have a limit price, and are always executed according to the maker order price.
Market Orders must always be taker orders
time_in_force
ti		 TimeInForce True Four supported types of orders: GTT, IOC, AON, FOK:

  • PARTIAL EXECUTION = GTT / IOC - allows partial size execution on each leg

  • FULL EXECUTION = AON / FOK - only allows full size execution on all legs

  • TAKER ONLY = IOC / FOK - only allows taker orders

  • MAKER OR TAKER = GTT / AON - allows maker or taker orders

Exchange only supports (GTT, IOC, FOK)
RFQ Maker only supports (GTT, AON), RFQ Taker only supports (FOK)
post_only
po		 boolean False
false		 If True, Order must be a maker order. It has to fill the orderbook instead of match it.
If False, Order can be either a maker or taker order. In this case, order creation is currently subject to a speedbump of 25ms to ensure orders are matched against updated orderbook quotes.
reduce_only
ro		 boolean False
false		 If True, Order must reduce the position size, or be cancelled
legs
l		 [OrderLeg] True The legs present in this order
The legs must be sorted by Asset.Instrument/Underlying/Quote/Expiration/StrikePrice
signature
s		 Signature True The signature approving this order
metadata
m		 OrderMetadata True Order Metadata, ignored by the smart contract, and unsigned by the client
state
s1		 OrderState False
''		 [Filled by GRVT Backend] The current state of the order, ignored by the smart contract, and unsigned by the client
TimeInForce
Must Fill All Can Fill Partial
Must Fill Immediately FOK IOC
Can Fill Till Time AON GTC

Value Description
GOOD_TILL_TIME = 1 GTT - Remains open until it is cancelled, or expired
ALL_OR_NONE = 2 AON - Either fill the whole order or none of it (Block Trades Only)
IMMEDIATE_OR_CANCEL = 3 IOC - Fill the order as much as possible, when hitting the orderbook. Then cancel it
FILL_OR_KILL = 4 FOK - Both AoN and IoC. Either fill the full order when hitting the orderbook, or cancel it
RETAIL_PRICE_IMPROVEMENT = 5 RPI - A GTT + PostOnly maker order, that can only be taken by non-algorithmic UI users.
OrderLeg
Name
Lite		 Type Required
Default		 Description
instrument
i		 string True The instrument to trade in this leg
size
s		 string True The total number of assets to trade in this leg, expressed in base asset decimal units.
limit_price
lp		 string False
0		 The limit price of the order leg, expressed in 9 decimals.
This is the number of quote currency units to pay/receive for this leg.
This should be null/0 if the order is a market order
is_buying_asset
ib		 boolean True Specifies if the order leg is a buy or sell
Signature
Name
Lite		 Type Required
Default		 Description
signer
s		 string True The address (public key) of the wallet signing the payload
r
r		 string True Signature R
s
s1		 string True Signature S
v
v		 integer True Signature V
expiration
e		 string True Timestamp after which this signature expires, expressed in unix nanoseconds. Must be capped at 30 days
nonce
n		 integer True Users can randomly generate this value, used as a signature deconflicting key.
ie. You can send the same exact instruction twice with different nonces.
When the same nonce is used, the same payload will generate the same signature.
Our system will consider the payload a duplicate, and ignore it.
OrderMetadata

Metadata fields are used to support Backend only operations. These operations are not trustless by nature.
Hence, fields in here are never signed, and is never transmitted to the smart contract.

Name
Lite		 Type Required
Default		 Description
client_order_id
co		 string True A unique identifier for the active order within a subaccount, specified by the client
This is used to identify the order in the client's system
This field can be used for order amendment/cancellation, but has no bearing on the smart contract layer
This field will not be propagated to the smart contract, and should not be signed by the client
This value must be unique for all active orders in a subaccount, or amendment/cancellation will not work as expected
Gravity UI will generate a random clientOrderID for each order in the range [0, 2^63 - 1]
To prevent any conflicts, client machines should generate a random clientOrderID in the range [2^63, 2^64 - 1]

When GRVT Backend receives an order with an overlapping clientOrderID, we will reject the order with rejectReason set to overlappingClientOrderId
create_time
ct		 string False
0		 [Filled by GRVT Backend] Time at which the order was received by GRVT in unix nanoseconds
trigger
t		 TriggerOrderMetadata False
``		 Trigger fields are used to support any type of trigger order such as TP/SL
broker
b		 BrokerTag False
``		 Specifies the broker who brokered the order
TriggerOrderMetadata

Contains metadata related to trigger orders, such as Take Profit (TP) or Stop Loss (SL).

Trigger orders are used to automatically execute an order when a predefined price condition is met, allowing traders to implement risk management strategies.


Name
Lite		 Type Required
Default		 Description
trigger_type
tt		 TriggerType True Type of the trigger order. eg: Take Profit, Stop Loss, etc
tpsl
t		 TPSLOrderMetadata True Contains metadata for Take Profit (TP) and Stop Loss (SL) trigger orders.
TriggerType

Defines the type of trigger order used in trading, such as Take Profit or Stop Loss.

Trigger orders allow execution based on pre-defined price conditions rather than immediate market conditions.


Value Description
UNSPECIFIED = 0 Not a trigger order. The order executes normally without any trigger conditions.
TAKE_PROFIT = 1 Take Profit Order - Executes when the price reaches a specified level to secure profits.
STOP_LOSS = 2 Stop Loss Order - Executes when the price reaches a specified level to limit losses.
TPSLOrderMetadata

Contains metadata for Take Profit (TP) and Stop Loss (SL) trigger orders.

### Fields:
- triggerBy: Defines the price type that activates the order (e.g., index price).
- triggerPrice: The price at which the order is triggered, expressed in 9 decimal precision.


Name
Lite		 Type Required
Default		 Description
trigger_by
tb		 TriggerBy True Defines the price type that activates a Take Profit (TP) or Stop Loss (SL) order
trigger_price
tp		 string True The Trigger Price of the order, expressed in 9 decimals.
close_position
cp		 boolean True If True, the order will close the position when the trigger price is reached
TriggerBy

Defines the price type that activates a Take Profit (TP) or Stop Loss (SL) order.

Trigger orders are executed when the selected price type reaches the specified trigger price.Different price types ensure flexibility in executing strategies based on market conditions.


Value Description
UNSPECIFIED = 0 no trigger condition
INDEX = 1 INDEX - Order is activated when the index price reaches the trigger price
LAST = 2 LAST - Order is activated when the last trade price reaches the trigger price
BrokerTag

BrokerTag is a tag for the broker that the order is sent from.

Value Description
UNSPECIFIED = 0
COIN_ROUTES = 1 CoinRoutes
ALERTATRON = 2 Alertatron
ORIGAMI = 3 Origami
OrderState
Name
Lite		 Type Required
Default		 Description
status
s		 OrderStatus True The status of the order
reject_reason
rr		 OrderRejectReason True The reason for rejection or cancellation
book_size
bs		 [string] True The number of assets available for orderbook/RFQ matching. Sorted in same order as Order.Legs
traded_size
ts		 [string] True The total number of assets traded. Sorted in same order as Order.Legs
update_time
ut		 string True Time at which the order was updated by GRVT, expressed in unix nanoseconds
avg_fill_price
af		 [string] True The average fill price of the order. Sorted in same order as Order.Legs
OrderStatus
Value Description
PENDING = 1 Order has been sent to the matching engine and is pending a transition to open/filled/rejected.
OPEN = 2 Order is actively matching on the matching engine, could be unfilled or partially filled.
FILLED = 3 Order is fully filled and hence closed. Taker Orders can transition directly from pending to filled, without going through open.
REJECTED = 4 Order is rejected by matching engine since if fails a particular check (See OrderRejectReason). Once an order is open, it cannot be rejected.
CANCELLED = 5 Order is cancelled by the user using one of the supported APIs (See OrderRejectReason). Before an order is open, it cannot be cancelled.
OrderRejectReason
Value Description
UNSPECIFIED = 0 order is not cancelled or rejected
CLIENT_CANCEL = 1 client called a Cancel API
CLIENT_BULK_CANCEL = 2 client called a Bulk Cancel API
CLIENT_SESSION_END = 3 client called a Session Cancel API, or set the WebSocket connection to 'cancelOrdersOnTerminate'
MARKET_CANCEL = 4 the market order was cancelled after no/partial fill. Lower precedence than other TimeInForce cancel reasons
IOC_CANCEL = 5 the IOC order was cancelled after no/partial fill
AON_CANCEL = 6 the AON order was cancelled as it could not be fully matched
FOK_CANCEL = 7 the FOK order was cancelled as it could not be fully matched
EXPIRED = 8 the order was cancelled as it has expired
FAIL_POST_ONLY = 9 the post-only order could not be posted into the orderbook
FAIL_REDUCE_ONLY = 10 the reduce-only order would have caused position size to increase
MM_PROTECTION = 11 the order was cancelled due to market maker protection trigger
SELF_TRADE_PROTECTION = 12 the order was cancelled due to self-trade protection trigger
SELF_MATCHED_SUBACCOUNT = 13 the order matched with another order from the same sub account
OVERLAPPING_CLIENT_ORDER_ID = 14 an active order on your sub account shares the same clientOrderId
BELOW_MARGIN = 15 the order will bring the sub account below initial margin requirement
LIQUIDATION = 16 the sub account is liquidated (and all open orders are cancelled by Gravity)
INSTRUMENT_INVALID = 17 instrument is invalid or not found on Gravity
INSTRUMENT_DEACTIVATED = 18 instrument is no longer tradable on Gravity. (typically due to a market halt, or instrument expiry)
SYSTEM_FAILOVER = 19 system failover resulting in loss of order state
UNAUTHORISED = 20 the credentials used (userSession/apiKeySession/walletSignature) is not authorised to perform the action
SESSION_KEY_EXPIRED = 21 the session key used to sign the order expired
SUB_ACCOUNT_NOT_FOUND = 22 the subaccount does not exist
NO_TRADE_PERMISSION = 23 the signature used to sign the order has no trade permission
UNSUPPORTED_TIME_IN_FORCE = 24 the order payload does not contain a supported TimeInForce value
MULTI_LEGGED_ORDER = 25 the order has multiple legs, but multiple legs are not supported by this venue
EXCEED_MAX_POSITION_SIZE = 26 the order would have caused the subaccount to exceed the max position size
EXCEED_MAX_SIGNATURE_EXPIRATION = 27 the signature supplied is more than 30 days in the future
MARKET_ORDER_WITH_LIMIT_PRICE = 28 the market order has a limit price set
CLIENT_CANCEL_ON_DISCONNECT_TRIGGERED = 29 client cancel on disconnect triggered
OCO_COUNTER_PART_TRIGGERED = 30 the OCO counter part order was triggered
REDUCE_ONLY_LIMIT = 31 the remaining order size was cancelled because it exceeded current position size
CLIENT_REPLACE = 32 the order was replaced by a client replace request

Success

Full Response 

{
    "result": {
        "order_id": "0x1234567890abcdef",
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "is_market": false,
        "time_in_force": "GOOD_TILL_TIME",
        "post_only": false,
        "reduce_only": false,
        "legs": [{
            "instrument": "BTC_USDT_Perp",
            "size": "10.5",
            "limit_price": "65038.01",
            "is_buying_asset": true
        }],
        "signature": {
            "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "expiration": "1697788800000000000",
            "nonce": 1234567890
        },
        "metadata": {
            "client_order_id": "23042",
            "create_time": "1697788800000000000",
            "trigger": {
                "trigger_type": "TAKE_PROFIT",
                "tpsl": {
                    "trigger_by": "LAST",
                    "trigger_price": "65038.10",
                    "close_position": false
                }
            },
            "broker": "BROKER_CODE"
        },
        "state": {
            "status": "PENDING",
            "reject_reason": "CLIENT_CANCEL",
            "book_size": ["10.5"],
            "traded_size": ["1.5"],
            "update_time": "1697788800000000000",
            "avg_fill_price": ["60000.4"]
        }
    }
}
Lite Response 
{
    "r": {
        "oi": "0x1234567890abcdef",
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "im": false,
        "ti": "GOOD_TILL_TIME",
        "po": false,
        "ro": false,
        "l": [{
            "i": "BTC_USDT_Perp",
            "s": "10.5",
            "lp": "65038.01",
            "ib": true
        }],
        "s": {
            "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "e": "1697788800000000000",
            "n": 1234567890
        },
        "m": {
            "co": "23042",
            "ct": "1697788800000000000",
            "t": {
                "tt": "TAKE_PROFIT",
                "t": {
                    "tb": "LAST",
                    "tp": "65038.10",
                    "cp": false
                }
            },
            "b": "BROKER_CODE"
        },
        "s1": {
            "s": "PENDING",
            "rr": "CLIENT_CANCEL",
            "bs": ["10.5"],
            "ts": ["1.5"],
            "ut": "1697788800000000000",
            "af": ["60000.4"]
        }
    }
}

Error Codes

Code HttpStatus Description
1000 401 You need to authenticate prior to using this functionality
1001 403 You are not authorized to access this functionality
1002 500 Internal Server Error
1003 400 Request could not be processed due to malformed syntax
1004 404 Data Not Found
1005 500 Unknown Error
1006 429 You have surpassed the allocated rate limit for your tier
1008 401 Your IP has not been whitelisted for access
1400 403 Signer does not have trade permission
1009 503 We are temporarily deactivating this API endpoint, please try again later
2000 403 Order signature is from an unauthorized signer
2001 403 Order signature has expired
2002 403 Order signature does not match payload
2003 403 Order sub account does not match logged in user
2004 403 Order signature is from an expired session key
2006 403 Order signature R/S must have exactly 64 characters long without 0x prefix
2005 403 Order signature V must be 27/28
2007 403 Order signature S must be in the lower half of the curve
2010 400 Order ID should be empty when creating an order
2011 400 Client Order ID should be supplied when creating an order
2012 400 Client Order ID overlaps with existing active order
2030 400 Orderbook Orders must have a TimeInForce of GTT/IOC/FOK
2031 400 RFQ Orders must have a TimeInForce of GTT/AON/IOC/FOK
2032 400 Post Only can only be set to true for GTT/AON orders
2020 400 Market Order must always be supplied without a limit price
2021 400 Limit Order must always be supplied with a limit price
2040 400 Order must contain at least one leg
2041 400 Order Legs must be sorted by Derivative.Instrument/Underlying/BaseCurrency/Expiration/StrikePrice
2042 400 Orderbook Orders must contain only one leg
2050 400 Order state must be empty upon creation
2051 400 Order execution metadata must be empty upon creation
2060 400 Order Legs contain one or more inactive derivative
2061 400 Unsupported Instrument Requested
2062 400 Order size smaller than min size
2063 400 Order size smaller than min block size in block trade venue
2064 400 Invalid limit price tick
2065 400 Order size too granular
2070 400 Liquidation Order is not supported
2080 400 Insufficient margin to create order
2081 400 Order Fill would result in exceeding maximum position size
2082 400 Pre-order check failed
2083 400 Order Fill would result in exceeding maximum position size under current configurable leverage tier
2090 429 Max open orders exceeded
2110 400 Invalid trigger by
2111 400 Unsupported trigger by
2112 400 Invalid trigger order
2113 400 Trigger price must be non-zero
2114 400 Invalid position linked TPSL orders, position linked TPSL must be a reduce-only order
2115 400 Invalid position linked TPSL orders, position linked TPSL must not have smaller size than the position
2116 400 Position linked TPSL order for this asset already exists
3004 500 Instrument does not have a valid maintenance margin configuration
3005 500 Instrument's underlying currency does not have a valid balance decimal configuration
3006 500 Instrument's quote currency does not have a valid balance decimal configuration
2400 400 Reduce only order with no position
2401 400 Reduce only order must not increase position size

Failure

Full Error Response 

{
    "request_id":1,
    "code":1000,
    "message":"You need to authenticate prior to using this functionality",
    "status":401
}
Lite Error Response 
{
    "ri":1,
    "c":1000,
    "m":"You need to authenticate prior to using this functionality",
    "s":401
}

Authentication

In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI.

# These are the variables you will need to set manually
GRVT_API_KEY="<insert_key_here>"
GRVT_SUB_ACCOUNT_ID="<insert_sub_account_id_here>"

Then, choose the environment you want to authenticate against.

# dev
GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login"
# staging
GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/api_key/login"
# testnet
GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/api_key/login"
# prod
GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/api_key/login"

Now, let’s authenticate and retrieve both the session cookie and the X-Grvt-Account-Id header value that you’ll need to access any endpoints requiring authentication.

echo $GRVT_API_KEY
echo $GRVT_SUB_ACCOUNT_ID
echo $GRVT_AUTH_ENDPOINT

RESPONSE=$(
    curl $GRVT_AUTH_ENDPOINT \
        -H 'Content-Type: application/json' \
        -H 'Cookie: rm=true;' \
        -d '{"api_key": "'$GRVT_API_KEY'"}' \
        -s -i
)

GRVT_COOKIE=$(echo "$RESPONSE" | grep -i 'set-cookie:' | grep -o 'gravity=[^;]*')
GRVT_ACCOUNT_ID=$(echo "$RESPONSE" | grep 'x-grvt-account-id:' | awk '{print $2}' | tr -d '\r')

echo "$GRVT_COOKIE"
echo "$GRVT_ACCOUNT_ID"

REST Full

curl --location 'https://trades.dev.gravitymarkets.io/full/v1/create_order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "order": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "is_market": false,
        "time_in_force": "GOOD_TILL_TIME",
        "post_only": false,
        "reduce_only": false,
        "legs": [{
            "instrument": "BTC_USDT_Perp",
            "size": "10.5",
            "limit_price": "65038.01",
            "is_buying_asset": true
        }],
        "signature": {
            "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "expiration": "1697788800000000000",
            "nonce": 1234567890
        },
        "metadata": {
            "client_order_id": "23042",
            "create_time": "1697788800000000000",
            "trigger": {
                "trigger_type": "TAKE_PROFIT",
                "tpsl": {
                    "trigger_by": "LAST",
                    "trigger_price": "65038.10",
                    "close_position": false
                }
            },
            "broker": "BROKER_CODE"
        }
    }
}
'

JSONRPC Full

wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/create_order",
    "params": {
        "order": {
            "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
            "is_market": false,
            "time_in_force": "GOOD_TILL_TIME",
            "post_only": false,
            "reduce_only": false,
            "legs": [{
                "instrument": "BTC_USDT_Perp",
                "size": "10.5",
                "limit_price": "65038.01",
                "is_buying_asset": true
            }],
            "signature": {
                "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
                "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
                "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
                "v": 28,
                "expiration": "1697788800000000000",
                "nonce": 1234567890
            },
            "metadata": {
                "client_order_id": "23042",
                "create_time": "1697788800000000000",
                "trigger": {
                    "trigger_type": "TAKE_PROFIT",
                    "tpsl": {
                        "trigger_by": "LAST",
                        "trigger_price": "65038.10",
                        "close_position": false
                    }
                },
                "broker": "BROKER_CODE"
            }
        }
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/create_order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "o": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "im": false,
        "ti": "GOOD_TILL_TIME",
        "po": false,
        "ro": false,
        "l": [{
            "i": "BTC_USDT_Perp",
            "s": "10.5",
            "lp": "65038.01",
            "ib": true
        }],
        "s": {
            "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "e": "1697788800000000000",
            "n": 1234567890
        },
        "m": {
            "co": "23042",
            "ct": "1697788800000000000",
            "t": {
                "tt": "TAKE_PROFIT",
                "t": {
                    "tb": "LAST",
                    "tp": "65038.10",
                    "cp": false
                }
            },
            "b": "BROKER_CODE"
        }
    }
}
'

JSONRPC Lite

wscat -c "wss://trades.dev.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/create_order",
    "p": {
        "o": {
            "sa": "'$GRVT_SUB_ACCOUNT_ID'",
            "im": false,
            "ti": "GOOD_TILL_TIME",
            "po": false,
            "ro": false,
            "l": [{
                "i": "BTC_USDT_Perp",
                "s": "10.5",
                "lp": "65038.01",
                "ib": true
            }],
            "s": {
                "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
                "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
                "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
                "v": 28,
                "e": "1697788800000000000",
                "n": 1234567890
            },
            "m": {
                "co": "23042",
                "ct": "1697788800000000000",
                "t": {
                    "tt": "TAKE_PROFIT",
                    "t": {
                        "tb": "LAST",
                        "tp": "65038.10",
                        "cp": false
                    }
                },
                "b": "BROKER_CODE"
            }
        }
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.staging.gravitymarkets.io/full/v1/create_order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "order": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "is_market": false,
        "time_in_force": "GOOD_TILL_TIME",
        "post_only": false,
        "reduce_only": false,
        "legs": [{
            "instrument": "BTC_USDT_Perp",
            "size": "10.5",
            "limit_price": "65038.01",
            "is_buying_asset": true
        }],
        "signature": {
            "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "expiration": "1697788800000000000",
            "nonce": 1234567890
        },
        "metadata": {
            "client_order_id": "23042",
            "create_time": "1697788800000000000",
            "trigger": {
                "trigger_type": "TAKE_PROFIT",
                "tpsl": {
                    "trigger_by": "LAST",
                    "trigger_price": "65038.10",
                    "close_position": false
                }
            },
            "broker": "BROKER_CODE"
        }
    }
}
'

JSONRPC Full

wscat -c "wss://trades.staging.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/create_order",
    "params": {
        "order": {
            "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
            "is_market": false,
            "time_in_force": "GOOD_TILL_TIME",
            "post_only": false,
            "reduce_only": false,
            "legs": [{
                "instrument": "BTC_USDT_Perp",
                "size": "10.5",
                "limit_price": "65038.01",
                "is_buying_asset": true
            }],
            "signature": {
                "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
                "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
                "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
                "v": 28,
                "expiration": "1697788800000000000",
                "nonce": 1234567890
            },
            "metadata": {
                "client_order_id": "23042",
                "create_time": "1697788800000000000",
                "trigger": {
                    "trigger_type": "TAKE_PROFIT",
                    "tpsl": {
                        "trigger_by": "LAST",
                        "trigger_price": "65038.10",
                        "close_position": false
                    }
                },
                "broker": "BROKER_CODE"
            }
        }
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/create_order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "o": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "im": false,
        "ti": "GOOD_TILL_TIME",
        "po": false,
        "ro": false,
        "l": [{
            "i": "BTC_USDT_Perp",
            "s": "10.5",
            "lp": "65038.01",
            "ib": true
        }],
        "s": {
            "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "e": "1697788800000000000",
            "n": 1234567890
        },
        "m": {
            "co": "23042",
            "ct": "1697788800000000000",
            "t": {
                "tt": "TAKE_PROFIT",
                "t": {
                    "tb": "LAST",
                    "tp": "65038.10",
                    "cp": false
                }
            },
            "b": "BROKER_CODE"
        }
    }
}
'

JSONRPC Lite

wscat -c "wss://trades.staging.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/create_order",
    "p": {
        "o": {
            "sa": "'$GRVT_SUB_ACCOUNT_ID'",
            "im": false,
            "ti": "GOOD_TILL_TIME",
            "po": false,
            "ro": false,
            "l": [{
                "i": "BTC_USDT_Perp",
                "s": "10.5",
                "lp": "65038.01",
                "ib": true
            }],
            "s": {
                "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
                "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
                "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
                "v": 28,
                "e": "1697788800000000000",
                "n": 1234567890
            },
            "m": {
                "co": "23042",
                "ct": "1697788800000000000",
                "t": {
                    "tt": "TAKE_PROFIT",
                    "t": {
                        "tb": "LAST",
                        "tp": "65038.10",
                        "cp": false
                    }
                },
                "b": "BROKER_CODE"
            }
        }
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.testnet.grvt.io/full/v1/create_order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "order": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "is_market": false,
        "time_in_force": "GOOD_TILL_TIME",
        "post_only": false,
        "reduce_only": false,
        "legs": [{
            "instrument": "BTC_USDT_Perp",
            "size": "10.5",
            "limit_price": "65038.01",
            "is_buying_asset": true
        }],
        "signature": {
            "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "expiration": "1697788800000000000",
            "nonce": 1234567890
        },
        "metadata": {
            "client_order_id": "23042",
            "create_time": "1697788800000000000",
            "trigger": {
                "trigger_type": "TAKE_PROFIT",
                "tpsl": {
                    "trigger_by": "LAST",
                    "trigger_price": "65038.10",
                    "close_position": false
                }
            },
            "broker": "BROKER_CODE"
        }
    }
}
'

JSONRPC Full

wscat -c "wss://trades.testnet.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/create_order",
    "params": {
        "order": {
            "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
            "is_market": false,
            "time_in_force": "GOOD_TILL_TIME",
            "post_only": false,
            "reduce_only": false,
            "legs": [{
                "instrument": "BTC_USDT_Perp",
                "size": "10.5",
                "limit_price": "65038.01",
                "is_buying_asset": true
            }],
            "signature": {
                "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
                "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
                "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
                "v": 28,
                "expiration": "1697788800000000000",
                "nonce": 1234567890
            },
            "metadata": {
                "client_order_id": "23042",
                "create_time": "1697788800000000000",
                "trigger": {
                    "trigger_type": "TAKE_PROFIT",
                    "tpsl": {
                        "trigger_by": "LAST",
                        "trigger_price": "65038.10",
                        "close_position": false
                    }
                },
                "broker": "BROKER_CODE"
            }
        }
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.testnet.grvt.io/lite/v1/create_order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "o": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "im": false,
        "ti": "GOOD_TILL_TIME",
        "po": false,
        "ro": false,
        "l": [{
            "i": "BTC_USDT_Perp",
            "s": "10.5",
            "lp": "65038.01",
            "ib": true
        }],
        "s": {
            "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "e": "1697788800000000000",
            "n": 1234567890
        },
        "m": {
            "co": "23042",
            "ct": "1697788800000000000",
            "t": {
                "tt": "TAKE_PROFIT",
                "t": {
                    "tb": "LAST",
                    "tp": "65038.10",
                    "cp": false
                }
            },
            "b": "BROKER_CODE"
        }
    }
}
'

JSONRPC Lite

wscat -c "wss://trades.testnet.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/create_order",
    "p": {
        "o": {
            "sa": "'$GRVT_SUB_ACCOUNT_ID'",
            "im": false,
            "ti": "GOOD_TILL_TIME",
            "po": false,
            "ro": false,
            "l": [{
                "i": "BTC_USDT_Perp",
                "s": "10.5",
                "lp": "65038.01",
                "ib": true
            }],
            "s": {
                "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
                "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
                "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
                "v": 28,
                "e": "1697788800000000000",
                "n": 1234567890
            },
            "m": {
                "co": "23042",
                "ct": "1697788800000000000",
                "t": {
                    "tt": "TAKE_PROFIT",
                    "t": {
                        "tb": "LAST",
                        "tp": "65038.10",
                        "cp": false
                    }
                },
                "b": "BROKER_CODE"
            }
        }
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.grvt.io/full/v1/create_order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "order": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "is_market": false,
        "time_in_force": "GOOD_TILL_TIME",
        "post_only": false,
        "reduce_only": false,
        "legs": [{
            "instrument": "BTC_USDT_Perp",
            "size": "10.5",
            "limit_price": "65038.01",
            "is_buying_asset": true
        }],
        "signature": {
            "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "expiration": "1697788800000000000",
            "nonce": 1234567890
        },
        "metadata": {
            "client_order_id": "23042",
            "create_time": "1697788800000000000",
            "trigger": {
                "trigger_type": "TAKE_PROFIT",
                "tpsl": {
                    "trigger_by": "LAST",
                    "trigger_price": "65038.10",
                    "close_position": false
                }
            },
            "broker": "BROKER_CODE"
        }
    }
}
'

JSONRPC Full

wscat -c "wss://trades.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/create_order",
    "params": {
        "order": {
            "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
            "is_market": false,
            "time_in_force": "GOOD_TILL_TIME",
            "post_only": false,
            "reduce_only": false,
            "legs": [{
                "instrument": "BTC_USDT_Perp",
                "size": "10.5",
                "limit_price": "65038.01",
                "is_buying_asset": true
            }],
            "signature": {
                "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
                "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
                "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
                "v": 28,
                "expiration": "1697788800000000000",
                "nonce": 1234567890
            },
            "metadata": {
                "client_order_id": "23042",
                "create_time": "1697788800000000000",
                "trigger": {
                    "trigger_type": "TAKE_PROFIT",
                    "tpsl": {
                        "trigger_by": "LAST",
                        "trigger_price": "65038.10",
                        "close_position": false
                    }
                },
                "broker": "BROKER_CODE"
            }
        }
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.grvt.io/lite/v1/create_order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "o": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "im": false,
        "ti": "GOOD_TILL_TIME",
        "po": false,
        "ro": false,
        "l": [{
            "i": "BTC_USDT_Perp",
            "s": "10.5",
            "lp": "65038.01",
            "ib": true
        }],
        "s": {
            "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "e": "1697788800000000000",
            "n": 1234567890
        },
        "m": {
            "co": "23042",
            "ct": "1697788800000000000",
            "t": {
                "tt": "TAKE_PROFIT",
                "t": {
                    "tb": "LAST",
                    "tp": "65038.10",
                    "cp": false
                }
            },
            "b": "BROKER_CODE"
        }
    }
}
'

JSONRPC Lite

wscat -c "wss://trades.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/create_order",
    "p": {
        "o": {
            "sa": "'$GRVT_SUB_ACCOUNT_ID'",
            "im": false,
            "ti": "GOOD_TILL_TIME",
            "po": false,
            "ro": false,
            "l": [{
                "i": "BTC_USDT_Perp",
                "s": "10.5",
                "lp": "65038.01",
                "ib": true
            }],
            "s": {
                "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
                "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
                "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
                "v": 28,
                "e": "1697788800000000000",
                "n": 1234567890
            },
            "m": {
                "co": "23042",
                "ct": "1697788800000000000",
                "t": {
                    "tt": "TAKE_PROFIT",
                    "t": {
                        "tb": "LAST",
                        "tp": "65038.10",
                        "cp": false
                    }
                },
                "b": "BROKER_CODE"
            }
        }
    },
    "i": 123
}
' -w 360

Cancel Order

FULL ENDPOINT: full/v1/cancel_order
LITE ENDPOINT: lite/v1/cancel_order

ApiCancelOrderRequest

Cancel an order on the orderbook for this trading account. Either order_id or client_order_id must be provided.

Name
Lite		 Type Required
Default		 Description
sub_account_id
sa		 string True The subaccount ID cancelling the order
order_id
oi		 string False
0		 Cancel the order with this order_id
client_order_id
co		 string False
0		 Cancel the order with this client_order_id
time_to_live_ms
tt		 string False
100		 Specifies the time-to-live (in milliseconds) for this cancellation.
During this period, any order creation with a matching client_order_id will be cancelled and not be added to the GRVT matching engine.
This mechanism helps mitigate time-of-flight issues where cancellations might arrive before the corresponding orders.
Hence, cancellation by order_id ignores this field as the exchange can only assign order_ids to already-processed order creations.
The duration cannot be negative, is rounded down to the nearest 100ms (e.g., '670' -> '600', '30' -> '0') and capped at 5 seconds (i.e., '5000').
Value of '0' or omission results in the default time-to-live value being applied.
If the caller requests multiple successive cancellations for a given order, such that the time-to-live windows overlap, only the first request will be considered.

Query

Full Request 

{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "order_id": "0x1028403",
    "client_order_id": "23042",
    "time_to_live_ms": "500"
}
Lite Request 
{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "oi": "0x1028403",
    "co": "23042",
    "tt": "500"
}

AckResponse

Used to acknowledge a request has been received and will be processed

Name
Lite		 Type Required
Default		 Description
result
r		 Ack True The Ack Object
Ack
Name
Lite		 Type Required
Default		 Description
ack
a		 boolean True Gravity has acknowledged that the request has been successfully received and it will process it in the backend

Success

Full Response 

{
    "result": {
        "ack": "true"
    }
}
Lite Response 
{
    "r": {
        "a": "true"
    }
}

Error Codes

Code HttpStatus Description
1000 401 You need to authenticate prior to using this functionality
1001 403 You are not authorized to access this functionality
1002 500 Internal Server Error
1003 400 Request could not be processed due to malformed syntax
1006 429 You have surpassed the allocated rate limit for your tier
1008 401 Your IP has not been whitelisted for access
2300 400 Order cancel time-to-live settings currently disabled.
2301 400 Order cancel time-to-live exceeds maximum allowed value.
3021 400 Either order ID or client order ID must be supplied

Failure

Full Error Response 

{
    "request_id":1,
    "code":1000,
    "message":"You need to authenticate prior to using this functionality",
    "status":401
}
Lite Error Response 
{
    "ri":1,
    "c":1000,
    "m":"You need to authenticate prior to using this functionality",
    "s":401
}

Authentication

In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI.

# These are the variables you will need to set manually
GRVT_API_KEY="<insert_key_here>"
GRVT_SUB_ACCOUNT_ID="<insert_sub_account_id_here>"

Then, choose the environment you want to authenticate against.

# dev
GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login"
# staging
GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/api_key/login"
# testnet
GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/api_key/login"
# prod
GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/api_key/login"

Now, let’s authenticate and retrieve both the session cookie and the X-Grvt-Account-Id header value that you’ll need to access any endpoints requiring authentication.

echo $GRVT_API_KEY
echo $GRVT_SUB_ACCOUNT_ID
echo $GRVT_AUTH_ENDPOINT

RESPONSE=$(
    curl $GRVT_AUTH_ENDPOINT \
        -H 'Content-Type: application/json' \
        -H 'Cookie: rm=true;' \
        -d '{"api_key": "'$GRVT_API_KEY'"}' \
        -s -i
)

GRVT_COOKIE=$(echo "$RESPONSE" | grep -i 'set-cookie:' | grep -o 'gravity=[^;]*')
GRVT_ACCOUNT_ID=$(echo "$RESPONSE" | grep 'x-grvt-account-id:' | awk '{print $2}' | tr -d '\r')

echo "$GRVT_COOKIE"
echo "$GRVT_ACCOUNT_ID"

REST Full

curl --location 'https://trades.dev.gravitymarkets.io/full/v1/cancel_order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "order_id": "0x1028403",
    "client_order_id": "23042",
    "time_to_live_ms": "500"
}
'

JSONRPC Full

wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/cancel_order",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "order_id": "0x1028403",
        "client_order_id": "23042",
        "time_to_live_ms": "500"
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/cancel_order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "oi": "0x1028403",
    "co": "23042",
    "tt": "500"
}
'

JSONRPC Lite

wscat -c "wss://trades.dev.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/cancel_order",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "oi": "0x1028403",
        "co": "23042",
        "tt": "500"
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.staging.gravitymarkets.io/full/v1/cancel_order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "order_id": "0x1028403",
    "client_order_id": "23042",
    "time_to_live_ms": "500"
}
'

JSONRPC Full

wscat -c "wss://trades.staging.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/cancel_order",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "order_id": "0x1028403",
        "client_order_id": "23042",
        "time_to_live_ms": "500"
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/cancel_order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "oi": "0x1028403",
    "co": "23042",
    "tt": "500"
}
'

JSONRPC Lite

wscat -c "wss://trades.staging.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/cancel_order",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "oi": "0x1028403",
        "co": "23042",
        "tt": "500"
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.testnet.grvt.io/full/v1/cancel_order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "order_id": "0x1028403",
    "client_order_id": "23042",
    "time_to_live_ms": "500"
}
'

JSONRPC Full

wscat -c "wss://trades.testnet.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/cancel_order",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "order_id": "0x1028403",
        "client_order_id": "23042",
        "time_to_live_ms": "500"
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.testnet.grvt.io/lite/v1/cancel_order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "oi": "0x1028403",
    "co": "23042",
    "tt": "500"
}
'

JSONRPC Lite

wscat -c "wss://trades.testnet.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/cancel_order",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "oi": "0x1028403",
        "co": "23042",
        "tt": "500"
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.grvt.io/full/v1/cancel_order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "order_id": "0x1028403",
    "client_order_id": "23042",
    "time_to_live_ms": "500"
}
'

JSONRPC Full

wscat -c "wss://trades.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/cancel_order",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "order_id": "0x1028403",
        "client_order_id": "23042",
        "time_to_live_ms": "500"
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.grvt.io/lite/v1/cancel_order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "oi": "0x1028403",
    "co": "23042",
    "tt": "500"
}
'

JSONRPC Lite

wscat -c "wss://trades.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/cancel_order",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "oi": "0x1028403",
        "co": "23042",
        "tt": "500"
    },
    "i": 123
}
' -w 360

Cancel All Orders

FULL ENDPOINT: full/v1/cancel_all_orders
LITE ENDPOINT: lite/v1/cancel_all_orders

ApiCancelAllOrdersRequest

Cancel all orders on the orderbook for this trading account. This may not match new orders in flight.

Name
Lite		 Type Required
Default		 Description
sub_account_id
sa		 string True The subaccount ID cancelling all orders
kind
k		 [Kind] False
all		 The kind filter to apply. If nil, this defaults to all kinds. Otherwise, only entries matching the filter will be cancelled
base
b		 [Currency] False
all		 The base filter to apply. If nil, this defaults to all bases. Otherwise, only entries matching the filter will be cancelled
quote
q		 [Currency] False
all		 The quote filter to apply. If nil, this defaults to all quotes. Otherwise, only entries matching the filter will be cancelled
Kind

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

Value Description
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

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token
Currency

The list of Currencies that are supported on the GRVT exchange

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token

Query

Full Request 

{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"]
}
Lite Request 
{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"]
}

AckResponse

Used to acknowledge a request has been received and will be processed

Name
Lite		 Type Required
Default		 Description
result
r		 Ack True The Ack Object
Ack
Name
Lite		 Type Required
Default		 Description
ack
a		 boolean True Gravity has acknowledged that the request has been successfully received and it will process it in the backend

Success

Full Response 

{
    "result": {
        "ack": "true"
    }
}
Lite Response 
{
    "r": {
        "a": "true"
    }
}

Error Codes

Code HttpStatus Description
1000 401 You need to authenticate prior to using this functionality
1001 403 You are not authorized to access this functionality
1002 500 Internal Server Error
1003 400 Request could not be processed due to malformed syntax
1006 429 You have surpassed the allocated rate limit for your tier
1008 401 Your IP has not been whitelisted for access

Failure

Full Error Response 

{
    "request_id":1,
    "code":1000,
    "message":"You need to authenticate prior to using this functionality",
    "status":401
}
Lite Error Response 
{
    "ri":1,
    "c":1000,
    "m":"You need to authenticate prior to using this functionality",
    "s":401
}

Authentication

In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI.

# These are the variables you will need to set manually
GRVT_API_KEY="<insert_key_here>"
GRVT_SUB_ACCOUNT_ID="<insert_sub_account_id_here>"

Then, choose the environment you want to authenticate against.

# dev
GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login"
# staging
GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/api_key/login"
# testnet
GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/api_key/login"
# prod
GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/api_key/login"

Now, let’s authenticate and retrieve both the session cookie and the X-Grvt-Account-Id header value that you’ll need to access any endpoints requiring authentication.

echo $GRVT_API_KEY
echo $GRVT_SUB_ACCOUNT_ID
echo $GRVT_AUTH_ENDPOINT

RESPONSE=$(
    curl $GRVT_AUTH_ENDPOINT \
        -H 'Content-Type: application/json' \
        -H 'Cookie: rm=true;' \
        -d '{"api_key": "'$GRVT_API_KEY'"}' \
        -s -i
)

GRVT_COOKIE=$(echo "$RESPONSE" | grep -i 'set-cookie:' | grep -o 'gravity=[^;]*')
GRVT_ACCOUNT_ID=$(echo "$RESPONSE" | grep 'x-grvt-account-id:' | awk '{print $2}' | tr -d '\r')

echo "$GRVT_COOKIE"
echo "$GRVT_ACCOUNT_ID"

REST Full

curl --location 'https://trades.dev.gravitymarkets.io/full/v1/cancel_all_orders' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"]
}
'

JSONRPC Full

wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/cancel_all_orders",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "kind": ["PERPETUAL"],
        "base": ["BTC", "ETH"],
        "quote": ["USDT", "USDC"]
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/cancel_all_orders' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"]
}
'

JSONRPC Lite

wscat -c "wss://trades.dev.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/cancel_all_orders",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "k": ["PERPETUAL"],
        "b": ["BTC", "ETH"],
        "q": ["USDT", "USDC"]
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.staging.gravitymarkets.io/full/v1/cancel_all_orders' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"]
}
'

JSONRPC Full

wscat -c "wss://trades.staging.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/cancel_all_orders",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "kind": ["PERPETUAL"],
        "base": ["BTC", "ETH"],
        "quote": ["USDT", "USDC"]
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/cancel_all_orders' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"]
}
'

JSONRPC Lite

wscat -c "wss://trades.staging.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/cancel_all_orders",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "k": ["PERPETUAL"],
        "b": ["BTC", "ETH"],
        "q": ["USDT", "USDC"]
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.testnet.grvt.io/full/v1/cancel_all_orders' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"]
}
'

JSONRPC Full

wscat -c "wss://trades.testnet.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/cancel_all_orders",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "kind": ["PERPETUAL"],
        "base": ["BTC", "ETH"],
        "quote": ["USDT", "USDC"]
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.testnet.grvt.io/lite/v1/cancel_all_orders' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"]
}
'

JSONRPC Lite

wscat -c "wss://trades.testnet.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/cancel_all_orders",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "k": ["PERPETUAL"],
        "b": ["BTC", "ETH"],
        "q": ["USDT", "USDC"]
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.grvt.io/full/v1/cancel_all_orders' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"]
}
'

JSONRPC Full

wscat -c "wss://trades.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/cancel_all_orders",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "kind": ["PERPETUAL"],
        "base": ["BTC", "ETH"],
        "quote": ["USDT", "USDC"]
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.grvt.io/lite/v1/cancel_all_orders' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"]
}
'

JSONRPC Lite

wscat -c "wss://trades.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/cancel_all_orders",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "k": ["PERPETUAL"],
        "b": ["BTC", "ETH"],
        "q": ["USDT", "USDC"]
    },
    "i": 123
}
' -w 360

Get Order

FULL ENDPOINT: full/v1/order
LITE ENDPOINT: lite/v1/order

ApiGetOrderRequest

Retrieve the order for the account. Either order_id or client_order_id must be provided.

Name
Lite		 Type Required
Default		 Description
sub_account_id
sa		 string True The subaccount ID to filter by
order_id
oi		 string False
0		 Filter for order_id
client_order_id
co		 string False
0		 Filter for client_order_id

Query

Full Request 

{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "order_id": "0x1028403",
    "client_order_id": "23042"
}
Lite Request 
{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "oi": "0x1028403",
    "co": "23042"
}

ApiGetOrderResponse

Name
Lite		 Type Required
Default		 Description
result
r		 Order True The order object for the requested filter
Order

Order is a typed payload used throughout the GRVT platform to express all orderbook, RFQ, and liquidation orders.
GRVT orders are capable of expressing both single-legged, and multi-legged orders by default.
This increases the learning curve slightly but reduces overall integration load, since the order payload is used across all GRVT trading venues.
Given GRVT's trustless settlement model, the Order payload also carries the signature, required to trade the order on our ZKSync Hyperchain.

All fields in the Order payload (except id, metadata, and state) are trustlessly enforced on our Hyperchain.
This minimizes the amount of trust users have to offer to GRVT

Name
Lite		 Type Required
Default		 Description
order_id
oi		 string False
0		 [Filled by GRVT Backend] A unique 128-bit identifier for the order, deterministically generated within the GRVT backend
sub_account_id
sa		 string True The subaccount initiating the order
is_market
im		 boolean False
false		 If the order is a market order
Market Orders do not have a limit price, and are always executed according to the maker order price.
Market Orders must always be taker orders
time_in_force
ti		 TimeInForce True Four supported types of orders: GTT, IOC, AON, FOK:

  • PARTIAL EXECUTION = GTT / IOC - allows partial size execution on each leg

  • FULL EXECUTION = AON / FOK - only allows full size execution on all legs

  • TAKER ONLY = IOC / FOK - only allows taker orders

  • MAKER OR TAKER = GTT / AON - allows maker or taker orders

Exchange only supports (GTT, IOC, FOK)
RFQ Maker only supports (GTT, AON), RFQ Taker only supports (FOK)
post_only
po		 boolean False
false		 If True, Order must be a maker order. It has to fill the orderbook instead of match it.
If False, Order can be either a maker or taker order. In this case, order creation is currently subject to a speedbump of 25ms to ensure orders are matched against updated orderbook quotes.
reduce_only
ro		 boolean False
false		 If True, Order must reduce the position size, or be cancelled
legs
l		 [OrderLeg] True The legs present in this order
The legs must be sorted by Asset.Instrument/Underlying/Quote/Expiration/StrikePrice
signature
s		 Signature True The signature approving this order
metadata
m		 OrderMetadata True Order Metadata, ignored by the smart contract, and unsigned by the client
state
s1		 OrderState False
''		 [Filled by GRVT Backend] The current state of the order, ignored by the smart contract, and unsigned by the client
TimeInForce
Must Fill All Can Fill Partial
Must Fill Immediately FOK IOC
Can Fill Till Time AON GTC

Value Description
GOOD_TILL_TIME = 1 GTT - Remains open until it is cancelled, or expired
ALL_OR_NONE = 2 AON - Either fill the whole order or none of it (Block Trades Only)
IMMEDIATE_OR_CANCEL = 3 IOC - Fill the order as much as possible, when hitting the orderbook. Then cancel it
FILL_OR_KILL = 4 FOK - Both AoN and IoC. Either fill the full order when hitting the orderbook, or cancel it
RETAIL_PRICE_IMPROVEMENT = 5 RPI - A GTT + PostOnly maker order, that can only be taken by non-algorithmic UI users.
OrderLeg
Name
Lite		 Type Required
Default		 Description
instrument
i		 string True The instrument to trade in this leg
size
s		 string True The total number of assets to trade in this leg, expressed in base asset decimal units.
limit_price
lp		 string False
0		 The limit price of the order leg, expressed in 9 decimals.
This is the number of quote currency units to pay/receive for this leg.
This should be null/0 if the order is a market order
is_buying_asset
ib		 boolean True Specifies if the order leg is a buy or sell
Signature
Name
Lite		 Type Required
Default		 Description
signer
s		 string True The address (public key) of the wallet signing the payload
r
r		 string True Signature R
s
s1		 string True Signature S
v
v		 integer True Signature V
expiration
e		 string True Timestamp after which this signature expires, expressed in unix nanoseconds. Must be capped at 30 days
nonce
n		 integer True Users can randomly generate this value, used as a signature deconflicting key.
ie. You can send the same exact instruction twice with different nonces.
When the same nonce is used, the same payload will generate the same signature.
Our system will consider the payload a duplicate, and ignore it.
OrderMetadata

Metadata fields are used to support Backend only operations. These operations are not trustless by nature.
Hence, fields in here are never signed, and is never transmitted to the smart contract.

Name
Lite		 Type Required
Default		 Description
client_order_id
co		 string True A unique identifier for the active order within a subaccount, specified by the client
This is used to identify the order in the client's system
This field can be used for order amendment/cancellation, but has no bearing on the smart contract layer
This field will not be propagated to the smart contract, and should not be signed by the client
This value must be unique for all active orders in a subaccount, or amendment/cancellation will not work as expected
Gravity UI will generate a random clientOrderID for each order in the range [0, 2^63 - 1]
To prevent any conflicts, client machines should generate a random clientOrderID in the range [2^63, 2^64 - 1]

When GRVT Backend receives an order with an overlapping clientOrderID, we will reject the order with rejectReason set to overlappingClientOrderId
create_time
ct		 string False
0		 [Filled by GRVT Backend] Time at which the order was received by GRVT in unix nanoseconds
trigger
t		 TriggerOrderMetadata False
``		 Trigger fields are used to support any type of trigger order such as TP/SL
broker
b		 BrokerTag False
``		 Specifies the broker who brokered the order
TriggerOrderMetadata

Contains metadata related to trigger orders, such as Take Profit (TP) or Stop Loss (SL).

Trigger orders are used to automatically execute an order when a predefined price condition is met, allowing traders to implement risk management strategies.


Name
Lite		 Type Required
Default		 Description
trigger_type
tt		 TriggerType True Type of the trigger order. eg: Take Profit, Stop Loss, etc
tpsl
t		 TPSLOrderMetadata True Contains metadata for Take Profit (TP) and Stop Loss (SL) trigger orders.
TriggerType

Defines the type of trigger order used in trading, such as Take Profit or Stop Loss.

Trigger orders allow execution based on pre-defined price conditions rather than immediate market conditions.


Value Description
UNSPECIFIED = 0 Not a trigger order. The order executes normally without any trigger conditions.
TAKE_PROFIT = 1 Take Profit Order - Executes when the price reaches a specified level to secure profits.
STOP_LOSS = 2 Stop Loss Order - Executes when the price reaches a specified level to limit losses.
TPSLOrderMetadata

Contains metadata for Take Profit (TP) and Stop Loss (SL) trigger orders.

### Fields:
- triggerBy: Defines the price type that activates the order (e.g., index price).
- triggerPrice: The price at which the order is triggered, expressed in 9 decimal precision.


Name
Lite		 Type Required
Default		 Description
trigger_by
tb		 TriggerBy True Defines the price type that activates a Take Profit (TP) or Stop Loss (SL) order
trigger_price
tp		 string True The Trigger Price of the order, expressed in 9 decimals.
close_position
cp		 boolean True If True, the order will close the position when the trigger price is reached
TriggerBy

Defines the price type that activates a Take Profit (TP) or Stop Loss (SL) order.

Trigger orders are executed when the selected price type reaches the specified trigger price.Different price types ensure flexibility in executing strategies based on market conditions.


Value Description
UNSPECIFIED = 0 no trigger condition
INDEX = 1 INDEX - Order is activated when the index price reaches the trigger price
LAST = 2 LAST - Order is activated when the last trade price reaches the trigger price
BrokerTag

BrokerTag is a tag for the broker that the order is sent from.

Value Description
UNSPECIFIED = 0
COIN_ROUTES = 1 CoinRoutes
ALERTATRON = 2 Alertatron
ORIGAMI = 3 Origami
OrderState
Name
Lite		 Type Required
Default		 Description
status
s		 OrderStatus True The status of the order
reject_reason
rr		 OrderRejectReason True The reason for rejection or cancellation
book_size
bs		 [string] True The number of assets available for orderbook/RFQ matching. Sorted in same order as Order.Legs
traded_size
ts		 [string] True The total number of assets traded. Sorted in same order as Order.Legs
update_time
ut		 string True Time at which the order was updated by GRVT, expressed in unix nanoseconds
avg_fill_price
af		 [string] True The average fill price of the order. Sorted in same order as Order.Legs
OrderStatus
Value Description
PENDING = 1 Order has been sent to the matching engine and is pending a transition to open/filled/rejected.
OPEN = 2 Order is actively matching on the matching engine, could be unfilled or partially filled.
FILLED = 3 Order is fully filled and hence closed. Taker Orders can transition directly from pending to filled, without going through open.
REJECTED = 4 Order is rejected by matching engine since if fails a particular check (See OrderRejectReason). Once an order is open, it cannot be rejected.
CANCELLED = 5 Order is cancelled by the user using one of the supported APIs (See OrderRejectReason). Before an order is open, it cannot be cancelled.
OrderRejectReason
Value Description
UNSPECIFIED = 0 order is not cancelled or rejected
CLIENT_CANCEL = 1 client called a Cancel API
CLIENT_BULK_CANCEL = 2 client called a Bulk Cancel API
CLIENT_SESSION_END = 3 client called a Session Cancel API, or set the WebSocket connection to 'cancelOrdersOnTerminate'
MARKET_CANCEL = 4 the market order was cancelled after no/partial fill. Lower precedence than other TimeInForce cancel reasons
IOC_CANCEL = 5 the IOC order was cancelled after no/partial fill
AON_CANCEL = 6 the AON order was cancelled as it could not be fully matched
FOK_CANCEL = 7 the FOK order was cancelled as it could not be fully matched
EXPIRED = 8 the order was cancelled as it has expired
FAIL_POST_ONLY = 9 the post-only order could not be posted into the orderbook
FAIL_REDUCE_ONLY = 10 the reduce-only order would have caused position size to increase
MM_PROTECTION = 11 the order was cancelled due to market maker protection trigger
SELF_TRADE_PROTECTION = 12 the order was cancelled due to self-trade protection trigger
SELF_MATCHED_SUBACCOUNT = 13 the order matched with another order from the same sub account
OVERLAPPING_CLIENT_ORDER_ID = 14 an active order on your sub account shares the same clientOrderId
BELOW_MARGIN = 15 the order will bring the sub account below initial margin requirement
LIQUIDATION = 16 the sub account is liquidated (and all open orders are cancelled by Gravity)
INSTRUMENT_INVALID = 17 instrument is invalid or not found on Gravity
INSTRUMENT_DEACTIVATED = 18 instrument is no longer tradable on Gravity. (typically due to a market halt, or instrument expiry)
SYSTEM_FAILOVER = 19 system failover resulting in loss of order state
UNAUTHORISED = 20 the credentials used (userSession/apiKeySession/walletSignature) is not authorised to perform the action
SESSION_KEY_EXPIRED = 21 the session key used to sign the order expired
SUB_ACCOUNT_NOT_FOUND = 22 the subaccount does not exist
NO_TRADE_PERMISSION = 23 the signature used to sign the order has no trade permission
UNSUPPORTED_TIME_IN_FORCE = 24 the order payload does not contain a supported TimeInForce value
MULTI_LEGGED_ORDER = 25 the order has multiple legs, but multiple legs are not supported by this venue
EXCEED_MAX_POSITION_SIZE = 26 the order would have caused the subaccount to exceed the max position size
EXCEED_MAX_SIGNATURE_EXPIRATION = 27 the signature supplied is more than 30 days in the future
MARKET_ORDER_WITH_LIMIT_PRICE = 28 the market order has a limit price set
CLIENT_CANCEL_ON_DISCONNECT_TRIGGERED = 29 client cancel on disconnect triggered
OCO_COUNTER_PART_TRIGGERED = 30 the OCO counter part order was triggered
REDUCE_ONLY_LIMIT = 31 the remaining order size was cancelled because it exceeded current position size
CLIENT_REPLACE = 32 the order was replaced by a client replace request

Success

Full Response 

{
    "result": {
        "order_id": "0x1234567890abcdef",
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "is_market": false,
        "time_in_force": "GOOD_TILL_TIME",
        "post_only": false,
        "reduce_only": false,
        "legs": [{
            "instrument": "BTC_USDT_Perp",
            "size": "10.5",
            "limit_price": "65038.01",
            "is_buying_asset": true
        }],
        "signature": {
            "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "expiration": "1697788800000000000",
            "nonce": 1234567890
        },
        "metadata": {
            "client_order_id": "23042",
            "create_time": "1697788800000000000",
            "trigger": {
                "trigger_type": "TAKE_PROFIT",
                "tpsl": {
                    "trigger_by": "LAST",
                    "trigger_price": "65038.10",
                    "close_position": false
                }
            },
            "broker": "BROKER_CODE"
        },
        "state": {
            "status": "PENDING",
            "reject_reason": "CLIENT_CANCEL",
            "book_size": ["10.5"],
            "traded_size": ["1.5"],
            "update_time": "1697788800000000000",
            "avg_fill_price": ["60000.4"]
        }
    }
}
Lite Response 
{
    "r": {
        "oi": "0x1234567890abcdef",
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "im": false,
        "ti": "GOOD_TILL_TIME",
        "po": false,
        "ro": false,
        "l": [{
            "i": "BTC_USDT_Perp",
            "s": "10.5",
            "lp": "65038.01",
            "ib": true
        }],
        "s": {
            "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "e": "1697788800000000000",
            "n": 1234567890
        },
        "m": {
            "co": "23042",
            "ct": "1697788800000000000",
            "t": {
                "tt": "TAKE_PROFIT",
                "t": {
                    "tb": "LAST",
                    "tp": "65038.10",
                    "cp": false
                }
            },
            "b": "BROKER_CODE"
        },
        "s1": {
            "s": "PENDING",
            "rr": "CLIENT_CANCEL",
            "bs": ["10.5"],
            "ts": ["1.5"],
            "ut": "1697788800000000000",
            "af": ["60000.4"]
        }
    }
}

Error Codes

Code HttpStatus Description
1000 401 You need to authenticate prior to using this functionality
1001 403 You are not authorized to access this functionality
1002 500 Internal Server Error
1003 400 Request could not be processed due to malformed syntax
1006 429 You have surpassed the allocated rate limit for your tier
1008 401 Your IP has not been whitelisted for access
1004 404 Data Not Found
3021 400 Either order ID or client order ID must be supplied

Failure

Full Error Response 

{
    "request_id":1,
    "code":1000,
    "message":"You need to authenticate prior to using this functionality",
    "status":401
}
Lite Error Response 
{
    "ri":1,
    "c":1000,
    "m":"You need to authenticate prior to using this functionality",
    "s":401
}

Authentication

In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI.

# These are the variables you will need to set manually
GRVT_API_KEY="<insert_key_here>"
GRVT_SUB_ACCOUNT_ID="<insert_sub_account_id_here>"

Then, choose the environment you want to authenticate against.

# dev
GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login"
# staging
GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/api_key/login"
# testnet
GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/api_key/login"
# prod
GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/api_key/login"

Now, let’s authenticate and retrieve both the session cookie and the X-Grvt-Account-Id header value that you’ll need to access any endpoints requiring authentication.

echo $GRVT_API_KEY
echo $GRVT_SUB_ACCOUNT_ID
echo $GRVT_AUTH_ENDPOINT

RESPONSE=$(
    curl $GRVT_AUTH_ENDPOINT \
        -H 'Content-Type: application/json' \
        -H 'Cookie: rm=true;' \
        -d '{"api_key": "'$GRVT_API_KEY'"}' \
        -s -i
)

GRVT_COOKIE=$(echo "$RESPONSE" | grep -i 'set-cookie:' | grep -o 'gravity=[^;]*')
GRVT_ACCOUNT_ID=$(echo "$RESPONSE" | grep 'x-grvt-account-id:' | awk '{print $2}' | tr -d '\r')

echo "$GRVT_COOKIE"
echo "$GRVT_ACCOUNT_ID"

REST Full

curl --location 'https://trades.dev.gravitymarkets.io/full/v1/order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "order_id": "0x1028403",
    "client_order_id": "23042"
}
'

JSONRPC Full

wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/order",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "order_id": "0x1028403",
        "client_order_id": "23042"
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "oi": "0x1028403",
    "co": "23042"
}
'

JSONRPC Lite

wscat -c "wss://trades.dev.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/order",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "oi": "0x1028403",
        "co": "23042"
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.staging.gravitymarkets.io/full/v1/order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "order_id": "0x1028403",
    "client_order_id": "23042"
}
'

JSONRPC Full

wscat -c "wss://trades.staging.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/order",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "order_id": "0x1028403",
        "client_order_id": "23042"
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "oi": "0x1028403",
    "co": "23042"
}
'

JSONRPC Lite

wscat -c "wss://trades.staging.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/order",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "oi": "0x1028403",
        "co": "23042"
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.testnet.grvt.io/full/v1/order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "order_id": "0x1028403",
    "client_order_id": "23042"
}
'

JSONRPC Full

wscat -c "wss://trades.testnet.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/order",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "order_id": "0x1028403",
        "client_order_id": "23042"
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.testnet.grvt.io/lite/v1/order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "oi": "0x1028403",
    "co": "23042"
}
'

JSONRPC Lite

wscat -c "wss://trades.testnet.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/order",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "oi": "0x1028403",
        "co": "23042"
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.grvt.io/full/v1/order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "order_id": "0x1028403",
    "client_order_id": "23042"
}
'

JSONRPC Full

wscat -c "wss://trades.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/order",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "order_id": "0x1028403",
        "client_order_id": "23042"
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.grvt.io/lite/v1/order' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "oi": "0x1028403",
    "co": "23042"
}
'

JSONRPC Lite

wscat -c "wss://trades.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/order",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "oi": "0x1028403",
        "co": "23042"
    },
    "i": 123
}
' -w 360

Open Orders

FULL ENDPOINT: full/v1/open_orders
LITE ENDPOINT: lite/v1/open_orders

ApiOpenOrdersRequest

Name
Lite		 Type Required
Default		 Description
sub_account_id
sa		 string True The subaccount ID to filter by
kind
k		 [Kind] False
all		 The kind filter to apply. If nil, this defaults to all kinds. Otherwise, only entries matching the filter will be returned
base
b		 [Currency] False
all		 The base filter to apply. If nil, this defaults to all bases. Otherwise, only entries matching the filter will be returned
quote
q		 [Currency] False
all		 The quote filter to apply. If nil, this defaults to all quotes. Otherwise, only entries matching the filter will be returned
Kind

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

Value Description
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

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token
Currency

The list of Currencies that are supported on the GRVT exchange

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token

Query

Full Request 

{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"]
}
Lite Request 
{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"]
}

ApiOpenOrdersResponse

Retrieves all open orders for the account. This may not match new orders in flight.

Name
Lite		 Type Required
Default		 Description
result
r		 [Order] True The Open Orders matching the request filter
Order

Order is a typed payload used throughout the GRVT platform to express all orderbook, RFQ, and liquidation orders.
GRVT orders are capable of expressing both single-legged, and multi-legged orders by default.
This increases the learning curve slightly but reduces overall integration load, since the order payload is used across all GRVT trading venues.
Given GRVT's trustless settlement model, the Order payload also carries the signature, required to trade the order on our ZKSync Hyperchain.

All fields in the Order payload (except id, metadata, and state) are trustlessly enforced on our Hyperchain.
This minimizes the amount of trust users have to offer to GRVT

Name
Lite		 Type Required
Default		 Description
order_id
oi		 string False
0		 [Filled by GRVT Backend] A unique 128-bit identifier for the order, deterministically generated within the GRVT backend
sub_account_id
sa		 string True The subaccount initiating the order
is_market
im		 boolean False
false		 If the order is a market order
Market Orders do not have a limit price, and are always executed according to the maker order price.
Market Orders must always be taker orders
time_in_force
ti		 TimeInForce True Four supported types of orders: GTT, IOC, AON, FOK:

  • PARTIAL EXECUTION = GTT / IOC - allows partial size execution on each leg

  • FULL EXECUTION = AON / FOK - only allows full size execution on all legs

  • TAKER ONLY = IOC / FOK - only allows taker orders

  • MAKER OR TAKER = GTT / AON - allows maker or taker orders

Exchange only supports (GTT, IOC, FOK)
RFQ Maker only supports (GTT, AON), RFQ Taker only supports (FOK)
post_only
po		 boolean False
false		 If True, Order must be a maker order. It has to fill the orderbook instead of match it.
If False, Order can be either a maker or taker order. In this case, order creation is currently subject to a speedbump of 25ms to ensure orders are matched against updated orderbook quotes.
reduce_only
ro		 boolean False
false		 If True, Order must reduce the position size, or be cancelled
legs
l		 [OrderLeg] True The legs present in this order
The legs must be sorted by Asset.Instrument/Underlying/Quote/Expiration/StrikePrice
signature
s		 Signature True The signature approving this order
metadata
m		 OrderMetadata True Order Metadata, ignored by the smart contract, and unsigned by the client
state
s1		 OrderState False
''		 [Filled by GRVT Backend] The current state of the order, ignored by the smart contract, and unsigned by the client
TimeInForce
Must Fill All Can Fill Partial
Must Fill Immediately FOK IOC
Can Fill Till Time AON GTC

Value Description
GOOD_TILL_TIME = 1 GTT - Remains open until it is cancelled, or expired
ALL_OR_NONE = 2 AON - Either fill the whole order or none of it (Block Trades Only)
IMMEDIATE_OR_CANCEL = 3 IOC - Fill the order as much as possible, when hitting the orderbook. Then cancel it
FILL_OR_KILL = 4 FOK - Both AoN and IoC. Either fill the full order when hitting the orderbook, or cancel it
RETAIL_PRICE_IMPROVEMENT = 5 RPI - A GTT + PostOnly maker order, that can only be taken by non-algorithmic UI users.
OrderLeg
Name
Lite		 Type Required
Default		 Description
instrument
i		 string True The instrument to trade in this leg
size
s		 string True The total number of assets to trade in this leg, expressed in base asset decimal units.
limit_price
lp		 string False
0		 The limit price of the order leg, expressed in 9 decimals.
This is the number of quote currency units to pay/receive for this leg.
This should be null/0 if the order is a market order
is_buying_asset
ib		 boolean True Specifies if the order leg is a buy or sell
Signature
Name
Lite		 Type Required
Default		 Description
signer
s		 string True The address (public key) of the wallet signing the payload
r
r		 string True Signature R
s
s1		 string True Signature S
v
v		 integer True Signature V
expiration
e		 string True Timestamp after which this signature expires, expressed in unix nanoseconds. Must be capped at 30 days
nonce
n		 integer True Users can randomly generate this value, used as a signature deconflicting key.
ie. You can send the same exact instruction twice with different nonces.
When the same nonce is used, the same payload will generate the same signature.
Our system will consider the payload a duplicate, and ignore it.
OrderMetadata

Metadata fields are used to support Backend only operations. These operations are not trustless by nature.
Hence, fields in here are never signed, and is never transmitted to the smart contract.

Name
Lite		 Type Required
Default		 Description
client_order_id
co		 string True A unique identifier for the active order within a subaccount, specified by the client
This is used to identify the order in the client's system
This field can be used for order amendment/cancellation, but has no bearing on the smart contract layer
This field will not be propagated to the smart contract, and should not be signed by the client
This value must be unique for all active orders in a subaccount, or amendment/cancellation will not work as expected
Gravity UI will generate a random clientOrderID for each order in the range [0, 2^63 - 1]
To prevent any conflicts, client machines should generate a random clientOrderID in the range [2^63, 2^64 - 1]

When GRVT Backend receives an order with an overlapping clientOrderID, we will reject the order with rejectReason set to overlappingClientOrderId
create_time
ct		 string False
0		 [Filled by GRVT Backend] Time at which the order was received by GRVT in unix nanoseconds
trigger
t		 TriggerOrderMetadata False
``		 Trigger fields are used to support any type of trigger order such as TP/SL
broker
b		 BrokerTag False
``		 Specifies the broker who brokered the order
TriggerOrderMetadata

Contains metadata related to trigger orders, such as Take Profit (TP) or Stop Loss (SL).

Trigger orders are used to automatically execute an order when a predefined price condition is met, allowing traders to implement risk management strategies.


Name
Lite		 Type Required
Default		 Description
trigger_type
tt		 TriggerType True Type of the trigger order. eg: Take Profit, Stop Loss, etc
tpsl
t		 TPSLOrderMetadata True Contains metadata for Take Profit (TP) and Stop Loss (SL) trigger orders.
TriggerType

Defines the type of trigger order used in trading, such as Take Profit or Stop Loss.

Trigger orders allow execution based on pre-defined price conditions rather than immediate market conditions.


Value Description
UNSPECIFIED = 0 Not a trigger order. The order executes normally without any trigger conditions.
TAKE_PROFIT = 1 Take Profit Order - Executes when the price reaches a specified level to secure profits.
STOP_LOSS = 2 Stop Loss Order - Executes when the price reaches a specified level to limit losses.
TPSLOrderMetadata

Contains metadata for Take Profit (TP) and Stop Loss (SL) trigger orders.

### Fields:
- triggerBy: Defines the price type that activates the order (e.g., index price).
- triggerPrice: The price at which the order is triggered, expressed in 9 decimal precision.


Name
Lite		 Type Required
Default		 Description
trigger_by
tb		 TriggerBy True Defines the price type that activates a Take Profit (TP) or Stop Loss (SL) order
trigger_price
tp		 string True The Trigger Price of the order, expressed in 9 decimals.
close_position
cp		 boolean True If True, the order will close the position when the trigger price is reached
TriggerBy

Defines the price type that activates a Take Profit (TP) or Stop Loss (SL) order.

Trigger orders are executed when the selected price type reaches the specified trigger price.Different price types ensure flexibility in executing strategies based on market conditions.


Value Description
UNSPECIFIED = 0 no trigger condition
INDEX = 1 INDEX - Order is activated when the index price reaches the trigger price
LAST = 2 LAST - Order is activated when the last trade price reaches the trigger price
BrokerTag

BrokerTag is a tag for the broker that the order is sent from.

Value Description
UNSPECIFIED = 0
COIN_ROUTES = 1 CoinRoutes
ALERTATRON = 2 Alertatron
ORIGAMI = 3 Origami
OrderState
Name
Lite		 Type Required
Default		 Description
status
s		 OrderStatus True The status of the order
reject_reason
rr		 OrderRejectReason True The reason for rejection or cancellation
book_size
bs		 [string] True The number of assets available for orderbook/RFQ matching. Sorted in same order as Order.Legs
traded_size
ts		 [string] True The total number of assets traded. Sorted in same order as Order.Legs
update_time
ut		 string True Time at which the order was updated by GRVT, expressed in unix nanoseconds
avg_fill_price
af		 [string] True The average fill price of the order. Sorted in same order as Order.Legs
OrderStatus
Value Description
PENDING = 1 Order has been sent to the matching engine and is pending a transition to open/filled/rejected.
OPEN = 2 Order is actively matching on the matching engine, could be unfilled or partially filled.
FILLED = 3 Order is fully filled and hence closed. Taker Orders can transition directly from pending to filled, without going through open.
REJECTED = 4 Order is rejected by matching engine since if fails a particular check (See OrderRejectReason). Once an order is open, it cannot be rejected.
CANCELLED = 5 Order is cancelled by the user using one of the supported APIs (See OrderRejectReason). Before an order is open, it cannot be cancelled.
OrderRejectReason
Value Description
UNSPECIFIED = 0 order is not cancelled or rejected
CLIENT_CANCEL = 1 client called a Cancel API
CLIENT_BULK_CANCEL = 2 client called a Bulk Cancel API
CLIENT_SESSION_END = 3 client called a Session Cancel API, or set the WebSocket connection to 'cancelOrdersOnTerminate'
MARKET_CANCEL = 4 the market order was cancelled after no/partial fill. Lower precedence than other TimeInForce cancel reasons
IOC_CANCEL = 5 the IOC order was cancelled after no/partial fill
AON_CANCEL = 6 the AON order was cancelled as it could not be fully matched
FOK_CANCEL = 7 the FOK order was cancelled as it could not be fully matched
EXPIRED = 8 the order was cancelled as it has expired
FAIL_POST_ONLY = 9 the post-only order could not be posted into the orderbook
FAIL_REDUCE_ONLY = 10 the reduce-only order would have caused position size to increase
MM_PROTECTION = 11 the order was cancelled due to market maker protection trigger
SELF_TRADE_PROTECTION = 12 the order was cancelled due to self-trade protection trigger
SELF_MATCHED_SUBACCOUNT = 13 the order matched with another order from the same sub account
OVERLAPPING_CLIENT_ORDER_ID = 14 an active order on your sub account shares the same clientOrderId
BELOW_MARGIN = 15 the order will bring the sub account below initial margin requirement
LIQUIDATION = 16 the sub account is liquidated (and all open orders are cancelled by Gravity)
INSTRUMENT_INVALID = 17 instrument is invalid or not found on Gravity
INSTRUMENT_DEACTIVATED = 18 instrument is no longer tradable on Gravity. (typically due to a market halt, or instrument expiry)
SYSTEM_FAILOVER = 19 system failover resulting in loss of order state
UNAUTHORISED = 20 the credentials used (userSession/apiKeySession/walletSignature) is not authorised to perform the action
SESSION_KEY_EXPIRED = 21 the session key used to sign the order expired
SUB_ACCOUNT_NOT_FOUND = 22 the subaccount does not exist
NO_TRADE_PERMISSION = 23 the signature used to sign the order has no trade permission
UNSUPPORTED_TIME_IN_FORCE = 24 the order payload does not contain a supported TimeInForce value
MULTI_LEGGED_ORDER = 25 the order has multiple legs, but multiple legs are not supported by this venue
EXCEED_MAX_POSITION_SIZE = 26 the order would have caused the subaccount to exceed the max position size
EXCEED_MAX_SIGNATURE_EXPIRATION = 27 the signature supplied is more than 30 days in the future
MARKET_ORDER_WITH_LIMIT_PRICE = 28 the market order has a limit price set
CLIENT_CANCEL_ON_DISCONNECT_TRIGGERED = 29 client cancel on disconnect triggered
OCO_COUNTER_PART_TRIGGERED = 30 the OCO counter part order was triggered
REDUCE_ONLY_LIMIT = 31 the remaining order size was cancelled because it exceeded current position size
CLIENT_REPLACE = 32 the order was replaced by a client replace request

Success

Full Response 

{
    "result": [{
        "order_id": "0x1234567890abcdef",
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "is_market": false,
        "time_in_force": "GOOD_TILL_TIME",
        "post_only": false,
        "reduce_only": false,
        "legs": [{
            "instrument": "BTC_USDT_Perp",
            "size": "10.5",
            "limit_price": "65038.01",
            "is_buying_asset": true
        }],
        "signature": {
            "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "expiration": "1697788800000000000",
            "nonce": 1234567890
        },
        "metadata": {
            "client_order_id": "23042",
            "create_time": "1697788800000000000",
            "trigger": {
                "trigger_type": "TAKE_PROFIT",
                "tpsl": {
                    "trigger_by": "LAST",
                    "trigger_price": "65038.10",
                    "close_position": false
                }
            },
            "broker": "BROKER_CODE"
        },
        "state": {
            "status": "PENDING",
            "reject_reason": "CLIENT_CANCEL",
            "book_size": ["10.5"],
            "traded_size": ["1.5"],
            "update_time": "1697788800000000000",
            "avg_fill_price": ["60000.4"]
        }
    }]
}
Lite Response 
{
    "r": [{
        "oi": "0x1234567890abcdef",
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "im": false,
        "ti": "GOOD_TILL_TIME",
        "po": false,
        "ro": false,
        "l": [{
            "i": "BTC_USDT_Perp",
            "s": "10.5",
            "lp": "65038.01",
            "ib": true
        }],
        "s": {
            "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "e": "1697788800000000000",
            "n": 1234567890
        },
        "m": {
            "co": "23042",
            "ct": "1697788800000000000",
            "t": {
                "tt": "TAKE_PROFIT",
                "t": {
                    "tb": "LAST",
                    "tp": "65038.10",
                    "cp": false
                }
            },
            "b": "BROKER_CODE"
        },
        "s1": {
            "s": "PENDING",
            "rr": "CLIENT_CANCEL",
            "bs": ["10.5"],
            "ts": ["1.5"],
            "ut": "1697788800000000000",
            "af": ["60000.4"]
        }
    }]
}

Error Codes

Code HttpStatus Description
1000 401 You need to authenticate prior to using this functionality
1001 403 You are not authorized to access this functionality
1002 500 Internal Server Error
1006 429 You have surpassed the allocated rate limit for your tier
1008 401 Your IP has not been whitelisted for access
1003 400 Request could not be processed due to malformed syntax

Failure

Full Error Response 

{
    "request_id":1,
    "code":1000,
    "message":"You need to authenticate prior to using this functionality",
    "status":401
}
Lite Error Response 
{
    "ri":1,
    "c":1000,
    "m":"You need to authenticate prior to using this functionality",
    "s":401
}

Authentication

In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI.

# These are the variables you will need to set manually
GRVT_API_KEY="<insert_key_here>"
GRVT_SUB_ACCOUNT_ID="<insert_sub_account_id_here>"

Then, choose the environment you want to authenticate against.

# dev
GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login"
# staging
GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/api_key/login"
# testnet
GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/api_key/login"
# prod
GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/api_key/login"

Now, let’s authenticate and retrieve both the session cookie and the X-Grvt-Account-Id header value that you’ll need to access any endpoints requiring authentication.

echo $GRVT_API_KEY
echo $GRVT_SUB_ACCOUNT_ID
echo $GRVT_AUTH_ENDPOINT

RESPONSE=$(
    curl $GRVT_AUTH_ENDPOINT \
        -H 'Content-Type: application/json' \
        -H 'Cookie: rm=true;' \
        -d '{"api_key": "'$GRVT_API_KEY'"}' \
        -s -i
)

GRVT_COOKIE=$(echo "$RESPONSE" | grep -i 'set-cookie:' | grep -o 'gravity=[^;]*')
GRVT_ACCOUNT_ID=$(echo "$RESPONSE" | grep 'x-grvt-account-id:' | awk '{print $2}' | tr -d '\r')

echo "$GRVT_COOKIE"
echo "$GRVT_ACCOUNT_ID"

REST Full

curl --location 'https://trades.dev.gravitymarkets.io/full/v1/open_orders' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"]
}
'

JSONRPC Full

wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/open_orders",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "kind": ["PERPETUAL"],
        "base": ["BTC", "ETH"],
        "quote": ["USDT", "USDC"]
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/open_orders' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"]
}
'

JSONRPC Lite

wscat -c "wss://trades.dev.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/open_orders",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "k": ["PERPETUAL"],
        "b": ["BTC", "ETH"],
        "q": ["USDT", "USDC"]
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.staging.gravitymarkets.io/full/v1/open_orders' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"]
}
'

JSONRPC Full

wscat -c "wss://trades.staging.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/open_orders",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "kind": ["PERPETUAL"],
        "base": ["BTC", "ETH"],
        "quote": ["USDT", "USDC"]
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/open_orders' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"]
}
'

JSONRPC Lite

wscat -c "wss://trades.staging.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/open_orders",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "k": ["PERPETUAL"],
        "b": ["BTC", "ETH"],
        "q": ["USDT", "USDC"]
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.testnet.grvt.io/full/v1/open_orders' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"]
}
'

JSONRPC Full

wscat -c "wss://trades.testnet.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/open_orders",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "kind": ["PERPETUAL"],
        "base": ["BTC", "ETH"],
        "quote": ["USDT", "USDC"]
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.testnet.grvt.io/lite/v1/open_orders' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"]
}
'

JSONRPC Lite

wscat -c "wss://trades.testnet.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/open_orders",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "k": ["PERPETUAL"],
        "b": ["BTC", "ETH"],
        "q": ["USDT", "USDC"]
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.grvt.io/full/v1/open_orders' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"]
}
'

JSONRPC Full

wscat -c "wss://trades.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/open_orders",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "kind": ["PERPETUAL"],
        "base": ["BTC", "ETH"],
        "quote": ["USDT", "USDC"]
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.grvt.io/lite/v1/open_orders' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"]
}
'

JSONRPC Lite

wscat -c "wss://trades.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/open_orders",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "k": ["PERPETUAL"],
        "b": ["BTC", "ETH"],
        "q": ["USDT", "USDC"]
    },
    "i": 123
}
' -w 360

Order History

FULL ENDPOINT: full/v1/order_history
LITE ENDPOINT: lite/v1/order_history

ApiOrderHistoryRequest

Retrieves the order history for the account.

Pagination works as follows:

  • We perform a reverse chronological lookup, starting from end_time. If end_time is not set, we start from the most recent data.
  • The lookup is limited to limit records. If more data is requested, the response will contain a next cursor for you to query the next page.
  • If a cursor is provided, it will be used to fetch results from that point onwards.
  • Pagination will continue until the start_time is reached. If start_time is not set, pagination will continue as far back as our data retention policy allows.

Name
Lite		 Type Required
Default		 Description
sub_account_id
sa		 string True The subaccount ID to filter by
kind
k		 [Kind] False
all		 The kind filter to apply. If nil, this defaults to all kinds. Otherwise, only entries matching the filter will be returned
base
b		 [Currency] False
all		 The base filter to apply. If nil, this defaults to all bases. Otherwise, only entries matching the filter will be returned
quote
q		 [Currency] False
all		 The quote filter to apply. If nil, this defaults to all quotes. Otherwise, only entries matching the filter will be returned
start_time
st		 string False
0		 The start time to apply in nanoseconds. If nil, this defaults to all start times. Otherwise, only entries matching the filter will be returned
end_time
et		 string False
now()		 The end time to apply in nanoseconds. If nil, this defaults to all end times. Otherwise, only entries matching the filter will be returned
limit
l		 integer False
500		 The limit to query for. Defaults to 500; Max 1000
cursor
c		 string False
''		 The cursor to indicate when to start the query from
Kind

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

Value Description
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

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token
Currency

The list of Currencies that are supported on the GRVT exchange

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token

Query

Full Request 

{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": ""
}
Lite Request 
{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c": ""
}

ApiOrderHistoryResponse

Name
Lite		 Type Required
Default		 Description
result
r		 [Order] True The Open Orders matching the request filter
next
n		 string True The cursor to indicate when to start the query from
Order

Order is a typed payload used throughout the GRVT platform to express all orderbook, RFQ, and liquidation orders.
GRVT orders are capable of expressing both single-legged, and multi-legged orders by default.
This increases the learning curve slightly but reduces overall integration load, since the order payload is used across all GRVT trading venues.
Given GRVT's trustless settlement model, the Order payload also carries the signature, required to trade the order on our ZKSync Hyperchain.

All fields in the Order payload (except id, metadata, and state) are trustlessly enforced on our Hyperchain.
This minimizes the amount of trust users have to offer to GRVT

Name
Lite		 Type Required
Default		 Description
order_id
oi		 string False
0		 [Filled by GRVT Backend] A unique 128-bit identifier for the order, deterministically generated within the GRVT backend
sub_account_id
sa		 string True The subaccount initiating the order
is_market
im		 boolean False
false		 If the order is a market order
Market Orders do not have a limit price, and are always executed according to the maker order price.
Market Orders must always be taker orders
time_in_force
ti		 TimeInForce True Four supported types of orders: GTT, IOC, AON, FOK:

  • PARTIAL EXECUTION = GTT / IOC - allows partial size execution on each leg

  • FULL EXECUTION = AON / FOK - only allows full size execution on all legs

  • TAKER ONLY = IOC / FOK - only allows taker orders

  • MAKER OR TAKER = GTT / AON - allows maker or taker orders

Exchange only supports (GTT, IOC, FOK)
RFQ Maker only supports (GTT, AON), RFQ Taker only supports (FOK)
post_only
po		 boolean False
false		 If True, Order must be a maker order. It has to fill the orderbook instead of match it.
If False, Order can be either a maker or taker order. In this case, order creation is currently subject to a speedbump of 25ms to ensure orders are matched against updated orderbook quotes.
reduce_only
ro		 boolean False
false		 If True, Order must reduce the position size, or be cancelled
legs
l		 [OrderLeg] True The legs present in this order
The legs must be sorted by Asset.Instrument/Underlying/Quote/Expiration/StrikePrice
signature
s		 Signature True The signature approving this order
metadata
m		 OrderMetadata True Order Metadata, ignored by the smart contract, and unsigned by the client
state
s1		 OrderState False
''		 [Filled by GRVT Backend] The current state of the order, ignored by the smart contract, and unsigned by the client
TimeInForce
Must Fill All Can Fill Partial
Must Fill Immediately FOK IOC
Can Fill Till Time AON GTC

Value Description
GOOD_TILL_TIME = 1 GTT - Remains open until it is cancelled, or expired
ALL_OR_NONE = 2 AON - Either fill the whole order or none of it (Block Trades Only)
IMMEDIATE_OR_CANCEL = 3 IOC - Fill the order as much as possible, when hitting the orderbook. Then cancel it
FILL_OR_KILL = 4 FOK - Both AoN and IoC. Either fill the full order when hitting the orderbook, or cancel it
RETAIL_PRICE_IMPROVEMENT = 5 RPI - A GTT + PostOnly maker order, that can only be taken by non-algorithmic UI users.
OrderLeg
Name
Lite		 Type Required
Default		 Description
instrument
i		 string True The instrument to trade in this leg
size
s		 string True The total number of assets to trade in this leg, expressed in base asset decimal units.
limit_price
lp		 string False
0		 The limit price of the order leg, expressed in 9 decimals.
This is the number of quote currency units to pay/receive for this leg.
This should be null/0 if the order is a market order
is_buying_asset
ib		 boolean True Specifies if the order leg is a buy or sell
Signature
Name
Lite		 Type Required
Default		 Description
signer
s		 string True The address (public key) of the wallet signing the payload
r
r		 string True Signature R
s
s1		 string True Signature S
v
v		 integer True Signature V
expiration
e		 string True Timestamp after which this signature expires, expressed in unix nanoseconds. Must be capped at 30 days
nonce
n		 integer True Users can randomly generate this value, used as a signature deconflicting key.
ie. You can send the same exact instruction twice with different nonces.
When the same nonce is used, the same payload will generate the same signature.
Our system will consider the payload a duplicate, and ignore it.
OrderMetadata

Metadata fields are used to support Backend only operations. These operations are not trustless by nature.
Hence, fields in here are never signed, and is never transmitted to the smart contract.

Name
Lite		 Type Required
Default		 Description
client_order_id
co		 string True A unique identifier for the active order within a subaccount, specified by the client
This is used to identify the order in the client's system
This field can be used for order amendment/cancellation, but has no bearing on the smart contract layer
This field will not be propagated to the smart contract, and should not be signed by the client
This value must be unique for all active orders in a subaccount, or amendment/cancellation will not work as expected
Gravity UI will generate a random clientOrderID for each order in the range [0, 2^63 - 1]
To prevent any conflicts, client machines should generate a random clientOrderID in the range [2^63, 2^64 - 1]

When GRVT Backend receives an order with an overlapping clientOrderID, we will reject the order with rejectReason set to overlappingClientOrderId
create_time
ct		 string False
0		 [Filled by GRVT Backend] Time at which the order was received by GRVT in unix nanoseconds
trigger
t		 TriggerOrderMetadata False
``		 Trigger fields are used to support any type of trigger order such as TP/SL
broker
b		 BrokerTag False
``		 Specifies the broker who brokered the order
TriggerOrderMetadata

Contains metadata related to trigger orders, such as Take Profit (TP) or Stop Loss (SL).

Trigger orders are used to automatically execute an order when a predefined price condition is met, allowing traders to implement risk management strategies.


Name
Lite		 Type Required
Default		 Description
trigger_type
tt		 TriggerType True Type of the trigger order. eg: Take Profit, Stop Loss, etc
tpsl
t		 TPSLOrderMetadata True Contains metadata for Take Profit (TP) and Stop Loss (SL) trigger orders.
TriggerType

Defines the type of trigger order used in trading, such as Take Profit or Stop Loss.

Trigger orders allow execution based on pre-defined price conditions rather than immediate market conditions.


Value Description
UNSPECIFIED = 0 Not a trigger order. The order executes normally without any trigger conditions.
TAKE_PROFIT = 1 Take Profit Order - Executes when the price reaches a specified level to secure profits.
STOP_LOSS = 2 Stop Loss Order - Executes when the price reaches a specified level to limit losses.
TPSLOrderMetadata

Contains metadata for Take Profit (TP) and Stop Loss (SL) trigger orders.

### Fields:
- triggerBy: Defines the price type that activates the order (e.g., index price).
- triggerPrice: The price at which the order is triggered, expressed in 9 decimal precision.


Name
Lite		 Type Required
Default		 Description
trigger_by
tb		 TriggerBy True Defines the price type that activates a Take Profit (TP) or Stop Loss (SL) order
trigger_price
tp		 string True The Trigger Price of the order, expressed in 9 decimals.
close_position
cp		 boolean True If True, the order will close the position when the trigger price is reached
TriggerBy

Defines the price type that activates a Take Profit (TP) or Stop Loss (SL) order.

Trigger orders are executed when the selected price type reaches the specified trigger price.Different price types ensure flexibility in executing strategies based on market conditions.


Value Description
UNSPECIFIED = 0 no trigger condition
INDEX = 1 INDEX - Order is activated when the index price reaches the trigger price
LAST = 2 LAST - Order is activated when the last trade price reaches the trigger price
BrokerTag

BrokerTag is a tag for the broker that the order is sent from.

Value Description
UNSPECIFIED = 0
COIN_ROUTES = 1 CoinRoutes
ALERTATRON = 2 Alertatron
ORIGAMI = 3 Origami
OrderState
Name
Lite		 Type Required
Default		 Description
status
s		 OrderStatus True The status of the order
reject_reason
rr		 OrderRejectReason True The reason for rejection or cancellation
book_size
bs		 [string] True The number of assets available for orderbook/RFQ matching. Sorted in same order as Order.Legs
traded_size
ts		 [string] True The total number of assets traded. Sorted in same order as Order.Legs
update_time
ut		 string True Time at which the order was updated by GRVT, expressed in unix nanoseconds
avg_fill_price
af		 [string] True The average fill price of the order. Sorted in same order as Order.Legs
OrderStatus
Value Description
PENDING = 1 Order has been sent to the matching engine and is pending a transition to open/filled/rejected.
OPEN = 2 Order is actively matching on the matching engine, could be unfilled or partially filled.
FILLED = 3 Order is fully filled and hence closed. Taker Orders can transition directly from pending to filled, without going through open.
REJECTED = 4 Order is rejected by matching engine since if fails a particular check (See OrderRejectReason). Once an order is open, it cannot be rejected.
CANCELLED = 5 Order is cancelled by the user using one of the supported APIs (See OrderRejectReason). Before an order is open, it cannot be cancelled.
OrderRejectReason
Value Description
UNSPECIFIED = 0 order is not cancelled or rejected
CLIENT_CANCEL = 1 client called a Cancel API
CLIENT_BULK_CANCEL = 2 client called a Bulk Cancel API
CLIENT_SESSION_END = 3 client called a Session Cancel API, or set the WebSocket connection to 'cancelOrdersOnTerminate'
MARKET_CANCEL = 4 the market order was cancelled after no/partial fill. Lower precedence than other TimeInForce cancel reasons
IOC_CANCEL = 5 the IOC order was cancelled after no/partial fill
AON_CANCEL = 6 the AON order was cancelled as it could not be fully matched
FOK_CANCEL = 7 the FOK order was cancelled as it could not be fully matched
EXPIRED = 8 the order was cancelled as it has expired
FAIL_POST_ONLY = 9 the post-only order could not be posted into the orderbook
FAIL_REDUCE_ONLY = 10 the reduce-only order would have caused position size to increase
MM_PROTECTION = 11 the order was cancelled due to market maker protection trigger
SELF_TRADE_PROTECTION = 12 the order was cancelled due to self-trade protection trigger
SELF_MATCHED_SUBACCOUNT = 13 the order matched with another order from the same sub account
OVERLAPPING_CLIENT_ORDER_ID = 14 an active order on your sub account shares the same clientOrderId
BELOW_MARGIN = 15 the order will bring the sub account below initial margin requirement
LIQUIDATION = 16 the sub account is liquidated (and all open orders are cancelled by Gravity)
INSTRUMENT_INVALID = 17 instrument is invalid or not found on Gravity
INSTRUMENT_DEACTIVATED = 18 instrument is no longer tradable on Gravity. (typically due to a market halt, or instrument expiry)
SYSTEM_FAILOVER = 19 system failover resulting in loss of order state
UNAUTHORISED = 20 the credentials used (userSession/apiKeySession/walletSignature) is not authorised to perform the action
SESSION_KEY_EXPIRED = 21 the session key used to sign the order expired
SUB_ACCOUNT_NOT_FOUND = 22 the subaccount does not exist
NO_TRADE_PERMISSION = 23 the signature used to sign the order has no trade permission
UNSUPPORTED_TIME_IN_FORCE = 24 the order payload does not contain a supported TimeInForce value
MULTI_LEGGED_ORDER = 25 the order has multiple legs, but multiple legs are not supported by this venue
EXCEED_MAX_POSITION_SIZE = 26 the order would have caused the subaccount to exceed the max position size
EXCEED_MAX_SIGNATURE_EXPIRATION = 27 the signature supplied is more than 30 days in the future
MARKET_ORDER_WITH_LIMIT_PRICE = 28 the market order has a limit price set
CLIENT_CANCEL_ON_DISCONNECT_TRIGGERED = 29 client cancel on disconnect triggered
OCO_COUNTER_PART_TRIGGERED = 30 the OCO counter part order was triggered
REDUCE_ONLY_LIMIT = 31 the remaining order size was cancelled because it exceeded current position size
CLIENT_REPLACE = 32 the order was replaced by a client replace request

Success

Full Response 

{
    "result": [{
        "order_id": "0x1234567890abcdef",
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "is_market": false,
        "time_in_force": "GOOD_TILL_TIME",
        "post_only": false,
        "reduce_only": false,
        "legs": [{
            "instrument": "BTC_USDT_Perp",
            "size": "10.5",
            "limit_price": "65038.01",
            "is_buying_asset": true
        }],
        "signature": {
            "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "expiration": "1697788800000000000",
            "nonce": 1234567890
        },
        "metadata": {
            "client_order_id": "23042",
            "create_time": "1697788800000000000",
            "trigger": {
                "trigger_type": "TAKE_PROFIT",
                "tpsl": {
                    "trigger_by": "LAST",
                    "trigger_price": "65038.10",
                    "close_position": false
                }
            },
            "broker": "BROKER_CODE"
        },
        "state": {
            "status": "PENDING",
            "reject_reason": "CLIENT_CANCEL",
            "book_size": ["10.5"],
            "traded_size": ["1.5"],
            "update_time": "1697788800000000000",
            "avg_fill_price": ["60000.4"]
        }
    }],
    "next": "Qw0918="
}
Lite Response 
{
    "r": [{
        "oi": "0x1234567890abcdef",
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "im": false,
        "ti": "GOOD_TILL_TIME",
        "po": false,
        "ro": false,
        "l": [{
            "i": "BTC_USDT_Perp",
            "s": "10.5",
            "lp": "65038.01",
            "ib": true
        }],
        "s": {
            "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "e": "1697788800000000000",
            "n": 1234567890
        },
        "m": {
            "co": "23042",
            "ct": "1697788800000000000",
            "t": {
                "tt": "TAKE_PROFIT",
                "t": {
                    "tb": "LAST",
                    "tp": "65038.10",
                    "cp": false
                }
            },
            "b": "BROKER_CODE"
        },
        "s1": {
            "s": "PENDING",
            "rr": "CLIENT_CANCEL",
            "bs": ["10.5"],
            "ts": ["1.5"],
            "ut": "1697788800000000000",
            "af": ["60000.4"]
        }
    }],
    "n": "Qw0918="
}

Error Codes

Code HttpStatus Description
1000 401 You need to authenticate prior to using this functionality
1001 403 You are not authorized to access this functionality
1002 500 Internal Server Error
1003 400 Request could not be processed due to malformed syntax
1006 429 You have surpassed the allocated rate limit for your tier
1008 401 Your IP has not been whitelisted for access

Failure

Full Error Response 

{
    "request_id":1,
    "code":1000,
    "message":"You need to authenticate prior to using this functionality",
    "status":401
}
Lite Error Response 
{
    "ri":1,
    "c":1000,
    "m":"You need to authenticate prior to using this functionality",
    "s":401
}

Authentication

In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI.

# These are the variables you will need to set manually
GRVT_API_KEY="<insert_key_here>"
GRVT_SUB_ACCOUNT_ID="<insert_sub_account_id_here>"

Then, choose the environment you want to authenticate against.

# dev
GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login"
# staging
GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/api_key/login"
# testnet
GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/api_key/login"
# prod
GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/api_key/login"

Now, let’s authenticate and retrieve both the session cookie and the X-Grvt-Account-Id header value that you’ll need to access any endpoints requiring authentication.

echo $GRVT_API_KEY
echo $GRVT_SUB_ACCOUNT_ID
echo $GRVT_AUTH_ENDPOINT

RESPONSE=$(
    curl $GRVT_AUTH_ENDPOINT \
        -H 'Content-Type: application/json' \
        -H 'Cookie: rm=true;' \
        -d '{"api_key": "'$GRVT_API_KEY'"}' \
        -s -i
)

GRVT_COOKIE=$(echo "$RESPONSE" | grep -i 'set-cookie:' | grep -o 'gravity=[^;]*')
GRVT_ACCOUNT_ID=$(echo "$RESPONSE" | grep 'x-grvt-account-id:' | awk '{print $2}' | tr -d '\r')

echo "$GRVT_COOKIE"
echo "$GRVT_ACCOUNT_ID"

REST Full

curl --location 'https://trades.dev.gravitymarkets.io/full/v1/order_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": ""
}
'

JSONRPC Full

wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/order_history",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "kind": ["PERPETUAL"],
        "base": ["BTC", "ETH"],
        "quote": ["USDT", "USDC"],
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": ""
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/order_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c": ""
}
'

JSONRPC Lite

wscat -c "wss://trades.dev.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/order_history",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "k": ["PERPETUAL"],
        "b": ["BTC", "ETH"],
        "q": ["USDT", "USDC"],
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c": ""
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.staging.gravitymarkets.io/full/v1/order_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": ""
}
'

JSONRPC Full

wscat -c "wss://trades.staging.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/order_history",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "kind": ["PERPETUAL"],
        "base": ["BTC", "ETH"],
        "quote": ["USDT", "USDC"],
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": ""
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/order_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c": ""
}
'

JSONRPC Lite

wscat -c "wss://trades.staging.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/order_history",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "k": ["PERPETUAL"],
        "b": ["BTC", "ETH"],
        "q": ["USDT", "USDC"],
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c": ""
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.testnet.grvt.io/full/v1/order_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": ""
}
'

JSONRPC Full

wscat -c "wss://trades.testnet.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/order_history",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "kind": ["PERPETUAL"],
        "base": ["BTC", "ETH"],
        "quote": ["USDT", "USDC"],
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": ""
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.testnet.grvt.io/lite/v1/order_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c": ""
}
'

JSONRPC Lite

wscat -c "wss://trades.testnet.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/order_history",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "k": ["PERPETUAL"],
        "b": ["BTC", "ETH"],
        "q": ["USDT", "USDC"],
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c": ""
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.grvt.io/full/v1/order_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": ""
}
'

JSONRPC Full

wscat -c "wss://trades.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/order_history",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "kind": ["PERPETUAL"],
        "base": ["BTC", "ETH"],
        "quote": ["USDT", "USDC"],
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": ""
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.grvt.io/lite/v1/order_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c": ""
}
'

JSONRPC Lite

wscat -c "wss://trades.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/order_history",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "k": ["PERPETUAL"],
        "b": ["BTC", "ETH"],
        "q": ["USDT", "USDC"],
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c": ""
    },
    "i": 123
}
' -w 360

Cancel On Disconnect

FULL ENDPOINT: full/v1/cancel_on_disconnect
LITE ENDPOINT: lite/v1/cancel_on_disconnect

ApiCancelOnDisconnectRequest

Auto-Cancel All Open Orders when the countdown time hits zero.

Market Maker inputs a countdown time parameter in milliseconds (e.g. 120000 for 120s) rounded down to the smallest second follows the following logic:
- Market Maker initially entered a value between 0 -> 1000, which is rounded to 0: will result in termination of their COD
- Market Maker initially entered a value between 1001 -> 300_000, which is rounded to the nearest second: will result in refresh of their COD
- Market Maker initially entered a value bigger than 300_000, which will result in error (upper bound)
Market Maker will send a heartbeat message by calling the endpoint at specific intervals (ex. every 30 seconds) to the server to refresh the count down.

If the server does not receive a heartbeat message within the countdown time, it will cancel all open orders for the specified Sub Account ID.

Name
Lite		 Type Required
Default		 Description
sub_account_id
sa		 string True The subaccount ID cancelling the orders for
countdown_time
ct		 string False
1000		 Countdown time in milliseconds (ex. 120000 for 120s).

0 to disable the timer.

Does not accept negative values.

Minimum acceptable value is 1,000.

Maximum acceptable value is 300,000

Query

Full Request 

{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "countdown_time": 300
}
Lite Request 
{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "ct": 300
}

AckResponse

Used to acknowledge a request has been received and will be processed

Name
Lite		 Type Required
Default		 Description
result
r		 Ack True The Ack Object
Ack
Name
Lite		 Type Required
Default		 Description
ack
a		 boolean True Gravity has acknowledged that the request has been successfully received and it will process it in the backend

Success

Full Response 

{
    "result": {
        "ack": "true"
    }
}
Lite Response 
{
    "r": {
        "a": "true"
    }
}

Error Codes

Code HttpStatus Description
1000 401 You need to authenticate prior to using this functionality
1001 403 You are not authorized to access this functionality
1002 500 Internal Server Error
1003 400 Request could not be processed due to malformed syntax
1006 429 You have surpassed the allocated rate limit for your tier
1008 401 Your IP has not been whitelisted for access
6000 400 Countdown time is bigger than 300s supported

Failure

Full Error Response 

{
    "request_id":1,
    "code":1000,
    "message":"You need to authenticate prior to using this functionality",
    "status":401
}
Lite Error Response 
{
    "ri":1,
    "c":1000,
    "m":"You need to authenticate prior to using this functionality",
    "s":401
}

Authentication

In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI.

# These are the variables you will need to set manually
GRVT_API_KEY="<insert_key_here>"
GRVT_SUB_ACCOUNT_ID="<insert_sub_account_id_here>"

Then, choose the environment you want to authenticate against.

# dev
GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login"
# staging
GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/api_key/login"
# testnet
GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/api_key/login"
# prod
GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/api_key/login"

Now, let’s authenticate and retrieve both the session cookie and the X-Grvt-Account-Id header value that you’ll need to access any endpoints requiring authentication.

echo $GRVT_API_KEY
echo $GRVT_SUB_ACCOUNT_ID
echo $GRVT_AUTH_ENDPOINT

RESPONSE=$(
    curl $GRVT_AUTH_ENDPOINT \
        -H 'Content-Type: application/json' \
        -H 'Cookie: rm=true;' \
        -d '{"api_key": "'$GRVT_API_KEY'"}' \
        -s -i
)

GRVT_COOKIE=$(echo "$RESPONSE" | grep -i 'set-cookie:' | grep -o 'gravity=[^;]*')
GRVT_ACCOUNT_ID=$(echo "$RESPONSE" | grep 'x-grvt-account-id:' | awk '{print $2}' | tr -d '\r')

echo "$GRVT_COOKIE"
echo "$GRVT_ACCOUNT_ID"

REST Full

curl --location 'https://trades.dev.gravitymarkets.io/full/v1/cancel_on_disconnect' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "countdown_time": 300
}
'

JSONRPC Full

wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/cancel_on_disconnect",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "countdown_time": 300
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/cancel_on_disconnect' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "ct": 300
}
'

JSONRPC Lite

wscat -c "wss://trades.dev.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/cancel_on_disconnect",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "ct": 300
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.staging.gravitymarkets.io/full/v1/cancel_on_disconnect' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "countdown_time": 300
}
'

JSONRPC Full

wscat -c "wss://trades.staging.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/cancel_on_disconnect",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "countdown_time": 300
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/cancel_on_disconnect' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "ct": 300
}
'

JSONRPC Lite

wscat -c "wss://trades.staging.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/cancel_on_disconnect",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "ct": 300
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.testnet.grvt.io/full/v1/cancel_on_disconnect' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "countdown_time": 300
}
'

JSONRPC Full

wscat -c "wss://trades.testnet.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/cancel_on_disconnect",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "countdown_time": 300
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.testnet.grvt.io/lite/v1/cancel_on_disconnect' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "ct": 300
}
'

JSONRPC Lite

wscat -c "wss://trades.testnet.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/cancel_on_disconnect",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "ct": 300
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.grvt.io/full/v1/cancel_on_disconnect' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "countdown_time": 300
}
'

JSONRPC Full

wscat -c "wss://trades.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/cancel_on_disconnect",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "countdown_time": 300
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.grvt.io/lite/v1/cancel_on_disconnect' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "ct": 300
}
'

JSONRPC Lite

wscat -c "wss://trades.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/cancel_on_disconnect",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "ct": 300
    },
    "i": 123
}
' -w 360

Execution

Fill History

FULL ENDPOINT: full/v1/fill_history
LITE ENDPOINT: lite/v1/fill_history

ApiFillHistoryRequest

Query for all historical fills made by a single account. A single order can be matched multiple times, hence there is no real way to uniquely identify a trade.

Pagination works as follows:

  • We perform a reverse chronological lookup, starting from end_time. If end_time is not set, we start from the most recent data.
  • The lookup is limited to limit records. If more data is requested, the response will contain a next cursor for you to query the next page.
  • If a cursor is provided, it will be used to fetch results from that point onwards.
  • Pagination will continue until the start_time is reached. If start_time is not set, pagination will continue as far back as our data retention policy allows.

Name
Lite		 Type Required
Default		 Description
sub_account_id
sa		 string True The sub account ID to request for
kind
k		 [Kind] False
all		 The kind filter to apply. If nil, this defaults to all kinds. Otherwise, only entries matching the filter will be returned
base
b		 [Currency] False
all		 The base filter to apply. If nil, this defaults to all bases. Otherwise, only entries matching the filter will be returned
quote
q		 [Currency] False
all		 The quote filter to apply. If nil, this defaults to all quotes. Otherwise, only entries matching the filter will be returned
start_time
st		 string False
0		 The start time to apply in unix nanoseconds. If nil, this defaults to all start times. Otherwise, only entries matching the filter will be returned
end_time
et		 string False
now()		 The end time to apply in unix nanoseconds. If nil, this defaults to all end times. Otherwise, only entries matching the filter will be returned
limit
l		 integer False
500		 The limit to query for. Defaults to 500; Max 1000
cursor
c		 string False
''		 The cursor to indicate when to start the query from
Kind

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

Value Description
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

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token
Currency

The list of Currencies that are supported on the GRVT exchange

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token

Query

Full Request 

{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": ""
}
Lite Request 
{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c": ""
}

ApiFillHistoryResponse

Name
Lite		 Type Required
Default		 Description
result
r		 [Fill] True The private trades matching the request asset
next
n		 string True The cursor to indicate when to start the query from
Fill
Name
Lite		 Type Required
Default		 Description
event_time
et		 string True Time at which the event was emitted in unix nanoseconds
sub_account_id
sa		 string True The sub account ID that participated in the trade
instrument
i		 string True The instrument being represented
is_buyer
ib		 boolean True The side that the subaccount took on the trade
is_taker
it		 boolean True The role that the subaccount took on the trade
size
s		 string True The number of assets being traded, expressed in base asset decimal units
price
p		 string True The traded price, expressed in 9 decimals
mark_price
mp		 string True The mark price of the instrument at point of trade, expressed in 9 decimals
index_price
ip		 string True The index price of the instrument at point of trade, expressed in 9 decimals
interest_rate
ir		 string True The interest rate of the underlying at point of trade, expressed in centibeeps (1/100th of a basis point)
forward_price
fp		 string True [Options] The forward price of the option at point of trade, expressed in 9 decimals
realized_pnl
rp		 string True The realized PnL of the trade, expressed in quote asset decimal units (0 if increasing position size)
fee
f		 string True The fees paid on the trade, expressed in quote asset decimal unit (negative if maker rebate applied)
fee_rate
fr		 string True The fee rate paid on the trade
trade_id
ti		 string True A trade identifier, globally unique, and monotonically increasing (not by 1).
All trades sharing a single taker execution share the same first component (before -), and event_time.
trade_id is guaranteed to be consistent across MarketData Trade and Trading Fill.
order_id
oi		 string True An order identifier
venue
v		 Venue True The venue where the trade occurred
client_order_id
co		 string True A unique identifier for the active order within a subaccount, specified by the client
This is used to identify the order in the client's system
This field can be used for order amendment/cancellation, but has no bearing on the smart contract layer
This field will not be propagated to the smart contract, and should not be signed by the client
This value must be unique for all active orders in a subaccount, or amendment/cancellation will not work as expected
Gravity UI will generate a random clientOrderID for each order in the range [0, 2^63 - 1]
To prevent any conflicts, client machines should generate a random clientOrderID in the range [2^63, 2^64 - 1]

When GRVT Backend receives an order with an overlapping clientOrderID, we will reject the order with rejectReason set to overlappingClientOrderId
signer
s1		 string True The address (public key) of the wallet signing the payload
broker
b		 BrokerTag False
``		 Specifies the broker who brokered the order
is_rpi
ir1		 boolean True If the trade is a RPI trade
Venue

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

Value Description
ORDERBOOK = 1 the trade is cleared on the orderbook venue
RFQ = 2 the trade is cleared on the RFQ venue
BrokerTag

BrokerTag is a tag for the broker that the order is sent from.

Value Description
UNSPECIFIED = 0
COIN_ROUTES = 1 CoinRoutes
ALERTATRON = 2 Alertatron
ORIGAMI = 3 Origami

Success

Full Response 

{
    "result": [{
        "event_time": "1697788800000000000",
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "instrument": "BTC_USDT_Perp",
        "is_buyer": true,
        "is_taker": true,
        "size": "0.30",
        "price": "65038.01",
        "mark_price": "65038.01",
        "index_price": "65038.01",
        "interest_rate": 0.0003,
        "forward_price": "65038.01",
        "realized_pnl": "2400.50",
        "fee": "9.75",
        "fee_rate": 0.0003,
        "trade_id": "209358-2",
        "order_id": "0x10000101000203040506",
        "venue": "ORDERBOOK",
        "client_order_id": "23042",
        "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "broker": "UNSPECIFIED",
        "is_rpi": false
    }],
    "next": "Qw0918="
}
Lite Response 
{
    "r": [{
        "et": "1697788800000000000",
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "i": "BTC_USDT_Perp",
        "ib": true,
        "it": true,
        "s": "0.30",
        "p": "65038.01",
        "mp": "65038.01",
        "ip": "65038.01",
        "ir": 0.0003,
        "fp": "65038.01",
        "rp": "2400.50",
        "f": "9.75",
        "fr": 0.0003,
        "ti": "209358-2",
        "oi": "0x10000101000203040506",
        "v": "ORDERBOOK",
        "co": "23042",
        "s1": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "b": "UNSPECIFIED",
        "ir1": false
    }],
    "n": "Qw0918="
}

Error Codes

Code HttpStatus Description
1000 401 You need to authenticate prior to using this functionality
1001 403 You are not authorized to access this functionality
1002 500 Internal Server Error
1003 400 Request could not be processed due to malformed syntax
1006 429 You have surpassed the allocated rate limit for your tier
1008 401 Your IP has not been whitelisted for access

Failure

Full Error Response 

{
    "request_id":1,
    "code":1000,
    "message":"You need to authenticate prior to using this functionality",
    "status":401
}
Lite Error Response 
{
    "ri":1,
    "c":1000,
    "m":"You need to authenticate prior to using this functionality",
    "s":401
}

Authentication

In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI.

# These are the variables you will need to set manually
GRVT_API_KEY="<insert_key_here>"
GRVT_SUB_ACCOUNT_ID="<insert_sub_account_id_here>"

Then, choose the environment you want to authenticate against.

# dev
GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login"
# staging
GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/api_key/login"
# testnet
GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/api_key/login"
# prod
GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/api_key/login"

Now, let’s authenticate and retrieve both the session cookie and the X-Grvt-Account-Id header value that you’ll need to access any endpoints requiring authentication.

echo $GRVT_API_KEY
echo $GRVT_SUB_ACCOUNT_ID
echo $GRVT_AUTH_ENDPOINT

RESPONSE=$(
    curl $GRVT_AUTH_ENDPOINT \
        -H 'Content-Type: application/json' \
        -H 'Cookie: rm=true;' \
        -d '{"api_key": "'$GRVT_API_KEY'"}' \
        -s -i
)

GRVT_COOKIE=$(echo "$RESPONSE" | grep -i 'set-cookie:' | grep -o 'gravity=[^;]*')
GRVT_ACCOUNT_ID=$(echo "$RESPONSE" | grep 'x-grvt-account-id:' | awk '{print $2}' | tr -d '\r')

echo "$GRVT_COOKIE"
echo "$GRVT_ACCOUNT_ID"

REST Full

curl --location 'https://trades.dev.gravitymarkets.io/full/v1/fill_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": ""
}
'

JSONRPC Full

wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/fill_history",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "kind": ["PERPETUAL"],
        "base": ["BTC", "ETH"],
        "quote": ["USDT", "USDC"],
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": ""
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/fill_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c": ""
}
'

JSONRPC Lite

wscat -c "wss://trades.dev.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/fill_history",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "k": ["PERPETUAL"],
        "b": ["BTC", "ETH"],
        "q": ["USDT", "USDC"],
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c": ""
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.staging.gravitymarkets.io/full/v1/fill_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": ""
}
'

JSONRPC Full

wscat -c "wss://trades.staging.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/fill_history",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "kind": ["PERPETUAL"],
        "base": ["BTC", "ETH"],
        "quote": ["USDT", "USDC"],
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": ""
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/fill_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c": ""
}
'

JSONRPC Lite

wscat -c "wss://trades.staging.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/fill_history",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "k": ["PERPETUAL"],
        "b": ["BTC", "ETH"],
        "q": ["USDT", "USDC"],
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c": ""
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.testnet.grvt.io/full/v1/fill_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": ""
}
'

JSONRPC Full

wscat -c "wss://trades.testnet.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/fill_history",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "kind": ["PERPETUAL"],
        "base": ["BTC", "ETH"],
        "quote": ["USDT", "USDC"],
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": ""
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.testnet.grvt.io/lite/v1/fill_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c": ""
}
'

JSONRPC Lite

wscat -c "wss://trades.testnet.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/fill_history",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "k": ["PERPETUAL"],
        "b": ["BTC", "ETH"],
        "q": ["USDT", "USDC"],
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c": ""
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.grvt.io/full/v1/fill_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": ""
}
'

JSONRPC Full

wscat -c "wss://trades.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/fill_history",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "kind": ["PERPETUAL"],
        "base": ["BTC", "ETH"],
        "quote": ["USDT", "USDC"],
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": ""
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.grvt.io/lite/v1/fill_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c": ""
}
'

JSONRPC Lite

wscat -c "wss://trades.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/fill_history",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "k": ["PERPETUAL"],
        "b": ["BTC", "ETH"],
        "q": ["USDT", "USDC"],
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c": ""
    },
    "i": 123
}
' -w 360

Positions

FULL ENDPOINT: full/v1/positions
LITE ENDPOINT: lite/v1/positions

ApiPositionsRequest

Query the positions of a sub account

Name
Lite		 Type Required
Default		 Description
sub_account_id
sa		 string True The sub account ID to request for
kind
k		 [Kind] False
all		 The kind filter to apply. If nil, this defaults to all kinds. Otherwise, only entries matching the filter will be returned
base
b		 [Currency] False
all		 The base filter to apply. If nil, this defaults to all bases. Otherwise, only entries matching the filter will be returned
quote
q		 [Currency] False
all		 The quote filter to apply. If nil, this defaults to all quotes. Otherwise, only entries matching the filter will be returned
Kind

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

Value Description
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

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token
Currency

The list of Currencies that are supported on the GRVT exchange

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token

Query

Full Request 

{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"]
}
Lite Request 
{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"]
}

ApiPositionsResponse

Name
Lite		 Type Required
Default		 Description
result
r		 [Positions] True The positions matching the request filter
Positions
Name
Lite		 Type Required
Default		 Description
event_time
et		 string True Time at which the event was emitted in unix nanoseconds
sub_account_id
sa		 string True The sub account ID that participated in the trade
instrument
i		 string True The instrument being represented
size
s		 string True The size of the position, expressed in base asset decimal units. Negative for short positions
notional
n		 string True The notional value of the position, negative for short assets, expressed in quote asset decimal units
entry_price
ep		 string True The entry price of the position, expressed in 9 decimals
Whenever increasing the size of a position, the entry price is updated to the new average entry price
new_entry_price = (old_entry_price * old_size + trade_price * trade_size) / (old_size + trade_size)
exit_price
ep1		 string True The exit price of the position, expressed in 9 decimals
Whenever decreasing the size of a position, the exit price is updated to the new average exit price
new_exit_price = (old_exit_price * old_exit_trade_size + trade_price * trade_size) / (old_exit_trade_size + trade_size)
mark_price
mp		 string True The mark price of the position, expressed in 9 decimals
unrealized_pnl
up		 string True The unrealized PnL of the position, expressed in quote asset decimal units
unrealized_pnl = (mark_price - entry_price) * size
realized_pnl
rp		 string True The realized PnL of the position, expressed in quote asset decimal units
realized_pnl = (exit_price - entry_price) * exit_trade_size
total_pnl
tp		 string True The total PnL of the position, expressed in quote asset decimal units
total_pnl = realized_pnl + unrealized_pnl
roi
r		 string True The ROI of the position, expressed as a percentage
roi = (total_pnl / (entry_price * abs(size))) * 100^
quote_index_price
qi		 string True The index price of the quote currency. (reported in USD)
est_liquidation_price
el		 string True The estimated liquidation price
leverage
l		 string True The current leverage value for this position

Success

Full Response 

{
    "result": [{
        "event_time": "1697788800000000000",
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "instrument": "BTC_USDT_Perp",
        "size": "2635000.50",
        "notional": "2635000.50",
        "entry_price": "65038.01",
        "exit_price": "65038.01",
        "mark_price": "65038.01",
        "unrealized_pnl": "135000.50",
        "realized_pnl": "-35000.30",
        "total_pnl": "100000.20",
        "roi": "10.20",
        "quote_index_price": "1.0000102",
        "est_liquidation_price": 60000.25,
        "leverage": "10"
    }]
}
Lite Response 
{
    "r": [{
        "et": "1697788800000000000",
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "i": "BTC_USDT_Perp",
        "s": "2635000.50",
        "n": "2635000.50",
        "ep": "65038.01",
        "ep1": "65038.01",
        "mp": "65038.01",
        "up": "135000.50",
        "rp": "-35000.30",
        "tp": "100000.20",
        "r": "10.20",
        "qi": "1.0000102",
        "el": 60000.25,
        "l": "10"
    }]
}

Error Codes

Code HttpStatus Description
1000 401 You need to authenticate prior to using this functionality
1001 403 You are not authorized to access this functionality
1002 500 Internal Server Error
1003 400 Request could not be processed due to malformed syntax
1006 429 You have surpassed the allocated rate limit for your tier
1008 401 Your IP has not been whitelisted for access

Failure

Full Error Response 

{
    "request_id":1,
    "code":1000,
    "message":"You need to authenticate prior to using this functionality",
    "status":401
}
Lite Error Response 
{
    "ri":1,
    "c":1000,
    "m":"You need to authenticate prior to using this functionality",
    "s":401
}

Authentication

In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI.

# These are the variables you will need to set manually
GRVT_API_KEY="<insert_key_here>"
GRVT_SUB_ACCOUNT_ID="<insert_sub_account_id_here>"

Then, choose the environment you want to authenticate against.

# dev
GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login"
# staging
GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/api_key/login"
# testnet
GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/api_key/login"
# prod
GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/api_key/login"

Now, let’s authenticate and retrieve both the session cookie and the X-Grvt-Account-Id header value that you’ll need to access any endpoints requiring authentication.

echo $GRVT_API_KEY
echo $GRVT_SUB_ACCOUNT_ID
echo $GRVT_AUTH_ENDPOINT

RESPONSE=$(
    curl $GRVT_AUTH_ENDPOINT \
        -H 'Content-Type: application/json' \
        -H 'Cookie: rm=true;' \
        -d '{"api_key": "'$GRVT_API_KEY'"}' \
        -s -i
)

GRVT_COOKIE=$(echo "$RESPONSE" | grep -i 'set-cookie:' | grep -o 'gravity=[^;]*')
GRVT_ACCOUNT_ID=$(echo "$RESPONSE" | grep 'x-grvt-account-id:' | awk '{print $2}' | tr -d '\r')

echo "$GRVT_COOKIE"
echo "$GRVT_ACCOUNT_ID"

REST Full

curl --location 'https://trades.dev.gravitymarkets.io/full/v1/positions' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"]
}
'

JSONRPC Full

wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/positions",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "kind": ["PERPETUAL"],
        "base": ["BTC", "ETH"],
        "quote": ["USDT", "USDC"]
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/positions' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"]
}
'

JSONRPC Lite

wscat -c "wss://trades.dev.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/positions",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "k": ["PERPETUAL"],
        "b": ["BTC", "ETH"],
        "q": ["USDT", "USDC"]
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.staging.gravitymarkets.io/full/v1/positions' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"]
}
'

JSONRPC Full

wscat -c "wss://trades.staging.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/positions",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "kind": ["PERPETUAL"],
        "base": ["BTC", "ETH"],
        "quote": ["USDT", "USDC"]
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/positions' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"]
}
'

JSONRPC Lite

wscat -c "wss://trades.staging.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/positions",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "k": ["PERPETUAL"],
        "b": ["BTC", "ETH"],
        "q": ["USDT", "USDC"]
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.testnet.grvt.io/full/v1/positions' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"]
}
'

JSONRPC Full

wscat -c "wss://trades.testnet.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/positions",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "kind": ["PERPETUAL"],
        "base": ["BTC", "ETH"],
        "quote": ["USDT", "USDC"]
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.testnet.grvt.io/lite/v1/positions' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"]
}
'

JSONRPC Lite

wscat -c "wss://trades.testnet.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/positions",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "k": ["PERPETUAL"],
        "b": ["BTC", "ETH"],
        "q": ["USDT", "USDC"]
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.grvt.io/full/v1/positions' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "kind": ["PERPETUAL"],
    "base": ["BTC", "ETH"],
    "quote": ["USDT", "USDC"]
}
'

JSONRPC Full

wscat -c "wss://trades.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/positions",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "kind": ["PERPETUAL"],
        "base": ["BTC", "ETH"],
        "quote": ["USDT", "USDC"]
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.grvt.io/lite/v1/positions' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "k": ["PERPETUAL"],
    "b": ["BTC", "ETH"],
    "q": ["USDT", "USDC"]
}
'

JSONRPC Lite

wscat -c "wss://trades.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/positions",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "k": ["PERPETUAL"],
        "b": ["BTC", "ETH"],
        "q": ["USDT", "USDC"]
    },
    "i": 123
}
' -w 360

Funding Payment History

FULL ENDPOINT: full/v1/funding_payment_history
LITE ENDPOINT: lite/v1/funding_payment_history

ApiFundingPaymentHistoryRequest

Query for all historical funding payments made by a single account.

Pagination works as follows:

  • We perform a reverse chronological lookup, starting from end_time. If end_time is not set, we start from the most recent data.
  • The lookup is limited to limit records. If more data is requested, the response will contain a next cursor for you to query the next page.
  • If a cursor is provided, it will be used to fetch results from that point onwards.
  • Pagination will continue until the start_time is reached. If start_time is not set, pagination will continue as far back as our data retention policy allows.

Name
Lite		 Type Required
Default		 Description
sub_account_id
sa		 string True The sub account ID to request for
instrument
i		 string False
all		 The perpetual instrument to filter for
start_time
st		 string False
0		 The start time to apply in unix nanoseconds. If nil, this defaults to all start times. Otherwise, only entries matching the filter will be returned
end_time
et		 string False
now()		 The end time to apply in unix nanoseconds. If nil, this defaults to all end times. Otherwise, only entries matching the filter will be returned
limit
l		 integer False
500		 The limit to query for. Defaults to 500; Max 1000
cursor
c		 string False
''		 The cursor to indicate when to start the query from

Query

Full Request 

{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "instrument": "BTC_USDT_Perp",
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": ""
}
Lite Request 
{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "i": "BTC_USDT_Perp",
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c": ""
}

ApiFundingPaymentHistoryResponse

Name
Lite		 Type Required
Default		 Description
result
r		 [FundingPayment] True The funding payments matching the request asset
next
n		 string True The cursor to indicate when to start the query from
FundingPayment
Name
Lite		 Type Required
Default		 Description
event_time
et		 string True Time at which the event was emitted in unix nanoseconds
sub_account_id
sa		 string True The sub account ID that made the funding payment
instrument
i		 string True The perpetual instrument being funded
currency
c		 Currency True The currency of the funding payment
amount
a		 string True The amount of the funding payment. Positive if paid, negative if received
tx_id
ti		 string True The transaction ID of the funding payment.
Funding payments can be triggered by a trade, transfer, or liquidation.
The tx_id will match the corresponding trade_id or tx_id.
Currency

The list of Currencies that are supported on the GRVT exchange

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token

Success

Full Response 

{
    "result": [{
        "event_time": "1697788800000000000",
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "instrument": "BTC_USDT_Perp",
        "currency": "USDT",
        "amount": "9.75",
        "tx_id": "209358"
    }],
    "next": "Qw0918="
}
Lite Response 
{
    "r": [{
        "et": "1697788800000000000",
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "i": "BTC_USDT_Perp",
        "c": "USDT",
        "a": "9.75",
        "ti": "209358"
    }],
    "n": "Qw0918="
}

Error Codes

Code HttpStatus Description
1000 401 You need to authenticate prior to using this functionality
1001 403 You are not authorized to access this functionality
1002 500 Internal Server Error
1003 400 Request could not be processed due to malformed syntax
1006 429 You have surpassed the allocated rate limit for your tier
1008 401 Your IP has not been whitelisted for access

Failure

Full Error Response 

{
    "request_id":1,
    "code":1000,
    "message":"You need to authenticate prior to using this functionality",
    "status":401
}
Lite Error Response 
{
    "ri":1,
    "c":1000,
    "m":"You need to authenticate prior to using this functionality",
    "s":401
}

Authentication

In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI.

# These are the variables you will need to set manually
GRVT_API_KEY="<insert_key_here>"
GRVT_SUB_ACCOUNT_ID="<insert_sub_account_id_here>"

Then, choose the environment you want to authenticate against.

# dev
GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login"
# staging
GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/api_key/login"
# testnet
GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/api_key/login"
# prod
GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/api_key/login"

Now, let’s authenticate and retrieve both the session cookie and the X-Grvt-Account-Id header value that you’ll need to access any endpoints requiring authentication.

echo $GRVT_API_KEY
echo $GRVT_SUB_ACCOUNT_ID
echo $GRVT_AUTH_ENDPOINT

RESPONSE=$(
    curl $GRVT_AUTH_ENDPOINT \
        -H 'Content-Type: application/json' \
        -H 'Cookie: rm=true;' \
        -d '{"api_key": "'$GRVT_API_KEY'"}' \
        -s -i
)

GRVT_COOKIE=$(echo "$RESPONSE" | grep -i 'set-cookie:' | grep -o 'gravity=[^;]*')
GRVT_ACCOUNT_ID=$(echo "$RESPONSE" | grep 'x-grvt-account-id:' | awk '{print $2}' | tr -d '\r')

echo "$GRVT_COOKIE"
echo "$GRVT_ACCOUNT_ID"

REST Full

curl --location 'https://trades.dev.gravitymarkets.io/full/v1/funding_payment_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "instrument": "BTC_USDT_Perp",
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": ""
}
'

JSONRPC Full

wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/funding_payment_history",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "instrument": "BTC_USDT_Perp",
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": ""
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/funding_payment_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "i": "BTC_USDT_Perp",
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c": ""
}
'

JSONRPC Lite

wscat -c "wss://trades.dev.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/funding_payment_history",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "i": "BTC_USDT_Perp",
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c": ""
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.staging.gravitymarkets.io/full/v1/funding_payment_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "instrument": "BTC_USDT_Perp",
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": ""
}
'

JSONRPC Full

wscat -c "wss://trades.staging.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/funding_payment_history",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "instrument": "BTC_USDT_Perp",
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": ""
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/funding_payment_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "i": "BTC_USDT_Perp",
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c": ""
}
'

JSONRPC Lite

wscat -c "wss://trades.staging.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/funding_payment_history",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "i": "BTC_USDT_Perp",
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c": ""
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.testnet.grvt.io/full/v1/funding_payment_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "instrument": "BTC_USDT_Perp",
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": ""
}
'

JSONRPC Full

wscat -c "wss://trades.testnet.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/funding_payment_history",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "instrument": "BTC_USDT_Perp",
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": ""
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.testnet.grvt.io/lite/v1/funding_payment_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "i": "BTC_USDT_Perp",
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c": ""
}
'

JSONRPC Lite

wscat -c "wss://trades.testnet.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/funding_payment_history",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "i": "BTC_USDT_Perp",
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c": ""
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.grvt.io/full/v1/funding_payment_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "instrument": "BTC_USDT_Perp",
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": ""
}
'

JSONRPC Full

wscat -c "wss://trades.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/funding_payment_history",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "instrument": "BTC_USDT_Perp",
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": ""
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.grvt.io/lite/v1/funding_payment_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "i": "BTC_USDT_Perp",
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c": ""
}
'

JSONRPC Lite

wscat -c "wss://trades.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/funding_payment_history",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "i": "BTC_USDT_Perp",
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c": ""
    },
    "i": 123
}
' -w 360

Transfer

Deposit History

FULL ENDPOINT: full/v1/deposit_history
LITE ENDPOINT: lite/v1/deposit_history

ApiDepositHistoryRequest

The request to get the historical deposits of an account
The history is returned in reverse chronological order

Pagination works as follows:

  • We perform a reverse chronological lookup, starting from end_time. If end_time is not set, we start from the most recent data.
  • The lookup is limited to limit records. If more data is requested, the response will contain a next cursor for you to query the next page.
  • If a cursor is provided, it will be used to fetch results from that point onwards.
  • Pagination will continue until the start_time is reached. If start_time is not set, pagination will continue as far back as our data retention policy allows.

Name
Lite		 Type Required
Default		 Description
currency
c		 [Currency] True The token currency to query for, if nil or empty, return all deposits. Otherwise, only entries matching the filter will be returned
start_time
st		 string False
0		 The start time to query for in unix nanoseconds
end_time
et		 string False
now()		 The end time to query for in unix nanoseconds
limit
l		 integer False
500		 The limit to query for. Defaults to 500; Max 1000
cursor
c1		 string False
''		 The cursor to indicate when to start the next query from
main_account_id
ma		 string False
``		 Main account ID being queried. By default, applies the requestor's main account ID.
Currency

The list of Currencies that are supported on the GRVT exchange

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token

Query

Full Request 

{
    "currency": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": "",
    "main_account_id": null
}
Lite Request 
{
    "c": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c1": "",
    "ma": null
}

ApiDepositHistoryResponse

Name
Lite		 Type Required
Default		 Description
result
r		 [DepositHistory] True The deposit history matching the request account
next
n		 string False
''		 The cursor to indicate when to start the next query from
DepositHistory
Name
Lite		 Type Required
Default		 Description
l_1_hash
l1		 string True The L1 txHash of the deposit
l_2_hash
l2		 string True The L2 txHash of the deposit
to_account_id
ta		 string True The account to deposit into
currency
c		 Currency True The token currency to deposit
num_tokens
nt		 string True The number of tokens to deposit
initiated_time
it		 string True The timestamp when the deposit was initiated on L1 in unix nanoseconds
confirmed_time
ct		 string True The timestamp when the deposit was confirmed on L2 in unix nanoseconds
from_address
fa		 string True The address of the sender
Currency

The list of Currencies that are supported on the GRVT exchange

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token

Success

Full Response 

{
    "result": [{
        "l_1_hash": "0x10000101000203040506",
        "l_2_hash": "0x10000101000203040506",
        "to_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "currency": "USDT",
        "num_tokens": "1500.0",
        "initiated_time": "1697788800000000000",
        "confirmed_time": "1697788800000000000",
        "from_address": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0"
    }],
    "next": "Qw0918="
}
Lite Response 
{
    "r": [{
        "l1": "0x10000101000203040506",
        "l2": "0x10000101000203040506",
        "ta": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "c": "USDT",
        "nt": "1500.0",
        "it": "1697788800000000000",
        "ct": "1697788800000000000",
        "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0"
    }],
    "n": "Qw0918="
}

Error Codes

Code HttpStatus Description
1000 401 You need to authenticate prior to using this functionality
1001 403 You are not authorized to access this functionality
1002 500 Internal Server Error
1003 400 Request could not be processed due to malformed syntax
1006 429 You have surpassed the allocated rate limit for your tier
1008 401 Your IP has not been whitelisted for access

Failure

Full Error Response 

{
    "request_id":1,
    "code":1000,
    "message":"You need to authenticate prior to using this functionality",
    "status":401
}
Lite Error Response 
{
    "ri":1,
    "c":1000,
    "m":"You need to authenticate prior to using this functionality",
    "s":401
}

Authentication

In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI.

# These are the variables you will need to set manually
GRVT_API_KEY="<insert_key_here>"
GRVT_SUB_ACCOUNT_ID="<insert_sub_account_id_here>"

Then, choose the environment you want to authenticate against.

# dev
GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login"
# staging
GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/api_key/login"
# testnet
GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/api_key/login"
# prod
GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/api_key/login"

Now, let’s authenticate and retrieve both the session cookie and the X-Grvt-Account-Id header value that you’ll need to access any endpoints requiring authentication.

echo $GRVT_API_KEY
echo $GRVT_SUB_ACCOUNT_ID
echo $GRVT_AUTH_ENDPOINT

RESPONSE=$(
    curl $GRVT_AUTH_ENDPOINT \
        -H 'Content-Type: application/json' \
        -H 'Cookie: rm=true;' \
        -d '{"api_key": "'$GRVT_API_KEY'"}' \
        -s -i
)

GRVT_COOKIE=$(echo "$RESPONSE" | grep -i 'set-cookie:' | grep -o 'gravity=[^;]*')
GRVT_ACCOUNT_ID=$(echo "$RESPONSE" | grep 'x-grvt-account-id:' | awk '{print $2}' | tr -d '\r')

echo "$GRVT_COOKIE"
echo "$GRVT_ACCOUNT_ID"

REST Full

curl --location 'https://trades.dev.gravitymarkets.io/full/v1/deposit_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "currency": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": "",
    "main_account_id": null
}
'

JSONRPC Full

wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/deposit_history",
    "params": {
        "currency": ["USDT", "USDC"],
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": "",
        "main_account_id": null
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/deposit_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "c": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c1": "",
    "ma": null
}
'

JSONRPC Lite

wscat -c "wss://trades.dev.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/deposit_history",
    "p": {
        "c": ["USDT", "USDC"],
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c1": "",
        "ma": null
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.staging.gravitymarkets.io/full/v1/deposit_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "currency": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": "",
    "main_account_id": null
}
'

JSONRPC Full

wscat -c "wss://trades.staging.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/deposit_history",
    "params": {
        "currency": ["USDT", "USDC"],
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": "",
        "main_account_id": null
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/deposit_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "c": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c1": "",
    "ma": null
}
'

JSONRPC Lite

wscat -c "wss://trades.staging.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/deposit_history",
    "p": {
        "c": ["USDT", "USDC"],
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c1": "",
        "ma": null
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.testnet.grvt.io/full/v1/deposit_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "currency": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": "",
    "main_account_id": null
}
'

JSONRPC Full

wscat -c "wss://trades.testnet.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/deposit_history",
    "params": {
        "currency": ["USDT", "USDC"],
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": "",
        "main_account_id": null
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.testnet.grvt.io/lite/v1/deposit_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "c": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c1": "",
    "ma": null
}
'

JSONRPC Lite

wscat -c "wss://trades.testnet.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/deposit_history",
    "p": {
        "c": ["USDT", "USDC"],
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c1": "",
        "ma": null
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.grvt.io/full/v1/deposit_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "currency": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": "",
    "main_account_id": null
}
'

JSONRPC Full

wscat -c "wss://trades.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/deposit_history",
    "params": {
        "currency": ["USDT", "USDC"],
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": "",
        "main_account_id": null
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.grvt.io/lite/v1/deposit_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "c": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c1": "",
    "ma": null
}
'

JSONRPC Lite

wscat -c "wss://trades.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/deposit_history",
    "p": {
        "c": ["USDT", "USDC"],
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c1": "",
        "ma": null
    },
    "i": 123
}
' -w 360

Transfer

FULL ENDPOINT: full/v1/transfer
LITE ENDPOINT: lite/v1/transfer

ApiTransferRequest

This API allows you to transfer funds in multiple different ways


  • Between SubAccounts within your Main Account

  • Between your MainAccount and your SubAccounts

  • To other MainAccounts that you have previously allowlisted

Fast Withdrawal Funding Address
For fast withdrawals, funds must be sent to the designated funding account address. Please ensure you use the correct address based on the environment:
Production Environment Address:
[To be updated, not ready yet]
This address should be specified as the to_account_id in your API requests for transferring funds using the transfer API. Ensure accurate input to avoid loss of funds or use the UI.

Name
Lite		 Type Required
Default		 Description
from_account_id
fa		 string True The main account to transfer from
from_sub_account_id
fs		 string True The subaccount to transfer from (0 if transferring from main account)
to_account_id
ta		 string True The main account to deposit into
to_sub_account_id
ts		 string True The subaccount to transfer to (0 if transferring to main account)
currency
c		 Currency True The token currency to transfer
num_tokens
nt		 string True The number of tokens to transfer, quoted in tokenCurrency decimal units
signature
s		 Signature True The signature of the transfer
transfer_type
tt		 TransferType True The type of transfer
transfer_metadata
tm		 string True The metadata of the transfer
Currency

The list of Currencies that are supported on the GRVT exchange

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token
Signature
Name
Lite		 Type Required
Default		 Description
signer
s		 string True The address (public key) of the wallet signing the payload
r
r		 string True Signature R
s
s1		 string True Signature S
v
v		 integer True Signature V
expiration
e		 string True Timestamp after which this signature expires, expressed in unix nanoseconds. Must be capped at 30 days
nonce
n		 integer True Users can randomly generate this value, used as a signature deconflicting key.
ie. You can send the same exact instruction twice with different nonces.
When the same nonce is used, the same payload will generate the same signature.
Our system will consider the payload a duplicate, and ignore it.
TransferType
Value Description
STANDARD = 1 Standard transfer that has nothing to do with bridging
FAST_ARB_DEPOSIT = 2 Fast Arb Deposit Metadata type
FAST_ARB_WITHDRAWAL = 3 Fast Arb Withdrawal Metadata type
NON_NATIVE_BRIDGE_DEPOSIT = 4 Transfer type for non native bridging deposit
NON_NATIVE_BRIDGE_WITHDRAWAL = 5 Transfer type for non native bridging withdrawal

Query

Full Request 

{
    "from_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "from_sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "to_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "to_sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "currency": "USDT",
    "num_tokens": "1500.0",
    "signature": {
        "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
        "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
        "v": 28,
        "expiration": "1697788800000000000",
        "nonce": 1234567890
    },
    "transfer_type": "STANDARD",
    "transfer_metadata": {"provider":"XY","direction":"WITHDRAWAL","provider_tx_id":"txn123456","chainid":"42161","endpoint":"0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0"}
}
Lite Request 
{
    "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "fs": "'$GRVT_SUB_ACCOUNT_ID'",
    "ta": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "ts": "'$GRVT_SUB_ACCOUNT_ID'",
    "c": "USDT",
    "nt": "1500.0",
    "s": {
        "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
        "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
        "v": 28,
        "e": "1697788800000000000",
        "n": 1234567890
    },
    "tt": "STANDARD",
    "tm": {"provider":"XY","direction":"WITHDRAWAL","provider_tx_id":"txn123456","chainid":"42161","endpoint":"0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0"}
}

ApiTransferResponse

Used to acknowledge a transfer request outcome

Name
Lite		 Type Required
Default		 Description
result
r		 ApiTransferAck True The Transfer response object
ApiTransferAck
Name
Lite		 Type Required
Default		 Description
ack
a		 boolean True Gravity has acknowledged that the transfer has been successfully processed. If true, a tx_id will be returned. If false, an error will be returned.
tx_id
ti		 string True The transaction ID of the transfer. This is only returned if the transfer is successful.

Success

Full Response 

{
    "result": {
        "ack": "true",
        "tx_id": "1028403"
    }
}
Lite Response 
{
    "r": {
        "a": "true",
        "ti": "1028403"
    }
}

Error Codes

Code HttpStatus Description
1000 401 You need to authenticate prior to using this functionality
1001 403 You are not authorized to access this functionality
1002 500 Internal Server Error
1003 400 Request could not be processed due to malformed syntax
1006 429 You have surpassed the allocated rate limit for your tier
1008 401 Your IP has not been whitelisted for access
5000 400 Transfer Metadata does not match the expected structure.
5001 400 Transfer Provider does not match the expected provider.
4002 400 Transfer failed with an unrefined failure reason, please report to GRVT
5002 400 Direction of the transfer does not match the expected direction.
5003 400 Endpoint account ID is invalid.
5004 400 Funding account does not exist in our system.
5005 400 Invalid ChainID for the transfer request.

Failure

Full Error Response 

{
    "request_id":1,
    "code":1000,
    "message":"You need to authenticate prior to using this functionality",
    "status":401
}
Lite Error Response 
{
    "ri":1,
    "c":1000,
    "m":"You need to authenticate prior to using this functionality",
    "s":401
}

Authentication

In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI.

# These are the variables you will need to set manually
GRVT_API_KEY="<insert_key_here>"
GRVT_SUB_ACCOUNT_ID="<insert_sub_account_id_here>"

Then, choose the environment you want to authenticate against.

# dev
GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login"
# staging
GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/api_key/login"
# testnet
GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/api_key/login"
# prod
GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/api_key/login"

Now, let’s authenticate and retrieve both the session cookie and the X-Grvt-Account-Id header value that you’ll need to access any endpoints requiring authentication.

echo $GRVT_API_KEY
echo $GRVT_SUB_ACCOUNT_ID
echo $GRVT_AUTH_ENDPOINT

RESPONSE=$(
    curl $GRVT_AUTH_ENDPOINT \
        -H 'Content-Type: application/json' \
        -H 'Cookie: rm=true;' \
        -d '{"api_key": "'$GRVT_API_KEY'"}' \
        -s -i
)

GRVT_COOKIE=$(echo "$RESPONSE" | grep -i 'set-cookie:' | grep -o 'gravity=[^;]*')
GRVT_ACCOUNT_ID=$(echo "$RESPONSE" | grep 'x-grvt-account-id:' | awk '{print $2}' | tr -d '\r')

echo "$GRVT_COOKIE"
echo "$GRVT_ACCOUNT_ID"

REST Full

curl --location 'https://trades.dev.gravitymarkets.io/full/v1/transfer' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "from_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "from_sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "to_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "to_sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "currency": "USDT",
    "num_tokens": "1500.0",
    "signature": {
        "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
        "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
        "v": 28,
        "expiration": "1697788800000000000",
        "nonce": 1234567890
    },
    "transfer_type": "STANDARD",
    "transfer_metadata": {"provider":"XY","direction":"WITHDRAWAL","provider_tx_id":"txn123456","chainid":"42161","endpoint":"0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0"}
}
'

JSONRPC Full

wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/transfer",
    "params": {
        "from_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "from_sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "to_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "to_sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "currency": "USDT",
        "num_tokens": "1500.0",
        "signature": {
            "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "expiration": "1697788800000000000",
            "nonce": 1234567890
        },
        "transfer_type": "STANDARD",
        "transfer_metadata": {"provider":"XY","direction":"WITHDRAWAL","provider_tx_id":"txn123456","chainid":"42161","endpoint":"0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0"}
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/transfer' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "fs": "'$GRVT_SUB_ACCOUNT_ID'",
    "ta": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "ts": "'$GRVT_SUB_ACCOUNT_ID'",
    "c": "USDT",
    "nt": "1500.0",
    "s": {
        "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
        "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
        "v": 28,
        "e": "1697788800000000000",
        "n": 1234567890
    },
    "tt": "STANDARD",
    "tm": {"provider":"XY","direction":"WITHDRAWAL","provider_tx_id":"txn123456","chainid":"42161","endpoint":"0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0"}
}
'

JSONRPC Lite

wscat -c "wss://trades.dev.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/transfer",
    "p": {
        "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "fs": "'$GRVT_SUB_ACCOUNT_ID'",
        "ta": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "ts": "'$GRVT_SUB_ACCOUNT_ID'",
        "c": "USDT",
        "nt": "1500.0",
        "s": {
            "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "e": "1697788800000000000",
            "n": 1234567890
        },
        "tt": "STANDARD",
        "tm": {"provider":"XY","direction":"WITHDRAWAL","provider_tx_id":"txn123456","chainid":"42161","endpoint":"0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0"}
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.staging.gravitymarkets.io/full/v1/transfer' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "from_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "from_sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "to_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "to_sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "currency": "USDT",
    "num_tokens": "1500.0",
    "signature": {
        "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
        "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
        "v": 28,
        "expiration": "1697788800000000000",
        "nonce": 1234567890
    },
    "transfer_type": "STANDARD",
    "transfer_metadata": {"provider":"XY","direction":"WITHDRAWAL","provider_tx_id":"txn123456","chainid":"42161","endpoint":"0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0"}
}
'

JSONRPC Full

wscat -c "wss://trades.staging.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/transfer",
    "params": {
        "from_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "from_sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "to_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "to_sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "currency": "USDT",
        "num_tokens": "1500.0",
        "signature": {
            "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "expiration": "1697788800000000000",
            "nonce": 1234567890
        },
        "transfer_type": "STANDARD",
        "transfer_metadata": {"provider":"XY","direction":"WITHDRAWAL","provider_tx_id":"txn123456","chainid":"42161","endpoint":"0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0"}
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/transfer' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "fs": "'$GRVT_SUB_ACCOUNT_ID'",
    "ta": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "ts": "'$GRVT_SUB_ACCOUNT_ID'",
    "c": "USDT",
    "nt": "1500.0",
    "s": {
        "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
        "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
        "v": 28,
        "e": "1697788800000000000",
        "n": 1234567890
    },
    "tt": "STANDARD",
    "tm": {"provider":"XY","direction":"WITHDRAWAL","provider_tx_id":"txn123456","chainid":"42161","endpoint":"0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0"}
}
'

JSONRPC Lite

wscat -c "wss://trades.staging.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/transfer",
    "p": {
        "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "fs": "'$GRVT_SUB_ACCOUNT_ID'",
        "ta": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "ts": "'$GRVT_SUB_ACCOUNT_ID'",
        "c": "USDT",
        "nt": "1500.0",
        "s": {
            "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "e": "1697788800000000000",
            "n": 1234567890
        },
        "tt": "STANDARD",
        "tm": {"provider":"XY","direction":"WITHDRAWAL","provider_tx_id":"txn123456","chainid":"42161","endpoint":"0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0"}
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.testnet.grvt.io/full/v1/transfer' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "from_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "from_sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "to_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "to_sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "currency": "USDT",
    "num_tokens": "1500.0",
    "signature": {
        "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
        "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
        "v": 28,
        "expiration": "1697788800000000000",
        "nonce": 1234567890
    },
    "transfer_type": "STANDARD",
    "transfer_metadata": {"provider":"XY","direction":"WITHDRAWAL","provider_tx_id":"txn123456","chainid":"42161","endpoint":"0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0"}
}
'

JSONRPC Full

wscat -c "wss://trades.testnet.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/transfer",
    "params": {
        "from_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "from_sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "to_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "to_sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "currency": "USDT",
        "num_tokens": "1500.0",
        "signature": {
            "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "expiration": "1697788800000000000",
            "nonce": 1234567890
        },
        "transfer_type": "STANDARD",
        "transfer_metadata": {"provider":"XY","direction":"WITHDRAWAL","provider_tx_id":"txn123456","chainid":"42161","endpoint":"0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0"}
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.testnet.grvt.io/lite/v1/transfer' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "fs": "'$GRVT_SUB_ACCOUNT_ID'",
    "ta": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "ts": "'$GRVT_SUB_ACCOUNT_ID'",
    "c": "USDT",
    "nt": "1500.0",
    "s": {
        "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
        "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
        "v": 28,
        "e": "1697788800000000000",
        "n": 1234567890
    },
    "tt": "STANDARD",
    "tm": {"provider":"XY","direction":"WITHDRAWAL","provider_tx_id":"txn123456","chainid":"42161","endpoint":"0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0"}
}
'

JSONRPC Lite

wscat -c "wss://trades.testnet.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/transfer",
    "p": {
        "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "fs": "'$GRVT_SUB_ACCOUNT_ID'",
        "ta": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "ts": "'$GRVT_SUB_ACCOUNT_ID'",
        "c": "USDT",
        "nt": "1500.0",
        "s": {
            "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "e": "1697788800000000000",
            "n": 1234567890
        },
        "tt": "STANDARD",
        "tm": {"provider":"XY","direction":"WITHDRAWAL","provider_tx_id":"txn123456","chainid":"42161","endpoint":"0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0"}
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.grvt.io/full/v1/transfer' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "from_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "from_sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "to_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "to_sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "currency": "USDT",
    "num_tokens": "1500.0",
    "signature": {
        "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
        "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
        "v": 28,
        "expiration": "1697788800000000000",
        "nonce": 1234567890
    },
    "transfer_type": "STANDARD",
    "transfer_metadata": {"provider":"XY","direction":"WITHDRAWAL","provider_tx_id":"txn123456","chainid":"42161","endpoint":"0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0"}
}
'

JSONRPC Full

wscat -c "wss://trades.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/transfer",
    "params": {
        "from_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "from_sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "to_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "to_sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "currency": "USDT",
        "num_tokens": "1500.0",
        "signature": {
            "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "expiration": "1697788800000000000",
            "nonce": 1234567890
        },
        "transfer_type": "STANDARD",
        "transfer_metadata": {"provider":"XY","direction":"WITHDRAWAL","provider_tx_id":"txn123456","chainid":"42161","endpoint":"0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0"}
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.grvt.io/lite/v1/transfer' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "fs": "'$GRVT_SUB_ACCOUNT_ID'",
    "ta": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "ts": "'$GRVT_SUB_ACCOUNT_ID'",
    "c": "USDT",
    "nt": "1500.0",
    "s": {
        "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
        "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
        "v": 28,
        "e": "1697788800000000000",
        "n": 1234567890
    },
    "tt": "STANDARD",
    "tm": {"provider":"XY","direction":"WITHDRAWAL","provider_tx_id":"txn123456","chainid":"42161","endpoint":"0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0"}
}
'

JSONRPC Lite

wscat -c "wss://trades.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/transfer",
    "p": {
        "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "fs": "'$GRVT_SUB_ACCOUNT_ID'",
        "ta": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "ts": "'$GRVT_SUB_ACCOUNT_ID'",
        "c": "USDT",
        "nt": "1500.0",
        "s": {
            "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "e": "1697788800000000000",
            "n": 1234567890
        },
        "tt": "STANDARD",
        "tm": {"provider":"XY","direction":"WITHDRAWAL","provider_tx_id":"txn123456","chainid":"42161","endpoint":"0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0"}
    },
    "i": 123
}
' -w 360

Transfer History

FULL ENDPOINT: full/v1/transfer_history
LITE ENDPOINT: lite/v1/transfer_history

ApiTransferHistoryRequest

The request to get the historical transfers of an account
The history is returned in reverse chronological order

Pagination works as follows:

  • We perform a reverse chronological lookup, starting from end_time. If end_time is not set, we start from the most recent data.
  • The lookup is limited to limit records. If more data is requested, the response will contain a next cursor for you to query the next page.
  • If a cursor is provided, it will be used to fetch results from that point onwards.
  • Pagination will continue until the start_time is reached. If start_time is not set, pagination will continue as far back as our data retention policy allows.

Name
Lite		 Type Required
Default		 Description
currency
c		 [Currency] True The token currency to query for, if nil or empty, return all transfers. Otherwise, only entries matching the filter will be returned
start_time
st		 string False
0		 The start time to query for in unix nanoseconds
end_time
et		 string False
now()		 The end time to query for in unix nanoseconds
limit
l		 integer False
500		 The limit to query for. Defaults to 500; Max 1000
cursor
c1		 string False
''		 The cursor to indicate when to start the next query from
tx_id
ti		 string False
0		 The transaction ID to query for
main_account_id
ma		 string False
``		 Main account ID being queried. By default, applies the requestor's main account ID.
Currency

The list of Currencies that are supported on the GRVT exchange

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token

Query

Full Request 

{
    "currency": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": "",
    "tx_id": "1028403",
    "main_account_id": null
}
Lite Request 
{
    "c": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c1": "",
    "ti": "1028403",
    "ma": null
}

ApiTransferHistoryResponse

Name
Lite		 Type Required
Default		 Description
result
r		 [TransferHistory] True The transfer history matching the request account
next
n		 string False
''		 The cursor to indicate when to start the next query from
TransferHistory
Name
Lite		 Type Required
Default		 Description
tx_id
ti		 string True The transaction ID of the transfer
from_account_id
fa		 string True The account to transfer from
from_sub_account_id
fs		 string True The subaccount to transfer from (0 if transferring from main account)
to_account_id
ta		 string True The account to deposit into
to_sub_account_id
ts		 string True The subaccount to transfer to (0 if transferring to main account)
currency
c		 Currency True The token currency to transfer
num_tokens
nt		 string True The number of tokens to transfer
signature
s		 Signature True The signature of the transfer
event_time
et		 string True The timestamp of the transfer in unix nanoseconds
transfer_type
tt		 TransferType True The type of transfer
transfer_metadata
tm		 string True The metadata of the transfer
Currency

The list of Currencies that are supported on the GRVT exchange

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token
Signature
Name
Lite		 Type Required
Default		 Description
signer
s		 string True The address (public key) of the wallet signing the payload
r
r		 string True Signature R
s
s1		 string True Signature S
v
v		 integer True Signature V
expiration
e		 string True Timestamp after which this signature expires, expressed in unix nanoseconds. Must be capped at 30 days
nonce
n		 integer True Users can randomly generate this value, used as a signature deconflicting key.
ie. You can send the same exact instruction twice with different nonces.
When the same nonce is used, the same payload will generate the same signature.
Our system will consider the payload a duplicate, and ignore it.
TransferType
Value Description
STANDARD = 1 Standard transfer that has nothing to do with bridging
FAST_ARB_DEPOSIT = 2 Fast Arb Deposit Metadata type
FAST_ARB_WITHDRAWAL = 3 Fast Arb Withdrawal Metadata type
NON_NATIVE_BRIDGE_DEPOSIT = 4 Transfer type for non native bridging deposit
NON_NATIVE_BRIDGE_WITHDRAWAL = 5 Transfer type for non native bridging withdrawal

Success

Full Response 

{
    "result": [{
        "tx_id": "1028403",
        "from_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "from_sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "to_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "to_sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "currency": "USDT",
        "num_tokens": "1500.0",
        "signature": {
            "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "expiration": "1697788800000000000",
            "nonce": 1234567890
        },
        "event_time": "1697788800000000000",
        "transfer_type": "STANDARD",
        "transfer_metadata": null
    }],
    "next": "Qw0918="
}
Lite Response 
{
    "r": [{
        "ti": "1028403",
        "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "fs": "'$GRVT_SUB_ACCOUNT_ID'",
        "ta": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "ts": "'$GRVT_SUB_ACCOUNT_ID'",
        "c": "USDT",
        "nt": "1500.0",
        "s": {
            "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "e": "1697788800000000000",
            "n": 1234567890
        },
        "et": "1697788800000000000",
        "tt": "STANDARD",
        "tm": null
    }],
    "n": "Qw0918="
}

Error Codes

Code HttpStatus Description
1000 401 You need to authenticate prior to using this functionality
1001 403 You are not authorized to access this functionality
1002 500 Internal Server Error
1003 400 Request could not be processed due to malformed syntax
1006 429 You have surpassed the allocated rate limit for your tier
1008 401 Your IP has not been whitelisted for access

Failure

Full Error Response 

{
    "request_id":1,
    "code":1000,
    "message":"You need to authenticate prior to using this functionality",
    "status":401
}
Lite Error Response 
{
    "ri":1,
    "c":1000,
    "m":"You need to authenticate prior to using this functionality",
    "s":401
}

Authentication

In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI.

# These are the variables you will need to set manually
GRVT_API_KEY="<insert_key_here>"
GRVT_SUB_ACCOUNT_ID="<insert_sub_account_id_here>"

Then, choose the environment you want to authenticate against.

# dev
GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login"
# staging
GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/api_key/login"
# testnet
GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/api_key/login"
# prod
GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/api_key/login"

Now, let’s authenticate and retrieve both the session cookie and the X-Grvt-Account-Id header value that you’ll need to access any endpoints requiring authentication.

echo $GRVT_API_KEY
echo $GRVT_SUB_ACCOUNT_ID
echo $GRVT_AUTH_ENDPOINT

RESPONSE=$(
    curl $GRVT_AUTH_ENDPOINT \
        -H 'Content-Type: application/json' \
        -H 'Cookie: rm=true;' \
        -d '{"api_key": "'$GRVT_API_KEY'"}' \
        -s -i
)

GRVT_COOKIE=$(echo "$RESPONSE" | grep -i 'set-cookie:' | grep -o 'gravity=[^;]*')
GRVT_ACCOUNT_ID=$(echo "$RESPONSE" | grep 'x-grvt-account-id:' | awk '{print $2}' | tr -d '\r')

echo "$GRVT_COOKIE"
echo "$GRVT_ACCOUNT_ID"

REST Full

curl --location 'https://trades.dev.gravitymarkets.io/full/v1/transfer_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "currency": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": "",
    "tx_id": "1028403",
    "main_account_id": null
}
'

JSONRPC Full

wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/transfer_history",
    "params": {
        "currency": ["USDT", "USDC"],
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": "",
        "tx_id": "1028403",
        "main_account_id": null
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/transfer_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "c": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c1": "",
    "ti": "1028403",
    "ma": null
}
'

JSONRPC Lite

wscat -c "wss://trades.dev.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/transfer_history",
    "p": {
        "c": ["USDT", "USDC"],
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c1": "",
        "ti": "1028403",
        "ma": null
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.staging.gravitymarkets.io/full/v1/transfer_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "currency": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": "",
    "tx_id": "1028403",
    "main_account_id": null
}
'

JSONRPC Full

wscat -c "wss://trades.staging.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/transfer_history",
    "params": {
        "currency": ["USDT", "USDC"],
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": "",
        "tx_id": "1028403",
        "main_account_id": null
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/transfer_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "c": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c1": "",
    "ti": "1028403",
    "ma": null
}
'

JSONRPC Lite

wscat -c "wss://trades.staging.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/transfer_history",
    "p": {
        "c": ["USDT", "USDC"],
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c1": "",
        "ti": "1028403",
        "ma": null
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.testnet.grvt.io/full/v1/transfer_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "currency": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": "",
    "tx_id": "1028403",
    "main_account_id": null
}
'

JSONRPC Full

wscat -c "wss://trades.testnet.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/transfer_history",
    "params": {
        "currency": ["USDT", "USDC"],
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": "",
        "tx_id": "1028403",
        "main_account_id": null
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.testnet.grvt.io/lite/v1/transfer_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "c": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c1": "",
    "ti": "1028403",
    "ma": null
}
'

JSONRPC Lite

wscat -c "wss://trades.testnet.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/transfer_history",
    "p": {
        "c": ["USDT", "USDC"],
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c1": "",
        "ti": "1028403",
        "ma": null
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.grvt.io/full/v1/transfer_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "currency": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": "",
    "tx_id": "1028403",
    "main_account_id": null
}
'

JSONRPC Full

wscat -c "wss://trades.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/transfer_history",
    "params": {
        "currency": ["USDT", "USDC"],
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": "",
        "tx_id": "1028403",
        "main_account_id": null
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.grvt.io/lite/v1/transfer_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "c": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c1": "",
    "ti": "1028403",
    "ma": null
}
'

JSONRPC Lite

wscat -c "wss://trades.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/transfer_history",
    "p": {
        "c": ["USDT", "USDC"],
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c1": "",
        "ti": "1028403",
        "ma": null
    },
    "i": 123
}
' -w 360

Withdrawal

FULL ENDPOINT: full/v1/withdrawal
LITE ENDPOINT: lite/v1/withdrawal

ApiWithdrawalRequest

Leverage this API to initialize a withdrawal from GRVT's Hyperchain onto Ethereum.
Do take note that the bridging process does take time. The GRVT UI will help you keep track of bridging progress, and notify you once its complete.

If not withdrawing the entirety of your balance, there is a minimum withdrawal amount. Currently that amount is ~25 USDT.
Withdrawal fees also apply to cover the cost of the Ethereum transaction.
Note that your funds will always remain in self-custory throughout the withdrawal process. At no stage does GRVT gain control over your funds.

Name
Lite		 Type Required
Default		 Description
from_account_id
fa		 string True The main account to withdraw from
to_eth_address
te		 string True The Ethereum wallet to withdraw into
currency
c		 Currency True The token currency to withdraw
num_tokens
nt		 string True The number of tokens to withdraw, quoted in tokenCurrency decimal units
signature
s		 Signature True The signature of the withdrawal
Currency

The list of Currencies that are supported on the GRVT exchange

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token
Signature
Name
Lite		 Type Required
Default		 Description
signer
s		 string True The address (public key) of the wallet signing the payload
r
r		 string True Signature R
s
s1		 string True Signature S
v
v		 integer True Signature V
expiration
e		 string True Timestamp after which this signature expires, expressed in unix nanoseconds. Must be capped at 30 days
nonce
n		 integer True Users can randomly generate this value, used as a signature deconflicting key.
ie. You can send the same exact instruction twice with different nonces.
When the same nonce is used, the same payload will generate the same signature.
Our system will consider the payload a duplicate, and ignore it.

Query

Full Request 

{
    "from_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "to_eth_address": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "currency": "USDT",
    "num_tokens": "1500.0",
    "signature": {
        "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
        "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
        "v": 28,
        "expiration": "1697788800000000000",
        "nonce": 1234567890
    }
}
Lite Request 
{
    "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "te": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "c": "USDT",
    "nt": "1500.0",
    "s": {
        "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
        "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
        "v": 28,
        "e": "1697788800000000000",
        "n": 1234567890
    }
}

AckResponse

Used to acknowledge a request has been received and will be processed

Name
Lite		 Type Required
Default		 Description
result
r		 Ack True The Ack Object
Ack
Name
Lite		 Type Required
Default		 Description
ack
a		 boolean True Gravity has acknowledged that the request has been successfully received and it will process it in the backend

Success

Full Response 

{
    "result": {
        "ack": "true"
    }
}
Lite Response 
{
    "r": {
        "a": "true"
    }
}

Error Codes

Code HttpStatus Description
1000 401 You need to authenticate prior to using this functionality
1001 403 You are not authorized to access this functionality
1002 500 Internal Server Error
1003 400 Request could not be processed due to malformed syntax
1006 429 You have surpassed the allocated rate limit for your tier
1008 401 Your IP has not been whitelisted for access
4010 400 This wallet is not supported. Please try another wallet.

Failure

Full Error Response 

{
    "request_id":1,
    "code":1000,
    "message":"You need to authenticate prior to using this functionality",
    "status":401
}
Lite Error Response 
{
    "ri":1,
    "c":1000,
    "m":"You need to authenticate prior to using this functionality",
    "s":401
}

Authentication

In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI.

# These are the variables you will need to set manually
GRVT_API_KEY="<insert_key_here>"
GRVT_SUB_ACCOUNT_ID="<insert_sub_account_id_here>"

Then, choose the environment you want to authenticate against.

# dev
GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login"
# staging
GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/api_key/login"
# testnet
GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/api_key/login"
# prod
GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/api_key/login"

Now, let’s authenticate and retrieve both the session cookie and the X-Grvt-Account-Id header value that you’ll need to access any endpoints requiring authentication.

echo $GRVT_API_KEY
echo $GRVT_SUB_ACCOUNT_ID
echo $GRVT_AUTH_ENDPOINT

RESPONSE=$(
    curl $GRVT_AUTH_ENDPOINT \
        -H 'Content-Type: application/json' \
        -H 'Cookie: rm=true;' \
        -d '{"api_key": "'$GRVT_API_KEY'"}' \
        -s -i
)

GRVT_COOKIE=$(echo "$RESPONSE" | grep -i 'set-cookie:' | grep -o 'gravity=[^;]*')
GRVT_ACCOUNT_ID=$(echo "$RESPONSE" | grep 'x-grvt-account-id:' | awk '{print $2}' | tr -d '\r')

echo "$GRVT_COOKIE"
echo "$GRVT_ACCOUNT_ID"

REST Full

curl --location 'https://trades.dev.gravitymarkets.io/full/v1/withdrawal' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "from_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "to_eth_address": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "currency": "USDT",
    "num_tokens": "1500.0",
    "signature": {
        "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
        "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
        "v": 28,
        "expiration": "1697788800000000000",
        "nonce": 1234567890
    }
}
'

JSONRPC Full

wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/withdrawal",
    "params": {
        "from_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "to_eth_address": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "currency": "USDT",
        "num_tokens": "1500.0",
        "signature": {
            "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "expiration": "1697788800000000000",
            "nonce": 1234567890
        }
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/withdrawal' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "te": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "c": "USDT",
    "nt": "1500.0",
    "s": {
        "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
        "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
        "v": 28,
        "e": "1697788800000000000",
        "n": 1234567890
    }
}
'

JSONRPC Lite

wscat -c "wss://trades.dev.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/withdrawal",
    "p": {
        "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "te": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "c": "USDT",
        "nt": "1500.0",
        "s": {
            "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "e": "1697788800000000000",
            "n": 1234567890
        }
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.staging.gravitymarkets.io/full/v1/withdrawal' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "from_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "to_eth_address": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "currency": "USDT",
    "num_tokens": "1500.0",
    "signature": {
        "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
        "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
        "v": 28,
        "expiration": "1697788800000000000",
        "nonce": 1234567890
    }
}
'

JSONRPC Full

wscat -c "wss://trades.staging.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/withdrawal",
    "params": {
        "from_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "to_eth_address": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "currency": "USDT",
        "num_tokens": "1500.0",
        "signature": {
            "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "expiration": "1697788800000000000",
            "nonce": 1234567890
        }
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/withdrawal' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "te": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "c": "USDT",
    "nt": "1500.0",
    "s": {
        "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
        "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
        "v": 28,
        "e": "1697788800000000000",
        "n": 1234567890
    }
}
'

JSONRPC Lite

wscat -c "wss://trades.staging.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/withdrawal",
    "p": {
        "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "te": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "c": "USDT",
        "nt": "1500.0",
        "s": {
            "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "e": "1697788800000000000",
            "n": 1234567890
        }
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.testnet.grvt.io/full/v1/withdrawal' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "from_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "to_eth_address": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "currency": "USDT",
    "num_tokens": "1500.0",
    "signature": {
        "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
        "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
        "v": 28,
        "expiration": "1697788800000000000",
        "nonce": 1234567890
    }
}
'

JSONRPC Full

wscat -c "wss://trades.testnet.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/withdrawal",
    "params": {
        "from_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "to_eth_address": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "currency": "USDT",
        "num_tokens": "1500.0",
        "signature": {
            "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "expiration": "1697788800000000000",
            "nonce": 1234567890
        }
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.testnet.grvt.io/lite/v1/withdrawal' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "te": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "c": "USDT",
    "nt": "1500.0",
    "s": {
        "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
        "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
        "v": 28,
        "e": "1697788800000000000",
        "n": 1234567890
    }
}
'

JSONRPC Lite

wscat -c "wss://trades.testnet.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/withdrawal",
    "p": {
        "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "te": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "c": "USDT",
        "nt": "1500.0",
        "s": {
            "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "e": "1697788800000000000",
            "n": 1234567890
        }
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.grvt.io/full/v1/withdrawal' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "from_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "to_eth_address": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "currency": "USDT",
    "num_tokens": "1500.0",
    "signature": {
        "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
        "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
        "v": 28,
        "expiration": "1697788800000000000",
        "nonce": 1234567890
    }
}
'

JSONRPC Full

wscat -c "wss://trades.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/withdrawal",
    "params": {
        "from_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "to_eth_address": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "currency": "USDT",
        "num_tokens": "1500.0",
        "signature": {
            "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "expiration": "1697788800000000000",
            "nonce": 1234567890
        }
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.grvt.io/lite/v1/withdrawal' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "te": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
    "c": "USDT",
    "nt": "1500.0",
    "s": {
        "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
        "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
        "v": 28,
        "e": "1697788800000000000",
        "n": 1234567890
    }
}
'

JSONRPC Lite

wscat -c "wss://trades.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/withdrawal",
    "p": {
        "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "te": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "c": "USDT",
        "nt": "1500.0",
        "s": {
            "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "e": "1697788800000000000",
            "n": 1234567890
        }
    },
    "i": 123
}
' -w 360

Withdrawal History

FULL ENDPOINT: full/v1/withdrawal_history
LITE ENDPOINT: lite/v1/withdrawal_history

ApiWithdrawalHistoryRequest

The request to get the historical withdrawals of an account
The history is returned in reverse chronological order

Pagination works as follows:

  • We perform a reverse chronological lookup, starting from end_time. If end_time is not set, we start from the most recent data.
  • The lookup is limited to limit records. If more data is requested, the response will contain a next cursor for you to query the next page.
  • If a cursor is provided, it will be used to fetch results from that point onwards.
  • Pagination will continue until the start_time is reached. If start_time is not set, pagination will continue as far back as our data retention policy allows.

Name
Lite		 Type Required
Default		 Description
currency
c		 [Currency] True The token currency to query for, if nil or empty, return all withdrawals. Otherwise, only entries matching the filter will be returned
start_time
st		 string False
0		 The start time to query for in unix nanoseconds
end_time
et		 string False
now()		 The end time to query for in unix nanoseconds
limit
l		 integer False
500		 The limit to query for. Defaults to 500; Max 1000
cursor
c1		 string False
''		 The cursor to indicate when to start the next query from
main_account_id
ma		 string False
``		 Main account ID being queried. By default, applies the requestor's main account ID.
Currency

The list of Currencies that are supported on the GRVT exchange

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token

Query

Full Request 

{
    "currency": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": "",
    "main_account_id": null
}
Lite Request 
{
    "c": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c1": "",
    "ma": null
}

ApiWithdrawalHistoryResponse

Name
Lite		 Type Required
Default		 Description
result
r		 [WithdrawalHistory] True The withdrawals history matching the request account
next
n		 string False
''		 The cursor to indicate when to start the next query from
WithdrawalHistory
Name
Lite		 Type Required
Default		 Description
tx_id
ti		 string True The transaction ID of the withdrawal
from_account_id
fa		 string True The subaccount to withdraw from
to_eth_address
te		 string True The ethereum address to withdraw to
currency
c		 Currency True The token currency to withdraw
num_tokens
nt		 string True The number of tokens to withdraw
signature
s		 Signature True The signature of the withdrawal
event_time
et		 string True The timestamp of the withdrawal in unix nanoseconds
Currency

The list of Currencies that are supported on the GRVT exchange

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token
Signature
Name
Lite		 Type Required
Default		 Description
signer
s		 string True The address (public key) of the wallet signing the payload
r
r		 string True Signature R
s
s1		 string True Signature S
v
v		 integer True Signature V
expiration
e		 string True Timestamp after which this signature expires, expressed in unix nanoseconds. Must be capped at 30 days
nonce
n		 integer True Users can randomly generate this value, used as a signature deconflicting key.
ie. You can send the same exact instruction twice with different nonces.
When the same nonce is used, the same payload will generate the same signature.
Our system will consider the payload a duplicate, and ignore it.

Success

Full Response 

{
    "result": [{
        "tx_id": "1028403",
        "from_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "to_eth_address": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "currency": "USDT",
        "num_tokens": "1500.0",
        "signature": {
            "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "expiration": "1697788800000000000",
            "nonce": 1234567890
        },
        "event_time": "1697788800000000000"
    }],
    "next": "Qw0918="
}
Lite Response 
{
    "r": [{
        "ti": "1028403",
        "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "te": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "c": "USDT",
        "nt": "1500.0",
        "s": {
            "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
            "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8",
            "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d",
            "v": 28,
            "e": "1697788800000000000",
            "n": 1234567890
        },
        "et": "1697788800000000000"
    }],
    "n": "Qw0918="
}

Error Codes

Code HttpStatus Description
1000 401 You need to authenticate prior to using this functionality
1001 403 You are not authorized to access this functionality
1002 500 Internal Server Error
1003 400 Request could not be processed due to malformed syntax
1006 429 You have surpassed the allocated rate limit for your tier
1008 401 Your IP has not been whitelisted for access

Failure

Full Error Response 

{
    "request_id":1,
    "code":1000,
    "message":"You need to authenticate prior to using this functionality",
    "status":401
}
Lite Error Response 
{
    "ri":1,
    "c":1000,
    "m":"You need to authenticate prior to using this functionality",
    "s":401
}

Authentication

In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI.

# These are the variables you will need to set manually
GRVT_API_KEY="<insert_key_here>"
GRVT_SUB_ACCOUNT_ID="<insert_sub_account_id_here>"

Then, choose the environment you want to authenticate against.

# dev
GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login"
# staging
GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/api_key/login"
# testnet
GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/api_key/login"
# prod
GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/api_key/login"

Now, let’s authenticate and retrieve both the session cookie and the X-Grvt-Account-Id header value that you’ll need to access any endpoints requiring authentication.

echo $GRVT_API_KEY
echo $GRVT_SUB_ACCOUNT_ID
echo $GRVT_AUTH_ENDPOINT

RESPONSE=$(
    curl $GRVT_AUTH_ENDPOINT \
        -H 'Content-Type: application/json' \
        -H 'Cookie: rm=true;' \
        -d '{"api_key": "'$GRVT_API_KEY'"}' \
        -s -i
)

GRVT_COOKIE=$(echo "$RESPONSE" | grep -i 'set-cookie:' | grep -o 'gravity=[^;]*')
GRVT_ACCOUNT_ID=$(echo "$RESPONSE" | grep 'x-grvt-account-id:' | awk '{print $2}' | tr -d '\r')

echo "$GRVT_COOKIE"
echo "$GRVT_ACCOUNT_ID"

REST Full

curl --location 'https://trades.dev.gravitymarkets.io/full/v1/withdrawal_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "currency": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": "",
    "main_account_id": null
}
'

JSONRPC Full

wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/withdrawal_history",
    "params": {
        "currency": ["USDT", "USDC"],
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": "",
        "main_account_id": null
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/withdrawal_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "c": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c1": "",
    "ma": null
}
'

JSONRPC Lite

wscat -c "wss://trades.dev.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/withdrawal_history",
    "p": {
        "c": ["USDT", "USDC"],
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c1": "",
        "ma": null
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.staging.gravitymarkets.io/full/v1/withdrawal_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "currency": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": "",
    "main_account_id": null
}
'

JSONRPC Full

wscat -c "wss://trades.staging.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/withdrawal_history",
    "params": {
        "currency": ["USDT", "USDC"],
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": "",
        "main_account_id": null
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/withdrawal_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "c": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c1": "",
    "ma": null
}
'

JSONRPC Lite

wscat -c "wss://trades.staging.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/withdrawal_history",
    "p": {
        "c": ["USDT", "USDC"],
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c1": "",
        "ma": null
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.testnet.grvt.io/full/v1/withdrawal_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "currency": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": "",
    "main_account_id": null
}
'

JSONRPC Full

wscat -c "wss://trades.testnet.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/withdrawal_history",
    "params": {
        "currency": ["USDT", "USDC"],
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": "",
        "main_account_id": null
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.testnet.grvt.io/lite/v1/withdrawal_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "c": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c1": "",
    "ma": null
}
'

JSONRPC Lite

wscat -c "wss://trades.testnet.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/withdrawal_history",
    "p": {
        "c": ["USDT", "USDC"],
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c1": "",
        "ma": null
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.grvt.io/full/v1/withdrawal_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "currency": ["USDT", "USDC"],
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": "",
    "main_account_id": null
}
'

JSONRPC Full

wscat -c "wss://trades.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/withdrawal_history",
    "params": {
        "currency": ["USDT", "USDC"],
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": "",
        "main_account_id": null
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.grvt.io/lite/v1/withdrawal_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "c": ["USDT", "USDC"],
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c1": "",
    "ma": null
}
'

JSONRPC Lite

wscat -c "wss://trades.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/withdrawal_history",
    "p": {
        "c": ["USDT", "USDC"],
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c1": "",
        "ma": null
    },
    "i": 123
}
' -w 360

Account

Sub Account Summary

FULL ENDPOINT: full/v1/account_summary
LITE ENDPOINT: lite/v1/account_summary

ApiSubAccountSummaryRequest

Name
Lite		 Type Required
Default		 Description
sub_account_id
sa		 string True The subaccount ID to filter by

Query

Full Request 

{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'"
}
Lite Request 
{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'"
}

ApiSubAccountSummaryResponse

Query for sub-account details, including base currency balance, all derivative positions, margin levels, and P&L.

Name
Lite		 Type Required
Default		 Description
result
r		 SubAccount True The sub account matching the request sub account
SubAccount
Name
Lite		 Type Required
Default		 Description
event_time
et		 string True Time at which the event was emitted in unix nanoseconds
sub_account_id
sa		 string True The sub account ID this entry refers to
margin_type
mt		 MarginType True The type of margin algorithm this subaccount uses
settle_currency
sc		 Currency True The settlement, margin, and reporting currency of this account.
This subaccount can only open positions quoted in this currency

In the future, when users select a Multi-Currency Margin Type, this will be USD
All other assets are converted to this currency for the purpose of calculating margin
unrealized_pnl
up		 string True The total unrealized PnL of all positions owned by this subaccount, denominated in quote currency decimal units.
unrealized_pnl = sum(position.unrealized_pnl * position.quote_index_price) / settle_index_price
total_equity
te		 string True The notional value of your account if all positions are closed, excluding trading fees (reported in settle_currency).
total_equity = sum(spot_balance.balance * spot_balance.index_price) / settle_index_price + unrealized_pnl
initial_margin
im		 string True The total_equity required to open positions in the account (reported in settle_currency).
Computation is different depending on account's margin_type
maintenance_margin
mm		 string True The total_equity required to avoid liquidation of positions in the account (reported in settle_currency).
Computation is different depending on account's margin_type
available_balance
ab		 string True The notional value available to transfer out of the trading account into the funding account (reported in settle_currency).
available_balance = total_equity - initial_margin - min(unrealized_pnl, 0)
spot_balances
sb		 [SpotBalance] True The list of spot assets owned by this sub account, and their balances
positions
p		 [Positions] True The list of positions owned by this sub account
settle_index_price
si		 string True The index price of the settle currency. (reported in USD)
MarginType
Value Description
SIMPLE_CROSS_MARGIN = 2 Simple Cross Margin Mode: all assets have a predictable margin impact, the whole subaccount shares a single margin
PORTFOLIO_CROSS_MARGIN = 3 Portfolio Cross Margin Mode: asset margin impact is analysed on portfolio level, the whole subaccount shares a single margin
Currency

The list of Currencies that are supported on the GRVT exchange

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token
SpotBalance
Name
Lite		 Type Required
Default		 Description
currency
c		 Currency True The currency you hold a spot balance in
balance
b		 string True This currency's balance in this trading account.
index_price
ip		 string True The index price of this currency. (reported in USD)
Currency

The list of Currencies that are supported on the GRVT exchange

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token
Positions
Name
Lite		 Type Required
Default		 Description
event_time
et		 string True Time at which the event was emitted in unix nanoseconds
sub_account_id
sa		 string True The sub account ID that participated in the trade
instrument
i		 string True The instrument being represented
size
s		 string True The size of the position, expressed in base asset decimal units. Negative for short positions
notional
n		 string True The notional value of the position, negative for short assets, expressed in quote asset decimal units
entry_price
ep		 string True The entry price of the position, expressed in 9 decimals
Whenever increasing the size of a position, the entry price is updated to the new average entry price
new_entry_price = (old_entry_price * old_size + trade_price * trade_size) / (old_size + trade_size)
exit_price
ep1		 string True The exit price of the position, expressed in 9 decimals
Whenever decreasing the size of a position, the exit price is updated to the new average exit price
new_exit_price = (old_exit_price * old_exit_trade_size + trade_price * trade_size) / (old_exit_trade_size + trade_size)
mark_price
mp		 string True The mark price of the position, expressed in 9 decimals
unrealized_pnl
up		 string True The unrealized PnL of the position, expressed in quote asset decimal units
unrealized_pnl = (mark_price - entry_price) * size
realized_pnl
rp		 string True The realized PnL of the position, expressed in quote asset decimal units
realized_pnl = (exit_price - entry_price) * exit_trade_size
total_pnl
tp		 string True The total PnL of the position, expressed in quote asset decimal units
total_pnl = realized_pnl + unrealized_pnl
roi
r		 string True The ROI of the position, expressed as a percentage
roi = (total_pnl / (entry_price * abs(size))) * 100^
quote_index_price
qi		 string True The index price of the quote currency. (reported in USD)
est_liquidation_price
el		 string True The estimated liquidation price
leverage
l		 string True The current leverage value for this position

Success

Full Response 

{
    "result": {
        "event_time": "1697788800000000000",
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "margin_type": "SIMPLE_CROSS_MARGIN",
        "settle_currency": "USDT",
        "unrealized_pnl": "123456.78",
        "total_equity": "123456.78",
        "initial_margin": "123456.78",
        "maintenance_margin": "123456.78",
        "available_balance": "123456.78",
        "spot_balances": [{
            "currency": "USDT",
            "balance": "123456.78",
            "index_price": "1.0000102"
        }],
        "positions": [{
            "event_time": "1697788800000000000",
            "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
            "instrument": "BTC_USDT_Perp",
            "size": "2635000.50",
            "notional": "2635000.50",
            "entry_price": "65038.01",
            "exit_price": "65038.01",
            "mark_price": "65038.01",
            "unrealized_pnl": "135000.50",
            "realized_pnl": "-35000.30",
            "total_pnl": "100000.20",
            "roi": "10.20",
            "quote_index_price": "1.0000102",
            "est_liquidation_price": 60000.25,
            "leverage": "10"
        }],
        "settle_index_price": "1.0000102"
    }
}
Lite Response 
{
    "r": {
        "et": "1697788800000000000",
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "mt": "SIMPLE_CROSS_MARGIN",
        "sc": "USDT",
        "up": "123456.78",
        "te": "123456.78",
        "im": "123456.78",
        "mm": "123456.78",
        "ab": "123456.78",
        "sb": [{
            "c": "USDT",
            "b": "123456.78",
            "ip": "1.0000102"
        }],
        "p": [{
            "et": "1697788800000000000",
            "sa": "'$GRVT_SUB_ACCOUNT_ID'",
            "i": "BTC_USDT_Perp",
            "s": "2635000.50",
            "n": "2635000.50",
            "ep": "65038.01",
            "ep1": "65038.01",
            "mp": "65038.01",
            "up": "135000.50",
            "rp": "-35000.30",
            "tp": "100000.20",
            "r": "10.20",
            "qi": "1.0000102",
            "el": 60000.25,
            "l": "10"
        }],
        "si": "1.0000102"
    }
}

Error Codes

Code HttpStatus Description
1000 401 You need to authenticate prior to using this functionality
1001 403 You are not authorized to access this functionality
1002 500 Internal Server Error
1003 400 Request could not be processed due to malformed syntax
1006 429 You have surpassed the allocated rate limit for your tier
1008 401 Your IP has not been whitelisted for access

Failure

Full Error Response 

{
    "request_id":1,
    "code":1000,
    "message":"You need to authenticate prior to using this functionality",
    "status":401
}
Lite Error Response 
{
    "ri":1,
    "c":1000,
    "m":"You need to authenticate prior to using this functionality",
    "s":401
}

Authentication

In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI.

# These are the variables you will need to set manually
GRVT_API_KEY="<insert_key_here>"
GRVT_SUB_ACCOUNT_ID="<insert_sub_account_id_here>"

Then, choose the environment you want to authenticate against.

# dev
GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login"
# staging
GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/api_key/login"
# testnet
GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/api_key/login"
# prod
GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/api_key/login"

Now, let’s authenticate and retrieve both the session cookie and the X-Grvt-Account-Id header value that you’ll need to access any endpoints requiring authentication.

echo $GRVT_API_KEY
echo $GRVT_SUB_ACCOUNT_ID
echo $GRVT_AUTH_ENDPOINT

RESPONSE=$(
    curl $GRVT_AUTH_ENDPOINT \
        -H 'Content-Type: application/json' \
        -H 'Cookie: rm=true;' \
        -d '{"api_key": "'$GRVT_API_KEY'"}' \
        -s -i
)

GRVT_COOKIE=$(echo "$RESPONSE" | grep -i 'set-cookie:' | grep -o 'gravity=[^;]*')
GRVT_ACCOUNT_ID=$(echo "$RESPONSE" | grep 'x-grvt-account-id:' | awk '{print $2}' | tr -d '\r')

echo "$GRVT_COOKIE"
echo "$GRVT_ACCOUNT_ID"

REST Full

curl --location 'https://trades.dev.gravitymarkets.io/full/v1/account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'"
}
'

JSONRPC Full

wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/account_summary",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'"
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'"
}
'

JSONRPC Lite

wscat -c "wss://trades.dev.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/account_summary",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'"
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.staging.gravitymarkets.io/full/v1/account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'"
}
'

JSONRPC Full

wscat -c "wss://trades.staging.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/account_summary",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'"
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'"
}
'

JSONRPC Lite

wscat -c "wss://trades.staging.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/account_summary",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'"
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.testnet.grvt.io/full/v1/account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'"
}
'

JSONRPC Full

wscat -c "wss://trades.testnet.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/account_summary",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'"
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.testnet.grvt.io/lite/v1/account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'"
}
'

JSONRPC Lite

wscat -c "wss://trades.testnet.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/account_summary",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'"
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.grvt.io/full/v1/account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'"
}
'

JSONRPC Full

wscat -c "wss://trades.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/account_summary",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'"
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.grvt.io/lite/v1/account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'"
}
'

JSONRPC Lite

wscat -c "wss://trades.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/account_summary",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'"
    },
    "i": 123
}
' -w 360

Sub Account History

FULL ENDPOINT: full/v1/account_history
LITE ENDPOINT: lite/v1/account_history

ApiSubAccountHistoryRequest

The request to get the history of a sub account
SubAccount Summary values are snapshotted once every hour
No snapshots are taken if the sub account has no activity in the hourly window
History is preserved only for the last 30 days

Pagination works as follows:

  • We perform a reverse chronological lookup, starting from end_time. If end_time is not set, we start from the most recent data.
  • The lookup is limited to limit records. If more data is requested, the response will contain a next cursor for you to query the next page.
  • If a cursor is provided, it will be used to fetch results from that point onwards.
  • Pagination will continue until the start_time is reached. If start_time is not set, pagination will continue as far back as our data retention policy allows.

Name
Lite		 Type Required
Default		 Description
sub_account_id
sa		 string True The sub account ID to request for
start_time
st		 string False
0		 Start time of sub account history in unix nanoseconds
end_time
et		 string False
now()		 End time of sub account history in unix nanoseconds
limit
l		 integer False
500		 The limit to query for. Defaults to 500; Max 1000
cursor
c		 string False
''		 The cursor to indicate when to start the next query from

Query

Full Request 

{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": ""
}
Lite Request 
{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c": ""
}

ApiSubAccountHistoryResponse

Name
Lite		 Type Required
Default		 Description
result
r		 [SubAccount] True The sub account history matching the request sub account
next
n		 string True The cursor to indicate when to start the next query from
SubAccount
Name
Lite		 Type Required
Default		 Description
event_time
et		 string True Time at which the event was emitted in unix nanoseconds
sub_account_id
sa		 string True The sub account ID this entry refers to
margin_type
mt		 MarginType True The type of margin algorithm this subaccount uses
settle_currency
sc		 Currency True The settlement, margin, and reporting currency of this account.
This subaccount can only open positions quoted in this currency

In the future, when users select a Multi-Currency Margin Type, this will be USD
All other assets are converted to this currency for the purpose of calculating margin
unrealized_pnl
up		 string True The total unrealized PnL of all positions owned by this subaccount, denominated in quote currency decimal units.
unrealized_pnl = sum(position.unrealized_pnl * position.quote_index_price) / settle_index_price
total_equity
te		 string True The notional value of your account if all positions are closed, excluding trading fees (reported in settle_currency).
total_equity = sum(spot_balance.balance * spot_balance.index_price) / settle_index_price + unrealized_pnl
initial_margin
im		 string True The total_equity required to open positions in the account (reported in settle_currency).
Computation is different depending on account's margin_type
maintenance_margin
mm		 string True The total_equity required to avoid liquidation of positions in the account (reported in settle_currency).
Computation is different depending on account's margin_type
available_balance
ab		 string True The notional value available to transfer out of the trading account into the funding account (reported in settle_currency).
available_balance = total_equity - initial_margin - min(unrealized_pnl, 0)
spot_balances
sb		 [SpotBalance] True The list of spot assets owned by this sub account, and their balances
positions
p		 [Positions] True The list of positions owned by this sub account
settle_index_price
si		 string True The index price of the settle currency. (reported in USD)
MarginType
Value Description
SIMPLE_CROSS_MARGIN = 2 Simple Cross Margin Mode: all assets have a predictable margin impact, the whole subaccount shares a single margin
PORTFOLIO_CROSS_MARGIN = 3 Portfolio Cross Margin Mode: asset margin impact is analysed on portfolio level, the whole subaccount shares a single margin
Currency

The list of Currencies that are supported on the GRVT exchange

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token
SpotBalance
Name
Lite		 Type Required
Default		 Description
currency
c		 Currency True The currency you hold a spot balance in
balance
b		 string True This currency's balance in this trading account.
index_price
ip		 string True The index price of this currency. (reported in USD)
Currency

The list of Currencies that are supported on the GRVT exchange

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token
Positions
Name
Lite		 Type Required
Default		 Description
event_time
et		 string True Time at which the event was emitted in unix nanoseconds
sub_account_id
sa		 string True The sub account ID that participated in the trade
instrument
i		 string True The instrument being represented
size
s		 string True The size of the position, expressed in base asset decimal units. Negative for short positions
notional
n		 string True The notional value of the position, negative for short assets, expressed in quote asset decimal units
entry_price
ep		 string True The entry price of the position, expressed in 9 decimals
Whenever increasing the size of a position, the entry price is updated to the new average entry price
new_entry_price = (old_entry_price * old_size + trade_price * trade_size) / (old_size + trade_size)
exit_price
ep1		 string True The exit price of the position, expressed in 9 decimals
Whenever decreasing the size of a position, the exit price is updated to the new average exit price
new_exit_price = (old_exit_price * old_exit_trade_size + trade_price * trade_size) / (old_exit_trade_size + trade_size)
mark_price
mp		 string True The mark price of the position, expressed in 9 decimals
unrealized_pnl
up		 string True The unrealized PnL of the position, expressed in quote asset decimal units
unrealized_pnl = (mark_price - entry_price) * size
realized_pnl
rp		 string True The realized PnL of the position, expressed in quote asset decimal units
realized_pnl = (exit_price - entry_price) * exit_trade_size
total_pnl
tp		 string True The total PnL of the position, expressed in quote asset decimal units
total_pnl = realized_pnl + unrealized_pnl
roi
r		 string True The ROI of the position, expressed as a percentage
roi = (total_pnl / (entry_price * abs(size))) * 100^
quote_index_price
qi		 string True The index price of the quote currency. (reported in USD)
est_liquidation_price
el		 string True The estimated liquidation price
leverage
l		 string True The current leverage value for this position

Success

Full Response 

{
    "result": [{
        "event_time": "1697788800000000000",
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "margin_type": "SIMPLE_CROSS_MARGIN",
        "settle_currency": "USDT",
        "unrealized_pnl": "123456.78",
        "total_equity": "123456.78",
        "initial_margin": "123456.78",
        "maintenance_margin": "123456.78",
        "available_balance": "123456.78",
        "spot_balances": [{
            "currency": "USDT",
            "balance": "123456.78",
            "index_price": "1.0000102"
        }],
        "positions": [{
            "event_time": "1697788800000000000",
            "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
            "instrument": "BTC_USDT_Perp",
            "size": "2635000.50",
            "notional": "2635000.50",
            "entry_price": "65038.01",
            "exit_price": "65038.01",
            "mark_price": "65038.01",
            "unrealized_pnl": "135000.50",
            "realized_pnl": "-35000.30",
            "total_pnl": "100000.20",
            "roi": "10.20",
            "quote_index_price": "1.0000102",
            "est_liquidation_price": 60000.25,
            "leverage": "10"
        }],
        "settle_index_price": "1.0000102"
    }],
    "next": "Qw0918="
}
Lite Response 
{
    "r": [{
        "et": "1697788800000000000",
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "mt": "SIMPLE_CROSS_MARGIN",
        "sc": "USDT",
        "up": "123456.78",
        "te": "123456.78",
        "im": "123456.78",
        "mm": "123456.78",
        "ab": "123456.78",
        "sb": [{
            "c": "USDT",
            "b": "123456.78",
            "ip": "1.0000102"
        }],
        "p": [{
            "et": "1697788800000000000",
            "sa": "'$GRVT_SUB_ACCOUNT_ID'",
            "i": "BTC_USDT_Perp",
            "s": "2635000.50",
            "n": "2635000.50",
            "ep": "65038.01",
            "ep1": "65038.01",
            "mp": "65038.01",
            "up": "135000.50",
            "rp": "-35000.30",
            "tp": "100000.20",
            "r": "10.20",
            "qi": "1.0000102",
            "el": 60000.25,
            "l": "10"
        }],
        "si": "1.0000102"
    }],
    "n": "Qw0918="
}

Error Codes

Code HttpStatus Description
1000 401 You need to authenticate prior to using this functionality
1001 403 You are not authorized to access this functionality
1002 500 Internal Server Error
1003 400 Request could not be processed due to malformed syntax
1006 429 You have surpassed the allocated rate limit for your tier
1008 401 Your IP has not been whitelisted for access

Failure

Full Error Response 

{
    "request_id":1,
    "code":1000,
    "message":"You need to authenticate prior to using this functionality",
    "status":401
}
Lite Error Response 
{
    "ri":1,
    "c":1000,
    "m":"You need to authenticate prior to using this functionality",
    "s":401
}

Authentication

In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI.

# These are the variables you will need to set manually
GRVT_API_KEY="<insert_key_here>"
GRVT_SUB_ACCOUNT_ID="<insert_sub_account_id_here>"

Then, choose the environment you want to authenticate against.

# dev
GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login"
# staging
GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/api_key/login"
# testnet
GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/api_key/login"
# prod
GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/api_key/login"

Now, let’s authenticate and retrieve both the session cookie and the X-Grvt-Account-Id header value that you’ll need to access any endpoints requiring authentication.

echo $GRVT_API_KEY
echo $GRVT_SUB_ACCOUNT_ID
echo $GRVT_AUTH_ENDPOINT

RESPONSE=$(
    curl $GRVT_AUTH_ENDPOINT \
        -H 'Content-Type: application/json' \
        -H 'Cookie: rm=true;' \
        -d '{"api_key": "'$GRVT_API_KEY'"}' \
        -s -i
)

GRVT_COOKIE=$(echo "$RESPONSE" | grep -i 'set-cookie:' | grep -o 'gravity=[^;]*')
GRVT_ACCOUNT_ID=$(echo "$RESPONSE" | grep 'x-grvt-account-id:' | awk '{print $2}' | tr -d '\r')

echo "$GRVT_COOKIE"
echo "$GRVT_ACCOUNT_ID"

REST Full

curl --location 'https://trades.dev.gravitymarkets.io/full/v1/account_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": ""
}
'

JSONRPC Full

wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/account_history",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": ""
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/account_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c": ""
}
'

JSONRPC Lite

wscat -c "wss://trades.dev.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/account_history",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c": ""
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.staging.gravitymarkets.io/full/v1/account_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": ""
}
'

JSONRPC Full

wscat -c "wss://trades.staging.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/account_history",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": ""
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/account_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c": ""
}
'

JSONRPC Lite

wscat -c "wss://trades.staging.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/account_history",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c": ""
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.testnet.grvt.io/full/v1/account_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": ""
}
'

JSONRPC Full

wscat -c "wss://trades.testnet.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/account_history",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": ""
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.testnet.grvt.io/lite/v1/account_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c": ""
}
'

JSONRPC Lite

wscat -c "wss://trades.testnet.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/account_history",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c": ""
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.grvt.io/full/v1/account_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "start_time": "1697788800000000000",
    "end_time": "1697788800000000000",
    "limit": 500,
    "cursor": ""
}
'

JSONRPC Full

wscat -c "wss://trades.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/account_history",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "start_time": "1697788800000000000",
        "end_time": "1697788800000000000",
        "limit": 500,
        "cursor": ""
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.grvt.io/lite/v1/account_history' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "st": "1697788800000000000",
    "et": "1697788800000000000",
    "l": 500,
    "c": ""
}
'

JSONRPC Lite

wscat -c "wss://trades.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/account_history",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "st": "1697788800000000000",
        "et": "1697788800000000000",
        "l": 500,
        "c": ""
    },
    "i": 123
}
' -w 360

Aggregated Account Summary

FULL ENDPOINT: full/v1/aggregated_account_summary
LITE ENDPOINT: lite/v1/aggregated_account_summary

EmptyRequest

Used for requests that do not require any parameters

Name
Lite		 Type Required
Default		 Description

Query

Full Request 

{
}
Lite Request 
{
}

ApiAggregatedAccountSummaryResponse

The aggregated account summary, that reports the total equity and spot balances of a funding (main) account, and its constituent trading (sub) accounts

Name
Lite		 Type Required
Default		 Description
result
r		 AggregatedAccountSummary True The aggregated account summary
AggregatedAccountSummary
Name
Lite		 Type Required
Default		 Description
main_account_id
ma		 string True The main account ID of the account to which the summary belongs
total_equity
te		 string True Total equity of the main (+ sub) account, denominated in USD
spot_balances
sb		 [SpotBalance] True The list of spot assets owned by this main (+ sub) account, and their balances
SpotBalance
Name
Lite		 Type Required
Default		 Description
currency
c		 Currency True The currency you hold a spot balance in
balance
b		 string True This currency's balance in this trading account.
index_price
ip		 string True The index price of this currency. (reported in USD)
Currency

The list of Currencies that are supported on the GRVT exchange

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token

Success

Full Response 

{
    "result": {
        "main_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "total_equity": "3945034.23",
        "spot_balances": [{
            "currency": "USDT",
            "balance": "123456.78",
            "index_price": "1.0000102"
        }]
    }
}
Lite Response 
{
    "r": {
        "ma": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "te": "3945034.23",
        "sb": [{
            "c": "USDT",
            "b": "123456.78",
            "ip": "1.0000102"
        }]
    }
}

Error Codes

Code HttpStatus Description
1001 403 You are not authorized to access this functionality
1002 500 Internal Server Error
1003 400 Request could not be processed due to malformed syntax
1006 429 You have surpassed the allocated rate limit for your tier
1008 401 Your IP has not been whitelisted for access

Failure

Full Error Response 

{
    "request_id":1,
    "code":1001,
    "message":"You are not authorized to access this functionality",
    "status":403
}
Lite Error Response 
{
    "ri":1,
    "c":1001,
    "m":"You are not authorized to access this functionality",
    "s":403
}

Authentication

In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI.

# These are the variables you will need to set manually
GRVT_API_KEY="<insert_key_here>"
GRVT_SUB_ACCOUNT_ID="<insert_sub_account_id_here>"

Then, choose the environment you want to authenticate against.

# dev
GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login"
# staging
GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/api_key/login"
# testnet
GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/api_key/login"
# prod
GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/api_key/login"

Now, let’s authenticate and retrieve both the session cookie and the X-Grvt-Account-Id header value that you’ll need to access any endpoints requiring authentication.

echo $GRVT_API_KEY
echo $GRVT_SUB_ACCOUNT_ID
echo $GRVT_AUTH_ENDPOINT

RESPONSE=$(
    curl $GRVT_AUTH_ENDPOINT \
        -H 'Content-Type: application/json' \
        -H 'Cookie: rm=true;' \
        -d '{"api_key": "'$GRVT_API_KEY'"}' \
        -s -i
)

GRVT_COOKIE=$(echo "$RESPONSE" | grep -i 'set-cookie:' | grep -o 'gravity=[^;]*')
GRVT_ACCOUNT_ID=$(echo "$RESPONSE" | grep 'x-grvt-account-id:' | awk '{print $2}' | tr -d '\r')

echo "$GRVT_COOKIE"
echo "$GRVT_ACCOUNT_ID"

REST Full

curl --location 'https://trades.dev.gravitymarkets.io/full/v1/aggregated_account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
}
'

JSONRPC Full

wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/aggregated_account_summary",
    "params": {
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/aggregated_account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
}
'

JSONRPC Lite

wscat -c "wss://trades.dev.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/aggregated_account_summary",
    "p": {
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.staging.gravitymarkets.io/full/v1/aggregated_account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
}
'

JSONRPC Full

wscat -c "wss://trades.staging.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/aggregated_account_summary",
    "params": {
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/aggregated_account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
}
'

JSONRPC Lite

wscat -c "wss://trades.staging.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/aggregated_account_summary",
    "p": {
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.testnet.grvt.io/full/v1/aggregated_account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
}
'

JSONRPC Full

wscat -c "wss://trades.testnet.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/aggregated_account_summary",
    "params": {
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.testnet.grvt.io/lite/v1/aggregated_account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
}
'

JSONRPC Lite

wscat -c "wss://trades.testnet.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/aggregated_account_summary",
    "p": {
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.grvt.io/full/v1/aggregated_account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
}
'

JSONRPC Full

wscat -c "wss://trades.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/aggregated_account_summary",
    "params": {
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.grvt.io/lite/v1/aggregated_account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
}
'

JSONRPC Lite

wscat -c "wss://trades.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/aggregated_account_summary",
    "p": {
    },
    "i": 123
}
' -w 360

Funding Account Summary

FULL ENDPOINT: full/v1/funding_account_summary
LITE ENDPOINT: lite/v1/funding_account_summary

EmptyRequest

Used for requests that do not require any parameters

Name
Lite		 Type Required
Default		 Description

Query

Full Request 

{
}
Lite Request 
{
}

ApiFundingAccountSummaryResponse

The funding account summary, that reports the total equity and spot balances of a funding (main) account

Name
Lite		 Type Required
Default		 Description
result
r		 FundingAccountSummary True The funding account summary
FundingAccountSummary

The funding account summary, that reports the total equity and spot balances of a funding (main) account

Name
Lite		 Type Required
Default		 Description
main_account_id
ma		 string True The main account ID of the account to which the summary belongs
total_equity
te		 string True Total equity of the main account, denominated in USD
spot_balances
sb		 [SpotBalance] True The list of spot assets owned by this main account, and their balances
SpotBalance
Name
Lite		 Type Required
Default		 Description
currency
c		 Currency True The currency you hold a spot balance in
balance
b		 string True This currency's balance in this trading account.
index_price
ip		 string True The index price of this currency. (reported in USD)
Currency

The list of Currencies that are supported on the GRVT exchange

Value Description
USD = 1 the USD fiat currency
USDC = 2 the USDC token
USDT = 3 the USDT token
ETH = 4 the ETH token
BTC = 5 the BTC token
SOL = 6 the SOL token
ARB = 7 the ARB token
BNB = 8 the BNB token
ZK = 9 the ZK token
POL = 10 the POL token
OP = 11 the OP token
ATOM = 12 the ATOM token
KPEPE = 13 the 1000PEPE token
TON = 14 the TON token
XRP = 15 the XRP token
TRUMP = 20 the TRUMP token
SUI = 21 the SUI token
LINK = 25 the LINK token
JUP = 27 the JUP token
FARTCOIN = 28 the FARTCOIN token
ENA = 29 the ENA token
DOGE = 30 the DOGE token
ADA = 33 the ADA token
AAVE = 34 the AAVE token
BERA = 35 the BERA token
IP = 40 the IP token

Success

Full Response 

{
    "result": {
        "main_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "total_equity": "3945034.23",
        "spot_balances": [{
            "currency": "USDT",
            "balance": "123456.78",
            "index_price": "1.0000102"
        }]
    }
}
Lite Response 
{
    "r": {
        "ma": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0",
        "te": "3945034.23",
        "sb": [{
            "c": "USDT",
            "b": "123456.78",
            "ip": "1.0000102"
        }]
    }
}

Error Codes

Code HttpStatus Description
1001 403 You are not authorized to access this functionality
1002 500 Internal Server Error
1003 400 Request could not be processed due to malformed syntax
1006 429 You have surpassed the allocated rate limit for your tier
1008 401 Your IP has not been whitelisted for access

Failure

Full Error Response 

{
    "request_id":1,
    "code":1001,
    "message":"You are not authorized to access this functionality",
    "status":403
}
Lite Error Response 
{
    "ri":1,
    "c":1001,
    "m":"You are not authorized to access this functionality",
    "s":403
}

Authentication

In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI.

# These are the variables you will need to set manually
GRVT_API_KEY="<insert_key_here>"
GRVT_SUB_ACCOUNT_ID="<insert_sub_account_id_here>"

Then, choose the environment you want to authenticate against.

# dev
GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login"
# staging
GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/api_key/login"
# testnet
GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/api_key/login"
# prod
GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/api_key/login"

Now, let’s authenticate and retrieve both the session cookie and the X-Grvt-Account-Id header value that you’ll need to access any endpoints requiring authentication.

echo $GRVT_API_KEY
echo $GRVT_SUB_ACCOUNT_ID
echo $GRVT_AUTH_ENDPOINT

RESPONSE=$(
    curl $GRVT_AUTH_ENDPOINT \
        -H 'Content-Type: application/json' \
        -H 'Cookie: rm=true;' \
        -d '{"api_key": "'$GRVT_API_KEY'"}' \
        -s -i
)

GRVT_COOKIE=$(echo "$RESPONSE" | grep -i 'set-cookie:' | grep -o 'gravity=[^;]*')
GRVT_ACCOUNT_ID=$(echo "$RESPONSE" | grep 'x-grvt-account-id:' | awk '{print $2}' | tr -d '\r')

echo "$GRVT_COOKIE"
echo "$GRVT_ACCOUNT_ID"

REST Full

curl --location 'https://trades.dev.gravitymarkets.io/full/v1/funding_account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
}
'

JSONRPC Full

wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/funding_account_summary",
    "params": {
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/funding_account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
}
'

JSONRPC Lite

wscat -c "wss://trades.dev.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/funding_account_summary",
    "p": {
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.staging.gravitymarkets.io/full/v1/funding_account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
}
'

JSONRPC Full

wscat -c "wss://trades.staging.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/funding_account_summary",
    "params": {
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/funding_account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
}
'

JSONRPC Lite

wscat -c "wss://trades.staging.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/funding_account_summary",
    "p": {
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.testnet.grvt.io/full/v1/funding_account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
}
'

JSONRPC Full

wscat -c "wss://trades.testnet.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/funding_account_summary",
    "params": {
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.testnet.grvt.io/lite/v1/funding_account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
}
'

JSONRPC Lite

wscat -c "wss://trades.testnet.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/funding_account_summary",
    "p": {
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.grvt.io/full/v1/funding_account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
}
'

JSONRPC Full

wscat -c "wss://trades.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/funding_account_summary",
    "params": {
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.grvt.io/lite/v1/funding_account_summary' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
}
'

JSONRPC Lite

wscat -c "wss://trades.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/funding_account_summary",
    "p": {
    },
    "i": 123
}
' -w 360

InitialLeverage

Get All Initial Leverage

FULL ENDPOINT: full/v1/get_all_initial_leverage
LITE ENDPOINT: lite/v1/get_all_initial_leverage

ApiGetAllInitialLeverageRequest

The request to get the initial leverage of a sub account

Name
Lite		 Type Required
Default		 Description
sub_account_id
sa		 string True The sub account ID to get the leverage for

Query

Full Request 

{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'"
}
Lite Request 
{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'"
}

ApiGetAllInitialLeverageResponse

The response to get the initial leverage of a sub account

Name
Lite		 Type Required
Default		 Description
results
r		 [InitialLeverageResult] True The initial leverage of the sub account
InitialLeverageResult
Name
Lite		 Type Required
Default		 Description
instrument
i		 string True The instrument to get the leverage for
leverage
l		 string True The initial leverage of the sub account
min_leverage
ml		 string True The min leverage this sub account can set
max_leverage
ml1		 string True The max leverage this sub account can set

Success

Full Response 

{
    "results": [{
        "instrument": "BTC_USDT_Perp",
        "leverage": "10",
        "min_leverage": "10",
        "max_leverage": "50"
    }]
}
Lite Response 
{
    "r": [{
        "i": "BTC_USDT_Perp",
        "l": "10",
        "ml": "10",
        "ml1": "50"
    }]
}

Error Codes

Code HttpStatus Description
1000 401 You need to authenticate prior to using this functionality
1001 403 You are not authorized to access this functionality
1002 500 Internal Server Error
1003 400 Request could not be processed due to malformed syntax
1006 429 You have surpassed the allocated rate limit for your tier
1004 404 Data Not Found

Failure

Full Error Response 

{
    "request_id":1,
    "code":1000,
    "message":"You need to authenticate prior to using this functionality",
    "status":401
}
Lite Error Response 
{
    "ri":1,
    "c":1000,
    "m":"You need to authenticate prior to using this functionality",
    "s":401
}

Authentication

In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI.

# These are the variables you will need to set manually
GRVT_API_KEY="<insert_key_here>"
GRVT_SUB_ACCOUNT_ID="<insert_sub_account_id_here>"

Then, choose the environment you want to authenticate against.

# dev
GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login"
# staging
GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/api_key/login"
# testnet
GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/api_key/login"
# prod
GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/api_key/login"

Now, let’s authenticate and retrieve both the session cookie and the X-Grvt-Account-Id header value that you’ll need to access any endpoints requiring authentication.

echo $GRVT_API_KEY
echo $GRVT_SUB_ACCOUNT_ID
echo $GRVT_AUTH_ENDPOINT

RESPONSE=$(
    curl $GRVT_AUTH_ENDPOINT \
        -H 'Content-Type: application/json' \
        -H 'Cookie: rm=true;' \
        -d '{"api_key": "'$GRVT_API_KEY'"}' \
        -s -i
)

GRVT_COOKIE=$(echo "$RESPONSE" | grep -i 'set-cookie:' | grep -o 'gravity=[^;]*')
GRVT_ACCOUNT_ID=$(echo "$RESPONSE" | grep 'x-grvt-account-id:' | awk '{print $2}' | tr -d '\r')

echo "$GRVT_COOKIE"
echo "$GRVT_ACCOUNT_ID"

REST Full

curl --location 'https://trades.dev.gravitymarkets.io/full/v1/get_all_initial_leverage' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'"
}
'

JSONRPC Full

wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/get_all_initial_leverage",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'"
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/get_all_initial_leverage' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'"
}
'

JSONRPC Lite

wscat -c "wss://trades.dev.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/get_all_initial_leverage",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'"
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.staging.gravitymarkets.io/full/v1/get_all_initial_leverage' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'"
}
'

JSONRPC Full

wscat -c "wss://trades.staging.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/get_all_initial_leverage",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'"
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/get_all_initial_leverage' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'"
}
'

JSONRPC Lite

wscat -c "wss://trades.staging.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/get_all_initial_leverage",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'"
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.testnet.grvt.io/full/v1/get_all_initial_leverage' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'"
}
'

JSONRPC Full

wscat -c "wss://trades.testnet.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/get_all_initial_leverage",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'"
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.testnet.grvt.io/lite/v1/get_all_initial_leverage' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'"
}
'

JSONRPC Lite

wscat -c "wss://trades.testnet.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/get_all_initial_leverage",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'"
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.grvt.io/full/v1/get_all_initial_leverage' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'"
}
'

JSONRPC Full

wscat -c "wss://trades.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/get_all_initial_leverage",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'"
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.grvt.io/lite/v1/get_all_initial_leverage' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'"
}
'

JSONRPC Lite

wscat -c "wss://trades.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/get_all_initial_leverage",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'"
    },
    "i": 123
}
' -w 360

Set Initial Leverage

FULL ENDPOINT: full/v1/set_initial_leverage
LITE ENDPOINT: lite/v1/set_initial_leverage

ApiSetInitialLeverageRequest

The request to set the initial leverage of a sub account

Name
Lite		 Type Required
Default		 Description
sub_account_id
sa		 string True The sub account ID to set the leverage for
instrument
i		 string True The instrument to set the leverage for
leverage
l		 string True The leverage to set for the sub account

Query

Full Request 

{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "instrument": "BTC_USDT_Perp",
    "leverage": "10"
}
Lite Request 
{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "i": "BTC_USDT_Perp",
    "l": "10"
}

ApiSetInitialLeverageResponse

The response to set the initial leverage of a sub account

Name
Lite		 Type Required
Default		 Description
success
s		 boolean True Whether the leverage was set successfully

Success

Full Response 

{
    "success": "true"
}
Lite Response 
{
    "s": "true"
}

Error Codes

Code HttpStatus Description
1000 401 You need to authenticate prior to using this functionality
1001 403 You are not authorized to access this functionality
1002 500 Internal Server Error
1003 400 Request could not be processed due to malformed syntax
1006 429 You have surpassed the allocated rate limit for your tier
1004 404 Data Not Found
2100 400 Invalid initial leverage

Failure

Full Error Response 

{
    "request_id":1,
    "code":1000,
    "message":"You need to authenticate prior to using this functionality",
    "status":401
}
Lite Error Response 
{
    "ri":1,
    "c":1000,
    "m":"You need to authenticate prior to using this functionality",
    "s":401
}

Authentication

In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI.

# These are the variables you will need to set manually
GRVT_API_KEY="<insert_key_here>"
GRVT_SUB_ACCOUNT_ID="<insert_sub_account_id_here>"

Then, choose the environment you want to authenticate against.

# dev
GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login"
# staging
GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/api_key/login"
# testnet
GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/api_key/login"
# prod
GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/api_key/login"

Now, let’s authenticate and retrieve both the session cookie and the X-Grvt-Account-Id header value that you’ll need to access any endpoints requiring authentication.

echo $GRVT_API_KEY
echo $GRVT_SUB_ACCOUNT_ID
echo $GRVT_AUTH_ENDPOINT

RESPONSE=$(
    curl $GRVT_AUTH_ENDPOINT \
        -H 'Content-Type: application/json' \
        -H 'Cookie: rm=true;' \
        -d '{"api_key": "'$GRVT_API_KEY'"}' \
        -s -i
)

GRVT_COOKIE=$(echo "$RESPONSE" | grep -i 'set-cookie:' | grep -o 'gravity=[^;]*')
GRVT_ACCOUNT_ID=$(echo "$RESPONSE" | grep 'x-grvt-account-id:' | awk '{print $2}' | tr -d '\r')

echo "$GRVT_COOKIE"
echo "$GRVT_ACCOUNT_ID"

REST Full

curl --location 'https://trades.dev.gravitymarkets.io/full/v1/set_initial_leverage' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "instrument": "BTC_USDT_Perp",
    "leverage": "10"
}
'

JSONRPC Full

wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/set_initial_leverage",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "instrument": "BTC_USDT_Perp",
        "leverage": "10"
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/set_initial_leverage' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "i": "BTC_USDT_Perp",
    "l": "10"
}
'

JSONRPC Lite

wscat -c "wss://trades.dev.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/set_initial_leverage",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "i": "BTC_USDT_Perp",
        "l": "10"
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.staging.gravitymarkets.io/full/v1/set_initial_leverage' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "instrument": "BTC_USDT_Perp",
    "leverage": "10"
}
'

JSONRPC Full

wscat -c "wss://trades.staging.gravitymarkets.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/set_initial_leverage",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "instrument": "BTC_USDT_Perp",
        "leverage": "10"
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/set_initial_leverage' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "i": "BTC_USDT_Perp",
    "l": "10"
}
'

JSONRPC Lite

wscat -c "wss://trades.staging.gravitymarkets.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/set_initial_leverage",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "i": "BTC_USDT_Perp",
        "l": "10"
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.testnet.grvt.io/full/v1/set_initial_leverage' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "instrument": "BTC_USDT_Perp",
    "leverage": "10"
}
'

JSONRPC Full

wscat -c "wss://trades.testnet.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/set_initial_leverage",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "instrument": "BTC_USDT_Perp",
        "leverage": "10"
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.testnet.grvt.io/lite/v1/set_initial_leverage' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "i": "BTC_USDT_Perp",
    "l": "10"
}
'

JSONRPC Lite

wscat -c "wss://trades.testnet.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/set_initial_leverage",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "i": "BTC_USDT_Perp",
        "l": "10"
    },
    "i": 123
}
' -w 360

REST Full

curl --location 'https://trades.grvt.io/full/v1/set_initial_leverage' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
    "instrument": "BTC_USDT_Perp",
    "leverage": "10"
}
'

JSONRPC Full

wscat -c "wss://trades.grvt.io/ws/full" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "jsonrpc": "2.0",
    "method": "v1/set_initial_leverage",
    "params": {
        "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'",
        "instrument": "BTC_USDT_Perp",
        "leverage": "10"
    },
    "id": 123
}
' -w 360

REST Lite

curl --location 'https://trades.grvt.io/lite/v1/set_initial_leverage' \
--header "Cookie: $GRVT_COOKIE" \
--header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
--data '{
    "sa": "'$GRVT_SUB_ACCOUNT_ID'",
    "i": "BTC_USDT_Perp",
    "l": "10"
}
'

JSONRPC Lite

wscat -c "wss://trades.grvt.io/ws/lite" \
-H "Cookie: $GRVT_COOKIE" \
-H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \
-x '
{
    "j": "2.0",
    "m": "v1/set_initial_leverage",
    "p": {
        "sa": "'$GRVT_SUB_ACCOUNT_ID'",
        "i": "BTC_USDT_Perp",
        "l": "10"
    },
    "i": 123
}
' -w 360