# Table of Contents - [Gravity Markets API Docs](#gravity-markets-api-docs) - [API Setup Guide - Gravity Markets API Docs](#api-setup-guide-gravity-markets-api-docs) - [Auth - Gravity Markets API Docs](#auth-gravity-markets-api-docs) - [Builder Integration - Gravity Markets API Docs](#builder-integration-gravity-markets-api-docs) - [GRVT Strategies - Gravity Markets API Docs](#grvt-strategies-gravity-markets-api-docs) - [Ack - Gravity Markets API Docs](#ack-gravity-markets-api-docs) - [Learn - Gravity Markets API Docs](#learn-gravity-markets-api-docs) - [Ack response - Gravity Markets API Docs](#ack-response-gravity-markets-api-docs) - [Api add isolated position margin response - Gravity Markets API Docs](#api-add-isolated-position-margin-response-gravity-markets-api-docs) - [Aggregated account summary - Gravity Markets API Docs](#aggregated-account-summary-gravity-markets-api-docs) - [Api add isolated position margin request - Gravity Markets API Docs](#api-add-isolated-position-margin-request-gravity-markets-api-docs) - [Api category affinity score request - Gravity Markets API Docs](#api-category-affinity-score-request-gravity-markets-api-docs) - [Api cancel all orders response - Gravity Markets API Docs](#api-cancel-all-orders-response-gravity-markets-api-docs) - [Api builder fill history request - Gravity Markets API Docs](#api-builder-fill-history-request-gravity-markets-api-docs) - [Api cancel on disconnect request - Gravity Markets API Docs](#api-cancel-on-disconnect-request-gravity-markets-api-docs) - [Api cancel order request - Gravity Markets API Docs](#api-cancel-order-request-gravity-markets-api-docs) - [Api authorized builder - Gravity Markets API Docs](#api-authorized-builder-gravity-markets-api-docs) - [Api get all initial leverage request - Gravity Markets API Docs](#api-get-all-initial-leverage-request-gravity-markets-api-docs) - [Api deposit history request - Gravity Markets API Docs](#api-deposit-history-request-gravity-markets-api-docs) - [Api drop client ws request - Gravity Markets API Docs](#api-drop-client-ws-request-gravity-markets-api-docs) - [Api drop client ws response - Gravity Markets API Docs](#api-drop-client-ws-response-gravity-markets-api-docs) - [Api cancel all orders request - Gravity Markets API Docs](#api-cancel-all-orders-request-gravity-markets-api-docs) - [Api authorize builder request - Gravity Markets API Docs](#api-authorize-builder-request-gravity-markets-api-docs) - [Api funding rate - Gravity Markets API Docs](#api-funding-rate-gravity-markets-api-docs) - [Api get all instruments request - Gravity Markets API Docs](#api-get-all-instruments-request-gravity-markets-api-docs) - [Api builder fill history response - Gravity Markets API Docs](#api-builder-fill-history-response-gravity-markets-api-docs) - [Api candlestick response - Gravity Markets API Docs](#api-candlestick-response-gravity-markets-api-docs) - [Api deposit history response - Gravity Markets API Docs](#api-deposit-history-response-gravity-markets-api-docs) - [Api category affinity score response - Gravity Markets API Docs](#api-category-affinity-score-response-gravity-markets-api-docs) - [Api get currency request - Gravity Markets API Docs](#api-get-currency-request-gravity-markets-api-docs) - [Api get ecosystem leaderboard request - Gravity Markets API Docs](#api-get-ecosystem-leaderboard-request-gravity-markets-api-docs) - [Api aggregated account summary response - Gravity Markets API Docs](#api-aggregated-account-summary-response-gravity-markets-api-docs) - [Api find ecosystem epoch metric response - Gravity Markets API Docs](#api-find-ecosystem-epoch-metric-response-gravity-markets-api-docs) - [Api find ecosystem leaderboard response - Gravity Markets API Docs](#api-find-ecosystem-leaderboard-response-gravity-markets-api-docs) - [Api deposit request - Gravity Markets API Docs](#api-deposit-request-gravity-markets-api-docs) - [Api find trader epoch metric response - Gravity Markets API Docs](#api-find-trader-epoch-metric-response-gravity-markets-api-docs) - [Api find first epoch metric response - Gravity Markets API Docs](#api-find-first-epoch-metric-response-gravity-markets-api-docs) - [Api find trader leaderboard response - Gravity Markets API Docs](#api-find-trader-leaderboard-response-gravity-markets-api-docs) - [Api funding payment history response - Gravity Markets API Docs](#api-funding-payment-history-response-gravity-markets-api-docs) - [Api candlestick request - Gravity Markets API Docs](#api-candlestick-request-gravity-markets-api-docs) - [Api funding payment history request - Gravity Markets API Docs](#api-funding-payment-history-request-gravity-markets-api-docs) - [Api funding rate request - Gravity Markets API Docs](#api-funding-rate-request-gravity-markets-api-docs) - [Api funding rate response - Gravity Markets API Docs](#api-funding-rate-response-gravity-markets-api-docs) - [Api get ecosystem referral stat response - Gravity Markets API Docs](#api-get-ecosystem-referral-stat-response-gravity-markets-api-docs) - [Api get instrument request - Gravity Markets API Docs](#api-get-instrument-request-gravity-markets-api-docs) - [Api fill history request - Gravity Markets API Docs](#api-fill-history-request-gravity-markets-api-docs) - [Api get currency response - Gravity Markets API Docs](#api-get-currency-response-gravity-markets-api-docs) - [Api get isolated position margin limits request - Gravity Markets API Docs](#api-get-isolated-position-margin-limits-request-gravity-markets-api-docs) - [Api get authorized builders response - Gravity Markets API Docs](#api-get-authorized-builders-response-gravity-markets-api-docs) - [Api get ecosystem leaderboard response - Gravity Markets API Docs](#api-get-ecosystem-leaderboard-response-gravity-markets-api-docs) - [Api get isolated position margin limits response - Gravity Markets API Docs](#api-get-isolated-position-margin-limits-response-gravity-markets-api-docs) - [Api get all initial leverage response - Gravity Markets API Docs](#api-get-all-initial-leverage-response-gravity-markets-api-docs) - [Api get filtered instruments request - Gravity Markets API Docs](#api-get-filtered-instruments-request-gravity-markets-api-docs) - [Api get list flat referral request - Gravity Markets API Docs](#api-get-list-flat-referral-request-gravity-markets-api-docs) - [Api get margin rules request - Gravity Markets API Docs](#api-get-margin-rules-request-gravity-markets-api-docs) - [Api get order group request - Gravity Markets API Docs](#api-get-order-group-request-gravity-markets-api-docs) - [Api get sub accounts response - Gravity Markets API Docs](#api-get-sub-accounts-response-gravity-markets-api-docs) - [Api get verified ecosystem leaderboard request - Gravity Markets API Docs](#api-get-verified-ecosystem-leaderboard-request-gravity-markets-api-docs) - [Api latest snap sub accounts request - Gravity Markets API Docs](#api-latest-snap-sub-accounts-request-gravity-markets-api-docs) - [Api get trader stat response - Gravity Markets API Docs](#api-get-trader-stat-response-gravity-markets-api-docs) - [Api list aggregated account summary request - Gravity Markets API Docs](#api-list-aggregated-account-summary-request-gravity-markets-api-docs) - [Api get lp info response - Gravity Markets API Docs](#api-get-lp-info-response-gravity-markets-api-docs) - [Api get order request - Gravity Markets API Docs](#api-get-order-request-gravity-markets-api-docs) - [Api get user ecosystem point request - Gravity Markets API Docs](#api-get-user-ecosystem-point-request-gravity-markets-api-docs) - [Api mini ticker request - Gravity Markets API Docs](#api-mini-ticker-request-gravity-markets-api-docs) - [Api order state request - Gravity Markets API Docs](#api-order-state-request-gravity-markets-api-docs) - [Api orderbook levels request - Gravity Markets API Docs](#api-orderbook-levels-request-gravity-markets-api-docs) - [Api query flat referral stat request - Gravity Markets API Docs](#api-query-flat-referral-stat-request-gravity-markets-api-docs) - [Api query flat referral stat response - Gravity Markets API Docs](#api-query-flat-referral-stat-response-gravity-markets-api-docs) - [Api query vault manager investor history request - Gravity Markets API Docs](#api-query-vault-manager-investor-history-request-gravity-markets-api-docs) - [Api set derisk to maintenance margin ratio response - Gravity Markets API Docs](#api-set-derisk-to-maintenance-margin-ratio-response-gravity-markets-api-docs) - [Api resolve epoch ecosystem metric response - Gravity Markets API Docs](#api-resolve-epoch-ecosystem-metric-response-gravity-markets-api-docs) - [Api set initial leverage request - Gravity Markets API Docs](#api-set-initial-leverage-request-gravity-markets-api-docs) - [Api ticker request - Gravity Markets API Docs](#api-ticker-request-gravity-markets-api-docs) - [Api fill history response - Gravity Markets API Docs](#api-fill-history-response-gravity-markets-api-docs) - [Api get latest lp snapshot response - Gravity Markets API Docs](#api-get-latest-lp-snapshot-response-gravity-markets-api-docs) - [Api get list flat referral response - Gravity Markets API Docs](#api-get-list-flat-referral-response-gravity-markets-api-docs) - [Api sub account history request - Gravity Markets API Docs](#api-sub-account-history-request-gravity-markets-api-docs) - [Api trade history request - Gravity Markets API Docs](#api-trade-history-request-gravity-markets-api-docs) - [Api get lp config response - Gravity Markets API Docs](#api-get-lp-config-response-gravity-markets-api-docs) - [Api user category affinity score request - Gravity Markets API Docs](#api-user-category-affinity-score-request-gravity-markets-api-docs) - [Api get lp leaderboard response - Gravity Markets API Docs](#api-get-lp-leaderboard-response-gravity-markets-api-docs) - [Api get lp point response - Gravity Markets API Docs](#api-get-lp-point-response-gravity-markets-api-docs) - [Api get order group response - Gravity Markets API Docs](#api-get-order-group-response-gravity-markets-api-docs) - [Api open orders request - Gravity Markets API Docs](#api-open-orders-request-gravity-markets-api-docs) - [Api positions request - Gravity Markets API Docs](#api-positions-request-gravity-markets-api-docs) - [Api vault view redemption queue request - Gravity Markets API Docs](#api-vault-view-redemption-queue-request-gravity-markets-api-docs) - [Approximate lp snapshot - Gravity Markets API Docs](#approximate-lp-snapshot-gravity-markets-api-docs) - [Builder fill history - Gravity Markets API Docs](#builder-fill-history-gravity-markets-api-docs) - [Candlestick - Gravity Markets API Docs](#candlestick-gravity-markets-api-docs) - [Candlestick type - Gravity Markets API Docs](#candlestick-type-gravity-markets-api-docs) - [Client tier - Gravity Markets API Docs](#client-tier-gravity-markets-api-docs) - [Deposit - Gravity Markets API Docs](#deposit-gravity-markets-api-docs) - [Empty request - Gravity Markets API Docs](#empty-request-gravity-markets-api-docs) - [Epoch - Gravity Markets API Docs](#epoch-gravity-markets-api-docs) - [Error - Gravity Markets API Docs](#error-gravity-markets-api-docs) - [Api get margin rules response - Gravity Markets API Docs](#api-get-margin-rules-response-gravity-markets-api-docs) - [Api get user ecosystem point response - Gravity Markets API Docs](#api-get-user-ecosystem-point-response-gravity-markets-api-docs) - [Api order history request - Gravity Markets API Docs](#api-order-history-request-gravity-markets-api-docs) - [Api mini ticker response - Gravity Markets API Docs](#api-mini-ticker-response-gravity-markets-api-docs) - [Api sub account trade aggregation response - Gravity Markets API Docs](#api-sub-account-trade-aggregation-response-gravity-markets-api-docs) - [Api sub account trade response - Gravity Markets API Docs](#api-sub-account-trade-response-gravity-markets-api-docs) - [Api withdrawal history request - Gravity Markets API Docs](#api-withdrawal-history-request-gravity-markets-api-docs) - [Candlestick interval - Gravity Markets API Docs](#candlestick-interval-gravity-markets-api-docs) - [Client order i ds by group - Gravity Markets API Docs](#client-order-i-ds-by-group-gravity-markets-api-docs) - [Ecosystem leaderboard user - Gravity Markets API Docs](#ecosystem-leaderboard-user-gravity-markets-api-docs) - [Currency detail - Gravity Markets API Docs](#currency-detail-gravity-markets-api-docs) - [Currency - Gravity Markets API Docs](#currency-gravity-markets-api-docs) - [Deposit history - Gravity Markets API Docs](#deposit-history-gravity-markets-api-docs) - [Ecosystem metric - Gravity Markets API Docs](#ecosystem-metric-gravity-markets-api-docs) - [Ecosystem point - Gravity Markets API Docs](#ecosystem-point-gravity-markets-api-docs) - [Epoch badge type - Gravity Markets API Docs](#epoch-badge-type-gravity-markets-api-docs) - [Flat referral - Gravity Markets API Docs](#flat-referral-gravity-markets-api-docs) - [Funding payment - Gravity Markets API Docs](#funding-payment-gravity-markets-api-docs) - [Funding rate - Gravity Markets API Docs](#funding-rate-gravity-markets-api-docs) - [Funding rate aggregation type - Gravity Markets API Docs](#funding-rate-aggregation-type-gravity-markets-api-docs) - [Instrument settlement period - Gravity Markets API Docs](#instrument-settlement-period-gravity-markets-api-docs) - [Kind - Gravity Markets API Docs](#kind-gravity-markets-api-docs) - [Api funding account summary response - Gravity Markets API Docs](#api-funding-account-summary-response-gravity-markets-api-docs) - [Api get latest lp snapshot request - Gravity Markets API Docs](#api-get-latest-lp-snapshot-request-gravity-markets-api-docs) - [Api get list reward epoch response - Gravity Markets API Docs](#api-get-list-reward-epoch-response-gravity-markets-api-docs) - [Api get lp config request - Gravity Markets API Docs](#api-get-lp-config-request-gravity-markets-api-docs) - [Api pre deposit check response - Gravity Markets API Docs](#api-pre-deposit-check-response-gravity-markets-api-docs) - [Api set derisk to maintenance margin ratio request - Gravity Markets API Docs](#api-set-derisk-to-maintenance-margin-ratio-request-gravity-markets-api-docs) - [Api settlement price - Gravity Markets API Docs](#api-settlement-price-gravity-markets-api-docs) - [Api settlement price request - Gravity Markets API Docs](#api-settlement-price-request-gravity-markets-api-docs) - [Api sub account trade aggregation request - Gravity Markets API Docs](#api-sub-account-trade-aggregation-request-gravity-markets-api-docs) - [Api sub account trade request - Gravity Markets API Docs](#api-sub-account-trade-request-gravity-markets-api-docs) - [Api ticker feed data v1 - Gravity Markets API Docs](#api-ticker-feed-data-v1-gravity-markets-api-docs) - [Api ticker response - Gravity Markets API Docs](#api-ticker-response-gravity-markets-api-docs) - [Api transfer response - Gravity Markets API Docs](#api-transfer-response-gravity-markets-api-docs) - [Api user category affinity score response - Gravity Markets API Docs](#api-user-category-affinity-score-response-gravity-markets-api-docs) - [Lp point - Gravity Markets API Docs](#lp-point-gravity-markets-api-docs) - [Margin tier response - Gravity Markets API Docs](#margin-tier-response-gravity-markets-api-docs) - [Orderbook level - Gravity Markets API Docs](#orderbook-level-gravity-markets-api-docs) - [Margin type - Gravity Markets API Docs](#margin-type-gravity-markets-api-docs) - [Position margin type - Gravity Markets API Docs](#position-margin-type-gravity-markets-api-docs) - [Jsonrpc request - Gravity Markets API Docs](#jsonrpc-request-gravity-markets-api-docs) - [Lp snapshot - Gravity Markets API Docs](#lp-snapshot-gravity-markets-api-docs) - [Mini ticker - Gravity Markets API Docs](#mini-ticker-gravity-markets-api-docs) - [Order status - Gravity Markets API Docs](#order-status-gravity-markets-api-docs) - [Order leg - Gravity Markets API Docs](#order-leg-gravity-markets-api-docs) - [Api get all instruments response - Gravity Markets API Docs](#api-get-all-instruments-response-gravity-markets-api-docs) - [Api get margin tiers response - Gravity Markets API Docs](#api-get-margin-tiers-response-gravity-markets-api-docs) - [Api transfer history request - Gravity Markets API Docs](#api-transfer-history-request-gravity-markets-api-docs) - [Api vault burn tokens request - Gravity Markets API Docs](#api-vault-burn-tokens-request-gravity-markets-api-docs) - [Api vault invest request - Gravity Markets API Docs](#api-vault-invest-request-gravity-markets-api-docs) - [Api vault investor history - Gravity Markets API Docs](#api-vault-investor-history-gravity-markets-api-docs) - [Asset margin tier response - Gravity Markets API Docs](#asset-margin-tier-response-gravity-markets-api-docs) - [Api get lp info request - Gravity Markets API Docs](#api-get-lp-info-request-gravity-markets-api-docs) - [Api get lp leaderboard request - Gravity Markets API Docs](#api-get-lp-leaderboard-request-gravity-markets-api-docs) - [Api get lp point request - Gravity Markets API Docs](#api-get-lp-point-request-gravity-markets-api-docs) - [Api orderbook levels response - Gravity Markets API Docs](#api-orderbook-levels-response-gravity-markets-api-docs) - [Api vault redeem request - Gravity Markets API Docs](#api-vault-redeem-request-gravity-markets-api-docs) - [Api withdrawal request - Gravity Markets API Docs](#api-withdrawal-request-gravity-markets-api-docs) - [Initial leverage result - Gravity Markets API Docs](#initial-leverage-result-gravity-markets-api-docs) - [Order reject reason - Gravity Markets API Docs](#order-reject-reason-gravity-markets-api-docs) - [Query get list epoch request - Gravity Markets API Docs](#query-get-list-epoch-request-gravity-markets-api-docs) - [Query main account leaderboard order by - Gravity Markets API Docs](#query-main-account-leaderboard-order-by-gravity-markets-api-docs) - [Query find epoch request - Gravity Markets API Docs](#query-find-epoch-request-gravity-markets-api-docs) - [Reward epoch status - Gravity Markets API Docs](#reward-epoch-status-gravity-markets-api-docs) - [Reward program type - Gravity Markets API Docs](#reward-program-type-gravity-markets-api-docs) - [Source - Gravity Markets API Docs](#source-gravity-markets-api-docs) - [Spot balance - Gravity Markets API Docs](#spot-balance-gravity-markets-api-docs) - [Stream reference - Gravity Markets API Docs](#stream-reference-gravity-markets-api-docs) - [Api pre deposit check request - Gravity Markets API Docs](#api-pre-deposit-check-request-gravity-markets-api-docs) - [Api query vault manager investor history response - Gravity Markets API Docs](#api-query-vault-manager-investor-history-response-gravity-markets-api-docs) - [Api set sub account position margin config request - Gravity Markets API Docs](#api-set-sub-account-position-margin-config-request-gravity-markets-api-docs) - [Api settlement price response - Gravity Markets API Docs](#api-settlement-price-response-gravity-markets-api-docs) - [Api trade history response - Gravity Markets API Docs](#api-trade-history-response-gravity-markets-api-docs) - [Orderbook levels - Gravity Markets API Docs](#orderbook-levels-gravity-markets-api-docs) - [Sub account trade interval - Gravity Markets API Docs](#sub-account-trade-interval-gravity-markets-api-docs) - [Signature - Gravity Markets API Docs](#signature-gravity-markets-api-docs) - [Session information - Gravity Markets API Docs](#session-information-gravity-markets-api-docs) - [Risk bracket - Gravity Markets API Docs](#risk-bracket-gravity-markets-api-docs) - [Time interval - Gravity Markets API Docs](#time-interval-gravity-markets-api-docs) - [Trader metric - Gravity Markets API Docs](#trader-metric-gravity-markets-api-docs) - [Api get filtered instruments response - Gravity Markets API Docs](#api-get-filtered-instruments-response-gravity-markets-api-docs) - [Api get list epoch badge response - Gravity Markets API Docs](#api-get-list-epoch-badge-response-gravity-markets-api-docs) - [Api trade response - Gravity Markets API Docs](#api-trade-response-gravity-markets-api-docs) - [Api transfer request - Gravity Markets API Docs](#api-transfer-request-gravity-markets-api-docs) - [Api vault investor summary response - Gravity Markets API Docs](#api-vault-investor-summary-response-gravity-markets-api-docs) - [Time in force - Gravity Markets API Docs](#time-in-force-gravity-markets-api-docs) - [Trader leaderboard user - Gravity Markets API Docs](#trader-leaderboard-user-gravity-markets-api-docs) - [Sub account trade aggregation - Gravity Markets API Docs](#sub-account-trade-aggregation-gravity-markets-api-docs) - [User category affinity score - Gravity Markets API Docs](#user-category-affinity-score-gravity-markets-api-docs) - [Vault type - Gravity Markets API Docs](#vault-type-gravity-markets-api-docs) - [Vault investor action - Gravity Markets API Docs](#vault-investor-action-gravity-markets-api-docs) - [Api get instrument response - Gravity Markets API Docs](#api-get-instrument-response-gravity-markets-api-docs) - [Api positions response - Gravity Markets API Docs](#api-positions-response-gravity-markets-api-docs) - [Api withdrawal history response - Gravity Markets API Docs](#api-withdrawal-history-response-gravity-markets-api-docs) - [Jsonrpc response - Gravity Markets API Docs](#jsonrpc-response-gravity-markets-api-docs) - [Query epoch badge point distribution request - Gravity Markets API Docs](#query-epoch-badge-point-distribution-request-gravity-markets-api-docs) - [Query epoch badge request - Gravity Markets API Docs](#query-epoch-badge-request-gravity-markets-api-docs) - [Positions - Gravity Markets API Docs](#positions-gravity-markets-api-docs) - [Query get latest lp snapshot response - Gravity Markets API Docs](#query-get-latest-lp-snapshot-response-gravity-markets-api-docs) - [Query get list epoch response - Gravity Markets API Docs](#query-get-list-epoch-response-gravity-markets-api-docs) - [Query find epoch response - Gravity Markets API Docs](#query-find-epoch-response-gravity-markets-api-docs) - [Reward epoch info - Gravity Markets API Docs](#reward-epoch-info-gravity-markets-api-docs) - [Venue - Gravity Markets API Docs](#venue-gravity-markets-api-docs) - [Ticker - Gravity Markets API Docs](#ticker-gravity-markets-api-docs) - [Trigger by - Gravity Markets API Docs](#trigger-by-gravity-markets-api-docs) - [Transfer type - Gravity Markets API Docs](#transfer-type-gravity-markets-api-docs) - [Transaction type - Gravity Markets API Docs](#transaction-type-gravity-markets-api-docs) - [Api order state response - Gravity Markets API Docs](#api-order-state-response-gravity-markets-api-docs) - [Api pre order check response - Gravity Markets API Docs](#api-pre-order-check-response-gravity-markets-api-docs) - [Epoch badge point distribution - Gravity Markets API Docs](#epoch-badge-point-distribution-gravity-markets-api-docs) - [Epoch badge - Gravity Markets API Docs](#epoch-badge-gravity-markets-api-docs) - [Cancel status feed - Gravity Markets API Docs](#cancel-status-feed-gravity-markets-api-docs) - [Fill - Gravity Markets API Docs](#fill-gravity-markets-api-docs) - [Funding account summary - Gravity Markets API Docs](#funding-account-summary-gravity-markets-api-docs) - [Trigger type - Gravity Markets API Docs](#trigger-type-gravity-markets-api-docs) - [User tracking event - Gravity Markets API Docs](#user-tracking-event-gravity-markets-api-docs) - [User vault category event pay load - Gravity Markets API Docs](#user-vault-category-event-pay-load-gravity-markets-api-docs) - [Vault investment - Gravity Markets API Docs](#vault-investment-gravity-markets-api-docs) - [Vault redemption - Gravity Markets API Docs](#vault-redemption-gravity-markets-api-docs) - [Ws list streams params - Gravity Markets API Docs](#ws-list-streams-params-gravity-markets-api-docs) - [Vault redemption req age category - Gravity Markets API Docs](#vault-redemption-req-age-category-gravity-markets-api-docs) - [Sub account trade - Gravity Markets API Docs](#sub-account-trade-gravity-markets-api-docs) - [Ws deposit feed selector v1 - Gravity Markets API Docs](#ws-deposit-feed-selector-v1-gravity-markets-api-docs) - [Ws order group feed selector v1 - Gravity Markets API Docs](#ws-order-group-feed-selector-v1-gravity-markets-api-docs) - [Ws cancel feed selector v1 - Gravity Markets API Docs](#ws-cancel-feed-selector-v1-gravity-markets-api-docs) - [Ws fill feed selector v1 - Gravity Markets API Docs](#ws-fill-feed-selector-v1-gravity-markets-api-docs) - [Ws order state feed selector v1 - Gravity Markets API Docs](#ws-order-state-feed-selector-v1-gravity-markets-api-docs) - [Ws order feed selector v1 - Gravity Markets API Docs](#ws-order-feed-selector-v1-gravity-markets-api-docs) - [Ws positions feed selector v1 - Gravity Markets API Docs](#ws-positions-feed-selector-v1-gravity-markets-api-docs) - [Ws request v1 - Gravity Markets API Docs](#ws-request-v1-gravity-markets-api-docs) - [Api transfer history response - Gravity Markets API Docs](#api-transfer-history-response-gravity-markets-api-docs) - [Ws mini ticker feed selector v1 - Gravity Markets API Docs](#ws-mini-ticker-feed-selector-v1-gravity-markets-api-docs) - [Api list aggregated account summary response - Gravity Markets API Docs](#api-list-aggregated-account-summary-response-gravity-markets-api-docs) - [Api vault view redemption queue response - Gravity Markets API Docs](#api-vault-view-redemption-queue-response-gravity-markets-api-docs) - [Order state - Gravity Markets API Docs](#order-state-gravity-markets-api-docs) - [Pre min redemptions - Gravity Markets API Docs](#pre-min-redemptions-gravity-markets-api-docs) - [Pre order check result - Gravity Markets API Docs](#pre-order-check-result-gravity-markets-api-docs) - [Tpsl order metadata - Gravity Markets API Docs](#tpsl-order-metadata-gravity-markets-api-docs) - [Trade - Gravity Markets API Docs](#trade-gravity-markets-api-docs) - [Ws orderbook levels feed selector v1 - Gravity Markets API Docs](#ws-orderbook-levels-feed-selector-v1-gravity-markets-api-docs) - [Ws response v1 - Gravity Markets API Docs](#ws-response-v1-gravity-markets-api-docs) - [Ws subscribe params - Gravity Markets API Docs](#ws-subscribe-params-gravity-markets-api-docs) - [Ws subscribe request v1 legacy - Gravity Markets API Docs](#ws-subscribe-request-v1-legacy-gravity-markets-api-docs) - [Ws unsubscribe result - Gravity Markets API Docs](#ws-unsubscribe-result-gravity-markets-api-docs) - [Ws unsubscribe all params - Gravity Markets API Docs](#ws-unsubscribe-all-params-gravity-markets-api-docs) - [Ws withdrawal feed selector v1 - Gravity Markets API Docs](#ws-withdrawal-feed-selector-v1-gravity-markets-api-docs) - [Ws subscribe result - Gravity Markets API Docs](#ws-subscribe-result-gravity-markets-api-docs) - [Ws subscribe response v1 legacy - Gravity Markets API Docs](#ws-subscribe-response-v1-legacy-gravity-markets-api-docs) - [Ws ticker feed selector v1 - Gravity Markets API Docs](#ws-ticker-feed-selector-v1-gravity-markets-api-docs) - [Claim ecosystem badge response - Gravity Markets API Docs](#claim-ecosystem-badge-response-gravity-markets-api-docs) - [Instrument - Gravity Markets API Docs](#instrument-gravity-markets-api-docs) - [Get claimable ecosystem badge response - Gravity Markets API Docs](#get-claimable-ecosystem-badge-response-gravity-markets-api-docs) - [Instrument display - Gravity Markets API Docs](#instrument-display-gravity-markets-api-docs) - [Vault redemption req view - Gravity Markets API Docs](#vault-redemption-req-view-gravity-markets-api-docs) - [Vault investor summary - Gravity Markets API Docs](#vault-investor-summary-gravity-markets-api-docs) - [Vault redemption request - Gravity Markets API Docs](#vault-redemption-request-gravity-markets-api-docs) - [Ws list streams result - Gravity Markets API Docs](#ws-list-streams-result-gravity-markets-api-docs) - [Ws transfer feed selector v1 - Gravity Markets API Docs](#ws-transfer-feed-selector-v1-gravity-markets-api-docs) - [Ws unsubscribe params - Gravity Markets API Docs](#ws-unsubscribe-params-gravity-markets-api-docs) - [Ws trade feed selector v1 - Gravity Markets API Docs](#ws-trade-feed-selector-v1-gravity-markets-api-docs) - [Snap funding account summary - Gravity Markets API Docs](#snap-funding-account-summary-gravity-markets-api-docs) - [Withdrawal history - Gravity Markets API Docs](#withdrawal-history-gravity-markets-api-docs) - [Withdrawal - Gravity Markets API Docs](#withdrawal-gravity-markets-api-docs) - [Ws candlestick feed data v1 - Gravity Markets API Docs](#ws-candlestick-feed-data-v1-gravity-markets-api-docs) - [Ws deposit feed data v1 - Gravity Markets API Docs](#ws-deposit-feed-data-v1-gravity-markets-api-docs) - [Ws mini ticker feed data v1 - Gravity Markets API Docs](#ws-mini-ticker-feed-data-v1-gravity-markets-api-docs) - [Ws order group feed data v1 - Gravity Markets API Docs](#ws-order-group-feed-data-v1-gravity-markets-api-docs) - [Order state feed - Gravity Markets API Docs](#order-state-feed-gravity-markets-api-docs) - [Query epoch badge response - Gravity Markets API Docs](#query-epoch-badge-response-gravity-markets-api-docs) - [Query epoch badge point distribution response - Gravity Markets API Docs](#query-epoch-badge-point-distribution-response-gravity-markets-api-docs) - [Ws ticker feed data v1 - Gravity Markets API Docs](#ws-ticker-feed-data-v1-gravity-markets-api-docs) - [Api latest snap sub accounts response - Gravity Markets API Docs](#api-latest-snap-sub-accounts-response-gravity-markets-api-docs) - [Transfer history - Gravity Markets API Docs](#transfer-history-gravity-markets-api-docs) - [Ws unsubscribe all result - Gravity Markets API Docs](#ws-unsubscribe-all-result-gravity-markets-api-docs) - [Api sub account history response - Gravity Markets API Docs](#api-sub-account-history-response-gravity-markets-api-docs) - [Api sub account summary response - Gravity Markets API Docs](#api-sub-account-summary-response-gravity-markets-api-docs) - [Ws candlestick feed selector v1 - Gravity Markets API Docs](#ws-candlestick-feed-selector-v1-gravity-markets-api-docs) - [Ws orderbook levels feed data v1 - Gravity Markets API Docs](#ws-orderbook-levels-feed-data-v1-gravity-markets-api-docs) - [Ws positions feed data v1 - Gravity Markets API Docs](#ws-positions-feed-data-v1-gravity-markets-api-docs) - [Ws trade feed data v1 - Gravity Markets API Docs](#ws-trade-feed-data-v1-gravity-markets-api-docs) - [Trigger order metadata - Gravity Markets API Docs](#trigger-order-metadata-gravity-markets-api-docs) - [Ws withdrawal feed data v1 - Gravity Markets API Docs](#ws-withdrawal-feed-data-v1-gravity-markets-api-docs) - [Order metadata - Gravity Markets API Docs](#order-metadata-gravity-markets-api-docs) - [Sub account - Gravity Markets API Docs](#sub-account-gravity-markets-api-docs) - [Transfer - Gravity Markets API Docs](#transfer-gravity-markets-api-docs) - [Ws cancel feed data v1 - Gravity Markets API Docs](#ws-cancel-feed-data-v1-gravity-markets-api-docs) - [Ws fill feed data v1 - Gravity Markets API Docs](#ws-fill-feed-data-v1-gravity-markets-api-docs) - [Ws transfer feed data v1 - Gravity Markets API Docs](#ws-transfer-feed-data-v1-gravity-markets-api-docs) - [Ws order state feed data v1 - Gravity Markets API Docs](#ws-order-state-feed-data-v1-gravity-markets-api-docs) - [Api cancel order response - Gravity Markets API Docs](#api-cancel-order-response-gravity-markets-api-docs) - [Api query trading performance request - Gravity Markets API Docs](#api-query-trading-performance-request-gravity-markets-api-docs) - [Api query trading performance response - Gravity Markets API Docs](#api-query-trading-performance-response-gravity-markets-api-docs) - [Api set initial leverage response - Gravity Markets API Docs](#api-set-initial-leverage-response-gravity-markets-api-docs) - [Api set sub account position margin config response - Gravity Markets API Docs](#api-set-sub-account-position-margin-config-response-gravity-markets-api-docs) - [Api socialized loss status response - Gravity Markets API Docs](#api-socialized-loss-status-response-gravity-markets-api-docs) - [Api sub account summary request - Gravity Markets API Docs](#api-sub-account-summary-request-gravity-markets-api-docs) - [Api bulk orders request - Gravity Markets API Docs](#api-bulk-orders-request-gravity-markets-api-docs) - [Api create bulk orders response - Gravity Markets API Docs](#api-create-bulk-orders-response-gravity-markets-api-docs) - [Api create order request - Gravity Markets API Docs](#api-create-order-request-gravity-markets-api-docs) - [Api create bulk orders request - Gravity Markets API Docs](#api-create-bulk-orders-request-gravity-markets-api-docs) - [Api create order response - Gravity Markets API Docs](#api-create-order-response-gravity-markets-api-docs) - [Api trade request - Gravity Markets API Docs](#api-trade-request-gravity-markets-api-docs) - [Api transfer ack - Gravity Markets API Docs](#api-transfer-ack-gravity-markets-api-docs) - [Api vault investor summary request - Gravity Markets API Docs](#api-vault-investor-summary-request-gravity-markets-api-docs) - [Api vault redeem cancel request - Gravity Markets API Docs](#api-vault-redeem-cancel-request-gravity-markets-api-docs) - [Approximate lp point - Gravity Markets API Docs](#approximate-lp-point-gravity-markets-api-docs) - [Asset max qty - Gravity Markets API Docs](#asset-max-qty-gravity-markets-api-docs) - [Bridge type - Gravity Markets API Docs](#bridge-type-gravity-markets-api-docs) - [Broker tag - Gravity Markets API Docs](#broker-tag-gravity-markets-api-docs) - [Cancel status - Gravity Markets API Docs](#cancel-status-gravity-markets-api-docs) - [Api bulk orders response - Gravity Markets API Docs](#api-bulk-orders-response-gravity-markets-api-docs) - [Api get order response - Gravity Markets API Docs](#api-get-order-response-gravity-markets-api-docs) - [Api open orders response - Gravity Markets API Docs](#api-open-orders-response-gravity-markets-api-docs) - [Api order history response - Gravity Markets API Docs](#api-order-history-response-gravity-markets-api-docs) - [Api pre order check request - Gravity Markets API Docs](#api-pre-order-check-request-gravity-markets-api-docs) - [Order - Gravity Markets API Docs](#order-gravity-markets-api-docs) - [Ws order feed data v1 - Gravity Markets API Docs](#ws-order-feed-data-v1-gravity-markets-api-docs) - [Market Data Websocket - Gravity Markets API Docs](#market-data-websocket-gravity-markets-api-docs) - [Market Data API - Gravity Markets API Docs](#market-data-api-gravity-markets-api-docs) - [Trading Websocket - Gravity Markets API Docs](#trading-websocket-gravity-markets-api-docs) - [Trading API - Gravity Markets API Docs](#trading-api-gravity-markets-api-docs) --- # Gravity Markets API Docs [Skip to content](https://api-docs.grvt.io/#overview) Overview ======== Connection Details ------------------ GRVT's services are hosted in AWS Tokyo (`ap-northeast-1`). For close partners with high trading volumes, we offer AWS PrivateLink. * * * Authentication -------------- GRVT supports API Authentication via session cookies, and API keys. You may follow the below steps to authenticate your requests. This section is conveniently inlined at every authenticated endpoint for your convenience. 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` * * * Order Creation -------------- ### Python SDK We have a [Python SDK](https://github.com/gravity-technologies/grvt-pysdk) available for usage. ([link](https://github.com/gravity-technologies/grvt-pysdk) ) `pip install grvt-pysdk` ### Step-by-Step Guide For specific information on how to _sign_ and _create_ an order, here's a step-by-step guide, using our Python SDK: * [Step 8-1: Fetch All Instruments](https://github.com/gravity-technologies/grvt-pysdk/blob/1a6eced13fa9fc06c4c78434a57a2cc274e88a35/tests/pysdk/test_grvt_raw_sync.py#L49-51) * [Step 8-2: Use Instrument Map in Order Signing](https://github.com/gravity-technologies/grvt-pysdk/blob/1a6eced13fa9fc06c4c78434a57a2cc274e88a35/tests/pysdk/test_grvt_raw_sync.py#L49-L55) * [Step 8-3: Create An Order](https://github.com/gravity-technologies/grvt-pysdk/blob/1a6eced13fa9fc06c4c78434a57a2cc274e88a35/tests/pysdk/test_raw_utils.py#L39-L62) * [Step 8-4: Sign Order](https://github.com/gravity-technologies/grvt-pysdk/blob/1a6eced13fa9fc06c4c78434a57a2cc274e88a35/src/pysdk/grvt_raw_signing.py#L69-L107) * [Step 8-5: Submit The Order](https://github.com/gravity-technologies/grvt-pysdk/blob/1a6eced13fa9fc06c4c78434a57a2cc274e88a35/tests/pysdk/test_grvt_raw_sync.py#L58) ### Chain IDs | **Network** | **Ethereum L1 Chain ID** | **GRVT L2 Chain ID** | | --- | --- | --- | | Sepolia (Dev) | 11155111 | 327 | | Sepolia (Stg) | 11155111 | 327 | | Sepolia (Testnet) | 11155111 | 326 | | Mainnet | 1 | 325 | * * * Encoding (Full vs Lite) ----------------------- For more versatile usage, all our APIs and Websockets are offered in `full` and `lite` variants. These variants are identical except for the JSON `field_name` used: * \`full\` uses the full field name, e.g. \`order\_id\` * \`lite\` uses the shortened field name, e.g. \`oi\` This is allows for users to trade off between simplicity and performance. * * * WebSocket Subscription ---------------------- ### Connecting to Authenticated Endpoints To subscribe to authenticated WebSocket streams (e.g., trade-related feeds), you must establish a WebSocket connection with both your `GRVT_COOKIE` and `X-Grvt-Account-Id` included. If your WebSocket client supports custom headers, set both as headers during the initial handshake. If custom headers are not supported, append `x_grvt_account_id` as a query parameter to the endpoint URL. #### Example (With Custom Headers): `wscat -c "wss://trades.dev.gravitymarkets.io/ws/full" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID"` #### Example (Without Custom Headers): `wscat -c "wss://trades.dev.gravitymarkets.io/ws/full?x_grvt_account_id=$GRVT_ACCOUNT_ID" \ -H "Cookie: $GRVT_COOKIE"` Full examples are available in the `Try it out` section of any `Trading Websocket` endpoint. In either case, once connected, you can send authenticated requests (e.g., `subscribe`) and interact with trade-related streams. ### Request Websocket subscriptions are initiated by sending a JSON RPC Request to the server. They have the following structure: * stream: The stream to subscribe to * feed: The list of feeds to subscribe to * method: The JSONRPC method. This is always \`"subscribe"\` * is\_full: Whether to subscribe to the \`full\` or \`lite\` feed. `{ "stream":"v1.book.s", "feed":["BTC_USDT_Perp@500-100-10"], "method":"subscribe", "is_full":true }` ### Response Upon subscribing, the server will respond with an initial JSON RPC Response. In the successful case, the following response will be returned: * stream: The stream that was subscribed to * subs: The list of subscriptions that were successfully subscribed to * unsubs: The list of subscriptions that were unsubscribed from `{ "stream":"v1.book.s", "subs":["BTC_USDT_Perp@500-100-10"], "unsubs":[] }` In the case of an error, the following response will be returned: * code: The error code * message: The error message * status: The HTTP status code `{ "code":3001, "message":"Stream handler not found", "status":400 }` ### Feed Structure For each WebSocket stream, users may subscribe to multiple feeds. Each stream defines its own feed structure, which is documented on the relevant page. However, they all share the same underlying structure. Firstly, feeds are broken down into `primary@secondary` selector pairs. * \`primary\` is used to determine the type of streaming data received. * \`secondary\` is used to determine the format/subtype of the streaming data received. When subscribing to the same `primary` selector again, the previous `secondary` selector will be replaced. eg. If previously subcribing to `"BTC_USDT_Perp@500-100-10"` and then subscribing to `"BTC_USDT_Perp@500-1-10"`, the subscribe response will return. `{ "stream":"v1.book.s", "subs":["BTC_USDT_Perp@500-1-10"], "unsubs":["BTC_USDT_Perp@500-100-10"] }` Within each `primary` or `secondary` selector, fields are separated by `-`, and ordered by the schema definition. ### Feed Data Stream The feed data stream will return a continuous stream of JSON objects. It has the following structure: * stream: The stream that the data is from * selector: The selector that the data is from * sequence\_number: This increases by one for each feed object published in the \`stream\`/\`selector\` pair. If the number \`jumps\`, it indicates data loss. * feed: The feed data object. Different for each stream. `{ "stream": "v1.book.s", "selector": "BTC_USDT_Perp@500-100-10", "sequence_number": "872634876", "feed": {} }` ### Event Time All feed data is published with an `event_time` timestamp (in unix nanoseconds). This timestamp is stamped by our core cluster, and is guaranteed to be consistent across all services and nodes. For All Streams, other than `MiniTicker` raw streams, event time is a globally consistent unique identifier for a message. ie. All connections via WebSocket/REST can agree that a message is the same via its `event_time`. ### Sequence Number Sequence Numbers are stamped at the gateway level. Which means that it only has relevance within a single websocket connection, and nothing more. It helps you to guarantee that you received the right number of `snapshot` updates, and did not miss any `delta` updates. * All snapshot payloads will have a sequence number of \`0\`. All delta payloads will have a sequence number of \`1+\`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in JSON RPC Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in JSON RPC Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by \`1\`. If it decreases, or increases by more than \`1\`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. * * * Back to top --- # API Setup Guide - Gravity Markets API Docs [Skip to content](https://api-docs.grvt.io/api_setup/#api-setup-guide) API Setup Guide =============== A short and simple API Setup guide to get you rolling quick! It assumes bare minimum knowledge about GRVT. So anyone can get through these steps. (ideally!) Step 1: Create Web2 Account --------------------------- Link: [https://testnet.grvt.io/exchange/sign-up](https://testnet.grvt.io/exchange/sign-up) ![create account](https://api-docs.grvt.io/assets/images/step1_image_correct.png) Follow the instructions to create your Personal Or Business Account. Step 2: Create Wallet --------------------- ![create wallet](https://api-docs.grvt.io/assets/images/step2_image1.png) ![create wallet](https://api-docs.grvt.io/assets/images/step2_image2.png) Follow the instructions to link your wallet to GRVT. You may link any of your existing wallets, or create a convenient web wallet on GRVT. Step 3: Create Web3 Accounts ---------------------------- GRVT has a two tier account structure. * Funding (main) Account: Used to bridge funds in and out of GRVT, acts as an administrative layer. * Trading (sub) Account: Used for derivative trading. ![create wallet](https://api-docs.grvt.io/assets/images/step3_image1.png) Follow the instructions to complete the setup. You have to sign on-chain to create your accounts, since this is the way we protect your self-custody. Step 4: Mint Tokens & Transfer ------------------------------ In testnet, we give you a convenient way to mint tokens, so that you can get up and testing quicker. Please remember to mint sufficient funds, and transfer some to your trading accounts. You may always revisit this link [https://testnet.grvt.io/exchange/deposit](https://testnet.grvt.io/exchange/deposit) to get more. ![mint](https://api-docs.grvt.io/assets/images/step4_image1.png) Step 5: Create API Key ---------------------- Finally we are getting to the heart of things! Create an API Key at this site [https://testnet.grvt.io/exchange/account/api-keys](https://testnet.grvt.io/exchange/account/api-keys) . ![Create API Key](https://api-docs.grvt.io/assets/images/step5_image1.png) ![Create API Key](https://api-docs.grvt.io/assets/images/step5_image2.png) ![Create API Key](https://api-docs.grvt.io/assets/images/step5_image3.png) Step 6: API Docs Auth --------------------- 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` The above section is inlined at every authenticated RPC & WS. Follow the instructions to authenticate using your API Key. Step 7: API Docs (Try It Out) ----------------------------- At every part of our API Docs, there's a working example you may use to test things out. You should be all set now! But don't hesitate to contact our team if you need any further help! ![Try It Out!](https://api-docs.grvt.io/assets/images/try_it_out.png) Step 8: Order Creation ---------------------- This is the most frequently asked question. ### Python SDK We have a [Python SDK](https://github.com/gravity-technologies/grvt-pysdk) available for usage. ([link](https://github.com/gravity-technologies/grvt-pysdk) ) `pip install grvt-pysdk` ### Step-by-Step Guide For specific information on how to _sign_ and _create an order_, here's a step-by-step guide, using our Python SDK: * [Step 8-1: Fetch All Instruments](https://github.com/gravity-technologies/grvt-pysdk/blob/1a6eced13fa9fc06c4c78434a57a2cc274e88a35/tests/pysdk/test_grvt_raw_sync.py#L49-51) * [Step 8-2: Use Instrument Map in Order Signing](https://github.com/gravity-technologies/grvt-pysdk/blob/1a6eced13fa9fc06c4c78434a57a2cc274e88a35/tests/pysdk/test_grvt_raw_sync.py#L49-L55) * [Step 8-3: Create An Order](https://github.com/gravity-technologies/grvt-pysdk/blob/1a6eced13fa9fc06c4c78434a57a2cc274e88a35/tests/pysdk/test_raw_utils.py#L39-L62) * [Step 8-4: Sign Order](https://github.com/gravity-technologies/grvt-pysdk/blob/1a6eced13fa9fc06c4c78434a57a2cc274e88a35/src/pysdk/grvt_raw_signing.py#L69-L107) * [Step 8-5: Submit The Order](https://github.com/gravity-technologies/grvt-pysdk/blob/1a6eced13fa9fc06c4c78434a57a2cc274e88a35/tests/pysdk/test_grvt_raw_sync.py#L58) ### Chain IDs | **Network** | **Ethereum L1 Chain ID** | **GRVT L2 Chain ID** | | --- | --- | --- | | Sepolia (Dev) | 11155111 | 327 | | Sepolia (Stg) | 11155111 | 327 | | Sepolia (Testnet) | 11155111 | 326 | | Mainnet | 1 | 325 | * * * Back to top --- # Auth - Gravity Markets API Docs Auth ==== Authentication In order to authenticate, you must first provision a valid API key. API keys can be provisioned via the GRVT UI. ```bash # These are the variables you will need to set manually GRVT_API_KEY="" GRVT_SUB_ACCOUNT_ID="" ``` Then, choose the environment you want to authenticate against. ```bash # dev GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/api_key/login" # stg 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 create a cookie that will be used to authenticate with our API Services. ```bash echo $GRVT_API_KEY echo $GRVT_SUB_ACCOUNT_ID echo $GRVT_AUTH_ENDPOINT GRVT_COOKIE=$( curl $GRVT_AUTH_ENDPOINT \ -H 'Content-Type: application/json' \ -H 'Cookie: rm=true;' \ -d "{ \"api_key\": \"$GRVT_API_KEY\" }" \ -s -i \ | grep -i 'set-cookie:' \ | grep -o 'gravity=[^;]*' ); echo $GRVT_COOKIE ``` Back to top --- # Builder Integration - Gravity Markets API Docs [Skip to content](https://api-docs.grvt.io/builder_codes/#builder-integration-guide) Builder Integration Guide ========================= Overview -------- This guide explains how to integrate your application with GRVT and enable trading on behalf of your users. Integration steps ----------------- ### 1\. Connect User Wallet ### 2\. Authorize Builder Choose the environment you want to authenticate against. `# dev GRVT_AUTH_ENDPOINT="https://edge.dev.gravitymarkets.io/auth/builder/authorize" # stg GRVT_AUTH_ENDPOINT="https://edge.staging.gravitymarkets.io/auth/builder/authorize" # testnet GRVT_AUTH_ENDPOINT="https://edge.testnet.grvt.io/auth/builder/authorize" # prod GRVT_AUTH_ENDPOINT="https://edge.grvt.io/auth/builder/authorize"` #### Request Parameters | "name" | Type | Required | Description | | --- | --- | --- | --- | | main\_account\_id | string | True | The Main Account ID of the user granting the authorization. | | builder\_account\_id | string | True | The Main Account ID of the Builder receiving the authorization. | | max\_futures\_fee\_rate | string | True | The maximum fee rate cap for Futures trades executed by this builder. The builder cannot charge fees exceeding this limit. | | max\_spot\_fee\_rate | string | True | The maximum fee rate cap for Spot trades executed by this builder. The builder cannot charge fees exceeding this limit. | | signature | Signature | True | The cryptographic signature authenticating this request. Must be signed by the private key associated with mainAccountID. See [Signing Payload](https://api-docs.grvt.io/builder_codes/#signing-payload)
section below for details. | | builder\_api\_key\_label | string | True | The user will see this label on the gravity api list UI. | | builder\_api\_key\_signer | string | True | An Ethereum public key pair that you generate for your user. This key can sign trades on behalf of your user across all sub-accounts they have. You can use the private key to sign trades on behalf of your user without sending Grvt the private key. | | builder\_api\_key\_permissions | string | True | Permissions as a sorted string (lowest bit to highest bit), separated by `&`:
\- Examples: `"Trade"`, `"Admin"`, `"Admin&Trade"`
\- Bit mapping: ADMIN=1, INTERNAL\_TRANSFER=2, EXTERNAL\_TRANSFER=3, WITHDRAW=4, VAULT\_INVESTOR=5, TRADE=6

**Please use TRADE for now** | #### Example Request `{ "main_account_id": "'0x...'", "builder_account_id": "'0x....'", "max_futures_fee_rate": "0.001", "max_spot_fee_rate": "0.0001", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "1" }, "builder_api_key_label": "superbuilder", "builder_api_key_signer": "0x....", "builder_api_key_permissions": "Admin&Trade" }` #### Signing Payload The signature must be created using EIP-712 typed data signing with the following structure: `{ "domain": { "chainId": 327, "name": "GRVT Exchange", "version": "0" }, "message": { "accountID": "'0x...'", "signer": "'0x....'", "permissions": "Trade", "builderAccountID": "'0x....'", "maxFutureFeeRate": 100, "maxSpotFeeRate": 10, "nonce": 1234567890, "expiration": 1697788800000000000 }, "primaryType": "AddAccountSignerWithBuilder", "types": { "EIP712Domain": [ { "name": "name", "type": "string" }, { "name": "version", "type": "string" }, { "name": "chainId", "type": "uint256" } ], "AddAccountSignerWithBuilder": [ { "name": "accountID", "type": "address" }, { "name": "signer", "type": "address" }, { "name": "permissions", "type": "string" }, { "name": "builderAccountID", "type": "address" }, { "name": "maxFutureFeeRate", "type": "uint32" }, { "name": "maxSpotFeeRate", "type": "uint32" }, { "name": "nonce", "type": "uint32" }, { "name": "expiration", "type": "int64" } ] } }` Chain ID The `chainId` value in the `domain` field must match the **GRVT L2 Chain ID** for your target environment. The example above uses `327` (Sepolia Dev/Stg). Refer to the **[Chain IDs](https://api-docs.grvt.io/#chain-ids) table** for all network-specific values. **Payload Fields:** | Field | Type | Description | | --- | --- | --- | | chainId | uint256 | The GRVT L2 Chain ID for the target network (in `domain` field). Refer to **[Chain IDs](https://api-docs.grvt.io/#chain-ids)
table** for network-specific values. | | accountID | address | The Main Account ID (Ethereum address) of the user granting authorization | | signer | address | The `builder_api_key_signer` - Ethereum public key that can sign trades on behalf of the user | | permissions | string | The `builder_api_key_permissions` as a sorted string (lowest bit to highest bit), separated by `&`:
\- Single permission: `"Admin"` or `"Trade"`
\- Multiple permissions: `"Admin&InternalTransfer"`, `"Admin&InternalTransfer&Trade"`
\- Bit mapping: ADMIN=1, INTERNAL\_TRANSFER=2, EXTERNAL\_TRANSFER=3, WITHDRAW=4, VAULT\_INVESTOR=5, TRADE=6
\- **Note:** Permissions are always sorted by bit position (e.g., `"Admin&Trade"`, never `"Trade&Admin"`) | | builderAccountID | address | The `builder_account_id` - Main Account ID of the Builder | | maxFutureFeeRate | uint32 | The `max_futures_fee_rate` - Maximum fee rate for Futures trades | | maxSpotFeeRate | uint32 | The `max_spot_fee_rate` - Maximum fee rate for Spot trades | | nonce | uint32 | Random value for signature deconflicting (0 to 4,294,967,295) | | expiration | int64 | Timestamp in unix nanoseconds when signature expires (max 30 days) | Permission String Format * Both the `permissions` field in the signing payload and the `builder_api_key_permissions` request parameter must use the **sorted string format** * When multiple permissions are granted, they must be sorted by bit position (lowest to highest) and joined with `&` * Examples: * Single permission: `"Trade"` or `"Admin"` * Multiple permissions: `"Admin&InternalTransfer"` (correct) vs ~`"InternalTransfer&Admin"`~ (incorrect - wrong order) * Combined: `"Admin&InternalTransfer&Trade"` * **Note:** The permission string format ensures a 1-to-1 mapping between the string and its bitmask value **Signing Process:** 1. The user must sign this EIP-712 typed data payload with their private key associated with `main_account_id` 2. The signing produces three values: `r`, `s`, and `v` 3. These values, along with the `signer` address, `nonce`, `expiration`, and `chain_id` are included in the `signature` field of the request Note The signature fields correspond to the [Signature](https://api-docs.grvt.io/schemas/signature) type used throughout the GRVT API. #### Example Response The API key is used for authentication in step 3. `{ "api_key": "abc....." }` ### 3\. Authenticate with API Key Use the `api_key` returned from step 2 to authenticate with the GRVT API and use trading functions. For detailed authentication instructions, please refer to the **[Authentication](https://api-docs.grvt.io/auth/) ** page. ### 4\. Manage Sub-Accounts Query available sub-accounts that your builder can trade on. **Reference:** **[Builder Codes - Get Sub Accounts](https://api-docs.grvt.io/trading_api/#get-sub-accounts) ** ### 5\. Execute Trades Your builder can now execute trades on all authorized sub-accounts using the Trade permission and the `builder_api_signer` key pair from one of the sub accounts. **Reference:** **[Builder Codes - Trading on Behalf of Users](https://api-docs.grvt.io/trading_api/#create-order) ** Back to top --- # GRVT Strategies - Gravity Markets API Docs [Skip to content](https://api-docs.grvt.io/grvt_strategies/#grvt-strategies-api-usage-guide) GRVT Strategies: API Usage Guide ================================ Overview -------- This document is for strategy managers who want to programmatically monitor and fulfill strategy requirements using GRVT’s strategy-monitoring APIs. Endpoints referenced can be found [here](https://api-docs.grvt.io/trading_api/#vault) Strategy Creation ----------------- ### Step 1: Become a strategy manager To create a strategy: 1. Go to the **Invest** page and click **Become a Strategy Manager**. 2. You must invest a minimum of **1000 USDT** to activate your strategy. 3. Strategy creation is currently limited to **whitelisted accounts**. To request access, [fill out this form](https://forms.gle/qmt8oW61Kef8ouodA) . For more details, see the [Strategy Setup Guide](https://help.grvt.io/en/articles/11640733-strategy-setup-guide-how-to-configure-fees-redemptions-and-rewards-on-grvt) . ![create strategy](https://api-docs.grvt.io/assets/images/create_strategy.png) ### Step 2: Switch to strategy trading account and start trading. You would need to then switch to your strategy trading account. and the The UI (user center icon on top right) will show that you are now trading from a strategy. Strategy trading accounts function like regular trading accounts but with key restrictions: you can only `invest` into your own strategy from your funding account, `redeem` shares for USDT to your trading account, and internal/external transfers via the [Transfer API](https://api-docs.grvt.io/trading_api/#transfer_1) are not allowed. ![Switch strategy trading account](https://api-docs.grvt.io/assets/images/switch_strategy_trading_account.png) ### Step 3: Invest and redeem from your own strategy. You can invest and redeem from your own strategy. Investing allows you to add more capital to the strategy in exchange for shares, and redeeming allows you to redeem your own shares for USDT. ### Leverage Configuration * Strategy trading accounts are held to a fixed opening leverage ratio of 5x (i.e., position size can be no larger than 5x of total equity). * Like general trading accounts, liquidation occurs if the account's leverage ratio exceeds 100x (i.e., trading account sustains unrealized losses such that total equity falls under 0.01x of position size). ### Additional Margin Requirements Strategy trading accounts have an additional margin requirement equal to the total value of urgent redemptions. The value of the additional margin requirement from urgent redemption requests can be read from the [Sub-Account Summary API](https://api-docs.grvt.io/trading_api/#sub-account-summary) , via the `vault_im_additions` field. For example, if Strategy A has 100k USDT in equity and 80k USDT in initial margin, and 30k USDT in redemptions become "urgent", the margin requirement rises to 110k USDT. Since this exceeds total equity, Strategy A is limited to risk-reducing orders only. Delist Triggers --------------- GRVT delists strategies that fail to meet baseline standards of performance and/or care. Delisting is irreversible and happens in any of the following events: ### Automatic Delist Conditions 1. **Share price falls below US$0.10** _(notable trigger: liquidation)_ 2. **Forced redemption fails for 48 hours** Delisted strategies cannot receive investment, nor will they be able to update fields such as name, description, or redemption window. ### Avoiding Price-Triggered Delists We compute your Share Price as follows: `Share Price = Strategy Equity / Share Count` If at risk of a share price-based delist, you have the following options: * Burn your shares and reduce total share count via the [Burn API](https://api-docs.grvt.io/trading_api/#vault-burn-tokens) * Invest further in your strategy to raise strategy equity ### Avoiding Redemption-Triggered Delists Look at our [dedicated section](https://api-docs.grvt.io/grvt_strategies/#consequences-of-sustained-redemption-failure) for more details. Monitoring & Servicing Redemptions ---------------------------------- GRVT provides an automated redemption-queueing system which fulfills redemption requests sequentially upon sufficient balance being available. This approach means you need only ensure sufficient balance to serve redemptions, without manually tracking and fulfilling individual redemption requests. Investors (including you, the strategy manager) can create a redemption request via the [Redeem API](https://api-docs.grvt.io/trading_api/#vault-redeem) . ### Calculating Balance Available for Automated Redemption GRVT calculates a strategy's auto-redeemable balance as follows: `Auto-Redeemable Balance = Available Balance - (Auto Redemption Barrier * Initial Margin) where: Available Balance = Total Equity - Initial Margin - max(Unrealized PnL, 0) 0.8x <= Auto Redemption Barrier <= 2.0x` Intuitively, this balance is your strategy's equity in excess of initial margin requirements, buffering for unrealized losses and accounting for strategy-specific risk tolerance (in the form of the manager-defined auto redemption barrier – a larger barrier value is more conservative). On each price tick, GRVT considers the redemption request at the head of a strategy's redemption queue and executes it if the strategy's balance available for automated redemption is at least as large as that request's value. Redemption Queue - Priority Assignment -------------------------------------- Redemption Requests fall into 3 categories: **Urgent**, **Normal-Priority**, and **Pre-Minimum Age**. ### Urgent Redemption Requests * Requests are urgent if their age exceeds 90% of your pre-defined maximum redemption period * Urgent requests are always considered first, in FIFO order * For strategies with urgent redemption requests, the oldest urgent redemption gets treated as the head of the queue ### Normal-Priority Redemption Requests * Requests are normal-priority if they have not aged past the 90% threshold described above * Normal-priority requests are considered in FIFO order, unless the FIFO head's requested redemption size is at least 5x larger than that of the smallest normal-priority request #### Example To begin, assume all requests are normal-priority: **FIFO Ordering:** 1k → 50k → 100k → 20k → 10k → 25k **Priority Ordering:** 1k → 10k → 50k → 20k → 100k → 25k If, instead, the 1k and 50k requests were urgent, they would then be considered in FIFO order regardless of relative sizing: **Result:** 1k → 50k → 10k → 20k → 100k → 25k ### Pre-Minimum Age Redemption Requests * Requests are pre-minimum age if they are younger than your pre-defined minimum redemption period * We track these requests upon investors creating the request, but make you aware of them only when they age past the minimum required age Strategy Manager Responsibilities --------------------------------- GRVT's [Redemption Queue API](https://api-docs.grvt.io/trading_api/#vault-redemption-queue) lets you: * Track your strategy's redemption queue * Ensure that you have sufficient auto-redeemable balance to service redemption requests in your queue before they exceed their maximum redemption period ### What happens if requests age past the maximum redemption period? To ensure capital gets returned to investors where possible, GRVT applies **forced redemption** on any requests that exceed your stipulated redemption period. GRVT executes these requests for you even if you might have insufficient auto-redeemable balance (likely, given that the request failed to automatically redeem in the first place). **Important:** Forced redemptions will deplete a strategy's equity balance. ### Could forced redemptions place me at risk of liquidation? GRVT will not force redemptions if doing so would leave the strategy in negative available balance (calculated per the above formula), so as to avoid pushing distressed strategies into liquidation. At this point, both you and your investor would begin receiving recurring email and UI notifications that your strategy is defaulting on redemption requests. You would need to either: * Increase strategy equity (e.g., by investing further in your strategy, realizing profit on a position, etc.) * Reduce margin requirements (e.g., by closing a losing position) This would allow leverage to decrease sufficiently for GRVT to continue forcing redemptions. Our de-risking algorithm, when it becomes active, will automate this for you by bring you back to a healthy available balance (more details will become available following the launch of said de-risking algorithm). All redemption requests will still need to be serviced in the order specified. ### Consequences of Sustained Redemption Failure Leaving any given redemption request blocked on forced redemption for more than 48 hours would result in the strategy being delisted and unwound for maximum funds to be returned to shareholders. Strategy Permissions for Business accounts ------------------------------------------ We offer fine-grained permission-based access control for business accounts that would like to utilize this when interacting or creating strategies. ### A. Strategy Trading Account Permissions These permissions are used to manage strategies by strategy managers. 1. `Strategy Admin` (Same as Trading Admin) 2. Can trade 3. Can add and manage users 4. Can invest and redeem 5. Can burn shares 6. Can close and delist a strategy 7. Can create API keys **Note:** A Funding Admin is inherently a Strategy Admin as well. 1. `Trade` - Can trade 2. `Transfer` - Not used for strategies ### B. Funding Account Permissions These permissions are used to invest into strategies from the funding account. 1. `Funding Admin` 2. Can invest into strategies from funding and trading accounts 3. Can redeem from strategies 4. Can burn shares 5. `Internal Transfer`, `External Transfer`, `Withdraw` - Cannot interact with strategies 6. `Strategy Investor` - Can invest into strategies from the funding account Back to top --- # Ack - Gravity Markets API Docs Ack === [Ack](https://api-docs.grvt.io/schemas/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 | Back to top --- # Learn - Gravity Markets API Docs [Skip to content](https://api-docs.grvt.io/learn/#learn) Learn ===== INTRODUCTION ------------ ### **Getting Started** Performance meetssafety and privacy GRVT is a custodial centralized exchange powered by ZK(zero knowledge) technology. We are [first official Appchain on zkSync's Hyperchain](https://t.co/KlxIeo4VbS) and received an investment from [Matter Labs](https://matter-labs.io/) , the creators of zkSync. **Testnet** [https://testnet.grvt.io/](https://testnet.grvt.io/) **Mainnet** [https://grvt.io/](https://grvt.io/) ### **Architecture Overview** GRVT's hybrid exchange architecture overview GRVT adopts a hybrid architecture that matches and stores data off chain and provides smart contract level guarantees of their execution on chain. GRVT adopted this architecture to improve throughput by processing transactions off the Ethereum Mainnet. ![Architecture Overview](https://api-docs.grvt.io/assets/images/architecture_overview.png) #### Offchain All user actions are initially processed off-chain by GRVT servers. Only actions impacting user funds, such as trades or account creation, are eventually pushed on-chain by GRVT. Non-fund-related actions, like KYC, remain off-chain. The GRVT servers forward relevant user actions to the GRVT chain. Key user actions that are pushed on-chain include transactions processed by the following: * Matching Engine: Orders that are matched by the matching engine are sent on-chain * Risk Engine: Liquidations are sent to the chain * Account Management: Creation of entities such as trading accounts or addition of wallets that can use funds * Fund Management: Internal and external transfer of funds #### Onchain A subset of the off chain actions are pushed to the GRVT chain. These actions are then published as zero-knowledge proofs to verify off-chain transactions on Ethereum. * Trade Settlement: Matched orders are settled on chain * Risk Engine Validation: Liquidations are validated on chain as being fair based on smart contract logic * Account Management Validations: Account Management actions are validated on chain * Fund Management: Fund transfers are validated and settled on chain #### GRVT Native Deposit Contracts * **GRVTBridgeProxy** Contract address used for depositing native tokens: `0xE17aeD2fC55f4A876315376ffA49FE6358113a65` * **L1NativeTokenVault** Contract that holds the deposited funds: `0xbed1eb542f9a5aa6419ff3deb921a372681111f6` When you deposit native tokens through GRVT, you’ll interact with **GRVTBridgeProxy**, while your assets will ultimately be stored in the **L1NativeTokenVault**. * * * CORE CONCEPTS ------------- ### **Accounts and Users** #### Funding Account Funding accounts are the highest level on-chain identity in GRVT. The purpose of the funding account is primarily fund management. They process deposits, withdrawals, external Transfers to other funding accounts and internal transfers to linked trading accounts. #### Trading Account Each funding account can link to multiple trading accounts. To trade derivatives, you must transfer funds from your funding account to a specific trading account. ![Accounts and Users](https://api-docs.grvt.io/assets/images/accounts_and_users.png) #### Users In the case of **individual accounts**, each account has a maximum of one user. The user has access to all the linked trading accounts. In the case of **_business accounts_**, each account can have one or more users. User can have accessto the funding account and/or trading trading accounts separately depending on their permissions. ### **User Identifiers** One User, One Email, One Wallet ![User Identifiers](https://api-docs.grvt.io/assets/images/user_identifiers.png) In GRVT, each user must register both Web2 and Web3 credentials. **Web2 Credentials (Emails)** Each user must sign up via email with a password setup or Google/Microsoft OAuth. This grants access to non-trading features such as completing your KYC, referrals, and more. It also allows you to view your portfolio and positions. **Web3 Credentials (Wallets)** Each user must then register a wallet on GRVT to enable trading features. Only trades signed with registered wallets can be executed by our trading engine. Additionally, actions that affect the ownership of your assets, such as trading, require a registered wallet. | **Credential Type** | **Identifier (Sample)** | **Secret** | **Use Case** | | --- | --- | --- | --- | | **Web2** | email (e.g., [\[email protected\]](https://api-docs.grvt.io/cdn-cgi/l/email-protection)
) | password/OAuth | Read + Write (No Trading) | | **Web3** | public key (e.g., 0xb794f5ea0ba39494ce839613fffba74279579268) | private key | Own, Sign Trades | ### **Account Identifiers** The on-chain Funding AccountID matches the wallet address that created the account. Business accounts can have multiple users, each with their own wallet linked to the funding account. #### Individual Account Representation ![Individual Account](https://api-docs.grvt.io/assets/images/account_identifiers_1.png) #### Business Account Representation ![Business Account](https://api-docs.grvt.io/assets/images/account_identifiers_2.png) #### Funding Account Off-Chain Representation (Read + Write) | Off-Chain accountIDs | Off chain user email addresses | | --- | --- | | ACC:2aO9cE9kJkah16urpA7DQKPOEdx | [\[email protected\]](https://api-docs.grvt.io/cdn-cgi/l/email-protection) | | ACC:2aO9cE9kJkah16urpA7DQKPOFxk | [\[email protected\]](https://api-docs.grvt.io/cdn-cgi/l/email-protection) | | ACC:2aO9cE9kJkah16urajkDQKPOEdx | [\[email protected\]](https://api-docs.grvt.io/cdn-cgi/l/email-protection)
, [\[email protected\]](https://api-docs.grvt.io/cdn-cgi/l/email-protection) | #### Funding Account On-Chain Representation (Own) | On-Chain accountIDs | On-Chain user wallets | | --- | --- | | 0xb794f5ea0ba39494ce839613fffba74279579268 | 0xb794f5ea0ba39494ce839613fffba74279579268 | | 0xdB055877e6c13b6A6B25aBcAA29B393777dD0a73 | 0xdB055877e6c13b6A6B25aBcAA29B393777dD0a73 | | 0x40b38765696e3d5d8d9d834d8aad4bb6e418e489 | 0x40b38765696e3d5d8d9d834d8aad4bb6e418e489, 0xe92d1a43df510f82c66382592a047d288f85226f | ### **API Keys** API keys for programmatic trading API Keys are only registered at Trading Account level with `trade` only permissions. Each API key needs to be tagged to a valid Ethereum public address. #### How to authenticate using API keys? * You will receive a session token by [authenticating](https://api-docs.grvt.io/#authentication) against your API key. This session token must be used then used in your `read` and `write` requests. #### How to authorize transactions using API keys? * Each API key must be tagged to a valid Ethereum address. There are two ways of doing so * Input (Secure): You possess a [public/private key pair.](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/keys/) You provide the public address, while only you have access to the secret private key. * Generate (Convenient): The GRVT front-end client generates a public/private key pair in your browser and allows you to copy the secret private key. GRVT does not store the private key after it is generated. * The Secret Private key must be used to sign orders using EIP-712 signing method. ![API keys 1](https://api-docs.grvt.io/assets/images/learn_image1.png) #### Mapping of API Keys to Trading Accounts ![API keys 2](https://api-docs.grvt.io/assets/images/learn_image2.png) Learn more: [Video Explanation](https://www.youtube.com/watch?v=7T1sJWjqJUE) ### **PBAC for Business Accounts** Permission Based Access Control for Business Accounts #### Funding Account Permissions There are four permissions on a Business funding account. Only those with a Funding Admin role are able to assign permissions to others. | Permission | Permissions | | --- | --- | | Funding Admin | * **Highest permission in the exchange, that supersedes all other permissions**
* Can create Trading Accounts
* Can trigger actions need to meet a multi-signature threshold like adding users to funding account, or adding a withdrawal/transfer address | | Internal Transfer | * Can transfer funds from the Funding Account to associated Trading Accounts | | External Transfer | * Can transfer funds to other funding accounts within GRVT if these accounts are in the transfer address book | | Withdrawal | * Can withdraw funds to pre-approved Layer 1 wallets | #### Trading Account Permissions | Permission | Access | | --- | --- | | Trading Admin | * Can add users to their Trading Accounts.
* Inherits "Trade" and "Transfer" permissions | | Trade | * Can trade from the given Trading Account | | Transfer | Can internally transfer funds to Funding Account or other trading accounts within the same Business Account | ![PBAC for Business Accounts](https://api-docs.grvt.io/assets/images/pbac_for_business_accounts.png) Visual Representation of Permission Based Access Control for Business Accounts ### **Multi-signature Admin Operations** Multi-signature operations for Business Account Privileged operations on the Business Funding Account, like onboarding new users or adding withdrawal wallets, require multi-signature approvals. Only those with the `Funding Admin` roles are authorized to approve these actions. `Funding Admin` can set custom thresholds, such as ⅔ (indicating two out of three Admins must sign off on the action) for these approvals. #### Admin Operations 1. Adding/editing permissions of users the `Funding Account` 2. Setting a new multi-sig threshold 3. Adding/Removing eligible wallets in the Withdrawal Address Book for withdrawals 4. Adding/Removing funding account addresses in the Transfer Address Book for external transfers ![Admin Operations](https://api-docs.grvt.io/assets/images/admin_operations.png) * * * HELP CENTER ----------- ### [Contact Support](https://help.grvt.io/en/) Back to top --- # Ack response - Gravity Markets API Docs Ack response ============ [AckResponse](https://api-docs.grvt.io/schemas/ack_response) 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](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api add isolated position margin response - Gravity Markets API Docs Api add isolated position margin response ========================================= [ApiAddIsolatedPositionMarginResponse](https://api-docs.grvt.io/schemas/api_add_isolated_position_margin_response) The response to add margin to a isolated position | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | success
`s` | boolean | True | Whether the margin mode and leverage was set successfully | Back to top --- # Aggregated account summary - Gravity Markets API Docs Aggregated account summary ========================== [AggregatedAccountSummary](https://api-docs.grvt.io/schemas/aggregated_account_summary) | 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 | | vault\_investments
`vi` | \[VaultInvestment\] | True | The list of vault investments held by this main account | | total\_sub\_account\_balance
`ts` | string | True | Deprecated: Use totalSubAccountEquity instead | | total\_sub\_account\_equity
`ts1` | string | True | Total equity of the sub accounts, denominated in USD | | total\_vault\_investments\_balance
`tv` | string | True | Total amount of the vault investments, denominated in USD | | total\_sub\_account\_available\_balance
`ts2` | string | True | Total available balance of the main account, denominated in USD | | total\_usd\_notional\_invested
`tu` | string | True | Total entry (initial investment) amount of the open investments, denominated in USD | [SpotBalance](https://api-docs.grvt.io/schemas/spot_balance) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | currency
`c` | string | 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`) | [VaultInvestment](https://api-docs.grvt.io/schemas/vault_investment) Summarizes a vault investment held by a funding account | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_id
`vi` | string | True | The trading account ID of the vault invested in. | | num\_lp\_tokens
`nl` | string | True | The number of shares held by the investor. | | share\_price
`sp` | string | True | The current share price (in USD) of this vault investment. | | usd\_notional\_invested
`un` | string | True | The USD notional invested in this vault investment. | Back to top --- # Api add isolated position margin request - Gravity Markets API Docs Api add isolated position margin request ======================================== [ApiAddIsolatedPositionMarginRequest](https://api-docs.grvt.io/schemas/api_add_isolated_position_margin_request) The request to add margin to a isolated position | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The sub account ID to add isolated margin in or remove margin from | | instrument
`i` | string | True | The instrument to add margin into, or remove margin from | | amount
`a` | string | True | The amount of margin to add to the position, positive to add, negative to remove, expressed in quote asset decimal units | | signature
`s` | Signature | True | The signature of this operation | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | Back to top --- # Api category affinity score request - Gravity Markets API Docs Api category affinity score request =================================== [ApiCategoryAffinityScoreRequest](https://api-docs.grvt.io/schemas/api_category_affinity_score_request) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | start\_time
`st` | string | True | The start time of query. Can leave empty to query from the beginning | | end\_time
`et` | string | True | The end time of query. Can leave empty to query until now | Back to top --- # Api cancel all orders response - Gravity Markets API Docs Api cancel all orders response ============================== [ApiCancelAllOrdersResponse](https://api-docs.grvt.io/schemas/api_cancel_all_orders_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | integer | True | The number of orders cancelled | Back to top --- # Api builder fill history request - Gravity Markets API Docs Api builder fill history request ================================ [ApiBuilderFillHistoryRequest](https://api-docs.grvt.io/schemas/api_builder_fill_history_request) The request to get the historical builder trade of a builder 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 | | --- | --- | --- | --- | | 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
`c` | string | False
`''` | The cursor to indicate when to start the next query from | Back to top --- # Api cancel on disconnect request - Gravity Markets API Docs Api cancel on disconnect request ================================ [ApiCancelOnDisconnectRequest](https://api-docs.grvt.io/schemas/api_cancel_on_disconnect_request) 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 | Back to top --- # Api cancel order request - Gravity Markets API Docs Api cancel order request ======================== [ApiCancelOrderRequest](https://api-docs.grvt.io/schemas/api_cancel_order_request) 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_id`s 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. | Back to top --- # Api authorized builder - Gravity Markets API Docs Api authorized builder ====================== [ApiAuthorizedBuilder](https://api-docs.grvt.io/schemas/api_authorized_builder) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | builder\_account\_id
`ba` | string | True | The main account ID of the builder | | max\_futures\_fee\_rate
`mf` | string | True | The maximum fee rate for the authorized builder | | max\_spot\_fee\_rate
`ms` | string | True | The maximum fee rate for the authorized builder | Back to top --- # Api get all initial leverage request - Gravity Markets API Docs Api get all initial leverage request ==================================== [ApiGetAllInitialLeverageRequest](https://api-docs.grvt.io/schemas/api_get_all_initial_leverage_request) 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 | Back to top --- # Api deposit history request - Gravity Markets API Docs Api deposit history request =========================== [ApiDepositHistoryRequest](https://api-docs.grvt.io/schemas/api_deposit_history_request) The request to get the historical deposits of an account The history is returned in reverse chronological order Both finalized and pending deposits are returned, and pending deposits are indicated by an empty `confirmedTime` field. 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` | \[string\] | 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. | Back to top --- # Api drop client ws request - Gravity Markets API Docs Api drop client ws request ========================== [ApiDropClientWsRequest](https://api-docs.grvt.io/schemas/api_drop_client_ws_request) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | main\_account\_id
`ma` | string | True | | Back to top --- # Api drop client ws response - Gravity Markets API Docs Api drop client ws response =========================== [ApiDropClientWsResponse](https://api-docs.grvt.io/schemas/api_drop_client_ws_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | num\_dropped
`nd` | integer | True | | Back to top --- # Api cancel all orders request - Gravity Markets API Docs Api cancel all orders request ============================= [ApiCancelAllOrdersRequest](https://api-docs.grvt.io/schemas/api_cancel_all_orders_request) 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` | \[string\] | 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` | \[string\] | False
`all` | The quote filter to apply. If nil, this defaults to all quotes. Otherwise, only entries matching the filter will be cancelled | [Kind](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api authorize builder request - Gravity Markets API Docs Api authorize builder request ============================= [ApiAuthorizeBuilderRequest](https://api-docs.grvt.io/schemas/api_authorize_builder_request) Authorizes a specific Builder to execute transactions on behalf of the Main Account. This endpoint acts as an **upsert** operation: \- **New Authorization**: If the builder is not currently authorized, a new record is created. \- **Update Limit**: If the builder is already authorized, this request updates the `maxFuturesFeeRate` and `maxSpotFeeRate` to the new values provided. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | main\_account\_id
`ma` | string | True | The Main Account ID of the user granting the authorization. | | builder\_account\_id
`ba` | string | True | The Main Account ID of the Builder receiving the authorization. | | max\_futures\_fee\_rate
`mf` | string | True | The maximum fee rate cap for **Futures** trades executed by this builder. The builder cannot charge fees exceeding this limit. | | max\_spot\_fee\_rate
`ms` | string | True | The maximum fee rate cap for **Spot** trades executed by this builder. The builder cannot charge fees exceeding this limit. | | signature
`s` | Signature | True | The cryptographic signature authenticating this request. Must be signed by the private key associated with `mainAccountID`. | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | Back to top --- # Api funding rate - Gravity Markets API Docs Api funding rate ================ [ApiFundingRate](https://api-docs.grvt.io/schemas/api_funding_rate) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | funding\_rate
`fr` | string | True | The funding rate of the instrument, expressed in percentage points | | funding\_time
`ft` | string | True | The funding timestamp of the funding rate, expressed in unix nanoseconds | | mark\_price
`mp` | string | True | The mark price of the instrument at funding timestamp, expressed in `9` decimals | | funding\_rate\_8\_h\_avg
`fr1` | string | True | Deprecated: Refer to `funding_rate` instead. Will be removed in a future release. | | funding\_interval\_hours
`fi` | integer | True | Funding interval in hours (e.g. 1/4/8/etc). | Back to top --- # Api get all instruments request - Gravity Markets API Docs Api get all instruments request =============================== [ApiGetAllInstrumentsRequest](https://api-docs.grvt.io/schemas/api_get_all_instruments_request) Fetch all instruments | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | is\_active
`ia` | boolean | False
`false` | Fetch only active instruments | Back to top --- # Api builder fill history response - Gravity Markets API Docs Api builder fill history response ================================= [ApiBuilderFillHistoryResponse](https://api-docs.grvt.io/schemas/api_builder_fill_history_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[BuilderFillHistory\] | True | The builder fill history matching the request builder account | | next
`n` | string | False
`''` | The cursor to indicate when to start the next query from | [BuilderFillHistory](https://api-docs.grvt.io/schemas/builder_fill_history) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | True | Time at which the event was emitted in unix nanoseconds | | off\_chain\_account\_id
`oc` | string | True | The off chain account id | | 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 | | fee\_rate
`fr` | string | True | Builder fee percentage charged for this order. referred to Order.builder builderFee | | fee
`f` | string | True | The builder fee paid on the trade, expressed in quote asset decimal unit. referred to Trade.builderFee | Back to top --- # Api candlestick response - Gravity Markets API Docs Api candlestick response ======================== [ApiCandlestickResponse](https://api-docs.grvt.io/schemas/api_candlestick_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[Candlestick\] | True | The candlestick result set for given interval | | next
`n` | string | False
`''` | The cursor to indicate when to start the next query from | [Candlestick](https://api-docs.grvt.io/schemas/candlestick) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | open\_time
`ot` | string | True | Open time of kline bar in unix nanoseconds | | close\_time
`ct` | string | True | Close time of kline bar in unix nanosecond | | open
`o` | string | True | The open price, expressed in underlying currency resolution units | | close
`c` | string | True | The close price, expressed in underlying currency resolution units | | high
`h` | string | True | The high price, expressed in underlying currency resolution units | | low
`l` | string | True | The low price, expressed in underlying currency resolution units | | volume\_b
`vb` | string | True | The underlying volume transacted, expressed in base asset decimal units | | volume\_q
`vq` | string | True | The quote volume transacted, expressed in quote asset decimal units | | trades
`t` | integer | True | The number of trades transacted | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | Back to top --- # Api deposit history response - Gravity Markets API Docs Api deposit history response ============================ [ApiDepositHistoryResponse](https://api-docs.grvt.io/schemas/api_deposit_history_response) | 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](https://api-docs.grvt.io/schemas/deposit_history) | 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` | string | 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, empty if the deposit is pending. | | from\_address
`fa` | string | True | The address of the sender | Back to top --- # Api category affinity score response - Gravity Markets API Docs Api category affinity score response ==================================== [ApiCategoryAffinityScoreResponse](https://api-docs.grvt.io/schemas/api_category_affinity_score_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[UserCategoryAffinityScore\] | True | The list of categoryAffinities score | [UserCategoryAffinityScore](https://api-docs.grvt.io/schemas/user_category_affinity_score) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_id
`ai` | string | True | The off chain account id | | category\_id
`ci` | string | True | target category | | affinity\_score
`as` | number | True | affinity score | Back to top --- # Api get currency request - Gravity Markets API Docs Api get currency request ======================== [ApiGetCurrencyRequest](https://api-docs.grvt.io/schemas/api_get_currency_request) Fetch all currencies | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | | | | | Back to top --- # Api get ecosystem leaderboard request - Gravity Markets API Docs Api get ecosystem leaderboard request ===================================== [ApiGetEcosystemLeaderboardRequest](https://api-docs.grvt.io/schemas/api_get_ecosystem_leaderboard_request) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | calculate\_from
`cf` | string | True | Start time of the epoch - phase | | limit
`l` | integer | True | The number of accounts to return | Back to top --- # Api aggregated account summary response - Gravity Markets API Docs Api aggregated account summary response ======================================= [ApiAggregatedAccountSummaryResponse](https://api-docs.grvt.io/schemas/api_aggregated_account_summary_response) 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](https://api-docs.grvt.io/schemas/aggregated_account_summary) | 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 | | vault\_investments
`vi` | \[VaultInvestment\] | True | The list of vault investments held by this main account | | total\_sub\_account\_balance
`ts` | string | True | Deprecated: Use totalSubAccountEquity instead | | total\_sub\_account\_equity
`ts1` | string | True | Total equity of the sub accounts, denominated in USD | | total\_vault\_investments\_balance
`tv` | string | True | Total amount of the vault investments, denominated in USD | | total\_sub\_account\_available\_balance
`ts2` | string | True | Total available balance of the main account, denominated in USD | | total\_usd\_notional\_invested
`tu` | string | True | Total entry (initial investment) amount of the open investments, denominated in USD | [SpotBalance](https://api-docs.grvt.io/schemas/spot_balance) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | currency
`c` | string | 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`) | [VaultInvestment](https://api-docs.grvt.io/schemas/vault_investment) Summarizes a vault investment held by a funding account | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_id
`vi` | string | True | The trading account ID of the vault invested in. | | num\_lp\_tokens
`nl` | string | True | The number of shares held by the investor. | | share\_price
`sp` | string | True | The current share price (in USD) of this vault investment. | | usd\_notional\_invested
`un` | string | True | The USD notional invested in this vault investment. | Back to top --- # Api find ecosystem epoch metric response - Gravity Markets API Docs Api find ecosystem epoch metric response ======================================== [ApiFindEcosystemEpochMetricResponse](https://api-docs.grvt.io/schemas/api_find_ecosystem_epoch_metric_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | metric
`m` | EcosystemMetric | True | The epoch metric | | rank
`r` | integer | True | The rank of the account in the ecosystem | | total
`t` | integer | True | The total number of accounts in the ecosystem | | last\_calculated\_at
`lc` | string | True | The time when the ecosystem points were last calculated | | total\_direct\_invite\_count
`td` | integer | True | Direct invite count without relying on epochs | | total\_indirect\_invite\_count
`ti` | integer | True | Indirect invite count without relying on epochs | [EcosystemMetric](https://api-docs.grvt.io/schemas/ecosystem_metric) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | direct\_invite\_count
`di` | integer | True | Direct invite count | | indirect\_invite\_count
`ii` | integer | True | Indirect invite count | | direct\_invite\_trading\_volume
`di1` | string | True | Direct invite trading volume | | indirect\_invite\_trading\_volume
`ii1` | string | True | Indirect invite trading volume | | total\_point
`tp` | string | True | Total ecosystem point of this epoch/phase | Back to top --- # Api find ecosystem leaderboard response - Gravity Markets API Docs Api find ecosystem leaderboard response ======================================= [ApiFindEcosystemLeaderboardResponse](https://api-docs.grvt.io/schemas/api_find_ecosystem_leaderboard_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | users
`u` | \[EcosystemLeaderboardUser\] | True | The list of ecosystem leaderboard users | [EcosystemLeaderboardUser](https://api-docs.grvt.io/schemas/ecosystem_leaderboard_user) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_id
`ai` | string | True | The off chain account id | | rank
`r` | integer | True | The rank of the account in the ecosystem | | total\_point
`tp` | string | True | Total ecosystem point | | twitter\_username
`tu` | string | True | The twitter username of the account | Back to top --- # Api deposit request - Gravity Markets API Docs Api deposit request =================== [ApiDepositRequest](https://api-docs.grvt.io/schemas/api_deposit_request) GRVT runs on a ZKSync Hyperchain which settles directly onto Ethereum. To Deposit funds from your L1 wallet into a GRVT SubAccount, you will be required to submit a deposit transaction directly to Ethereum. GRVT's bridge verifier will scan Ethereum from time to time. Once it receives proof that your deposit has been confirmed on Ethereum, it will initiate the deposit process. This current payload is used for alpha testing only. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | to\_account\_id
`ta` | string | True | The main account to deposit into | | currency
`c` | Currency | True | The token currency to deposit | | num\_tokens
`nt` | string | True | The number of tokens to deposit, quoted in token\_currency decimals | [Currency](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api find trader epoch metric response - Gravity Markets API Docs Api find trader epoch metric response ===================================== [ApiFindTraderEpochMetricResponse](https://api-docs.grvt.io/schemas/api_find_trader_epoch_metric_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | metric
`m` | TraderMetric | True | Phase zero metric | | rank
`r` | integer | True | The rank of the account in the trader | | total
`t` | integer | True | The total number of accounts in the trader | | last\_calculated\_at
`lc` | string | True | The time when the trader points were last calculated | [TraderMetric](https://api-docs.grvt.io/schemas/trader_metric) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | total\_fee
`tf` | string | True | Total fee paid | | total\_point
`tp` | number | True | Total trader point of this epoch/phase | Back to top --- # Api find first epoch metric response - Gravity Markets API Docs Api find first epoch metric response ==================================== [ApiFindFirstEpochMetricResponse](https://api-docs.grvt.io/schemas/api_find_first_epoch_metric_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | phase\_zero\_metric
`pz` | EcosystemMetric | True | Phase zero metric | | phase\_one\_metric
`po` | EcosystemMetric | True | Phase one metric | | rank
`r` | integer | True | The rank of the account in the ecosystem | | total
`t` | integer | True | The total number of accounts in the ecosystem | | total\_point
`tp` | string | True | Total ecosystem point of the first epoch | | last\_calculated\_at
`lc` | string | True | The time when the ecosystem points were last calculated | [EcosystemMetric](https://api-docs.grvt.io/schemas/ecosystem_metric) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | direct\_invite\_count
`di` | integer | True | Direct invite count | | indirect\_invite\_count
`ii` | integer | True | Indirect invite count | | direct\_invite\_trading\_volume
`di1` | string | True | Direct invite trading volume | | indirect\_invite\_trading\_volume
`ii1` | string | True | Indirect invite trading volume | | total\_point
`tp` | string | True | Total ecosystem point of this epoch/phase | [EcosystemMetric](https://api-docs.grvt.io/schemas/ecosystem_metric) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | direct\_invite\_count
`di` | integer | True | Direct invite count | | indirect\_invite\_count
`ii` | integer | True | Indirect invite count | | direct\_invite\_trading\_volume
`di1` | string | True | Direct invite trading volume | | indirect\_invite\_trading\_volume
`ii1` | string | True | Indirect invite trading volume | | total\_point
`tp` | string | True | Total ecosystem point of this epoch/phase | Back to top --- # Api find trader leaderboard response - Gravity Markets API Docs Api find trader leaderboard response ==================================== [ApiFindTraderLeaderboardResponse](https://api-docs.grvt.io/schemas/api_find_trader_leaderboard_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | users
`u` | \[TraderLeaderboardUser\] | True | The list of trader leaderboard users | [TraderLeaderboardUser](https://api-docs.grvt.io/schemas/trader_leaderboard_user) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_id
`ai` | string | True | The off chain account id | | rank
`r` | integer | True | The rank of the account in the Trader | | total\_point
`tp` | number | True | Total Trader point | | twitter\_username
`tu` | string | True | The twitter username of the account | Back to top --- # Api funding payment history response - Gravity Markets API Docs Api funding payment history response ==================================== [ApiFundingPaymentHistoryResponse](https://api-docs.grvt.io/schemas/api_funding_payment_history_response) | 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](https://api-docs.grvt.io/schemas/funding_payment) | 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` | string | 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`. | Back to top --- # Api candlestick request - Gravity Markets API Docs Api candlestick request ======================= [ApiCandlestickRequest](https://api-docs.grvt.io/schemas/api_candlestick_request) Kline/Candlestick bars for an instrument. Klines are uniquely identified by their instrument, type, interval, and open time. 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 | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | interval
`i1` | CandlestickInterval | True | The interval of each candlestick | | type
`t` | CandlestickType | True | The type of candlestick data to retrieve | | start\_time
`st` | string | False
`0` | Start time of kline data in unix nanoseconds | | end\_time
`et` | string | False
`now()` | End time of kline data 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 query from | [CandlestickInterval](https://api-docs.grvt.io/schemas/candlestick_interval) | Value | Description | | --- | --- | | `CI_1_M` = 1 | 1 minute | | `CI_3_M` = 2 | 3 minutes | | `CI_5_M` = 3 | 5 minutes | | `CI_15_M` = 4 | 15 minutes | | `CI_30_M` = 5 | 30 minutes | | `CI_1_H` = 6 | 1 hour | | `CI_2_H` = 7 | 2 hour | | `CI_4_H` = 8 | 4 hour | | `CI_6_H` = 9 | 6 hour | | `CI_8_H` = 10 | 8 hour | | `CI_12_H` = 11 | 12 hour | | `CI_1_D` = 12 | 1 day | | `CI_3_D` = 13 | 3 days | | `CI_5_D` = 14 | 5 days | | `CI_1_W` = 15 | 1 week | | `CI_2_W` = 16 | 2 weeks | | `CI_3_W` = 17 | 3 weeks | | `CI_4_W` = 18 | 4 weeks | [CandlestickType](https://api-docs.grvt.io/schemas/candlestick_type) | Value | Description | | --- | --- | | `TRADE` = 1 | Tracks traded prices | | `MARK` = 2 | Tracks mark prices | | `INDEX` = 3 | Tracks index prices | | `MID` = 4 | Tracks book mid prices | Back to top --- # Api funding payment history request - Gravity Markets API Docs Api funding payment history request =================================== [ApiFundingPaymentHistoryRequest](https://api-docs.grvt.io/schemas/api_funding_payment_history_request) 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 | | 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` | \[string\] | 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` | \[string\] | False
`all` | The quote filter to apply. If nil, this defaults to all quotes. Otherwise, only entries matching the filter will be returned | [Kind](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api funding rate request - Gravity Markets API Docs Api funding rate request ======================== [ApiFundingRateRequest](https://api-docs.grvt.io/schemas/api_funding_rate_request) Lookup the historical funding rate of a perpetual future. 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 | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | start\_time
`st` | string | False
`0` | Start time of funding rate in unix nanoseconds | | end\_time
`et` | string | False
`now()` | End time of funding rate 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 query from | | agg\_type
`at` | FundingRateAggregationType | False
`'FUNDING_INTERVAL'` | Aggregation method for historical funding rate observations. Defaults to using the instrument-specific funding interval. | [FundingRateAggregationType](https://api-docs.grvt.io/schemas/funding_rate_aggregation_type) Specifies different methods of aggregating historical funding rates | Value | Description | | --- | --- | | `FUNDING_INTERVAL` = 1 | Default value -- one record returned per funding interval. Query instruments endpoint to learn funding interval of each instrument. | | `ONE_HOURLY` = 2 | Returns one record per hour -- normalizes all funding rates to 1h durations, so `fundingRate` value is cumulative and can exceed a funding interval's configured cap / floor. | | `FOUR_HOURLY` = 3 | Returns one record per 4 hours -- normalizes all funding rates to 4h durations, so `fundingRate` value is cumulative and can exceed a funding interval's configured cap / floor. | | `EIGHT_HOURLY` = 4 | Returns one record for eight hours -- normalizes all funding rates to 8h durations, so `fundingRate` value is cumulative and can exceed a funding interval's configured cap / floor. | Back to top --- # Api funding rate response - Gravity Markets API Docs Api funding rate response ========================= [ApiFundingRateResponse](https://api-docs.grvt.io/schemas/api_funding_rate_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[ApiFundingRate\] | True | The funding rate result set for given interval | | next
`n` | string | False
`''` | The cursor to indicate when to start the next query from | [ApiFundingRate](https://api-docs.grvt.io/schemas/api_funding_rate) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | funding\_rate
`fr` | string | True | The funding rate of the instrument, expressed in percentage points | | funding\_time
`ft` | string | True | The funding timestamp of the funding rate, expressed in unix nanoseconds | | mark\_price
`mp` | string | True | The mark price of the instrument at funding timestamp, expressed in `9` decimals | | funding\_rate\_8\_h\_avg
`fr1` | string | True | Deprecated: Refer to `funding_rate` instead. Will be removed in a future release. | | funding\_interval\_hours
`fi` | integer | True | Funding interval in hours (e.g. 1/4/8/etc). | Back to top --- # Api get ecosystem referral stat response - Gravity Markets API Docs Api get ecosystem referral stat response ======================================== [ApiGetEcosystemReferralStatResponse](https://api-docs.grvt.io/schemas/api_get_ecosystem_referral_stat_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | direct\_invite\_count
`di` | integer | True | Direct invite count | | indirect\_invite\_count
`ii` | integer | True | Indirect invite count | | direct\_invite\_trading\_volume
`di1` | string | True | Total volume traded by direct invites multiple by 1e9 | | indirect\_invite\_trading\_volume
`ii1` | string | True | Total volume traded by indirect invites multiple by 1e9 | Back to top --- # Api get instrument request - Gravity Markets API Docs Api get instrument request ========================== [ApiGetInstrumentRequest](https://api-docs.grvt.io/schemas/api_get_instrument_request) Fetch a single instrument by supplying the asset or instrument name | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | Back to top --- # Api fill history request - Gravity Markets API Docs Api fill history request ======================== [ApiFillHistoryRequest](https://api-docs.grvt.io/schemas/api_fill_history_request) 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` | \[string\] | 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` | \[string\] | 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](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api get currency response - Gravity Markets API Docs Api get currency response ========================= [ApiGetCurrencyResponse](https://api-docs.grvt.io/schemas/api_get_currency_response) The list of currencies | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[CurrencyDetail\] | True | The list of currencies | [CurrencyDetail](https://api-docs.grvt.io/schemas/currency_detail) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | id
`i` | integer | True | The integer value of the currency | | symbol
`s` | string | True | The name of the currency | | balance\_decimals
`bd` | integer | True | The balance decimals of the currency | | quantity\_multiplier
`qm` | string | True | The quantity multiplier of the currency | Back to top --- # Api get isolated position margin limits request - Gravity Markets API Docs Api get isolated position margin limits request =============================================== [ApiGetIsolatedPositionMarginLimitsRequest](https://api-docs.grvt.io/schemas/api_get_isolated_position_margin_limits_request) The request to get the max addable and removable amount for an isolated position | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The sub account ID to get the margin limits for | | instrument
`i` | string | True | The isolated position asset to get the margin limits for | Back to top --- # Api get authorized builders response - Gravity Markets API Docs Api get authorized builders response ==================================== [ApiGetAuthorizedBuildersResponse](https://api-docs.grvt.io/schemas/api_get_authorized_builders_response) Returns list of authorized builders and the associated fee | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | results
`r` | \[ApiAuthorizedBuilder\] | True | The list of authorized builders | [ApiAuthorizedBuilder](https://api-docs.grvt.io/schemas/api_authorized_builder) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | builder\_account\_id
`ba` | string | True | The main account ID of the builder | | max\_futures\_fee\_rate
`mf` | string | True | The maximum fee rate for the authorized builder | | max\_spot\_fee\_rate
`ms` | string | True | The maximum fee rate for the authorized builder | Back to top --- # Api get ecosystem leaderboard response - Gravity Markets API Docs Api get ecosystem leaderboard response ====================================== [ApiGetEcosystemLeaderboardResponse](https://api-docs.grvt.io/schemas/api_get_ecosystem_leaderboard_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | points
`p` | \[EcosystemPoint\] | True | The list of ecosystem points | [EcosystemPoint](https://api-docs.grvt.io/schemas/ecosystem_point) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_id
`ai` | string | True | The off chain account id | | main\_account\_id
`ma` | string | True | The main account id | | total\_point
`tp` | string | True | Total ecosystem point | | direct\_invite\_count
`di` | integer | True | Direct invite count | | indirect\_invite\_count
`ii` | integer | True | Indirect invite count | | direct\_invite\_trading\_volume
`di1` | string | True | Direct invite trading volume | | indirect\_invite\_trading\_volume
`ii1` | string | True | Indirect invite trading volume | | calculate\_at
`ca` | string | True | The time when the ecosystem point is calculated | | calculate\_from
`cf` | string | True | Start time of the epoch - phase | | calculate\_to
`ct` | string | True | End time of the epoch - phase | | rank
`r` | integer | True | The rank of the account in the ecosystem | | epoch
`e` | integer | True | The epoch number of the ecosystem point | | brokered\_trading\_volume
`bt` | string | True | Brokered trading volume | | brokered\_trading\_point
`bt1` | string | True | Brokered trading point | | referee\_kyc\_point
`rk` | string | True | Referee KYC point | | referrer\_kyc\_point
`rk1` | string | True | Referrer KYC point | Back to top --- # Api get isolated position margin limits response - Gravity Markets API Docs Api get isolated position margin limits response ================================================ [ApiGetIsolatedPositionMarginLimitsResponse](https://api-docs.grvt.io/schemas/api_get_isolated_position_margin_limits_response) The response to get the max addable and removable amount for an isolated position request | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The isolated position asset | | max\_addable\_amount
`ma` | string | True | The max addable amount that can be added to the isolated position, expressed in quote asset decimal units | | max\_removable\_amount
`mr` | string | True | The max removable amount that can be removed from the isolated position, expressed in quote asset decimal units | Back to top --- # Api get all initial leverage response - Gravity Markets API Docs Api get all initial leverage response ===================================== [ApiGetAllInitialLeverageResponse](https://api-docs.grvt.io/schemas/api_get_all_initial_leverage_response) 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](https://api-docs.grvt.io/schemas/initial_leverage_result) | 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 this instrument | | min\_leverage
`ml` | string | True | The min leverage user can set for this instrument | | max\_leverage
`ml1` | string | True | The max leverage user can set for this instrument | | margin\_type
`mt` | PositionMarginType | True | The margin type of this instrument | [PositionMarginType](https://api-docs.grvt.io/schemas/position_margin_type) | Value | Description | | --- | --- | | `ISOLATED` = 1 | Isolated Margin Mode: each position is allocated a fixed amount of collateral | | `CROSS` = 2 | Cross Margin Mode: uses all available funds in your account as collateral across all cross margin positions | Back to top --- # Api get filtered instruments request - Gravity Markets API Docs Api get filtered instruments request ==================================== [ApiGetFilteredInstrumentsRequest](https://api-docs.grvt.io/schemas/api_get_filtered_instruments_request) Fetch a list of instruments based on the filters provided | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | 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` | \[string\] | 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` | \[string\] | False
`all` | The quote filter to apply. If nil, this defaults to all quotes. Otherwise, only entries matching the filter will be returned | | is\_active
`ia` | boolean | False
`false` | Request for active instruments only | | limit
`l` | integer | False
`500` | The limit to query for. Defaults to 500; Max 100000 | [Kind](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api get list flat referral request - Gravity Markets API Docs Api get list flat referral request ================================== [ApiGetListFlatReferralRequest](https://api-docs.grvt.io/schemas/api_get_list_flat_referral_request) startTime and endTime are optional parameters. The semantics of these parameters are as follows: | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | referral\_id
`ri` | string | True | The off chain referrer account id to get all flat referrals | | start\_time
`st` | string | False
`0` | Optional. Start time in unix nanoseconds | | end\_time
`et` | string | False
`now()` | Optional. End time in unix nanoseconds | | account\_id
`ai` | string | True | The off chain account id to get all user's referrers | Back to top --- # Api get margin rules request - Gravity Markets API Docs Api get margin rules request ============================ [ApiGetMarginRulesRequest](https://api-docs.grvt.io/schemas/api_get_margin_rules_request) API request payload to get margin rules for a particular instrument | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The instrument to query margin rules for | Back to top --- # Api get order group request - Gravity Markets API Docs Api get order group request =========================== [ApiGetOrderGroupRequest](https://api-docs.grvt.io/schemas/api_get_order_group_request) Retrieves the grouping of non-cancelled, non-filled client orders for a given subaccount when the grouping exist. helping to identify TP/SL pairs or other order relationships within the account. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The subaccount ID for which the order groups should be retrieved. | Back to top --- # Api get sub accounts response - Gravity Markets API Docs Api get sub accounts response ============================= [ApiGetSubAccountsResponse](https://api-docs.grvt.io/schemas/api_get_sub_accounts_response) Response payload containing all sub-accounts accessible within the given auth session | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_ids
`sa` | \[string\] | True | List of sub-account IDs accessible to the session | Back to top --- # Api get verified ecosystem leaderboard request - Gravity Markets API Docs Api get verified ecosystem leaderboard request ============================================== [ApiGetVerifiedEcosystemLeaderboardRequest](https://api-docs.grvt.io/schemas/api_get_verified_ecosystem_leaderboard_request) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | calculate\_from
`cf` | string | True | Start time of the epoch | | completed\_kyc\_before
`ck` | string | True | Completed KYC before this time | Back to top --- # Api latest snap sub accounts request - Gravity Markets API Docs Api latest snap sub accounts request ==================================== [ApiLatestSnapSubAccountsRequest](https://api-docs.grvt.io/schemas/api_latest_snap_sub_accounts_request) The request to get the latest snapshot of list sub account | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_i\_ds
`sa` | \[string\] | True | The list of sub account ids to query | Back to top --- # Api get trader stat response - Gravity Markets API Docs Api get trader stat response ============================ [ApiGetTraderStatResponse](https://api-docs.grvt.io/schemas/api_get_trader_stat_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | total\_fee
`tf` | string | True | Total fee paid | Back to top --- # Api list aggregated account summary request - Gravity Markets API Docs Api list aggregated account summary request =========================================== [ApiListAggregatedAccountSummaryRequest](https://api-docs.grvt.io/schemas/api_list_aggregated_account_summary_request) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | main\_account\_ids
`ma` | \[unknown\] | True | The list of main account ID to request for | Back to top --- # Api get lp info response - Gravity Markets API Docs Api get lp info response ======================== [ApiGetLPInfoResponse](https://api-docs.grvt.io/schemas/api_get_lp_info_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | is\_lp\_maker
`il` | boolean | True | Is LP maker | | spread\_score\_value\_multiplier
`ss` | string | True | The spread score value multiplier | | depth\_score\_value\_multiplier
`ds` | string | True | The depth score value multiplier | | market\_share\_value\_multiplier
`ms` | string | True | The market share value multiplier | | underlying\_multiplier
`um` | string | True | Underlying multiplier | | market\_share\_multiplier
`ms1` | string | True | The market share multiplier, equal to the maker trading volume in the past 2 hours | | ask\_fast\_market\_multiplier
`af` | integer | True | Ask fast market multiplier | | bid\_fast\_market\_multiplier
`bf` | integer | True | Bid fast market multiplier | Back to top --- # Api get order request - Gravity Markets API Docs Api get order request ===================== [ApiGetOrderRequest](https://api-docs.grvt.io/schemas/api_get_order_request) 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` | Back to top --- # Api get user ecosystem point request - Gravity Markets API Docs Api get user ecosystem point request ==================================== [ApiGetUserEcosystemPointRequest](https://api-docs.grvt.io/schemas/api_get_user_ecosystem_point_request) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_id
`ai` | string | True | The off chain account id | | calculate\_from
`cf` | string | True | Start time of the epoch - phase | | include\_user\_rank
`iu` | boolean | True | Include user rank in the response | Back to top --- # Api mini ticker request - Gravity Markets API Docs Api mini ticker request ======================= [ApiMiniTickerRequest](https://api-docs.grvt.io/schemas/api_mini_ticker_request) Retrieves a single mini ticker value for a single instrument. Please do not use this to repeatedly poll for data -- a websocket subscription is much more performant, and useful. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | Back to top --- # Api order state request - Gravity Markets API Docs Api order state request ======================= [ApiOrderStateRequest](https://api-docs.grvt.io/schemas/api_order_state_request) Retrieve the order state 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` | Back to top --- # Api orderbook levels request - Gravity Markets API Docs Api orderbook levels request ============================ [ApiOrderbookLevelsRequest](https://api-docs.grvt.io/schemas/api_orderbook_levels_request) Retrieves aggregated price depth for a single instrument, with a maximum depth of 10 levels. Do not use this to poll for data -- a websocket subscription is much more performant, and useful. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | depth
`d` | integer | True | Depth of the order book to be retrieved (10, 50, 100, 500) | Back to top --- # Api query flat referral stat request - Gravity Markets API Docs Api query flat referral stat request ==================================== [ApiQueryFlatReferralStatRequest](https://api-docs.grvt.io/schemas/api_query_flat_referral_stat_request) Query flat referral stats | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_id
`ai` | string | True | The off chain account id to get referral stats | Back to top --- # Api query flat referral stat response - Gravity Markets API Docs Api query flat referral stat response ===================================== [ApiQueryFlatReferralStatResponse](https://api-docs.grvt.io/schemas/api_query_flat_referral_stat_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | direct\_invite\_count
`di` | integer | True | Direct invite count | | indirect\_invite\_count
`ii` | integer | True | Indirect invite count | Back to top --- # Api query vault manager investor history request - Gravity Markets API Docs Api query vault manager investor history request ================================================ [ApiQueryVaultManagerInvestorHistoryRequest](https://api-docs.grvt.io/schemas/api_query_vault_manager_investor_history_request) Request for the manager to retrieve the vault investor history for their vault | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_id
`vi` | string | True | The unique identifier of the vault to filter by | | only\_own\_investments
`oo` | boolean | True | Whether to only return investments made by the manager | | start\_time
`st` | string | False
`0` | Optional. Start time in unix nanoseconds | | end\_time
`et` | string | False
`now()` | Optional. End time in unix nanoseconds | Back to top --- # Api set derisk to maintenance margin ratio response - Gravity Markets API Docs Api set derisk to maintenance margin ratio response =================================================== [ApiSetDeriskToMaintenanceMarginRatioResponse](https://api-docs.grvt.io/schemas/api_set_derisk_to_maintenance_margin_ratio_response) The response to set the derisk margin to maintenance margin ratio of a sub account | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | success
`s` | boolean | True | Whether the derisk margin to maintenance margin ratio was set successfully | Back to top --- # Api resolve epoch ecosystem metric response - Gravity Markets API Docs Api resolve epoch ecosystem metric response =========================================== [ApiResolveEpochEcosystemMetricResponse](https://api-docs.grvt.io/schemas/api_resolve_epoch_ecosystem_metric_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | epoch\_name
`en` | string | True | The name of the epoch | | point
`p` | integer | True | Ecosystem points up to the most recently calculated time within this epoch | | last\_calculated\_time
`lc` | string | True | The time in unix nanoseconds when the ecosystem points were last calculated | Back to top --- # Api set initial leverage request - Gravity Markets API Docs Api set initial leverage request ================================ [ApiSetInitialLeverageRequest](https://api-docs.grvt.io/schemas/api_set_initial_leverage_request) 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 | Back to top --- # Api ticker request - Gravity Markets API Docs Api ticker request ================== [ApiTickerRequest](https://api-docs.grvt.io/schemas/api_ticker_request) Retrieves a single ticker value for a single instrument. Please do not use this to repeatedly poll for data -- a websocket subscription is much more performant, and useful. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | Back to top --- # Api fill history response - Gravity Markets API Docs Api fill history response ========================= [ApiFillHistoryResponse](https://api-docs.grvt.io/schemas/api_fill_history_response) | 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](https://api-docs.grvt.io/schemas/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 | | is\_liquidation
`il` | boolean | True | If the trade was a liquidation | | 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 | | builder
`b1` | string | True | The main account ID of the builder. referred to Order.builder | | builder\_fee\_rate
`bf` | string | True | Builder fee percentage charged for this order. referred to Order.builder builderFee | | builder\_fee
`bf1` | string | True | The builder fee paid on the trade, expressed in quote asset decimal unit. referred to Trade.builderFee | [Venue](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/broker_tag) 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 | Back to top --- # Api get latest lp snapshot response - Gravity Markets API Docs Api get latest lp snapshot response =================================== [ApiGetLatestLPSnapshotResponse](https://api-docs.grvt.io/schemas/api_get_latest_lp_snapshot_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | snapshot
`s` | ApproximateLPSnapshot | True | The latest LP snapshot | [ApproximateLPSnapshot](https://api-docs.grvt.io/schemas/approximate_lp_snapshot) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | main\_account\_id
`ma` | string | True | The main account id | | underlying\_multiplier
`um` | string | True | Underlying multiplier | | market\_share\_multiplier
`ms` | string | True | Market share multiplier | | bid\_fast\_market\_multiplier
`bf` | integer | True | Fast market multiplier | | ask\_fast\_market\_multiplier
`af` | integer | True | Fast market multiplier | | liquidity\_score
`ls` | string | True | Liquidity score | | calculate\_at
`ca` | string | True | The time when the snapshot was calculated | Back to top --- # Api get list flat referral response - Gravity Markets API Docs Api get list flat referral response =================================== [ApiGetListFlatReferralResponse](https://api-docs.grvt.io/schemas/api_get_list_flat_referral_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | flat\_referrals
`fr` | \[FlatReferral\] | True | The list of flat referrals | [FlatReferral](https://api-docs.grvt.io/schemas/flat_referral) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_id
`ai` | string | True | The off chain account id | | referrer\_id
`ri` | string | True | The off chain referrer account id | | referrer\_level
`rl` | integer | True | The referrer level; 1: direct referrer, 2: indirect referrer | | account\_create\_time
`ac` | string | True | The account creation time | | main\_account\_id
`ma` | string | True | The main account id | | referrer\_main\_account\_id
`rm` | string | True | The referrer main account id | | is\_business
`ib` | boolean | True | The account is a business account or not | | is\_kyc\_completed
`ik` | boolean | True | The account is KYC verified or not | | kyc\_completed\_at
`kc` | string | True | The KYC completed time | | kyc\_type
`kt` | string | True | The KYC type, can be 'individual' or 'business' | | kyc\_first\_completed\_at
`kf` | string | True | The first KYC completed time | Back to top --- # Api sub account history request - Gravity Markets API Docs Api sub account history request =============================== [ApiSubAccountHistoryRequest](https://api-docs.grvt.io/schemas/api_sub_account_history_request) 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 | Back to top --- # Api trade history request - Gravity Markets API Docs Api trade history request ========================= [ApiTradeHistoryRequest](https://api-docs.grvt.io/schemas/api_trade_history_request) Perform historical lookup of public trades in any given instrument. This endpoint offers public trading data, use the Trading APIs instead to query for your personalized trade tape. Only data from the last three months will be retained. 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 | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | 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 | Back to top --- # Api get lp config response - Gravity Markets API Docs Api get lp config response ========================== [ApiGetLPConfigResponse](https://api-docs.grvt.io/schemas/api_get_lp_config_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | spread\_score\_multiplier
`ss` | string | True | The spread score multiplier | | depth\_score\_multiplier
`ds` | string | True | The depth score multiplier | | market\_share\_multiplier
`ms` | string | True | The market share multiplier | | is\_lp\_maker
`il` | boolean | True | Is LP maker | Back to top --- # Api user category affinity score request - Gravity Markets API Docs Api user category affinity score request ======================================== [ApiUserCategoryAffinityScoreRequest](https://api-docs.grvt.io/schemas/api_user_category_affinity_score_request) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_id
`ai` | string | True | The off chain account id | | start\_time
`st` | string | True | The start time of query. Can leave empty to query from the beginning | | end\_time
`et` | string | True | The end time of query. Can leave empty to query until now | Back to top --- # Api get lp leaderboard response - Gravity Markets API Docs Api get lp leaderboard response =============================== [ApiGetLPLeaderboardResponse](https://api-docs.grvt.io/schemas/api_get_lp_leaderboard_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | points
`p` | \[ApproximateLPPoint\] | True | The list of LP points | [ApproximateLPPoint](https://api-docs.grvt.io/schemas/approximate_lp_point) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | off\_chain\_account\_id
`oc` | string | True | The off chain account id | | liquidity\_score
`ls` | string | True | Liquidity score | | rank
`r` | integer | True | The rank of user in the LP leaderboard | Back to top --- # Api get lp point response - Gravity Markets API Docs Api get lp point response ========================= [ApiGetLPPointResponse](https://api-docs.grvt.io/schemas/api_get_lp_point_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | point
`p` | LPPoint | True | LP points of user | | maker\_count
`mc` | integer | True | The number of maker | [LPPoint](https://api-docs.grvt.io/schemas/lp_point) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | main\_account\_id
`ma` | string | True | The main account id | | liquidity\_score
`ls` | string | True | Liquidity score | | rank
`r` | integer | True | The rank of user in the LP leaderboard | Back to top --- # Api get order group response - Gravity Markets API Docs Api get order group response ============================ [ApiGetOrderGroupResponse](https://api-docs.grvt.io/schemas/api_get_order_group_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[ClientOrderIDsByGroup\] | True | A list of client orders grouped by their associated order group.
Each entry in the list contains a `groupID` and the corresponding `clientOrderID`s
that belong to that group. | [ClientOrderIDsByGroup](https://api-docs.grvt.io/schemas/client_order_i_ds_by_group) Grouping for the client order id and their associated groups. This is used to define TP/SL pairs or other order groupings after loading the list of Open Orders. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | group\_id
`gi` | string | True | The group this order belongs to. It can be used to define TP/SL pairs or other order groupings | | client\_order\_id
`co` | \[string\] | True | List of client order IDs in the group | | sub\_account\_id
`sa` | string | True | The sub account ID that these orders belong to | Back to top --- # Api open orders request - Gravity Markets API Docs Api open orders request ======================= [ApiOpenOrdersRequest](https://api-docs.grvt.io/schemas/api_open_orders_request) | 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` | \[string\] | 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` | \[string\] | False
`all` | The quote filter to apply. If nil, this defaults to all quotes. Otherwise, only entries matching the filter will be returned | [Kind](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api positions request - Gravity Markets API Docs Api positions request ===================== [ApiPositionsRequest](https://api-docs.grvt.io/schemas/api_positions_request) 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` | \[string\] | 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` | \[string\] | False
`all` | The quote filter to apply. If nil, this defaults to all quotes. Otherwise, only entries matching the filter will be returned | [Kind](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api vault view redemption queue request - Gravity Markets API Docs Api vault view redemption queue request ======================================= [ApiVaultViewRedemptionQueueRequest](https://api-docs.grvt.io/schemas/api_vault_view_redemption_queue_request) Request payload for a vault manager to view the redemption queue for their vault. Fetches the redemption queue for a vault, ordered by descending priority. **Urgent** redemption requests, defined as having been pending >90% of the manager-defined maximum redemption period, have top priority (following insertion order). **Non-urgent** redemption requests are otherwise prioritized by insertion order, **unless** they are >5x the size of the smallest redemption request. E.g., If FIFO ordering (all non-urgent) is 1k -> 50k -> 100k -> 20k -> 10k -> 25k, then priority ordering is 1k -> 10k -> 50k -> 20k -> 100k -> 25k. Only displays redemption requests that are eligible for automated redemption, i.e., have been pending for the manager-defined minimum redemption period. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_id
`vi` | string | True | The unique identifier of the vault to fetch the redemption queue for. | Back to top --- # Approximate lp snapshot - Gravity Markets API Docs Approximate lp snapshot ======================= [ApproximateLPSnapshot](https://api-docs.grvt.io/schemas/approximate_lp_snapshot) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | main\_account\_id
`ma` | string | True | The main account id | | underlying\_multiplier
`um` | string | True | Underlying multiplier | | market\_share\_multiplier
`ms` | string | True | Market share multiplier | | bid\_fast\_market\_multiplier
`bf` | integer | True | Fast market multiplier | | ask\_fast\_market\_multiplier
`af` | integer | True | Fast market multiplier | | liquidity\_score
`ls` | string | True | Liquidity score | | calculate\_at
`ca` | string | True | The time when the snapshot was calculated | Back to top --- # Builder fill history - Gravity Markets API Docs Builder fill history ==================== [BuilderFillHistory](https://api-docs.grvt.io/schemas/builder_fill_history) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | True | Time at which the event was emitted in unix nanoseconds | | off\_chain\_account\_id
`oc` | string | True | The off chain account id | | 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 | | fee\_rate
`fr` | string | True | Builder fee percentage charged for this order. referred to Order.builder builderFee | | fee
`f` | string | True | The builder fee paid on the trade, expressed in quote asset decimal unit. referred to Trade.builderFee | Back to top --- # Candlestick - Gravity Markets API Docs Candlestick =========== [Candlestick](https://api-docs.grvt.io/schemas/candlestick) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | open\_time
`ot` | string | True | Open time of kline bar in unix nanoseconds | | close\_time
`ct` | string | True | Close time of kline bar in unix nanosecond | | open
`o` | string | True | The open price, expressed in underlying currency resolution units | | close
`c` | string | True | The close price, expressed in underlying currency resolution units | | high
`h` | string | True | The high price, expressed in underlying currency resolution units | | low
`l` | string | True | The low price, expressed in underlying currency resolution units | | volume\_b
`vb` | string | True | The underlying volume transacted, expressed in base asset decimal units | | volume\_q
`vq` | string | True | The quote volume transacted, expressed in quote asset decimal units | | trades
`t` | integer | True | The number of trades transacted | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | Back to top --- # Candlestick type - Gravity Markets API Docs Candlestick type ================ [CandlestickType](https://api-docs.grvt.io/schemas/candlestick_type) | Value | Description | | --- | --- | | `TRADE` = 1 | Tracks traded prices | | `MARK` = 2 | Tracks mark prices | | `INDEX` = 3 | Tracks index prices | | `MID` = 4 | Tracks book mid prices | Back to top --- # Client tier - Gravity Markets API Docs Client tier =========== [ClientTier](https://api-docs.grvt.io/schemas/client_tier) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | tier
`t` | integer | True | | | futures\_taker\_fee
`ft` | integer | True | | | futures\_maker\_fee
`fm` | integer | True | | | options\_taker\_fee
`ot` | integer | True | | | options\_maker\_fee
`om` | integer | True | | Back to top --- # Deposit - Gravity Markets API Docs Deposit ======= [Deposit](https://api-docs.grvt.io/schemas/deposit) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | tx\_hash
`th` | string | True | The hash of the bridgemint event producing the deposit | | to\_account\_id
`ta` | string | True | The account to deposit into | | currency
`c` | string | True | The token currency to deposit | | num\_tokens
`nt` | string | True | The number of tokens to deposit | Back to top --- # Empty request - Gravity Markets API Docs Empty request ============= [EmptyRequest](https://api-docs.grvt.io/schemas/empty_request) Used for requests that do not require any parameters | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | | | | | Back to top --- # Epoch - Gravity Markets API Docs Epoch ===== [Epoch](https://api-docs.grvt.io/schemas/epoch) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | epoch
`e` | integer | True | The epoch number | | start\_time
`st` | string | True | The start time of the epoch | | end\_time
`et` | string | True | The end time of the epoch | Back to top --- # Error - Gravity Markets API Docs Error ===== [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | Back to top --- # Api get margin rules response - Gravity Markets API Docs Api get margin rules response ============================= [ApiGetMarginRulesResponse](https://api-docs.grvt.io/schemas/api_get_margin_rules_response) API response payload for margin rules of a particular instrument | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The instrument name | | max\_position\_size
`mp` | string | True | The maximum position size, expressed in base asset decimal units | | risk\_brackets
`rb` | \[RiskBracket\] | True | List of risk brackets defining margin requirements at different notional tiers | [RiskBracket](https://api-docs.grvt.io/schemas/risk_bracket) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | tier
`t` | integer | True | 1-indexed tier number | | notional\_floor
`nf` | string | True | Lower bound of notional value (inclusive) in quote currency | | notional\_cap
`nc` | string | False
`None` | Upper bound of notional value (exclusive) in quote currency, omitted for last tier | | maintenance\_margin\_rate
`mm` | string | True | Maintenance margin rate as a decimal (e.g., '0.01' for 1%) | | initial\_margin\_rate
`im` | string | True | Initial margin rate as a decimal (e.g., '0.02' for 2%) | | max\_leverage
`ml` | integer | True | Maximum leverage allowed at this tier (floor of 1 / initial\_margin\_rate) | | cumulative\_maintenance\_amount
`cm` | string | True | Cumulative maintenance margin amount in quote currency | Back to top --- # Api get user ecosystem point response - Gravity Markets API Docs Api get user ecosystem point response ===================================== [ApiGetUserEcosystemPointResponse](https://api-docs.grvt.io/schemas/api_get_user_ecosystem_point_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | points
`p` | \[EcosystemPoint\] | True | The list of ecosystem points | [EcosystemPoint](https://api-docs.grvt.io/schemas/ecosystem_point) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_id
`ai` | string | True | The off chain account id | | main\_account\_id
`ma` | string | True | The main account id | | total\_point
`tp` | string | True | Total ecosystem point | | direct\_invite\_count
`di` | integer | True | Direct invite count | | indirect\_invite\_count
`ii` | integer | True | Indirect invite count | | direct\_invite\_trading\_volume
`di1` | string | True | Direct invite trading volume | | indirect\_invite\_trading\_volume
`ii1` | string | True | Indirect invite trading volume | | calculate\_at
`ca` | string | True | The time when the ecosystem point is calculated | | calculate\_from
`cf` | string | True | Start time of the epoch - phase | | calculate\_to
`ct` | string | True | End time of the epoch - phase | | rank
`r` | integer | True | The rank of the account in the ecosystem | | epoch
`e` | integer | True | The epoch number of the ecosystem point | | brokered\_trading\_volume
`bt` | string | True | Brokered trading volume | | brokered\_trading\_point
`bt1` | string | True | Brokered trading point | | referee\_kyc\_point
`rk` | string | True | Referee KYC point | | referrer\_kyc\_point
`rk1` | string | True | Referrer KYC point | Back to top --- # Api order history request - Gravity Markets API Docs Api order history request ========================= [ApiOrderHistoryRequest](https://api-docs.grvt.io/schemas/api_order_history_request) 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` | \[string\] | 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` | \[string\] | 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](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api mini ticker response - Gravity Markets API Docs Api mini ticker response ======================== [ApiMiniTickerResponse](https://api-docs.grvt.io/schemas/api_mini_ticker_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | MiniTicker | True | The mini ticker matching the request asset | [MiniTicker](https://api-docs.grvt.io/schemas/mini_ticker) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | False
`None` | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | False
`None` | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | mark\_price
`mp` | string | False
`None` | The mark price of the instrument, expressed in `9` decimals | | index\_price
`ip` | string | False
`None` | The index price of the instrument, expressed in `9` decimals | | last\_price
`lp` | string | False
`None` | The last traded price of the instrument (also close price), expressed in `9` decimals | | last\_size
`ls` | string | False
`None` | The number of assets traded in the last trade, expressed in base asset decimal units | | mid\_price
`mp1` | string | False
`None` | The mid price of the instrument, expressed in `9` decimals | | best\_bid\_price
`bb` | string | False
`None` | The best bid price of the instrument, expressed in `9` decimals | | best\_bid\_size
`bb1` | string | False
`None` | The number of assets offered on the best bid price of the instrument, expressed in base asset decimal units | | best\_ask\_price
`ba` | string | False
`None` | The best ask price of the instrument, expressed in `9` decimals | | best\_ask\_size
`ba1` | string | False
`None` | The number of assets offered on the best ask price of the instrument, expressed in base asset decimal units | Back to top --- # Api sub account trade aggregation response - Gravity Markets API Docs Api sub account trade aggregation response ========================================== [ApiSubAccountTradeAggregationResponse](https://api-docs.grvt.io/schemas/api_sub_account_trade_aggregation_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[SubAccountTradeAggregation\] | True | The sub account trade aggregation result set for given interval | | next
`n` | string | False
`''` | The cursor to indicate when to start the next query from | [SubAccountTradeAggregation](https://api-docs.grvt.io/schemas/sub_account_trade_aggregation) Similar to sub-account trade, but not divided by individual assets. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The sub account id | | total\_fee
`tf` | string | True | Total fee paid | | total\_trade\_volume
`tt` | string | True | Total volume traded | | num\_traded
`nt` | string | True | Number of trades | | positive\_fee
`pf` | string | True | Total positive fee paid by user | | signer
`s` | string | True | The signer of the trade | | realized\_pnl
`rp` | string | True | Realized PnL | Back to top --- # Api sub account trade response - Gravity Markets API Docs Api sub account trade response ============================== [ApiSubAccountTradeResponse](https://api-docs.grvt.io/schemas/api_sub_account_trade_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[SubAccountTrade\] | True | The sub account trade result set for given interval | [SubAccountTrade](https://api-docs.grvt.io/schemas/sub_account_trade) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | start\_interval
`si` | string | True | Start of calculation epoch | | sub\_account\_id
`sa` | string | True | The sub account id | | instrument
`i` | string | True | The instrument being represented | | total\_fee
`tf` | string | True | Total fee paid | | total\_trade\_volume
`tt` | string | True | Total volume traded | Back to top --- # Api withdrawal history request - Gravity Markets API Docs Api withdrawal history request ============================== [ApiWithdrawalHistoryRequest](https://api-docs.grvt.io/schemas/api_withdrawal_history_request) The request to get the historical withdrawals of an account The history is returned in reverse chronological order Both finalized and pending withdrawals are returned, and pending withdrawals are indicated by an empty `l1Hash` field. 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` | \[string\] | 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. | Back to top --- # Candlestick interval - Gravity Markets API Docs Candlestick interval ==================== [CandlestickInterval](https://api-docs.grvt.io/schemas/candlestick_interval) | Value | Description | | --- | --- | | `CI_1_M` = 1 | 1 minute | | `CI_3_M` = 2 | 3 minutes | | `CI_5_M` = 3 | 5 minutes | | `CI_15_M` = 4 | 15 minutes | | `CI_30_M` = 5 | 30 minutes | | `CI_1_H` = 6 | 1 hour | | `CI_2_H` = 7 | 2 hour | | `CI_4_H` = 8 | 4 hour | | `CI_6_H` = 9 | 6 hour | | `CI_8_H` = 10 | 8 hour | | `CI_12_H` = 11 | 12 hour | | `CI_1_D` = 12 | 1 day | | `CI_3_D` = 13 | 3 days | | `CI_5_D` = 14 | 5 days | | `CI_1_W` = 15 | 1 week | | `CI_2_W` = 16 | 2 weeks | | `CI_3_W` = 17 | 3 weeks | | `CI_4_W` = 18 | 4 weeks | Back to top --- # Client order i ds by group - Gravity Markets API Docs Client order i ds by group ========================== [ClientOrderIDsByGroup](https://api-docs.grvt.io/schemas/client_order_i_ds_by_group) Grouping for the client order id and their associated groups. This is used to define TP/SL pairs or other order groupings after loading the list of Open Orders. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | group\_id
`gi` | string | True | The group this order belongs to. It can be used to define TP/SL pairs or other order groupings | | client\_order\_id
`co` | \[string\] | True | List of client order IDs in the group | | sub\_account\_id
`sa` | string | True | The sub account ID that these orders belong to | Back to top --- # Ecosystem leaderboard user - Gravity Markets API Docs Ecosystem leaderboard user ========================== [EcosystemLeaderboardUser](https://api-docs.grvt.io/schemas/ecosystem_leaderboard_user) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_id
`ai` | string | True | The off chain account id | | rank
`r` | integer | True | The rank of the account in the ecosystem | | total\_point
`tp` | string | True | Total ecosystem point | | twitter\_username
`tu` | string | True | The twitter username of the account | Back to top --- # Currency detail - Gravity Markets API Docs Currency detail =============== [CurrencyDetail](https://api-docs.grvt.io/schemas/currency_detail) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | id
`i` | integer | True | The integer value of the currency | | symbol
`s` | string | True | The name of the currency | | balance\_decimals
`bd` | integer | True | The balance decimals of the currency | | quantity\_multiplier
`qm` | string | True | The quantity multiplier of the currency | Back to top --- # Currency - Gravity Markets API Docs Currency ======== [Currency](https://api-docs.grvt.io/schemas/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 | Back to top --- # Deposit history - Gravity Markets API Docs Deposit history =============== [DepositHistory](https://api-docs.grvt.io/schemas/deposit_history) | 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` | string | 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, empty if the deposit is pending. | | from\_address
`fa` | string | True | The address of the sender | Back to top --- # Ecosystem metric - Gravity Markets API Docs Ecosystem metric ================ [EcosystemMetric](https://api-docs.grvt.io/schemas/ecosystem_metric) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | direct\_invite\_count
`di` | integer | True | Direct invite count | | indirect\_invite\_count
`ii` | integer | True | Indirect invite count | | direct\_invite\_trading\_volume
`di1` | string | True | Direct invite trading volume | | indirect\_invite\_trading\_volume
`ii1` | string | True | Indirect invite trading volume | | total\_point
`tp` | string | True | Total ecosystem point of this epoch/phase | Back to top --- # Ecosystem point - Gravity Markets API Docs Ecosystem point =============== [EcosystemPoint](https://api-docs.grvt.io/schemas/ecosystem_point) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_id
`ai` | string | True | The off chain account id | | main\_account\_id
`ma` | string | True | The main account id | | total\_point
`tp` | string | True | Total ecosystem point | | direct\_invite\_count
`di` | integer | True | Direct invite count | | indirect\_invite\_count
`ii` | integer | True | Indirect invite count | | direct\_invite\_trading\_volume
`di1` | string | True | Direct invite trading volume | | indirect\_invite\_trading\_volume
`ii1` | string | True | Indirect invite trading volume | | calculate\_at
`ca` | string | True | The time when the ecosystem point is calculated | | calculate\_from
`cf` | string | True | Start time of the epoch - phase | | calculate\_to
`ct` | string | True | End time of the epoch - phase | | rank
`r` | integer | True | The rank of the account in the ecosystem | | epoch
`e` | integer | True | The epoch number of the ecosystem point | | brokered\_trading\_volume
`bt` | string | True | Brokered trading volume | | brokered\_trading\_point
`bt1` | string | True | Brokered trading point | | referee\_kyc\_point
`rk` | string | True | Referee KYC point | | referrer\_kyc\_point
`rk1` | string | True | Referrer KYC point | Back to top --- # Epoch badge type - Gravity Markets API Docs Epoch badge type ================ [EpochBadgeType](https://api-docs.grvt.io/schemas/epoch_badge_type) | Value | Description | | --- | --- | | `CHAMPION` = 1 | Champion | | `LEGEND` = 2 | Legend | | `VETERAN` = 3 | Veteran | | `ELITE` = 4 | Elite | | `MASTER` = 5 | Master | | `EXPERT` = 6 | Expert | | `WARRIOR` = 7 | Warrior | | `SERGEANT` = 8 | Sergeant | | `RANGER` = 9 | Ranger | | `CHALLENGER` = 10 | Challenger | | `APPRENTICE` = 11 | Apprentice | | `ROOKIE` = 12 | Rookie | Back to top --- # Flat referral - Gravity Markets API Docs Flat referral ============= [FlatReferral](https://api-docs.grvt.io/schemas/flat_referral) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_id
`ai` | string | True | The off chain account id | | referrer\_id
`ri` | string | True | The off chain referrer account id | | referrer\_level
`rl` | integer | True | The referrer level; 1: direct referrer, 2: indirect referrer | | account\_create\_time
`ac` | string | True | The account creation time | | main\_account\_id
`ma` | string | True | The main account id | | referrer\_main\_account\_id
`rm` | string | True | The referrer main account id | | is\_business
`ib` | boolean | True | The account is a business account or not | | is\_kyc\_completed
`ik` | boolean | True | The account is KYC verified or not | | kyc\_completed\_at
`kc` | string | True | The KYC completed time | | kyc\_type
`kt` | string | True | The KYC type, can be 'individual' or 'business' | | kyc\_first\_completed\_at
`kf` | string | True | The first KYC completed time | Back to top --- # Funding payment - Gravity Markets API Docs Funding payment =============== [FundingPayment](https://api-docs.grvt.io/schemas/funding_payment) | 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` | string | 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`. | Back to top --- # Funding rate - Gravity Markets API Docs Funding rate ============ [FundingRate](https://api-docs.grvt.io/schemas/funding_rate) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | funding\_rate
`fr` | string | True | The funding rate of the instrument, expressed in percentage points | | funding\_time
`ft` | string | True | The funding timestamp of the funding rate, expressed in unix nanoseconds | | mark\_price
`mp` | string | True | The mark price of the instrument at funding timestamp, expressed in `9` decimals | | funding\_rate\_8\_h\_avg
`fr1` | string | True | The 8h average funding rate of the instrument, expressed in percentage points | Back to top --- # Funding rate aggregation type - Gravity Markets API Docs Funding rate aggregation type ============================= [FundingRateAggregationType](https://api-docs.grvt.io/schemas/funding_rate_aggregation_type) Specifies different methods of aggregating historical funding rates | Value | Description | | --- | --- | | `FUNDING_INTERVAL` = 1 | Default value -- one record returned per funding interval. Query instruments endpoint to learn funding interval of each instrument. | | `ONE_HOURLY` = 2 | Returns one record per hour -- normalizes all funding rates to 1h durations, so `fundingRate` value is cumulative and can exceed a funding interval's configured cap / floor. | | `FOUR_HOURLY` = 3 | Returns one record per 4 hours -- normalizes all funding rates to 4h durations, so `fundingRate` value is cumulative and can exceed a funding interval's configured cap / floor. | | `EIGHT_HOURLY` = 4 | Returns one record for eight hours -- normalizes all funding rates to 8h durations, so `fundingRate` value is cumulative and can exceed a funding interval's configured cap / floor. | Back to top --- # Instrument settlement period - Gravity Markets API Docs Instrument settlement period ============================ [InstrumentSettlementPeriod](https://api-docs.grvt.io/schemas/instrument_settlement_period) | Value | Description | | --- | --- | | `PERPETUAL` = 1 | Instrument settles through perpetual funding cycles | | `DAILY` = 2 | Instrument settles at an expiry date, marked as a daily instrument | | `WEEKLY` = 3 | Instrument settles at an expiry date, marked as a weekly instrument | | `MONTHLY` = 4 | Instrument settles at an expiry date, marked as a monthly instrument | | `QUARTERLY` = 5 | Instrument settles at an expiry date, marked as a quarterly instrument | Back to top --- # Kind - Gravity Markets API Docs Kind ==== [Kind](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api funding account summary response - Gravity Markets API Docs Api funding account summary response ==================================== [ApiFundingAccountSummaryResponse](https://api-docs.grvt.io/schemas/api_funding_account_summary_response) 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 | | tier
`t` | ClientTier | True | Client fee tier at the time of query | [FundingAccountSummary](https://api-docs.grvt.io/schemas/funding_account_summary) 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 | | vault\_investments
`vi` | \[VaultInvestment\] | True | The list of vault investments held by this main account | [SpotBalance](https://api-docs.grvt.io/schemas/spot_balance) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | currency
`c` | string | 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`) | [VaultInvestment](https://api-docs.grvt.io/schemas/vault_investment) Summarizes a vault investment held by a funding account | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_id
`vi` | string | True | The trading account ID of the vault invested in. | | num\_lp\_tokens
`nl` | string | True | The number of shares held by the investor. | | share\_price
`sp` | string | True | The current share price (in USD) of this vault investment. | | usd\_notional\_invested
`un` | string | True | The USD notional invested in this vault investment. | [ClientTier](https://api-docs.grvt.io/schemas/client_tier) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | tier
`t` | integer | True | | | futures\_taker\_fee
`ft` | integer | True | | | futures\_maker\_fee
`fm` | integer | True | | | options\_taker\_fee
`ot` | integer | True | | | options\_maker\_fee
`om` | integer | True | | Back to top --- # Api get latest lp snapshot request - Gravity Markets API Docs Api get latest lp snapshot request ================================== [ApiGetLatestLPSnapshotRequest](https://api-docs.grvt.io/schemas/api_get_latest_lp_snapshot_request) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | kind
`k` | Kind | False
`0` | The kind filter to apply | | base
`b` | Currency | False
`0` | The base filter to apply | [Kind](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api get list reward epoch response - Gravity Markets API Docs Api get list reward epoch response ================================== [ApiGetListRewardEpochResponse](https://api-docs.grvt.io/schemas/api_get_list_reward_epoch_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | ecosystem\_epochs
`ee` | \[RewardEpochInfo\] | True | The list of epoch for ecosystem reward | | trading\_epochs
`te` | \[RewardEpochInfo\] | True | The list of epoch for trader reward and lp reward | [RewardEpochInfo](https://api-docs.grvt.io/schemas/reward_epoch_info) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | epoch
`e` | integer | True | The epoch number | | epoch\_start\_time
`es` | string | True | The start time of the epoch | | epoch\_end\_time
`ee` | string | True | The end time of the epoch | | status
`s` | RewardEpochStatus | True | The status of the epoch | [RewardEpochStatus](https://api-docs.grvt.io/schemas/reward_epoch_status) | Value | Description | | --- | --- | | `PAST` = 1 | Past | | `CURRENT` = 2 | Current | | `FUTURE` = 3 | Future | [RewardEpochInfo](https://api-docs.grvt.io/schemas/reward_epoch_info) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | epoch
`e` | integer | True | The epoch number | | epoch\_start\_time
`es` | string | True | The start time of the epoch | | epoch\_end\_time
`ee` | string | True | The end time of the epoch | | status
`s` | RewardEpochStatus | True | The status of the epoch | [RewardEpochStatus](https://api-docs.grvt.io/schemas/reward_epoch_status) | Value | Description | | --- | --- | | `PAST` = 1 | Past | | `CURRENT` = 2 | Current | | `FUTURE` = 3 | Future | Back to top --- # Api get lp config request - Gravity Markets API Docs Api get lp config request ========================= [ApiGetLPConfigRequest](https://api-docs.grvt.io/schemas/api_get_lp_config_request) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | kind
`k` | Kind | True | The kind filter to apply | | base
`b` | Currency | True | The base filter to apply | [Kind](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api pre deposit check response - Gravity Markets API Docs Api pre deposit check response ============================== [ApiPreDepositCheckResponse](https://api-docs.grvt.io/schemas/api_pre_deposit_check_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | max\_deposit\_limit
`md` | string | True | Max Deposit Limit reported for the Bridge Account reported in the currency balance | | currency
`c` | Currency | True | The currency you hold the deposit in | [Currency](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api set derisk to maintenance margin ratio request - Gravity Markets API Docs Api set derisk to maintenance margin ratio request ================================================== [ApiSetDeriskToMaintenanceMarginRatioRequest](https://api-docs.grvt.io/schemas/api_set_derisk_to_maintenance_margin_ratio_request) The request to set the derisk margin to maintenance margin ratio 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 | | ratio
`r` | string | True | The derisk margin to maintenance margin ratio of this sub account | | signature
`s` | Signature | True | The signature of this operation | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | Back to top --- # Api settlement price - Gravity Markets API Docs Api settlement price ==================== [APISettlementPrice](https://api-docs.grvt.io/schemas/api_settlement_price) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | base
`b` | Currency | True | The base currency of the settlement price | | quote
`q` | Currency | True | The quote currency of the settlement price | | settlement\_time
`st` | string | True | The settlement timestamp of the settlement price, expressed in unix nanoseconds | | settlement\_price
`sp` | string | True | The settlement price, expressed in `9` decimals | [Currency](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api settlement price request - Gravity Markets API Docs Api settlement price request ============================ [ApiSettlementPriceRequest](https://api-docs.grvt.io/schemas/api_settlement_price_request) Lookup the historical settlement price of various pairs. 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 | | --- | --- | --- | --- | | base
`b` | Currency | True | The base currency to select | | quote
`q` | Currency | True | The quote currency to select | | start\_time
`st` | string | False
`0` | Start time of settlement price in unix nanoseconds | | end\_time
`et` | string | False
`now()` | End time of settlement price in unix nanoseconds | | limit
`l` | integer | False
`30` | The limit to query for. Defaults to 500; Max 1000 | | cursor
`c` | string | False
`''` | The cursor to indicate when to start the query from | [Currency](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api sub account trade aggregation request - Gravity Markets API Docs Api sub account trade aggregation request ========================================= [ApiSubAccountTradeAggregationRequest](https://api-docs.grvt.io/schemas/api_sub_account_trade_aggregation_request) startTime are optional parameters. The semantics of these parameters are as follows: | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | limit
`l` | integer | True | Optional. The limit of the number of results to return | | interval
`i` | SubAccountTradeInterval | True | The interval of each sub account trade | | sub\_account\_i\_ds
`sa` | \[string\] | True | The list of sub account ids to query | | start\_interval
`si` | string | True | Optional. The starting time in unix nanoseconds of a specific interval to query | | start\_time
`st` | string | False
`0` | Optional. Start time in unix nanoseconds | | end\_time
`et` | string | False
`now()` | Optional. End time in unix nanoseconds | | is\_maker
`im` | boolean | True | Filter on the maker of the trade | | is\_taker
`it` | boolean | True | Filter on the taker of the trade | | cursor
`c` | string | False
\`\` | The cursor to indicate when to start the next query from | | group\_by\_signer
`gb` | boolean | True | Whether to group trades by signer per sub account | [SubAccountTradeInterval](https://api-docs.grvt.io/schemas/sub_account_trade_interval) | Value | Description | | --- | --- | | `SAT_1_MO` = 1 | 1 month | | `SAT_1_D` = 2 | 1 day | | `SAT_1_H` = 3 | 1 hour | | `SAT_4_H` = 4 | 4 hour | Back to top --- # Api sub account trade request - Gravity Markets API Docs Api sub account trade request ============================= [ApiSubAccountTradeRequest](https://api-docs.grvt.io/schemas/api_sub_account_trade_request) startTime are optional parameters. The semantics of these parameters are as follows: | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | interval
`i1` | SubAccountTradeInterval | True | The interval of each sub account trade | | sub\_account\_i\_ds
`sa` | \[string\] | True | The list of sub account ids to query | | start\_interval
`si` | string | True | Optional. The starting time in unix nanoseconds of a specific interval to query | | start\_time
`st` | string | False
`0` | Optional. Start time in unix nanoseconds | | end\_time
`et` | string | False
`now()` | Optional. End time in unix nanoseconds | [SubAccountTradeInterval](https://api-docs.grvt.io/schemas/sub_account_trade_interval) | Value | Description | | --- | --- | | `SAT_1_MO` = 1 | 1 month | | `SAT_1_D` = 2 | 1 day | Back to top --- # Api ticker feed data v1 - Gravity Markets API Docs Api ticker feed data v1 ======================= [ApiTickerFeedDataV1](https://api-docs.grvt.io/schemas/api_ticker_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | Ticker | True | The mini ticker matching the request asset | [Ticker](https://api-docs.grvt.io/schemas/ticker) Derived data such as the below, will not be included by default: \- 24 hour volume (`buyVolume + sellVolume`) \- 24 hour taker buy/sell ratio (`buyVolume / sellVolume`) \- 24 hour average trade price (`volumeQ / volumeU`) \- 24 hour average trade volume (`volume / trades`) \- 24 hour percentage change (`24hStatChange / 24hStat`) \- 48 hour statistics (`2 * 24hStat - 24hStatChange`) To query for an extended ticker payload, leverage the `greeks` and the `derived` flags. Ticker extensions are currently under design to offer you more convenience. These flags are only supported on the `Ticker Snapshot` WS endpoint, and on the `Ticker` API endpoint. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | False
`None` | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | False
`None` | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | mark\_price
`mp` | string | False
`None` | The mark price of the instrument, expressed in `9` decimals | | index\_price
`ip` | string | False
`None` | The index price of the instrument, expressed in `9` decimals | | last\_price
`lp` | string | False
`None` | The last traded price of the instrument (also close price), expressed in `9` decimals | | last\_size
`ls` | string | False
`None` | The number of assets traded in the last trade, expressed in base asset decimal units | | mid\_price
`mp1` | string | False
`None` | The mid price of the instrument, expressed in `9` decimals | | best\_bid\_price
`bb` | string | False
`None` | The best bid price of the instrument, expressed in `9` decimals | | best\_bid\_size
`bb1` | string | False
`None` | The number of assets offered on the best bid price of the instrument, expressed in base asset decimal units | | best\_ask\_price
`ba` | string | False
`None` | The best ask price of the instrument, expressed in `9` decimals | | best\_ask\_size
`ba1` | string | False
`None` | The number of assets offered on the best ask price of the instrument, expressed in base asset decimal units | | funding\_rate\_8h\_curr
`fr` | string | False
`None` | The current funding rate of the instrument, expressed in percentage points | | funding\_rate\_8h\_avg
`fr1` | string | False
`None` | The average funding rate of the instrument (over last 8h), expressed in percentage points | | interest\_rate
`ir` | string | False
`None` | The interest rate of the underlying, expressed in centibeeps (1/100th of a basis point) | | forward\_price
`fp` | string | False
`None` | \[Options\] The forward price of the option, expressed in `9` decimals | | buy\_volume\_24h\_b
`bv` | string | False
`None` | The 24 hour taker buy volume of the instrument, expressed in base asset decimal units | | sell\_volume\_24h\_b
`sv` | string | False
`None` | The 24 hour taker sell volume of the instrument, expressed in base asset decimal units | | buy\_volume\_24h\_q
`bv1` | string | False
`None` | The 24 hour taker buy volume of the instrument, expressed in quote asset decimal units | | sell\_volume\_24h\_q
`sv1` | string | False
`None` | The 24 hour taker sell volume of the instrument, expressed in quote asset decimal units | | high\_price
`hp` | string | False
`None` | The 24 hour highest traded price of the instrument, expressed in `9` decimals | | low\_price
`lp1` | string | False
`None` | The 24 hour lowest traded price of the instrument, expressed in `9` decimals | | open\_price
`op` | string | False
`None` | The 24 hour first traded price of the instrument, expressed in `9` decimals | | open\_interest
`oi` | string | False
`None` | The open interest in the instrument, expressed in base asset decimal units | | long\_short\_ratio
`ls1` | string | False
`None` | The ratio of accounts that are net long vs net short on this instrument | Back to top --- # Api ticker response - Gravity Markets API Docs Api ticker response =================== [ApiTickerResponse](https://api-docs.grvt.io/schemas/api_ticker_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | Ticker | True | The mini ticker matching the request asset | [Ticker](https://api-docs.grvt.io/schemas/ticker) Derived data such as the below, will not be included by default: \- 24 hour volume (`buyVolume + sellVolume`) \- 24 hour taker buy/sell ratio (`buyVolume / sellVolume`) \- 24 hour average trade price (`volumeQ / volumeU`) \- 24 hour average trade volume (`volume / trades`) \- 24 hour percentage change (`24hStatChange / 24hStat`) \- 48 hour statistics (`2 * 24hStat - 24hStatChange`) To query for an extended ticker payload, leverage the `greeks` and the `derived` flags. Ticker extensions are currently under design to offer you more convenience. These flags are only supported on the `Ticker Snapshot` WS endpoint, and on the `Ticker` API endpoint. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | False
`None` | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | False
`None` | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | mark\_price
`mp` | string | False
`None` | The mark price of the instrument, expressed in `9` decimals | | index\_price
`ip` | string | False
`None` | The index price of the instrument, expressed in `9` decimals | | last\_price
`lp` | string | False
`None` | The last traded price of the instrument (also close price), expressed in `9` decimals | | last\_size
`ls` | string | False
`None` | The number of assets traded in the last trade, expressed in base asset decimal units | | mid\_price
`mp1` | string | False
`None` | The mid price of the instrument, expressed in `9` decimals | | best\_bid\_price
`bb` | string | False
`None` | The best bid price of the instrument, expressed in `9` decimals | | best\_bid\_size
`bb1` | string | False
`None` | The number of assets offered on the best bid price of the instrument, expressed in base asset decimal units | | best\_ask\_price
`ba` | string | False
`None` | The best ask price of the instrument, expressed in `9` decimals | | best\_ask\_size
`ba1` | string | False
`None` | The number of assets offered on the best ask price of the instrument, expressed in base asset decimal units | | funding\_rate\_8h\_curr
`fr` | string | False
`None` | DEPRECATED: To be removed in a future release. Please refer to the field `funding_rate` instead, for the funding rate being applied over `funding_interval_hours` (interval ending at `next_funding_time`). | | funding\_rate\_8h\_avg
`fr1` | string | False
`None` | DEPRECATED: To be removed in a future release. Please refer to the field `funding_rate` instead, for the funding rate being applied over `funding_interval_hours` (interval ending at `next_funding_time`). | | interest\_rate
`ir` | string | False
`None` | The interest rate of the underlying, expressed in centibeeps (1/100th of a basis point) | | forward\_price
`fp` | string | False
`None` | \[Options\] The forward price of the option, expressed in `9` decimals | | buy\_volume\_24h\_b
`bv` | string | False
`None` | The 24 hour taker buy volume of the instrument, expressed in base asset decimal units | | sell\_volume\_24h\_b
`sv` | string | False
`None` | The 24 hour taker sell volume of the instrument, expressed in base asset decimal units | | buy\_volume\_24h\_q
`bv1` | string | False
`None` | The 24 hour taker buy volume of the instrument, expressed in quote asset decimal units | | sell\_volume\_24h\_q
`sv1` | string | False
`None` | The 24 hour taker sell volume of the instrument, expressed in quote asset decimal units | | high\_price
`hp` | string | False
`None` | The 24 hour highest traded price of the instrument, expressed in `9` decimals | | low\_price
`lp1` | string | False
`None` | The 24 hour lowest traded price of the instrument, expressed in `9` decimals | | open\_price
`op` | string | False
`None` | The 24 hour first traded price of the instrument, expressed in `9` decimals | | open\_interest
`oi` | string | False
`None` | The open interest in the instrument, expressed in base asset decimal units | | long\_short\_ratio
`ls1` | string | False
`None` | The ratio of accounts that are net long vs net short on this instrument | | funding\_rate
`fr2` | string | False
`None` | The current indicative funding rate for the active interval, expressed in centibeeps | | next\_funding\_time
`nf` | string | False
`None` | Timestamp in nanoseconds when the current funding interval ends | Back to top --- # Api transfer response - Gravity Markets API Docs Api transfer response ===================== [ApiTransferResponse](https://api-docs.grvt.io/schemas/api_transfer_response) Used to acknowledge a transfer request outcome | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | ApiTransferAck | True | The Transfer response object | [ApiTransferAck](https://api-docs.grvt.io/schemas/api_transfer_ack) | 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. | Back to top --- # Api user category affinity score response - Gravity Markets API Docs Api user category affinity score response ========================================= [ApiUserCategoryAffinityScoreResponse](https://api-docs.grvt.io/schemas/api_user_category_affinity_score_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[UserCategoryAffinityScore\] | True | The list of categoryAffinities score | [UserCategoryAffinityScore](https://api-docs.grvt.io/schemas/user_category_affinity_score) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_id
`ai` | string | True | The off chain account id | | category\_id
`ci` | string | True | target category | | affinity\_score
`as` | number | True | affinity score | Back to top --- # Lp point - Gravity Markets API Docs Lp point ======== [LPPoint](https://api-docs.grvt.io/schemas/lp_point) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | main\_account\_id
`ma` | string | True | The main account id | | liquidity\_score
`ls` | string | True | Liquidity score | | rank
`r` | integer | True | The rank of user in the LP leaderboard | Back to top --- # Margin tier response - Gravity Markets API Docs Margin tier response ==================== [MarginTierResponse](https://api-docs.grvt.io/schemas/margin_tier_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | lower\_bound
`lb` | string | True | | | rate
`r` | string | True | | Back to top --- # Orderbook level - Gravity Markets API Docs Orderbook level =============== [OrderbookLevel](https://api-docs.grvt.io/schemas/orderbook_level) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | price
`p` | string | True | The price of the level, expressed in `9` decimals | | size
`s` | string | True | The number of assets offered, expressed in base asset decimal units | | num\_orders
`no` | integer | True | The number of open orders at this level | Back to top --- # Margin type - Gravity Markets API Docs Margin type =========== [MarginType](https://api-docs.grvt.io/schemas/margin_type) | 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 | Back to top --- # Position margin type - Gravity Markets API Docs Position margin type ==================== [PositionMarginType](https://api-docs.grvt.io/schemas/position_margin_type) | Value | Description | | --- | --- | | `ISOLATED` = 1 | Isolated Margin Mode: each position is allocated a fixed amount of collateral | | `CROSS` = 2 | Cross Margin Mode: uses all available funds in your account as collateral across all cross margin positions | Back to top --- # Jsonrpc request - Gravity Markets API Docs Jsonrpc request =============== [JSONRPCRequest](https://api-docs.grvt.io/schemas/jsonrpc_request) All Websocket JSON RPC Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | method
`m` | string | True | The method to use for the request (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | | params
`p` | object | True | The parameters for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | Back to top --- # Lp snapshot - Gravity Markets API Docs Lp snapshot =========== [LPSnapshot](https://api-docs.grvt.io/schemas/lp_snapshot) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | main\_account\_id
`ma` | string | True | The main account id | | lp\_asset
`la` | string | True | The LP Asset | | underlying\_multiplier
`um` | string | True | Underlying multiplier | | maker\_trading\_volume
`mt` | string | True | Maker trading volume | | bid\_fast\_market\_multiplier
`bf` | integer | True | Fast market multiplier | | ask\_fast\_market\_multiplier
`af` | integer | True | Fast market multiplier | | liquidity\_score
`ls` | string | True | Liquidity score | | calculate\_at
`ca` | string | True | The time when the snapshot was calculated | Back to top --- # Mini ticker - Gravity Markets API Docs Mini ticker =========== [MiniTicker](https://api-docs.grvt.io/schemas/mini_ticker) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | False
`None` | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | False
`None` | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | mark\_price
`mp` | string | False
`None` | The mark price of the instrument, expressed in `9` decimals | | index\_price
`ip` | string | False
`None` | The index price of the instrument, expressed in `9` decimals | | last\_price
`lp` | string | False
`None` | The last traded price of the instrument (also close price), expressed in `9` decimals | | last\_size
`ls` | string | False
`None` | The number of assets traded in the last trade, expressed in base asset decimal units | | mid\_price
`mp1` | string | False
`None` | The mid price of the instrument, expressed in `9` decimals | | best\_bid\_price
`bb` | string | False
`None` | The best bid price of the instrument, expressed in `9` decimals | | best\_bid\_size
`bb1` | string | False
`None` | The number of assets offered on the best bid price of the instrument, expressed in base asset decimal units | | best\_ask\_price
`ba` | string | False
`None` | The best ask price of the instrument, expressed in `9` decimals | | best\_ask\_size
`ba1` | string | False
`None` | The number of assets offered on the best ask price of the instrument, expressed in base asset decimal units | Back to top --- # Order status - Gravity Markets API Docs Order status ============ [OrderStatus](https://api-docs.grvt.io/schemas/order_status) | 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. | Back to top --- # Order leg - Gravity Markets API Docs Order leg ========= [OrderLeg](https://api-docs.grvt.io/schemas/order_leg) | 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 | Back to top --- # Api get all instruments response - Gravity Markets API Docs Api get all instruments response ================================ [ApiGetAllInstrumentsResponse](https://api-docs.grvt.io/schemas/api_get_all_instruments_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[InstrumentDisplay\] | True | List of instruments | [InstrumentDisplay](https://api-docs.grvt.io/schemas/instrument_display) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | instrument\_hash
`ih` | string | True | The asset ID used for instrument signing. | | base
`b` | string | True | The base currency | | quote
`q` | string | True | The quote currency | | kind
`k` | Kind | True | The kind of instrument | | venues
`v` | \[Venue\] | True | Venues that this instrument can be traded at | | settlement\_period
`sp1` | InstrumentSettlementPeriod | True | The settlement period of the instrument | | base\_decimals
`bd` | integer | True | The smallest denomination of the base asset supported by GRVT (+3 represents 0.001, -3 represents 1000, 0 represents 1) | | quote\_decimals
`qd` | integer | True | The smallest denomination of the quote asset supported by GRVT (+3 represents 0.001, -3 represents 1000, 0 represents 1) | | tick\_size
`ts` | string | True | The size of a single tick, expressed in price decimal units | | min\_size
`ms` | string | True | The minimum contract size, expressed in base asset decimal units | | create\_time
`ct` | string | True | Creation time in unix nanoseconds | | max\_position\_size
`mp` | string | True | The maximum position size, expressed in base asset decimal units | | funding\_interval\_hours
`fi` | integer | False
`None` | Defines the funding interval to be applied. | | adjusted\_funding\_rate\_cap
`af` | string | False
`None` | Funding rate cap over the defined `intervalHours`. | | adjusted\_funding\_rate\_floor
`af1` | string | False
`None` | Funding rate floor over the defined `intervalHours`. | | min\_notional
`mn` | string | True | The minimum order notional value, expressed in quote currency decimal units | [Kind](https://api-docs.grvt.io/schemas/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 | [Venue](https://api-docs.grvt.io/schemas/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 | [InstrumentSettlementPeriod](https://api-docs.grvt.io/schemas/instrument_settlement_period) | Value | Description | | --- | --- | | `PERPETUAL` = 1 | Instrument settles through perpetual funding cycles | | `DAILY` = 2 | Instrument settles at an expiry date, marked as a daily instrument | | `WEEKLY` = 3 | Instrument settles at an expiry date, marked as a weekly instrument | | `MONTHLY` = 4 | Instrument settles at an expiry date, marked as a monthly instrument | | `QUARTERLY` = 5 | Instrument settles at an expiry date, marked as a quarterly instrument | Back to top --- # Api get margin tiers response - Gravity Markets API Docs Api get margin tiers response ============================= [ApiGetMarginTiersResponse](https://api-docs.grvt.io/schemas/api_get_margin_tiers_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | results
`r` | \[AssetMarginTierResponse\] | True | | [AssetMarginTierResponse](https://api-docs.grvt.io/schemas/asset_margin_tier_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | asset
`a` | string | True | | | tiers
`t` | \[MarginTierResponse\] | True | | [MarginTierResponse](https://api-docs.grvt.io/schemas/margin_tier_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | lower\_bound
`lb` | string | True | | | rate
`r` | string | True | | Back to top --- # Api transfer history request - Gravity Markets API Docs Api transfer history request ============================ [ApiTransferHistoryRequest](https://api-docs.grvt.io/schemas/api_transfer_history_request) 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` | \[string\] | 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. | | transfer\_types
`tt` | \[TransferType\] | False
`[]` | The transfer type to filters for. If the list is empty, return all transfer types. | [TransferType](https://api-docs.grvt.io/schemas/transfer_type) | Value | Description | | --- | --- | | `UNSPECIFIED` = 0 | Default transfer that has nothing to do with bridging | | `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 | | `ADHOC_INCENTIVE` = 6 | Transfer type for adhoc incentive | | `REFERRAL_INCENTIVE` = 7 | Transfer type for referral incentive | | `TRADING_DEPOSIT_YIELD_INCENTIVE` = 8 | Transfer type for trading deposit yield incentive | Back to top --- # Api vault burn tokens request - Gravity Markets API Docs Api vault burn tokens request ============================= [ApiVaultBurnTokensRequest](https://api-docs.grvt.io/schemas/api_vault_burn_tokens_request) Request payload for burning tokens in a vault. This API allows a client to burn a specified amount of tokens in a particular vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_id
`vi` | string | True | The unique identifier of the vault to burn tokens from. | | currency
`c` | string | True | The currency used for the burn. This should be the vault's quote currency. | | num\_tokens
`nt` | string | True | The number of tokens to burn. | | signature
`s` | Signature | True | The digital signature from the investing account.
This signature must be generated by the main account ID and is used to verify the authenticity of the request.
The signature must comply with AccountPermExternalTransfer permission. | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | Back to top --- # Api vault invest request - Gravity Markets API Docs Api vault invest request ======================== [ApiVaultInvestRequest](https://api-docs.grvt.io/schemas/api_vault_invest_request) Request payload for investing in a vault. This API allows a client to invest a specified amount of tokens in a particular vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_id
`vi` | string | True | The unique identifier of the vault to invest in. | | currency
`c` | string | True | The currency used for the investment. This should be the vault's quote currency. | | num\_tokens
`nt` | string | True | The investment sum, in terms of the token currency specified (i.e., `numTokens` of '1000' with `tokenCurrency` of 'USDT' denotes investment of 1,000 USDT). | | signature
`s` | Signature | True | The digital signature from the investing account.
This signature must be generated by the main account ID and is used to verify the authenticity of the request.
The signature must comply with AccountPermExternalTransfer permission. | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | Back to top --- # Api vault investor history - Gravity Markets API Docs Api vault investor history ========================== [ApiVaultInvestorHistory](https://api-docs.grvt.io/schemas/api_vault_investor_history) The vault investor history returned by the service to client | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | True | Time at which the event was emitted in unix nanoseconds | | off\_chain\_account\_id
`oc` | string | True | The off chain account id of the investor, only visible to the manager | | vault\_id
`vi` | string | True | The unique identifier of the vault. | | type
`t` | VaultInvestorAction | True | The type of transaction that occurred. List of types: vaultInvest, vaultBurnLpToken, vaultRedeem | | price
`p` | string | True | The price of the vault LP tokens at the time of the event. | | size
`s` | string | True | The amount of Vault LP tokens invested or redeemed. | | realized\_pnl
`rp` | string | True | The realized PnL of the vault. | | performance\_fee
`pf` | string | True | The performance fee of the vault. | [VaultInvestorAction](https://api-docs.grvt.io/schemas/vault_investor_action) | Value | Description | | --- | --- | | `UNSPECIFIED` = 0 | | | `VAULT_INVEST` = 1 | | | `VAULT_BURN_LP_TOKEN` = 2 | | | `VAULT_REDEEM` = 3 | | Back to top --- # Asset margin tier response - Gravity Markets API Docs Asset margin tier response ========================== [AssetMarginTierResponse](https://api-docs.grvt.io/schemas/asset_margin_tier_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | asset
`a` | string | True | | | tiers
`t` | \[MarginTierResponse\] | True | | [MarginTierResponse](https://api-docs.grvt.io/schemas/margin_tier_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | lower\_bound
`lb` | string | True | | | rate
`r` | string | True | | Back to top --- # Api get lp info request - Gravity Markets API Docs Api get lp info request ======================= [ApiGetLPInfoRequest](https://api-docs.grvt.io/schemas/api_get_lp_info_request) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | kind
`k` | Kind | True | The kind filter to apply | | base
`b` | Currency | False
`0` | The base filter to apply | [Kind](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api get lp leaderboard request - Gravity Markets API Docs Api get lp leaderboard request ============================== [ApiGetLPLeaderboardRequest](https://api-docs.grvt.io/schemas/api_get_lp_leaderboard_request) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | epoch
`e` | integer | False
`0` | The epoch to filter | | limit
`l` | integer | True | The number of accounts to return | | kind
`k` | Kind | True | The kind filter to apply | | base
`b` | Currency | True | The base filter to apply | [Kind](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api get lp point request - Gravity Markets API Docs Api get lp point request ======================== [ApiGetLPPointRequest](https://api-docs.grvt.io/schemas/api_get_lp_point_request) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | epoch
`e` | integer | False
`0` | The epoch to filter | | kind
`k` | Kind | False
`0` | Optional. The kind filter to apply | | base
`b` | Currency | False
`0` | Optional. The base filter to apply | [Kind](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api orderbook levels response - Gravity Markets API Docs Api orderbook levels response ============================= [ApiOrderbookLevelsResponse](https://api-docs.grvt.io/schemas/api_orderbook_levels_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | OrderbookLevels | True | The orderbook levels objects matching the request asset | [OrderbookLevels](https://api-docs.grvt.io/schemas/orderbook_levels) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | True | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | bids
`b` | \[OrderbookLevel\] | True | The list of best bids up till query depth | | asks
`a` | \[OrderbookLevel\] | True | The list of best asks up till query depth | [OrderbookLevel](https://api-docs.grvt.io/schemas/orderbook_level) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | price
`p` | string | True | The price of the level, expressed in `9` decimals | | size
`s` | string | True | The number of assets offered, expressed in base asset decimal units | | num\_orders
`no` | integer | True | The number of open orders at this level | [OrderbookLevel](https://api-docs.grvt.io/schemas/orderbook_level) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | price
`p` | string | True | The price of the level, expressed in `9` decimals | | size
`s` | string | True | The number of assets offered, expressed in base asset decimal units | | num\_orders
`no` | integer | True | The number of open orders at this level | Back to top --- # Api vault redeem request - Gravity Markets API Docs Api vault redeem request ======================== [ApiVaultRedeemRequest](https://api-docs.grvt.io/schemas/api_vault_redeem_request) Request payload for redeeming from a vault. This API allows a client to redeem a specified amount of tokens from a particular vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_id
`vi` | string | True | The unique identifier of the vault to redeem from. | | currency
`c` | string | True | The currency used for the redemption. This should be the vault's quote currency. | | num\_tokens
`nt` | string | True | The number of shares to redeem. | | signature
`s` | Signature | True | The digital signature from the investing account.
This signature must be generated by the main account ID and is used to verify the authenticity of the request.
The signature must comply with AccountPermExternalTransfer permission. | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | Back to top --- # Api withdrawal request - Gravity Markets API Docs Api withdrawal request ====================== [ApiWithdrawalRequest](https://api-docs.grvt.io/schemas/api_withdrawal_request) 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` | string | 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 | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | Back to top --- # Initial leverage result - Gravity Markets API Docs Initial leverage result ======================= [InitialLeverageResult](https://api-docs.grvt.io/schemas/initial_leverage_result) | 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 this instrument | | min\_leverage
`ml` | string | True | The min leverage user can set for this instrument | | max\_leverage
`ml1` | string | True | The max leverage user can set for this instrument | | margin\_type
`mt` | PositionMarginType | True | The margin type of this instrument | [PositionMarginType](https://api-docs.grvt.io/schemas/position_margin_type) | Value | Description | | --- | --- | | `ISOLATED` = 1 | Isolated Margin Mode: each position is allocated a fixed amount of collateral | | `CROSS` = 2 | Cross Margin Mode: uses all available funds in your account as collateral across all cross margin positions | Back to top --- # Order reject reason - Gravity Markets API Docs Order reject reason =================== [OrderRejectReason](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | Back to top --- # Query get list epoch request - Gravity Markets API Docs Query get list epoch request ============================ [QueryGetListEpochRequest](https://api-docs.grvt.io/schemas/query_get_list_epoch_request) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | limit
`l` | integer | False
`0` | The limit to query for | Back to top --- # Query main account leaderboard order by - Gravity Markets API Docs Query main account leaderboard order by ======================================= [QueryMainAccountLeaderboardOrderBy](https://api-docs.grvt.io/schemas/query_main_account_leaderboard_order_by) | Value | Description | | --- | --- | | `PNL` = 1 | Sort by realized PnL | | `TRADING_VOLUME` = 2 | Sort by trading volume | Back to top --- # Query find epoch request - Gravity Markets API Docs Query find epoch request ======================== [QueryFindEpochRequest](https://api-docs.grvt.io/schemas/query_find_epoch_request) Query epoch by time or epoch number | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | time
`t` | string | False
`0` | The time to query the epoch | | epoch
`e` | integer | False
`0` | The epoch number | Back to top --- # Reward epoch status - Gravity Markets API Docs Reward epoch status =================== [RewardEpochStatus](https://api-docs.grvt.io/schemas/reward_epoch_status) | Value | Description | | --- | --- | | `PAST` = 1 | Past | | `CURRENT` = 2 | Current | | `FUTURE` = 3 | Future | Back to top --- # Reward program type - Gravity Markets API Docs Reward program type =================== [RewardProgramType](https://api-docs.grvt.io/schemas/reward_program_type) | Value | Description | | --- | --- | | `ECOSYSTEM` = 1 | | | `TRADER` = 2 | | | `LP` = 3 | | Back to top --- # Source - Gravity Markets API Docs Source ====== [Source](https://api-docs.grvt.io/schemas/source) Defines the source of the order or trade, such as a UI, API, or a bot. This is used to track the source of the order, and is not signed by the client | Value | Description | | --- | --- | | `WEB` = 1 | The order/trade was created by a web client | | `MOBILE` = 2 | The order/trade was created by a mobile client | | `API` = 3 | The order/trade was created by an API client | | `LIQUIDATOR` = 4 | The order/trade was created by the liquidator service | Back to top --- # Spot balance - Gravity Markets API Docs Spot balance ============ [SpotBalance](https://api-docs.grvt.io/schemas/spot_balance) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | currency
`c` | string | 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`) | Back to top --- # Stream reference - Gravity Markets API Docs Stream reference ================ [StreamReference](https://api-docs.grvt.io/schemas/stream_reference) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of selectors for the stream | Back to top --- # Api pre deposit check request - Gravity Markets API Docs Api pre deposit check request ============================= [ApiPreDepositCheckRequest](https://api-docs.grvt.io/schemas/api_pre_deposit_check_request) UI only for bridge deposits through non native bridge. Currently only supports XY Finance bridge account. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | currency
`c` | Currency | True | The currency you hold the deposit in | | bridge
`b` | BridgeType | True | The bridge type to conduct checks for | [Currency](https://api-docs.grvt.io/schemas/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 | [BridgeType](https://api-docs.grvt.io/schemas/bridge_type) | Value | Description | | --- | --- | | `XY` = 1 | XY Bridge type | Back to top --- # Api query vault manager investor history response - Gravity Markets API Docs Api query vault manager investor history response ================================================= [ApiQueryVaultManagerInvestorHistoryResponse](https://api-docs.grvt.io/schemas/api_query_vault_manager_investor_history_response) Response to retrieve the vault summary for a given vault | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[ApiVaultInvestorHistory\] | True | The list of vault investor history belong to the manager | [ApiVaultInvestorHistory](https://api-docs.grvt.io/schemas/api_vault_investor_history) The vault investor history returned by the service to client | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | True | Time at which the event was emitted in unix nanoseconds | | off\_chain\_account\_id
`oc` | string | True | The off chain account id of the investor, only visible to the manager | | vault\_id
`vi` | string | True | The unique identifier of the vault. | | type
`t` | VaultInvestorAction | True | The type of transaction that occurred. List of types: vaultInvest, vaultBurnLpToken, vaultRedeem | | price
`p` | string | True | The price of the vault LP tokens at the time of the event. | | size
`s` | string | True | The amount of Vault LP tokens invested or redeemed. | | realized\_pnl
`rp` | string | True | The realized PnL of the vault. | | performance\_fee
`pf` | string | True | The performance fee of the vault. | [VaultInvestorAction](https://api-docs.grvt.io/schemas/vault_investor_action) | Value | Description | | --- | --- | | `UNSPECIFIED` = 0 | | | `VAULT_INVEST` = 1 | | | `VAULT_BURN_LP_TOKEN` = 2 | | | `VAULT_REDEEM` = 3 | | Back to top --- # Api set sub account position margin config request - Gravity Markets API Docs Api set sub account position margin config request ================================================== [ApiSetSubAccountPositionMarginConfigRequest](https://api-docs.grvt.io/schemas/api_set_sub_account_position_margin_config_request) Sets the margin type and leverage configuration for a specific position (instrument) within a sub account. This configuration is applied per-instrument, allowing different margin settings for different positions. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The sub account ID to set the margin type and leverage for | | instrument
`i` | string | True | The instrument of the position to set the margin type and leverage for | | margin\_type
`mt` | PositionMarginType | True | The margin type to set for the position | | leverage
`l` | string | True | The leverage to set for the position | | signature
`s` | Signature | True | The signature of this operation | [PositionMarginType](https://api-docs.grvt.io/schemas/position_margin_type) | Value | Description | | --- | --- | | `ISOLATED` = 1 | Isolated Margin Mode: each position is allocated a fixed amount of collateral | | `CROSS` = 2 | Cross Margin Mode: uses all available funds in your account as collateral across all cross margin positions | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | Back to top --- # Api settlement price response - Gravity Markets API Docs Api settlement price response ============================= [ApiSettlementPriceResponse](https://api-docs.grvt.io/schemas/api_settlement_price_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[APISettlementPrice\] | True | The funding rate result set for given interval | | next
`n` | string | False
`''` | The cursor to indicate when to start the next query from | [APISettlementPrice](https://api-docs.grvt.io/schemas/api_settlement_price) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | base
`b` | Currency | True | The base currency of the settlement price | | quote
`q` | Currency | True | The quote currency of the settlement price | | settlement\_time
`st` | string | True | The settlement timestamp of the settlement price, expressed in unix nanoseconds | | settlement\_price
`sp` | string | True | The settlement price, expressed in `9` decimals | [Currency](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api trade history response - Gravity Markets API Docs Api trade history response ========================== [ApiTradeHistoryResponse](https://api-docs.grvt.io/schemas/api_trade_history_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[Trade\] | True | The public trades matching the request asset | | next
`n` | string | False
`''` | The cursor to indicate when to start the next query from | [Trade](https://api-docs.grvt.io/schemas/trade) All private RFQs and Private AXEs will be filtered out from the responses | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | True | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | is\_taker\_buyer
`it` | boolean | True | If taker was the buyer 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 | | 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`. | | venue
`v` | Venue | True | The venue where the trade occurred | | is\_rpi
`ir1` | boolean | True | If the trade is a RPI trade | [Venue](https://api-docs.grvt.io/schemas/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 | Back to top --- # Orderbook levels - Gravity Markets API Docs Orderbook levels ================ [OrderbookLevels](https://api-docs.grvt.io/schemas/orderbook_levels) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | True | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | bids
`b` | \[OrderbookLevel\] | True | The list of best bids up till query depth | | asks
`a` | \[OrderbookLevel\] | True | The list of best asks up till query depth | [OrderbookLevel](https://api-docs.grvt.io/schemas/orderbook_level) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | price
`p` | string | True | The price of the level, expressed in `9` decimals | | size
`s` | string | True | The number of assets offered, expressed in base asset decimal units | | num\_orders
`no` | integer | True | The number of open orders at this level | [OrderbookLevel](https://api-docs.grvt.io/schemas/orderbook_level) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | price
`p` | string | True | The price of the level, expressed in `9` decimals | | size
`s` | string | True | The number of assets offered, expressed in base asset decimal units | | num\_orders
`no` | integer | True | The number of open orders at this level | Back to top --- # Sub account trade interval - Gravity Markets API Docs Sub account trade interval ========================== [SubAccountTradeInterval](https://api-docs.grvt.io/schemas/sub_account_trade_interval) | Value | Description | | --- | --- | | `SAT_1_MO` = 1 | 1 month | | `SAT_1_D` = 2 | 1 day | | `SAT_1_H` = 3 | 1 hour | | `SAT_4_H` = 4 | 4 hour | Back to top --- # Signature - Gravity Markets API Docs Signature ========= [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | Back to top --- # Session information - Gravity Markets API Docs Session information =================== [SessionInformation](https://api-docs.grvt.io/schemas/session_information) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | country\_code
`cc` | string | True | country code of user based on IP address | | client\_session\_id
`cs` | string | True | unique identity of the session generated from client | | device\_screen\_size
`ds` | string | True | screen size | | device\_os
`do` | string | True | OS of user's device | | device\_os\_version
`do1` | string | True | OS version of user's device | Back to top --- # Risk bracket - Gravity Markets API Docs Risk bracket ============ [RiskBracket](https://api-docs.grvt.io/schemas/risk_bracket) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | tier
`t` | integer | True | 1-indexed tier number | | notional\_floor
`nf` | string | True | Lower bound of notional value (inclusive) in quote currency | | notional\_cap
`nc` | string | False
`None` | Upper bound of notional value (exclusive) in quote currency, omitted for last tier | | maintenance\_margin\_rate
`mm` | string | True | Maintenance margin rate as a decimal (e.g., '0.01' for 1%) | | initial\_margin\_rate
`im` | string | True | Initial margin rate as a decimal (e.g., '0.02' for 2%) | | max\_leverage
`ml` | integer | True | Maximum leverage allowed at this tier (floor of 1 / initial\_margin\_rate) | | cumulative\_maintenance\_amount
`cm` | string | True | Cumulative maintenance margin amount in quote currency | Back to top --- # Time interval - Gravity Markets API Docs Time interval ============= [TimeInterval](https://api-docs.grvt.io/schemas/time_interval) Time interval can be used as a filter in metric/portfolio management APIs | Value | Description | | --- | --- | | `INTERVAL_1_D` = 1 | 1 day | | `INTERVAL_7_D` = 2 | 7 days | | `INTERVAL_30_D` = 3 | 30 days | | `INTERVAL_90_D` = 4 | 90 days | Back to top --- # Trader metric - Gravity Markets API Docs Trader metric ============= [TraderMetric](https://api-docs.grvt.io/schemas/trader_metric) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | total\_fee
`tf` | string | True | Total fee paid | | total\_point
`tp` | number | True | Total trader point of this epoch/phase | Back to top --- # Api get filtered instruments response - Gravity Markets API Docs Api get filtered instruments response ===================================== [ApiGetFilteredInstrumentsResponse](https://api-docs.grvt.io/schemas/api_get_filtered_instruments_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[InstrumentDisplay\] | True | The instruments matching the request filter | [InstrumentDisplay](https://api-docs.grvt.io/schemas/instrument_display) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | instrument\_hash
`ih` | string | True | The asset ID used for instrument signing. | | base
`b` | string | True | The base currency | | quote
`q` | string | True | The quote currency | | kind
`k` | Kind | True | The kind of instrument | | venues
`v` | \[Venue\] | True | Venues that this instrument can be traded at | | settlement\_period
`sp1` | InstrumentSettlementPeriod | True | The settlement period of the instrument | | base\_decimals
`bd` | integer | True | The smallest denomination of the base asset supported by GRVT (+3 represents 0.001, -3 represents 1000, 0 represents 1) | | quote\_decimals
`qd` | integer | True | The smallest denomination of the quote asset supported by GRVT (+3 represents 0.001, -3 represents 1000, 0 represents 1) | | tick\_size
`ts` | string | True | The size of a single tick, expressed in price decimal units | | min\_size
`ms` | string | True | The minimum contract size, expressed in base asset decimal units | | create\_time
`ct` | string | True | Creation time in unix nanoseconds | | max\_position\_size
`mp` | string | True | The maximum position size, expressed in base asset decimal units | | funding\_interval\_hours
`fi` | integer | False
`None` | Defines the funding interval to be applied. | | adjusted\_funding\_rate\_cap
`af` | string | False
`None` | Funding rate cap over the defined `intervalHours`. | | adjusted\_funding\_rate\_floor
`af1` | string | False
`None` | Funding rate floor over the defined `intervalHours`. | | min\_notional
`mn` | string | True | The minimum order notional value, expressed in quote currency decimal units | [Kind](https://api-docs.grvt.io/schemas/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 | [Venue](https://api-docs.grvt.io/schemas/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 | [InstrumentSettlementPeriod](https://api-docs.grvt.io/schemas/instrument_settlement_period) | Value | Description | | --- | --- | | `PERPETUAL` = 1 | Instrument settles through perpetual funding cycles | | `DAILY` = 2 | Instrument settles at an expiry date, marked as a daily instrument | | `WEEKLY` = 3 | Instrument settles at an expiry date, marked as a weekly instrument | | `MONTHLY` = 4 | Instrument settles at an expiry date, marked as a monthly instrument | | `QUARTERLY` = 5 | Instrument settles at an expiry date, marked as a quarterly instrument | Back to top --- # Api get list epoch badge response - Gravity Markets API Docs Api get list epoch badge response ================================= [ApiGetListEpochBadgeResponse](https://api-docs.grvt.io/schemas/api_get_list_epoch_badge_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[EpochBadge\] | True | The list of epoch badges | [EpochBadge](https://api-docs.grvt.io/schemas/epoch_badge) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_id
`ai` | string | True | The off chain account id | | main\_account\_id
`ma` | string | True | The account ID | | type
`t` | RewardProgramType | True | The type of the reward program | | epoch
`e` | integer | True | The epoch number | | epoch\_start\_time
`es` | string | True | The start time of the epoch | | epoch\_end\_time
`ee` | string | True | The end time of the epoch | | badge
`b` | EpochBadgeType | True | The type of the badge | | distributed\_badges
`db` | \[EpochBadgeType\] | True | The distributed badges | | total\_point
`tp` | string | True | Total point | | rank
`r` | integer | True | Rank | | claimed\_at
`ca` | string | True | The time when the badge was claimed, or the epoch end time if the user has already completed the KYC process | [RewardProgramType](https://api-docs.grvt.io/schemas/reward_program_type) | Value | Description | | --- | --- | | `ECOSYSTEM` = 1 | | | `TRADER` = 2 | | | `LP` = 3 | | [EpochBadgeType](https://api-docs.grvt.io/schemas/epoch_badge_type) | Value | Description | | --- | --- | | `CHAMPION` = 1 | Champion | | `LEGEND` = 2 | Legend | | `VETERAN` = 3 | Veteran | | `ELITE` = 4 | Elite | | `MASTER` = 5 | Master | | `EXPERT` = 6 | Expert | | `WARRIOR` = 7 | Warrior | | `SERGEANT` = 8 | Sergeant | | `RANGER` = 9 | Ranger | | `CHALLENGER` = 10 | Challenger | | `APPRENTICE` = 11 | Apprentice | | `ROOKIE` = 12 | Rookie | [EpochBadgeType](https://api-docs.grvt.io/schemas/epoch_badge_type) | Value | Description | | --- | --- | | `CHAMPION` = 1 | Champion | | `LEGEND` = 2 | Legend | | `VETERAN` = 3 | Veteran | | `ELITE` = 4 | Elite | | `MASTER` = 5 | Master | | `EXPERT` = 6 | Expert | | `WARRIOR` = 7 | Warrior | | `SERGEANT` = 8 | Sergeant | | `RANGER` = 9 | Ranger | | `CHALLENGER` = 10 | Challenger | | `APPRENTICE` = 11 | Apprentice | | `ROOKIE` = 12 | Rookie | Back to top --- # Api trade response - Gravity Markets API Docs Api trade response ================== [ApiTradeResponse](https://api-docs.grvt.io/schemas/api_trade_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[Trade\] | True | The public trades matching the request asset | [Trade](https://api-docs.grvt.io/schemas/trade) All private RFQs and Private AXEs will be filtered out from the responses | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | True | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | is\_taker\_buyer
`it` | boolean | True | If taker was the buyer 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 | | 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`. | | venue
`v` | Venue | True | The venue where the trade occurred | | is\_rpi
`ir1` | boolean | True | If the trade is a RPI trade | [Venue](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api transfer request - Gravity Markets API Docs Api transfer request ==================== [ApiTransferRequest](https://api-docs.grvt.io/schemas/api_transfer_request) 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` | string | 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 | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [TransferType](https://api-docs.grvt.io/schemas/transfer_type) | Value | Description | | --- | --- | | `UNSPECIFIED` = 0 | Default transfer that has nothing to do with bridging | | `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 | | `ADHOC_INCENTIVE` = 6 | Transfer type for adhoc incentive | | `REFERRAL_INCENTIVE` = 7 | Transfer type for referral incentive | | `TRADING_DEPOSIT_YIELD_INCENTIVE` = 8 | Transfer type for trading deposit yield incentive | Back to top --- # Api vault investor summary response - Gravity Markets API Docs Api vault investor summary response =================================== [ApiVaultInvestorSummaryResponse](https://api-docs.grvt.io/schemas/api_vault_investor_summary_response) Response payload for the summary of a vault investor. This API provides the summary of investments in a specific vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_investor\_summary
`vi` | \[VaultInvestorSummary\] | True | The summary of investments in the vault. | [VaultInvestorSummary](https://api-docs.grvt.io/schemas/vault_investor_summary) Vault investor summary information. This struct contains the summary of investments in a vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The unique identifier of the vault sub account. | | num\_lp\_tokens
`nl` | string | True | The number of Vault LP tokens held by the investor. | | avg\_entry\_price
`ae` | string | True | The average entry price (in USD) of the vault LP tokens. | | current\_price
`cp` | string | True | The current price (in USD) of the vault LP tokens. | | total\_equity
`te` | string | True | The current valuation (in USD) of all held vault LP tokens. | | all\_time\_realized\_pnl
`at` | string | True | The all-time realized PnL (in USD) that the investor has received from the vault. | | pending\_redemption
`pr` | VaultRedemption | False
`None` | The singleton pending redemption (omitted if none). | | can\_burn
`cb` | boolean | False
`true` | True if the requesting account is authorized to burn tokens on this vault, omitted otherwise. | [VaultRedemption](https://api-docs.grvt.io/schemas/vault_redemption) Vault redemption information. This struct contains information about a pending redemption from a vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | num\_lp\_tokens
`nl` | string | True | The number of LP Tokens requested for redemption. | | request\_valuation
`rv` | string | True | The valuation (in USD) of the redemption request. | | request\_time
`rt` | string | True | \[Filled by GRVT Backend\] Time at which the redemption request was received by GRVT in unix nanoseconds | | max\_redemption\_period\_timestamp
`mr` | string | True | \[Filled by GRVT Backend\] Time in unix nanoseconds, beyond which the request will be force-redeemed. | | cancel\_blocked
`cb` | boolean | False
`true` | Omitted for redemption requests to non-cross exchange vaults. True if cancellation is blocked within the CEV allocation allowance for the user's current tier (e.g. because the user has already transferred out the spot balance underlying the redemption request). | Back to top --- # Time in force - Gravity Markets API Docs Time in force ============= [TimeInForce](https://api-docs.grvt.io/schemas/time_in_force) | | 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. | Back to top --- # Trader leaderboard user - Gravity Markets API Docs Trader leaderboard user ======================= [TraderLeaderboardUser](https://api-docs.grvt.io/schemas/trader_leaderboard_user) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_id
`ai` | string | True | The off chain account id | | rank
`r` | integer | True | The rank of the account in the Trader | | total\_point
`tp` | number | True | Total Trader point | | twitter\_username
`tu` | string | True | The twitter username of the account | Back to top --- # Sub account trade aggregation - Gravity Markets API Docs Sub account trade aggregation ============================= [SubAccountTradeAggregation](https://api-docs.grvt.io/schemas/sub_account_trade_aggregation) Similar to sub-account trade, but not divided by individual assets. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The sub account id | | total\_fee
`tf` | string | True | Total fee paid | | total\_trade\_volume
`tt` | string | True | Total volume traded | | num\_traded
`nt` | string | True | Number of trades | | positive\_fee
`pf` | string | True | Total positive fee paid by user | | signer
`s` | string | True | The signer of the trade | | realized\_pnl
`rp` | string | True | Realized PnL | Back to top --- # User category affinity score - Gravity Markets API Docs User category affinity score ============================ [UserCategoryAffinityScore](https://api-docs.grvt.io/schemas/user_category_affinity_score) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_id
`ai` | string | True | The off chain account id | | category\_id
`ci` | string | True | target category | | affinity\_score
`as` | number | True | affinity score | Back to top --- # Vault type - Gravity Markets API Docs Vault type ========== [VaultType](https://api-docs.grvt.io/schemas/vault_type) | Value | Description | | --- | --- | | `PRIME` = 1 | Prime vault | | `LAUNCH_PAD` = 2 | Launchpad vault | Back to top --- # Vault investor action - Gravity Markets API Docs Vault investor action ===================== [VaultInvestorAction](https://api-docs.grvt.io/schemas/vault_investor_action) | Value | Description | | --- | --- | | `UNSPECIFIED` = 0 | | | `VAULT_INVEST` = 1 | | | `VAULT_BURN_LP_TOKEN` = 2 | | | `VAULT_REDEEM` = 3 | | Back to top --- # Api get instrument response - Gravity Markets API Docs Api get instrument response =========================== [ApiGetInstrumentResponse](https://api-docs.grvt.io/schemas/api_get_instrument_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | InstrumentDisplay | True | The instrument matching the request asset | [InstrumentDisplay](https://api-docs.grvt.io/schemas/instrument_display) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | instrument\_hash
`ih` | string | True | The asset ID used for instrument signing. | | base
`b` | string | True | The base currency | | quote
`q` | string | True | The quote currency | | kind
`k` | Kind | True | The kind of instrument | | venues
`v` | \[Venue\] | True | Venues that this instrument can be traded at | | settlement\_period
`sp1` | InstrumentSettlementPeriod | True | The settlement period of the instrument | | base\_decimals
`bd` | integer | True | The smallest denomination of the base asset supported by GRVT (+3 represents 0.001, -3 represents 1000, 0 represents 1) | | quote\_decimals
`qd` | integer | True | The smallest denomination of the quote asset supported by GRVT (+3 represents 0.001, -3 represents 1000, 0 represents 1) | | tick\_size
`ts` | string | True | The size of a single tick, expressed in price decimal units | | min\_size
`ms` | string | True | The minimum contract size, expressed in base asset decimal units | | create\_time
`ct` | string | True | Creation time in unix nanoseconds | | max\_position\_size
`mp` | string | True | The maximum position size, expressed in base asset decimal units | | funding\_interval\_hours
`fi` | integer | False
`None` | Defines the funding interval to be applied. | | adjusted\_funding\_rate\_cap
`af` | string | False
`None` | Funding rate cap over the defined `intervalHours`. | | adjusted\_funding\_rate\_floor
`af1` | string | False
`None` | Funding rate floor over the defined `intervalHours`. | | min\_notional
`mn` | string | True | The minimum order notional value, expressed in quote currency decimal units | [Kind](https://api-docs.grvt.io/schemas/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 | [Venue](https://api-docs.grvt.io/schemas/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 | [InstrumentSettlementPeriod](https://api-docs.grvt.io/schemas/instrument_settlement_period) | Value | Description | | --- | --- | | `PERPETUAL` = 1 | Instrument settles through perpetual funding cycles | | `DAILY` = 2 | Instrument settles at an expiry date, marked as a daily instrument | | `WEEKLY` = 3 | Instrument settles at an expiry date, marked as a weekly instrument | | `MONTHLY` = 4 | Instrument settles at an expiry date, marked as a monthly instrument | | `QUARTERLY` = 5 | Instrument settles at an expiry date, marked as a quarterly instrument | Back to top --- # Api positions response - Gravity Markets API Docs Api positions response ====================== [ApiPositionsResponse](https://api-docs.grvt.io/schemas/api_positions_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[Positions\] | True | The positions matching the request filter | [Positions](https://api-docs.grvt.io/schemas/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 | | cumulative\_fee
`cf` | string | True | The cumulative fee paid on the position, expressed in quote asset decimal units | | cumulative\_realized\_funding\_payment
`cr` | string | True | The cumulative realized funding payment of the position, expressed in quote asset decimal units. Positive if paid, negative if received | | margin\_type
`mt` | PositionMarginType | True | The margin type of the position | | isolated\_balance
`ib` | string | False
`None` | \[IsolatedOnly\] The wallet balance reserved for this isolated margin position, expressed in quote asset decimal units. If this positions is liquidated, this is the maximal balance that can be lost | | isolated\_im
`ii` | string | False
`None` | \[IsolatedOnly\] The initial margin of the isolated margin position, expressed in quote asset decimal units. The `total_equity` required to open more size in the position | | isolated\_mm
`im` | string | False
`None` | \[IsolatedOnly\] The maintenance margin of the isolated margin position, expressed in quote asset decimal units. The `total_equity` required to avoid liquidation of the position | [PositionMarginType](https://api-docs.grvt.io/schemas/position_margin_type) | Value | Description | | --- | --- | | `ISOLATED` = 1 | Isolated Margin Mode: each position is allocated a fixed amount of collateral | | `CROSS` = 2 | Cross Margin Mode: uses all available funds in your account as collateral across all cross margin positions | Back to top --- # Api withdrawal history response - Gravity Markets API Docs Api withdrawal history response =============================== [ApiWithdrawalHistoryResponse](https://api-docs.grvt.io/schemas/api_withdrawal_history_response) | 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](https://api-docs.grvt.io/schemas/withdrawal_history) | 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` | string | 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 | | l\_1\_hash
`l1` | string | False
`''` | The finalized withdrawal transaction hash on L1, empty if the withdrawal is 'pending'. | | l\_2\_hash
`l2` | string | True | The transaction hash on L2 | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | Back to top --- # Jsonrpc response - Gravity Markets API Docs Jsonrpc response ================ [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | Back to top --- # Query epoch badge point distribution request - Gravity Markets API Docs Query epoch badge point distribution request ============================================ [QueryEpochBadgePointDistributionRequest](https://api-docs.grvt.io/schemas/query_epoch_badge_point_distribution_request) Query list of epoch badges | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | epoch
`e` | integer | False
`'all'` | The numerical epoch index | | type
`t` | RewardProgramType | True | The type of the reward program | [RewardProgramType](https://api-docs.grvt.io/schemas/reward_program_type) | Value | Description | | --- | --- | | `ECOSYSTEM` = 1 | | | `TRADER` = 2 | | | `LP` = 3 | | Back to top --- # Query epoch badge request - Gravity Markets API Docs Query epoch badge request ========================= [QueryEpochBadgeRequest](https://api-docs.grvt.io/schemas/query_epoch_badge_request) Query list of epoch badges | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_id
`ai` | string | False
`'all'` | The off chain account id to get referral stats | | epoch
`e` | integer | False
`'all'` | The numerical epoch index | | type
`t` | RewardProgramType | False
`'all'` | The type of the reward program | | limit
`l` | integer | False
`'500'` | The limit to query for. Defaults to 500; Max 1000 | | cursor
`c` | string | False
`'all'` | The cursor to indicate when to start the query from | [RewardProgramType](https://api-docs.grvt.io/schemas/reward_program_type) | Value | Description | | --- | --- | | `ECOSYSTEM` = 1 | | | `TRADER` = 2 | | | `LP` = 3 | | Back to top --- # Positions - Gravity Markets API Docs Positions ========= [Positions](https://api-docs.grvt.io/schemas/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 | | cumulative\_fee
`cf` | string | True | The cumulative fee paid on the position, expressed in quote asset decimal units | | cumulative\_realized\_funding\_payment
`cr` | string | True | The cumulative realized funding payment of the position, expressed in quote asset decimal units. Positive if paid, negative if received | | margin\_type
`mt` | PositionMarginType | True | The margin type of the position | | isolated\_balance
`ib` | string | False
`None` | \[IsolatedOnly\] The wallet balance reserved for this isolated margin position, expressed in quote asset decimal units. If this positions is liquidated, this is the maximal balance that can be lost | | isolated\_im
`ii` | string | False
`None` | \[IsolatedOnly\] The initial margin of the isolated margin position, expressed in quote asset decimal units. The `total_equity` required to open more size in the position | | isolated\_mm
`im` | string | False
`None` | \[IsolatedOnly\] The maintenance margin of the isolated margin position, expressed in quote asset decimal units. The `total_equity` required to avoid liquidation of the position | [PositionMarginType](https://api-docs.grvt.io/schemas/position_margin_type) | Value | Description | | --- | --- | | `ISOLATED` = 1 | Isolated Margin Mode: each position is allocated a fixed amount of collateral | | `CROSS` = 2 | Cross Margin Mode: uses all available funds in your account as collateral across all cross margin positions | Back to top --- # Query get latest lp snapshot response - Gravity Markets API Docs Query get latest lp snapshot response ===================================== [QueryGetLatestLPSnapshotResponse](https://api-docs.grvt.io/schemas/query_get_latest_lp_snapshot_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | snapshot
`s` | LPSnapshot | True | The latest LP snapshot | [LPSnapshot](https://api-docs.grvt.io/schemas/lp_snapshot) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | main\_account\_id
`ma` | string | True | The main account id | | lp\_asset
`la` | string | True | The LP Asset | | underlying\_multiplier
`um` | string | True | Underlying multiplier | | maker\_trading\_volume
`mt` | string | True | Maker trading volume | | bid\_fast\_market\_multiplier
`bf` | integer | True | Fast market multiplier | | ask\_fast\_market\_multiplier
`af` | integer | True | Fast market multiplier | | liquidity\_score
`ls` | string | True | Liquidity score | | calculate\_at
`ca` | string | True | The time when the snapshot was calculated | Back to top --- # Query get list epoch response - Gravity Markets API Docs Query get list epoch response ============================= [QueryGetListEpochResponse](https://api-docs.grvt.io/schemas/query_get_list_epoch_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[Epoch\] | True | The list of epochs | [Epoch](https://api-docs.grvt.io/schemas/epoch) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | epoch
`e` | integer | True | The epoch number | | start\_time
`st` | string | True | The start time of the epoch | | end\_time
`et` | string | True | The end time of the epoch | Back to top --- # Query find epoch response - Gravity Markets API Docs Query find epoch response ========================= [QueryFindEpochResponse](https://api-docs.grvt.io/schemas/query_find_epoch_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | epoch
`e` | Epoch | True | The epoch | [Epoch](https://api-docs.grvt.io/schemas/epoch) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | epoch
`e` | integer | True | The epoch number | | start\_time
`st` | string | True | The start time of the epoch | | end\_time
`et` | string | True | The end time of the epoch | Back to top --- # Reward epoch info - Gravity Markets API Docs Reward epoch info ================= [RewardEpochInfo](https://api-docs.grvt.io/schemas/reward_epoch_info) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | epoch
`e` | integer | True | The epoch number | | epoch\_start\_time
`es` | string | True | The start time of the epoch | | epoch\_end\_time
`ee` | string | True | The end time of the epoch | | status
`s` | RewardEpochStatus | True | The status of the epoch | [RewardEpochStatus](https://api-docs.grvt.io/schemas/reward_epoch_status) | Value | Description | | --- | --- | | `PAST` = 1 | Past | | `CURRENT` = 2 | Current | | `FUTURE` = 3 | Future | Back to top --- # Venue - Gravity Markets API Docs Venue ===== [Venue](https://api-docs.grvt.io/schemas/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 | Back to top --- # Ticker - Gravity Markets API Docs Ticker ====== [Ticker](https://api-docs.grvt.io/schemas/ticker) Derived data such as the below, will not be included by default: \- 24 hour volume (`buyVolume + sellVolume`) \- 24 hour taker buy/sell ratio (`buyVolume / sellVolume`) \- 24 hour average trade price (`volumeQ / volumeU`) \- 24 hour average trade volume (`volume / trades`) \- 24 hour percentage change (`24hStatChange / 24hStat`) \- 48 hour statistics (`2 * 24hStat - 24hStatChange`) To query for an extended ticker payload, leverage the `greeks` and the `derived` flags. Ticker extensions are currently under design to offer you more convenience. These flags are only supported on the `Ticker Snapshot` WS endpoint, and on the `Ticker` API endpoint. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | False
`None` | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | False
`None` | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | mark\_price
`mp` | string | False
`None` | The mark price of the instrument, expressed in `9` decimals | | index\_price
`ip` | string | False
`None` | The index price of the instrument, expressed in `9` decimals | | last\_price
`lp` | string | False
`None` | The last traded price of the instrument (also close price), expressed in `9` decimals | | last\_size
`ls` | string | False
`None` | The number of assets traded in the last trade, expressed in base asset decimal units | | mid\_price
`mp1` | string | False
`None` | The mid price of the instrument, expressed in `9` decimals | | best\_bid\_price
`bb` | string | False
`None` | The best bid price of the instrument, expressed in `9` decimals | | best\_bid\_size
`bb1` | string | False
`None` | The number of assets offered on the best bid price of the instrument, expressed in base asset decimal units | | best\_ask\_price
`ba` | string | False
`None` | The best ask price of the instrument, expressed in `9` decimals | | best\_ask\_size
`ba1` | string | False
`None` | The number of assets offered on the best ask price of the instrument, expressed in base asset decimal units | | funding\_rate\_8h\_curr
`fr` | string | False
`None` | DEPRECATED: To be removed in a future release. Please refer to the field `funding_rate` instead, for the funding rate being applied over `funding_interval_hours` (interval ending at `next_funding_time`). | | funding\_rate\_8h\_avg
`fr1` | string | False
`None` | DEPRECATED: To be removed in a future release. Please refer to the field `funding_rate` instead, for the funding rate being applied over `funding_interval_hours` (interval ending at `next_funding_time`). | | interest\_rate
`ir` | string | False
`None` | The interest rate of the underlying, expressed in centibeeps (1/100th of a basis point) | | forward\_price
`fp` | string | False
`None` | \[Options\] The forward price of the option, expressed in `9` decimals | | buy\_volume\_24h\_b
`bv` | string | False
`None` | The 24 hour taker buy volume of the instrument, expressed in base asset decimal units | | sell\_volume\_24h\_b
`sv` | string | False
`None` | The 24 hour taker sell volume of the instrument, expressed in base asset decimal units | | buy\_volume\_24h\_q
`bv1` | string | False
`None` | The 24 hour taker buy volume of the instrument, expressed in quote asset decimal units | | sell\_volume\_24h\_q
`sv1` | string | False
`None` | The 24 hour taker sell volume of the instrument, expressed in quote asset decimal units | | high\_price
`hp` | string | False
`None` | The 24 hour highest traded price of the instrument, expressed in `9` decimals | | low\_price
`lp1` | string | False
`None` | The 24 hour lowest traded price of the instrument, expressed in `9` decimals | | open\_price
`op` | string | False
`None` | The 24 hour first traded price of the instrument, expressed in `9` decimals | | open\_interest
`oi` | string | False
`None` | The open interest in the instrument, expressed in base asset decimal units | | long\_short\_ratio
`ls1` | string | False
`None` | The ratio of accounts that are net long vs net short on this instrument | | funding\_rate
`fr2` | string | False
`None` | The current indicative funding rate for the active interval, expressed in centibeeps | | next\_funding\_time
`nf` | string | False
`None` | Timestamp in nanoseconds when the current funding interval ends | Back to top --- # Trigger by - Gravity Markets API Docs Trigger by ========== [TriggerBy](https://api-docs.grvt.io/schemas/trigger_by) 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 | | `MID` = 3 | MID - Order is activated when the mid price reaches the trigger price | | `MARK` = 4 | MARK - Order is activated when the mark price reaches the trigger price | Back to top --- # Transfer type - Gravity Markets API Docs Transfer type ============= [TransferType](https://api-docs.grvt.io/schemas/transfer_type) | Value | Description | | --- | --- | | `UNSPECIFIED` = 0 | Default transfer that has nothing to do with bridging | | `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 | | `ADHOC_INCENTIVE` = 6 | Transfer type for adhoc incentive | | `REFERRAL_INCENTIVE` = 7 | Transfer type for referral incentive | | `TRADING_DEPOSIT_YIELD_INCENTIVE` = 8 | Transfer type for trading deposit yield incentive | Back to top --- # Transaction type - Gravity Markets API Docs Transaction type ================ [TransactionType](https://api-docs.grvt.io/schemas/transaction_type) | Value | Description | | --- | --- | | `UNSPECIFIED_1` = 1 | | | `UNSPECIFIED_2` = 2 | | | `UNSPECIFIED_3` = 3 | | | `CREATE_ACCOUNT` = 4 | | | `CREATE_SUB_ACCOUNT` = 5 | | | `SET_ACCOUNT_MULTI_SIG_THRESHOLD` = 6 | | | `ADD_ACCOUNT_SIGNER` = 7 | | | `REMOVE_ACCOUNT_SIGNER` = 8 | | | `ADD_WITHDRAWAL_ADDRESS` = 9 | | | `REMOVE_WITHDRAWAL_ADDRESS` = 10 | | | `ADD_TRANSFER_ACCOUNT` = 11 | | | `REMOVE_TRANSFER_ACCOUNT` = 12 | | | `SET_SUB_ACCOUNT_MARGIN_TYPE` = 13 | | | `ADD_SUB_ACCOUNT_SIGNER` = 14 | | | `REMOVE_SUB_ACCOUNT_SIGNER` = 15 | | | `ADD_SESSION_KEY` = 16 | | | `REMOVE_SESSION_KEY` = 17 | | | `DEPOSIT` = 18 | | | `WITHDRAWAL` = 19 | | | `TRANSFER` = 20 | | | `MARK_PRICE_TICK` = 21 | | | `SETTLEMENT_PRICE_TICK` = 22 | | | `FUNDING_TICK` = 23 | | | `INTEREST_RATE_TICK` = 24 | | | `SCHEDULE_CONFIG` = 25 | | | `SET_CONFIG` = 26 | | | `TRADE` = 27 | | | `ADD_RECOVERY_ADDRESS` = 28 | | | `REMOVE_RECOVERY_ADDRESS` = 29 | | | `RECOVER_ADDRESS` = 30 | | | `SETTLE_START` = 31 | | | `SETTLE_INSTRUMENTS` = 32 | | | `SETTLE_SOCIALISED_LOSS` = 33 | | | `SETTLE_END` = 34 | | | `SCHEDULE_SIMPLE_CROSS_MAINTENANCE_MARGIN_TIERS` = 35 | | | `SET_SIMPLE_CROSS_MAINTENANCE_MARGIN_TIERS` = 36 | | | `INITIALIZE_CONFIG` = 37 | | | `CREATE_ACCOUNT_WITH_SUB_ACCOUNT` = 38 | | | `VAULT_CREATE` = 39 | | | `VAULT_UPDATE` = 40 | | | `VAULT_DELIST` = 41 | | | `VAULT_CLOSE` = 42 | | | `VAULT_INVEST` = 43 | | | `VAULT_BURN_LP_TOKEN` = 44 | | | `VAULT_REDEEM` = 45 | | | `VAULT_MANAGEMENT_FEE_TICK` = 46 | | | `ADD_CURRENCY` = 47 | | | `SET_DERISK_TO_MAINTENANCE_MARGIN_RATIO` = 48 | | Back to top --- # Api order state response - Gravity Markets API Docs Api order state response ======================== [ApiOrderStateResponse](https://api-docs.grvt.io/schemas/api_order_state_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | state
`s` | OrderState | True | The order state for the requested filter | [OrderState](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | Back to top --- # Api pre order check response - Gravity Markets API Docs Api pre order check response ============================ [ApiPreOrderCheckResponse](https://api-docs.grvt.io/schemas/api_pre_order_check_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | results
`r` | \[PreOrderCheckResult\] | True | Pre order check for each new order in the request | [PreOrderCheckResult](https://api-docs.grvt.io/schemas/pre_order_check_result) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | max\_qty
`mq` | \[AssetMaxQty\] | True | The maximum quantity for each leg | | margin\_required
`mr` | string | True | The margin required for the order (reported in `settle_currency`) | | order\_valid
`ov` | boolean | True | Whether the order is valid | | reason
`r` | string | True | The reason the order is invalid, if any | | settle\_currency
`sc` | Currency | True | The subAccount settle currency | [AssetMaxQty](https://api-docs.grvt.io/schemas/asset_max_qty) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | asset
`a` | string | True | The asset associated with the max quantity | | max\_buy\_qty
`mb` | string | True | The maximum buy quantity | | max\_sell\_qty
`ms` | string | True | The maximum sell quantity | [Currency](https://api-docs.grvt.io/schemas/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 | Back to top --- # Epoch badge point distribution - Gravity Markets API Docs Epoch badge point distribution ============================== [EpochBadgePointDistribution](https://api-docs.grvt.io/schemas/epoch_badge_point_distribution) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | badge
`b` | EpochBadgeType | True | The type of the badge | | epoch
`e` | integer | True | The epoch number | | type
`t` | RewardProgramType | True | The type of the reward program | | min\_point
`mp` | string | True | The minimum point to get the badge | | max\_point
`mp1` | string | True | The maximum point to get the badge | | min\_rank
`mr` | integer | True | The minimum rank to get the badge | | max\_rank
`mr1` | integer | True | The maximum rank to get the badge | | total\_point
`tp` | string | True | The total point to get the badge | | count
`c` | integer | True | The number of users to get the badge | [EpochBadgeType](https://api-docs.grvt.io/schemas/epoch_badge_type) | Value | Description | | --- | --- | | `CHAMPION` = 1 | Champion | | `LEGEND` = 2 | Legend | | `VETERAN` = 3 | Veteran | | `ELITE` = 4 | Elite | | `MASTER` = 5 | Master | | `EXPERT` = 6 | Expert | | `WARRIOR` = 7 | Warrior | | `SERGEANT` = 8 | Sergeant | | `RANGER` = 9 | Ranger | | `CHALLENGER` = 10 | Challenger | | `APPRENTICE` = 11 | Apprentice | | `ROOKIE` = 12 | Rookie | [RewardProgramType](https://api-docs.grvt.io/schemas/reward_program_type) | Value | Description | | --- | --- | | `ECOSYSTEM` = 1 | | | `TRADER` = 2 | | | `LP` = 3 | | Back to top --- # Epoch badge - Gravity Markets API Docs Epoch badge =========== [EpochBadge](https://api-docs.grvt.io/schemas/epoch_badge) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_id
`ai` | string | True | The off chain account id | | main\_account\_id
`ma` | string | True | The account ID | | type
`t` | RewardProgramType | True | The type of the reward program | | epoch
`e` | integer | True | The epoch number | | epoch\_start\_time
`es` | string | True | The start time of the epoch | | epoch\_end\_time
`ee` | string | True | The end time of the epoch | | badge
`b` | EpochBadgeType | True | The type of the badge | | distributed\_badges
`db` | \[EpochBadgeType\] | True | The distributed badges | | total\_point
`tp` | string | True | Total point | | rank
`r` | integer | True | Rank | | claimed\_at
`ca` | string | True | The time when the badge was claimed, or the epoch end time if the user has already completed the KYC process | [RewardProgramType](https://api-docs.grvt.io/schemas/reward_program_type) | Value | Description | | --- | --- | | `ECOSYSTEM` = 1 | | | `TRADER` = 2 | | | `LP` = 3 | | [EpochBadgeType](https://api-docs.grvt.io/schemas/epoch_badge_type) | Value | Description | | --- | --- | | `CHAMPION` = 1 | Champion | | `LEGEND` = 2 | Legend | | `VETERAN` = 3 | Veteran | | `ELITE` = 4 | Elite | | `MASTER` = 5 | Master | | `EXPERT` = 6 | Expert | | `WARRIOR` = 7 | Warrior | | `SERGEANT` = 8 | Sergeant | | `RANGER` = 9 | Ranger | | `CHALLENGER` = 10 | Challenger | | `APPRENTICE` = 11 | Apprentice | | `ROOKIE` = 12 | Rookie | [EpochBadgeType](https://api-docs.grvt.io/schemas/epoch_badge_type) | Value | Description | | --- | --- | | `CHAMPION` = 1 | Champion | | `LEGEND` = 2 | Legend | | `VETERAN` = 3 | Veteran | | `ELITE` = 4 | Elite | | `MASTER` = 5 | Master | | `EXPERT` = 6 | Expert | | `WARRIOR` = 7 | Warrior | | `SERGEANT` = 8 | Sergeant | | `RANGER` = 9 | Ranger | | `CHALLENGER` = 10 | Challenger | | `APPRENTICE` = 11 | Apprentice | | `ROOKIE` = 12 | Rookie | Back to top --- # Cancel status feed - Gravity Markets API Docs Cancel status feed ================== [CancelStatusFeed](https://api-docs.grvt.io/schemas/cancel_status_feed) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The subaccount ID that requested the cancellation | | client\_order\_id
`co` | string | True | A unique identifier for the active order within a subaccount, specified by the client | | order\_id
`oi` | string | True | A unique 128-bit identifier for the order, deterministically generated within the GRVT backend | | reason
`r` | OrderRejectReason | True | The user-provided reason for cancelling the order | | update\_time
`ut` | string | False
`0` | \[Filled by GRVT Backend\] Time at which the cancellation status was updated by GRVT in unix nanoseconds | | cancel\_status
`cs` | CancelStatus | True | Status of the cancellation attempt | [OrderRejectReason](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | [CancelStatus](https://api-docs.grvt.io/schemas/cancel_status) | Value | Description | | --- | --- | | `EXPIRED` = 1 | Cancellation has expired because corresponding order had not arrived within the defined time-to-live window. | | `DROPPED_DUPLICATE` = 2 | This cancellation request was dropped because its TTL window overlaps with another cancellation request for the same order. | Back to top --- # Fill - Gravity Markets API Docs Fill ==== [Fill](https://api-docs.grvt.io/schemas/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 | | is\_liquidation
`il` | boolean | True | If the trade was a liquidation | | 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 | | builder
`b1` | string | True | The main account ID of the builder. referred to Order.builder | | builder\_fee\_rate
`bf` | string | True | Builder fee percentage charged for this order. referred to Order.builder builderFee | | builder\_fee
`bf1` | string | True | The builder fee paid on the trade, expressed in quote asset decimal unit. referred to Trade.builderFee | [Venue](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/broker_tag) 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 | Back to top --- # Funding account summary - Gravity Markets API Docs Funding account summary ======================= [FundingAccountSummary](https://api-docs.grvt.io/schemas/funding_account_summary) 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 | | vault\_investments
`vi` | \[VaultInvestment\] | True | The list of vault investments held by this main account | [SpotBalance](https://api-docs.grvt.io/schemas/spot_balance) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | currency
`c` | string | 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`) | [VaultInvestment](https://api-docs.grvt.io/schemas/vault_investment) Summarizes a vault investment held by a funding account | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_id
`vi` | string | True | The trading account ID of the vault invested in. | | num\_lp\_tokens
`nl` | string | True | The number of shares held by the investor. | | share\_price
`sp` | string | True | The current share price (in USD) of this vault investment. | | usd\_notional\_invested
`un` | string | True | The USD notional invested in this vault investment. | Back to top --- # Trigger type - Gravity Markets API Docs Trigger type ============ [TriggerType](https://api-docs.grvt.io/schemas/trigger_type) 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. | Back to top --- # User tracking event - Gravity Markets API Docs User tracking event =================== [UserTrackingEvent](https://api-docs.grvt.io/schemas/user_tracking_event) event of user | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_id
`ei` | string | True | uuid for event | | tracking\_version
`tv` | integer | True | version of tracking | | event\_time
`et` | string | True | timestamp of event | | event\_type
`et1` | string | True | event type | | event\_sub\_type
`es` | string | True | event sub type | | client\_session\_id
`cs` | string | True | unique identity of the session generated from client | | device\_os
`do` | string | True | OS of user's device | | device\_os\_version
`do1` | string | True | OS version of user's device | | sub\_account\_id
`sa` | string | True | sub account id | | trading\_address
`ta` | string | True | trading session key | | screen\_size
`ss` | string | True | screen size | | event\_data
`ed` | string | True | event data | | user\_id
`ui` | string | True | user id | | account\_id
`ai` | string | True | account id | | auth\_session\_hash
`as` | string | True | auth session hash of the authenticated session on backend | | country\_code
`cc` | string | True | country code of user based on IP address | Back to top --- # User vault category event pay load - Gravity Markets API Docs User vault category event pay load ================================== [UserVaultCategoryEventPayLoad](https://api-docs.grvt.io/schemas/user_vault_category_event_pay_load) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | category\_id
`ci` | string | True | category ID of event | | vault\_id
`vi` | string | True | vault ID | | action
`a` | string | True | action of event. search/filter/invest... | | num\_bumps
`nb` | string | True | number of bumps in this event. default 1 | Back to top --- # Vault investment - Gravity Markets API Docs Vault investment ================ [VaultInvestment](https://api-docs.grvt.io/schemas/vault_investment) Summarizes a vault investment held by a funding account | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_id
`vi` | string | True | The trading account ID of the vault invested in. | | num\_lp\_tokens
`nl` | string | True | The number of shares held by the investor. | | share\_price
`sp` | string | True | The current share price (in USD) of this vault investment. | | usd\_notional\_invested
`un` | string | True | The USD notional invested in this vault investment. | Back to top --- # Vault redemption - Gravity Markets API Docs Vault redemption ================ [VaultRedemption](https://api-docs.grvt.io/schemas/vault_redemption) Vault redemption information. This struct contains information about a pending redemption from a vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | num\_lp\_tokens
`nl` | string | True | The number of LP Tokens requested for redemption. | | request\_valuation
`rv` | string | True | The valuation (in USD) of the redemption request. | | request\_time
`rt` | string | True | \[Filled by GRVT Backend\] Time at which the redemption request was received by GRVT in unix nanoseconds | | max\_redemption\_period\_timestamp
`mr` | string | True | \[Filled by GRVT Backend\] Time in unix nanoseconds, beyond which the request will be force-redeemed. | | cancel\_blocked
`cb` | boolean | False
`true` | Omitted for redemption requests to non-cross exchange vaults. True if cancellation is blocked within the CEV allocation allowance for the user's current tier (e.g. because the user has already transferred out the spot balance underlying the redemption request). | Back to top --- # Ws list streams params - Gravity Markets API Docs Ws list streams params ====================== [WSListStreamsParams](https://api-docs.grvt.io/schemas/ws_list_streams_params) List down all the streams this connection has connected to. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | | | | | Back to top --- # Vault redemption req age category - Gravity Markets API Docs Vault redemption req age category ================================= [VaultRedemptionReqAgeCategory](https://api-docs.grvt.io/schemas/vault_redemption_req_age_category) Denotes the age category of a given redemption request. | Value | Description | | --- | --- | | `NORMAL` = 1 | This request is at least as old as the minimum redemption period, and is eligible for automated redemption. | | `URGENT` = 2 | This request is nearing the maxmimum redemption period and will be factored into pre-order check margin requirements. | | `OVERDUE` = 3 | This request has exceeded the maximum redemption period and will be considered for forced redemptions. | | `PRE_MIN` = 4 | This request has yet to exceed the minimum redemption period, and is not yet eligible for automated redemption. | Back to top --- # Sub account trade - Gravity Markets API Docs Sub account trade ================= [SubAccountTrade](https://api-docs.grvt.io/schemas/sub_account_trade) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | start\_interval
`si` | string | True | Start of calculation epoch | | sub\_account\_id
`sa` | string | True | The sub account id | | instrument
`i` | string | True | The instrument being represented | | total\_fee
`tf` | string | True | Total fee paid | | total\_trade\_volume
`tt` | string | True | Total volume traded | Back to top --- # Ws deposit feed selector v1 - Gravity Markets API Docs Ws deposit feed selector v1 =========================== [WSDepositFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_deposit_feed_selector_v1) Subscribes to a feed of deposits. This will execute when there is any deposit to selected account. To subscribe to a main account, specify the account ID (eg. `0x9fe3758b67ce7a2875ee4b452f01a5282d84ed8a`). | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | main\_account\_id
`ma` | string | True | The main account ID to request for | Back to top --- # Ws order group feed selector v1 - Gravity Markets API Docs Ws order group feed selector v1 =============================== [WSOrderGroupFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_order_group_feed_selector_v1) Subscribes to a feed of order group to get updated when a new group is created for the subAccount specified. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The subaccount ID to filter by | Back to top --- # Ws cancel feed selector v1 - Gravity Markets API Docs Ws cancel feed selector v1 ========================== [WSCancelFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_cancel_feed_selector_v1) Subscribes to a feed of time-to-live expiry events for order cancellations requested by a given subaccount. **This stream presently only provides expiry updates for cancel-order requests set with a valid TTL value**. Successful order cancellations will reflect as updates published to the [order-state stream](https://api-docs.grvt.io/trading_streams/#order-state) . _A future release will expand the functionality of this stream to provide more general status updates on order cancellation requests._ Each Order can be uniquely identified by its `client_order_id`. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The subaccount ID to filter by | Back to top --- # Ws fill feed selector v1 - Gravity Markets API Docs Ws fill feed selector v1 ======================== [WSFillFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_fill_feed_selector_v1) Subscribes to a feed of private trade updates. This happens when a trade is executed. To subscribe to all private trades, specify an empty `instrument` (eg. `2345123`). Otherwise, specify the `instrument` to only receive private trades for that instrument (eg. `2345123-BTC_USDT_Perp`). | 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 instrument filter to apply. | Back to top --- # Ws order state feed selector v1 - Gravity Markets API Docs Ws order state feed selector v1 =============================== [WSOrderStateFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_order_state_feed_selector_v1) Subscribes to a feed of order updates pertaining to orders made by your account. Unlike the Order Stream, this only streams state updates, drastically improving throughput, and latency. Each Order can be uniquely identified by its `order_id` or `client_order_id`. To subscribe to all orders, specify an empty `instrument` (eg. `2345123`). Otherwise, specify the `instrument` to only receive orders for that instrument (eg. `2345123-BTC_USDT_Perp`). | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The subaccount ID to filter by | | instrument
`i` | string | False
`'all'` | The instrument filter to apply. | Back to top --- # Ws order feed selector v1 - Gravity Markets API Docs Ws order feed selector v1 ========================= [WSOrderFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_order_feed_selector_v1) Subscribes to a feed of order updates pertaining to orders made by your account. Each Order can be uniquely identified by its `order_id` or `client_order_id`. To subscribe to all orders, specify an empty `instrument` (eg. `2345123`). Otherwise, specify the `instrument` to only receive orders for that instrument (eg. `2345123-BTC_USDT_Perp`). | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The subaccount ID to filter by | | instrument
`i` | string | False
`'all'` | The instrument filter to apply. | Back to top --- # Ws positions feed selector v1 - Gravity Markets API Docs Ws positions feed selector v1 ============================= [WSPositionsFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_positions_feed_selector_v1) Subscribes to a feed of position updates. Updates get published when a trade is executed, and when leverage configurations are changed for instruments with ongoing positions. To subscribe to all positions, specify an empty `instrument` (eg. `2345123`). Otherwise, specify the `instrument` to only receive positions for that instrument (eg. `2345123-BTC_USDT_Perp`). | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The subaccount ID to filter by | | instrument
`i` | string | False
`'all'` | The instrument filter to apply. | Back to top --- # Ws request v1 - Gravity Markets API Docs Ws request v1 ============= [WSRequestV1](https://api-docs.grvt.io/schemas/ws_request_v1) All V1 Websocket Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | number | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | feed
`f` | \[string\] | True | The list of feeds to subscribe to | | method
`m` | string | True | The method to use for the request (eg: subscribe / unsubscribe) | | is\_full
`if` | boolean | False
`false` | Whether the request is for full data or lite data | Back to top --- # Api transfer history response - Gravity Markets API Docs Api transfer history response ============================= [ApiTransferHistoryResponse](https://api-docs.grvt.io/schemas/api_transfer_history_response) | 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](https://api-docs.grvt.io/schemas/transfer_history) | 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` | string | 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 | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [TransferType](https://api-docs.grvt.io/schemas/transfer_type) | Value | Description | | --- | --- | | `UNSPECIFIED` = 0 | Default transfer that has nothing to do with bridging | | `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 | | `ADHOC_INCENTIVE` = 6 | Transfer type for adhoc incentive | | `REFERRAL_INCENTIVE` = 7 | Transfer type for referral incentive | | `TRADING_DEPOSIT_YIELD_INCENTIVE` = 8 | Transfer type for trading deposit yield incentive | Back to top --- # Ws mini ticker feed selector v1 - Gravity Markets API Docs Ws mini ticker feed selector v1 =============================== [WSMiniTickerFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_mini_ticker_feed_selector_v1) Subscribes to a mini ticker feed for a single instrument. The `mini.s` channel offers simpler integration. To experience higher publishing rates, please use the `mini.d` channel. Unlike the `mini.d` channel which publishes an initial snapshot, then only streams deltas after, the `mini.s` channel publishes full snapshots at each feed. The Delta feed will work as follows: * On subscription, the server will send a full snapshot of the mini ticker. * After the snapshot, the server will only send deltas of the mini ticker. * The server will send a delta if any of the fields in the mini ticker have changed. Field Semantics: * \[DeltaOnly\] If a field is not updated, {} * If a field is updated, {field: '123'} * If a field is set to zero, {field: '0'} * If a field is set to null, {field: ''} | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | rate
`r` | integer | True | The minimal rate at which we publish feeds (in milliseconds)
Delta (0 - `raw`, 50, 100, 200, 500, 1000, 5000)
Snapshot (200, 500, 1000, 5000) | Back to top --- # Api list aggregated account summary response - Gravity Markets API Docs Api list aggregated account summary response ============================================ [ApiListAggregatedAccountSummaryResponse](https://api-docs.grvt.io/schemas/api_list_aggregated_account_summary_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_summaries
`as` | \[ApiAggregatedAccountSummaryResponse\] | True | The list of aggregated account summaries of requested main accounts | [ApiAggregatedAccountSummaryResponse](https://api-docs.grvt.io/schemas/api_aggregated_account_summary_response) 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](https://api-docs.grvt.io/schemas/aggregated_account_summary) | 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](https://api-docs.grvt.io/schemas/spot_balance) | 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](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api vault view redemption queue response - Gravity Markets API Docs Api vault view redemption queue response ======================================== [ApiVaultViewRedemptionQueueResponse](https://api-docs.grvt.io/schemas/api_vault_view_redemption_queue_response) Response payload for a vault manager to view the redemption queue for their vault, ordered by descending priority. Also includes counters for total redemption sizes pending as well as urgent (refer to API integration guide for more detail on redemption request classifications). | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | redemption\_queue
`rq` | \[VaultRedemptionRequest\] | True | Outstanding vault redemption requests, ordered by descending priority. Excludes requests that have not yet aged past the minimum redemption period. | | pending\_redemption\_token\_count
`pr` | string | True | Number of shares eligible for automated redemption (held in queue for at least the minimum redemption period). | | urgent\_redemption\_token\_count
`ur` | string | True | Number of shares nearing the maximum redemption period (>= 90% of maximum redemption period). | | auto\_redeemable\_balance
`ar` | string | True | Amount available for automated redemption request servicing (in USD). | | share\_price
`sp` | string | True | Current share price (in USD). | | pre\_min
`pm` | PreMinRedemptions | True | Dedicated section for requests yet to wait at least the minimum redemption period. | [VaultRedemptionRequest](https://api-docs.grvt.io/schemas/vault_redemption_request) Representation of a pending redemption request for a given vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_time
`rt` | string | True | \[Filled by GRVT Backend\] Time at which the redemption request was received by GRVT in unix nanoseconds | | num\_lp\_tokens
`nl` | string | True | The number of shares to redeem | | max\_redemption\_period\_timestamp
`mr` | string | True | \[Filled by GRVT Backend\] Time in unix nanoseconds, beyond which the request will be force-redeemed. | | age\_category
`ac` | VaultRedemptionReqAgeCategory | True | Age category of this redemption request. | | is\_manager
`im` | boolean | False
`None` | `true` if this request belongs to the vault manager, omitted otherwise. | | eligible\_for\_auto\_redemption\_timestamp
`ef` | string | True | \[Filled by GRVT Backend\] Time in unix nanoseconds, beyond which the request will be eligible for automated redemption. | [VaultRedemptionReqAgeCategory](https://api-docs.grvt.io/schemas/vault_redemption_req_age_category) Denotes the age category of a given redemption request. | Value | Description | | --- | --- | | `NORMAL` = 1 | This request is at least as old as the minimum redemption period, and is eligible for automated redemption. | | `URGENT` = 2 | This request is nearing the maxmimum redemption period and will be factored into pre-order check margin requirements. | | `OVERDUE` = 3 | This request has exceeded the maximum redemption period and will be considered for forced redemptions. | | `PRE_MIN` = 4 | This request has yet to exceed the minimum redemption period, and is not yet eligible for automated redemption. | [PreMinRedemptions](https://api-docs.grvt.io/schemas/pre_min_redemptions) Vault redemption queue section hidden from main view. All requests here have yet to age past the vault's minimum redemption period. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | requests
`r` | \[VaultRedemptionRequest\] | True | Pre-minimum-age redemption requests, ordered by age (first element is the oldest request that is pre-minimum-age). | | token\_count
`tc` | string | True | Number of shares in the pre-minimum-age section of the vault's redemption queue. | [VaultRedemptionRequest](https://api-docs.grvt.io/schemas/vault_redemption_request) Representation of a pending redemption request for a given vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_time
`rt` | string | True | \[Filled by GRVT Backend\] Time at which the redemption request was received by GRVT in unix nanoseconds | | num\_lp\_tokens
`nl` | string | True | The number of shares to redeem | | max\_redemption\_period\_timestamp
`mr` | string | True | \[Filled by GRVT Backend\] Time in unix nanoseconds, beyond which the request will be force-redeemed. | | age\_category
`ac` | VaultRedemptionReqAgeCategory | True | Age category of this redemption request. | | is\_manager
`im` | boolean | False
`None` | `true` if this request belongs to the vault manager, omitted otherwise. | | eligible\_for\_auto\_redemption\_timestamp
`ef` | string | True | \[Filled by GRVT Backend\] Time in unix nanoseconds, beyond which the request will be eligible for automated redemption. | [VaultRedemptionReqAgeCategory](https://api-docs.grvt.io/schemas/vault_redemption_req_age_category) Denotes the age category of a given redemption request. | Value | Description | | --- | --- | | `NORMAL` = 1 | This request is at least as old as the minimum redemption period, and is eligible for automated redemption. | | `URGENT` = 2 | This request is nearing the maxmimum redemption period and will be factored into pre-order check margin requirements. | | `OVERDUE` = 3 | This request has exceeded the maximum redemption period and will be considered for forced redemptions. | | `PRE_MIN` = 4 | This request has yet to exceed the minimum redemption period, and is not yet eligible for automated redemption. | Back to top --- # Order state - Gravity Markets API Docs Order state =========== [OrderState](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | Back to top --- # Pre min redemptions - Gravity Markets API Docs Pre min redemptions =================== [PreMinRedemptions](https://api-docs.grvt.io/schemas/pre_min_redemptions) Vault redemption queue section hidden from main view. All requests here have yet to age past the vault's minimum redemption period. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | requests
`r` | \[VaultRedemptionRequest\] | True | Pre-minimum-age redemption requests, ordered by age (first element is the oldest request that is pre-minimum-age). | | token\_count
`tc` | string | True | Number of shares in the pre-minimum-age section of the vault's redemption queue. | [VaultRedemptionRequest](https://api-docs.grvt.io/schemas/vault_redemption_request) Representation of a pending redemption request for a given vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_time
`rt` | string | True | \[Filled by GRVT Backend\] Time at which the redemption request was received by GRVT in unix nanoseconds | | num\_lp\_tokens
`nl` | string | True | The number of shares to redeem | | max\_redemption\_period\_timestamp
`mr` | string | True | \[Filled by GRVT Backend\] Time in unix nanoseconds, beyond which the request will be force-redeemed. | | age\_category
`ac` | VaultRedemptionReqAgeCategory | True | Age category of this redemption request. | | is\_manager
`im` | boolean | False
`None` | `true` if this request belongs to the vault manager, omitted otherwise. | | eligible\_for\_auto\_redemption\_timestamp
`ef` | string | True | \[Filled by GRVT Backend\] Time in unix nanoseconds, beyond which the request will be eligible for automated redemption. | [VaultRedemptionReqAgeCategory](https://api-docs.grvt.io/schemas/vault_redemption_req_age_category) Denotes the age category of a given redemption request. | Value | Description | | --- | --- | | `NORMAL` = 1 | This request is at least as old as the minimum redemption period, and is eligible for automated redemption. | | `URGENT` = 2 | This request is nearing the maxmimum redemption period and will be factored into pre-order check margin requirements. | | `OVERDUE` = 3 | This request has exceeded the maximum redemption period and will be considered for forced redemptions. | | `PRE_MIN` = 4 | This request has yet to exceed the minimum redemption period, and is not yet eligible for automated redemption. | Back to top --- # Pre order check result - Gravity Markets API Docs Pre order check result ====================== [PreOrderCheckResult](https://api-docs.grvt.io/schemas/pre_order_check_result) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | max\_qty
`mq` | \[AssetMaxQty\] | True | The maximum quantity for each leg | | margin\_required
`mr` | string | True | The margin required for the order (reported in `settle_currency`) | | order\_valid
`ov` | boolean | True | Whether the order is valid | | reason
`r` | string | True | The reason the order is invalid, if any | | settle\_currency
`sc` | Currency | True | The subAccount settle currency | [AssetMaxQty](https://api-docs.grvt.io/schemas/asset_max_qty) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | asset
`a` | string | True | The asset associated with the max quantity | | max\_buy\_qty
`mb` | string | True | The maximum buy quantity | | max\_sell\_qty
`ms` | string | True | The maximum sell quantity | [Currency](https://api-docs.grvt.io/schemas/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 | Back to top --- # Tpsl order metadata - Gravity Markets API Docs Tpsl order metadata =================== [TPSLOrderMetadata](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_by) 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 | | `MID` = 3 | MID - Order is activated when the mid price reaches the trigger price | | `MARK` = 4 | MARK - Order is activated when the mark price reaches the trigger price | Back to top --- # Trade - Gravity Markets API Docs Trade ===== [Trade](https://api-docs.grvt.io/schemas/trade) All private RFQs and Private AXEs will be filtered out from the responses | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | True | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | is\_taker\_buyer
`it` | boolean | True | If taker was the buyer 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 | | 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`. | | venue
`v` | Venue | True | The venue where the trade occurred | | is\_rpi
`ir1` | boolean | True | If the trade is a RPI trade | [Venue](https://api-docs.grvt.io/schemas/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 | Back to top --- # Ws orderbook levels feed selector v1 - Gravity Markets API Docs Ws orderbook levels feed selector v1 ==================================== [WSOrderbookLevelsFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_orderbook_levels_feed_selector_v1) Subscribes to aggregated orderbook updates for a single instrument. The `book.s` channel offers simpler integration. To experience higher publishing rates, please use the `book.d` channel. Unlike the `book.d` channel which publishes an initial snapshot, then only streams deltas after, the `book.s` channel publishes full snapshots at each feed. The Delta feed will work as follows: * On subscription, the server will send a full snapshot of all levels of the Orderbook. * After the snapshot, the server will only send levels that have changed in value. Subscription Pattern: * Delta - `instrument@rate` * Snapshot - `instrument@rate-depth` Field Semantics: * \[DeltaOnly\] If a level is not updated, level not published * If a level is updated, {size: '123'} * If a level is set to zero, {size: '0'} * Incoming levels will be published as soon as price moves * Outgoing levels will be published with `size = 0` | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | rate
`r` | integer | True | The minimal rate at which we publish feeds (in milliseconds)
Delta (50, 100, 500, 1000)
Snapshot (500, 1000) | | depth
`d` | integer | False
`'0'` | Depth of the order book to be retrieved
Delta(0 - `unlimited`)
Snapshot(10, 50, 100, 500) | Back to top --- # Ws response v1 - Gravity Markets API Docs Ws response v1 ============== [WSResponseV1](https://api-docs.grvt.io/schemas/ws_response_v1) All V1 Websocket Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | number | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[number\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | Back to top --- # Ws subscribe params - Gravity Markets API Docs Ws subscribe params =================== [WSSubscribeParams](https://api-docs.grvt.io/schemas/ws_subscribe_params) All V1 Websocket Subscription Requests are housed in this wrapper. You may specify a stream and a list of feeds to subscribe to. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. Sequence numbers can be either gateway-specific or global: \- **Gateway Unique Sequence Number**: Increments by one per stream, resets to 0 on gateway restart. \- **Global Unique Sequence Number**: A cluster-wide unique number assigned to each cluster payload, does not reset on gateway restarts, and can be used to track and identify message order across streams using `sequence_number` and `prev_sequence_number` in the feed response. Set `useGlobalSequenceNumber = true` if you need a persistent, unique identifier across all streams or ordering across multiple feeds. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to subscribe to | Back to top --- # Ws subscribe request v1 legacy - Gravity Markets API Docs Ws subscribe request v1 legacy ============================== [WSSubscribeRequestV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_request_v1_legacy) All V1 Websocket Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | feed
`f` | \[string\] | True | The list of feeds to subscribe to | | method
`m` | string | True | The method to use for the request (eg: subscribe / unsubscribe) | | is\_full
`if` | boolean | False
`false` | Whether the request is for full data or lite data | Back to top --- # Ws unsubscribe result - Gravity Markets API Docs Ws unsubscribe result ===================== [WSUnsubscribeResult](https://api-docs.grvt.io/schemas/ws_unsubscribe_result) Returns a confirmation of all unsubscribes | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | Back to top --- # Ws unsubscribe all params - Gravity Markets API Docs Ws unsubscribe all params ========================= [WSUnsubscribeAllParams](https://api-docs.grvt.io/schemas/ws_unsubscribe_all_params) All V1 Websocket Unsubscription Request to unsubscribe from all active websocket streams. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | | | | | Back to top --- # Ws withdrawal feed selector v1 - Gravity Markets API Docs Ws withdrawal feed selector v1 ============================== [WSWithdrawalFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_withdrawal_feed_selector_v1) Subscribes to a feed of withdrawals. This will execute when there is any withdrawal from the selected account. To subscribe to a main account, specify the account ID (eg. `0x9fe3758b67ce7a2875ee4b452f01a5282d84ed8a`). | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | main\_account\_id
`ma` | string | True | The main account ID to request for | Back to top --- # Ws subscribe result - Gravity Markets API Docs Ws subscribe result =================== [WSSubscribeResult](https://api-docs.grvt.io/schemas/ws_subscribe_result) To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | Back to top --- # Ws subscribe response v1 legacy - Gravity Markets API Docs Ws subscribe response v1 legacy =============================== [WSSubscribeResponseV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_response_v1_legacy) All V1 Websocket Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | Back to top --- # Ws ticker feed selector v1 - Gravity Markets API Docs Ws ticker feed selector v1 ========================== [WSTickerFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_ticker_feed_selector_v1) Subscribes to a ticker feed for a single instrument. The `ticker.s` channel offers simpler integration. To experience higher publishing rates, please use the `ticker.d` channel. Unlike the `ticker.d` channel which publishes an initial snapshot, then only streams deltas after, the `ticker.s` channel publishes full snapshots at each feed. The Delta feed will work as follows: * On subscription, the server will send a full snapshot of the ticker. * After the snapshot, the server will only send deltas of the ticker. * The server will send a delta if any of the fields in the ticker have changed. Field Semantics: * \[DeltaOnly\] If a field is not updated, {} * If a field is updated, {field: '123'} * If a field is set to zero, {field: '0'} * If a field is set to null, {field: ''} | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | rate
`r` | integer | True | The minimal rate at which we publish feeds (in milliseconds)
Delta (100, 200, 500, 1000, 5000)
Snapshot (500, 1000, 5000) | Back to top --- # Claim ecosystem badge response - Gravity Markets API Docs Claim ecosystem badge response ============================== [ClaimEcosystemBadgeResponse](https://api-docs.grvt.io/schemas/claim_ecosystem_badge_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | badge
`b` | EpochBadge | True | The epoch badge | [EpochBadge](https://api-docs.grvt.io/schemas/epoch_badge) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_id
`ai` | string | True | The off chain account id | | main\_account\_id
`ma` | string | True | The account ID | | type
`t` | RewardProgramType | True | The type of the reward program | | epoch
`e` | integer | True | The epoch number | | epoch\_start\_time
`es` | string | True | The start time of the epoch | | epoch\_end\_time
`ee` | string | True | The end time of the epoch | | badge
`b` | EpochBadgeType | True | The type of the badge | | distributed\_badges
`db` | \[EpochBadgeType\] | True | The distributed badges | | total\_point
`tp` | string | True | Total point | | rank
`r` | integer | True | Rank | | claimed\_at
`ca` | string | True | The time when the badge was claimed, or the epoch end time if the user has already completed the KYC process | [RewardProgramType](https://api-docs.grvt.io/schemas/reward_program_type) | Value | Description | | --- | --- | | `ECOSYSTEM` = 1 | | | `TRADER` = 2 | | | `LP` = 3 | | [EpochBadgeType](https://api-docs.grvt.io/schemas/epoch_badge_type) | Value | Description | | --- | --- | | `CHAMPION` = 1 | Champion | | `LEGEND` = 2 | Legend | | `VETERAN` = 3 | Veteran | | `ELITE` = 4 | Elite | | `MASTER` = 5 | Master | | `EXPERT` = 6 | Expert | | `WARRIOR` = 7 | Warrior | | `SERGEANT` = 8 | Sergeant | | `RANGER` = 9 | Ranger | | `CHALLENGER` = 10 | Challenger | | `APPRENTICE` = 11 | Apprentice | | `ROOKIE` = 12 | Rookie | [EpochBadgeType](https://api-docs.grvt.io/schemas/epoch_badge_type) | Value | Description | | --- | --- | | `CHAMPION` = 1 | Champion | | `LEGEND` = 2 | Legend | | `VETERAN` = 3 | Veteran | | `ELITE` = 4 | Elite | | `MASTER` = 5 | Master | | `EXPERT` = 6 | Expert | | `WARRIOR` = 7 | Warrior | | `SERGEANT` = 8 | Sergeant | | `RANGER` = 9 | Ranger | | `CHALLENGER` = 10 | Challenger | | `APPRENTICE` = 11 | Apprentice | | `ROOKIE` = 12 | Rookie | Back to top --- # Instrument - Gravity Markets API Docs Instrument ========== [Instrument](https://api-docs.grvt.io/schemas/instrument) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | instrument\_hash
`ih` | string | True | The asset ID used for instrument signing. | | base
`b` | string | True | The base currency | | quote
`q` | string | True | The quote currency | | kind
`k` | Kind | True | The kind of instrument | | venues
`v` | \[Venue\] | True | Venues that this instrument can be traded at | | settlement\_period
`sp1` | InstrumentSettlementPeriod | True | The settlement period of the instrument | | base\_decimals
`bd` | integer | True | The smallest denomination of the base asset supported by GRVT (+3 represents 0.001, -3 represents 1000, 0 represents 1) | | quote\_decimals
`qd` | integer | True | The smallest denomination of the quote asset supported by GRVT (+3 represents 0.001, -3 represents 1000, 0 represents 1) | | tick\_size
`ts` | string | True | The size of a single tick, expressed in price decimal units | | min\_size
`ms` | string | True | The minimum contract size, expressed in base asset decimal units | | create\_time
`ct` | string | True | Creation time in unix nanoseconds | | max\_position\_size
`mp` | string | True | The maximum position size, expressed in base asset decimal units | [Kind](https://api-docs.grvt.io/schemas/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 | [Venue](https://api-docs.grvt.io/schemas/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 | [InstrumentSettlementPeriod](https://api-docs.grvt.io/schemas/instrument_settlement_period) | Value | Description | | --- | --- | | `PERPETUAL` = 1 | Instrument settles through perpetual funding cycles | | `DAILY` = 2 | Instrument settles at an expiry date, marked as a daily instrument | | `WEEKLY` = 3 | Instrument settles at an expiry date, marked as a weekly instrument | | `MONTHLY` = 4 | Instrument settles at an expiry date, marked as a monthly instrument | | `QUARTERLY` = 5 | Instrument settles at an expiry date, marked as a quarterly instrument | Back to top --- # Get claimable ecosystem badge response - Gravity Markets API Docs Get claimable ecosystem badge response ====================================== [GetClaimableEcosystemBadgeResponse](https://api-docs.grvt.io/schemas/get_claimable_ecosystem_badge_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | badge
`b` | EpochBadge | True | The epoch badge | | is\_claimable
`ic` | boolean | True | Whether the badge is claimable | | claimable\_until
`cu` | string | True | The time when the badge is claimable | [EpochBadge](https://api-docs.grvt.io/schemas/epoch_badge) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_id
`ai` | string | True | The off chain account id | | main\_account\_id
`ma` | string | True | The account ID | | type
`t` | RewardProgramType | True | The type of the reward program | | epoch
`e` | integer | True | The epoch number | | epoch\_start\_time
`es` | string | True | The start time of the epoch | | epoch\_end\_time
`ee` | string | True | The end time of the epoch | | badge
`b` | EpochBadgeType | True | The type of the badge | | distributed\_badges
`db` | \[EpochBadgeType\] | True | The distributed badges | | total\_point
`tp` | string | True | Total point | | rank
`r` | integer | True | Rank | | claimed\_at
`ca` | string | True | The time when the badge was claimed, or the epoch end time if the user has already completed the KYC process | [RewardProgramType](https://api-docs.grvt.io/schemas/reward_program_type) | Value | Description | | --- | --- | | `ECOSYSTEM` = 1 | | | `TRADER` = 2 | | | `LP` = 3 | | [EpochBadgeType](https://api-docs.grvt.io/schemas/epoch_badge_type) | Value | Description | | --- | --- | | `CHAMPION` = 1 | Champion | | `LEGEND` = 2 | Legend | | `VETERAN` = 3 | Veteran | | `ELITE` = 4 | Elite | | `MASTER` = 5 | Master | | `EXPERT` = 6 | Expert | | `WARRIOR` = 7 | Warrior | | `SERGEANT` = 8 | Sergeant | | `RANGER` = 9 | Ranger | | `CHALLENGER` = 10 | Challenger | | `APPRENTICE` = 11 | Apprentice | | `ROOKIE` = 12 | Rookie | [EpochBadgeType](https://api-docs.grvt.io/schemas/epoch_badge_type) | Value | Description | | --- | --- | | `CHAMPION` = 1 | Champion | | `LEGEND` = 2 | Legend | | `VETERAN` = 3 | Veteran | | `ELITE` = 4 | Elite | | `MASTER` = 5 | Master | | `EXPERT` = 6 | Expert | | `WARRIOR` = 7 | Warrior | | `SERGEANT` = 8 | Sergeant | | `RANGER` = 9 | Ranger | | `CHALLENGER` = 10 | Challenger | | `APPRENTICE` = 11 | Apprentice | | `ROOKIE` = 12 | Rookie | Back to top --- # Instrument display - Gravity Markets API Docs Instrument display ================== [InstrumentDisplay](https://api-docs.grvt.io/schemas/instrument_display) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | instrument\_hash
`ih` | string | True | The asset ID used for instrument signing. | | base
`b` | string | True | The base currency | | quote
`q` | string | True | The quote currency | | kind
`k` | Kind | True | The kind of instrument | | venues
`v` | \[Venue\] | True | Venues that this instrument can be traded at | | settlement\_period
`sp1` | InstrumentSettlementPeriod | True | The settlement period of the instrument | | base\_decimals
`bd` | integer | True | The smallest denomination of the base asset supported by GRVT (+3 represents 0.001, -3 represents 1000, 0 represents 1) | | quote\_decimals
`qd` | integer | True | The smallest denomination of the quote asset supported by GRVT (+3 represents 0.001, -3 represents 1000, 0 represents 1) | | tick\_size
`ts` | string | True | The size of a single tick, expressed in price decimal units | | min\_size
`ms` | string | True | The minimum contract size, expressed in base asset decimal units | | create\_time
`ct` | string | True | Creation time in unix nanoseconds | | max\_position\_size
`mp` | string | True | The maximum position size, expressed in base asset decimal units | | funding\_interval\_hours
`fi` | integer | False
`None` | Defines the funding interval to be applied. | | adjusted\_funding\_rate\_cap
`af` | string | False
`None` | Funding rate cap over the defined `intervalHours`. | | adjusted\_funding\_rate\_floor
`af1` | string | False
`None` | Funding rate floor over the defined `intervalHours`. | | min\_notional
`mn` | string | True | The minimum order notional value, expressed in quote currency decimal units | [Kind](https://api-docs.grvt.io/schemas/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 | [Venue](https://api-docs.grvt.io/schemas/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 | [InstrumentSettlementPeriod](https://api-docs.grvt.io/schemas/instrument_settlement_period) | Value | Description | | --- | --- | | `PERPETUAL` = 1 | Instrument settles through perpetual funding cycles | | `DAILY` = 2 | Instrument settles at an expiry date, marked as a daily instrument | | `WEEKLY` = 3 | Instrument settles at an expiry date, marked as a weekly instrument | | `MONTHLY` = 4 | Instrument settles at an expiry date, marked as a monthly instrument | | `QUARTERLY` = 5 | Instrument settles at an expiry date, marked as a quarterly instrument | Back to top --- # Vault redemption req view - Gravity Markets API Docs Vault redemption req view ========================= [VaultRedemptionReqView](https://api-docs.grvt.io/schemas/vault_redemption_req_view) Representation of a pending redemption request for a given vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_time
`rt` | string | True | \[Filled by GRVT Backend\] Time at which the redemption request was received by GRVT in unix nanoseconds | | num\_lp\_tokens
`nl` | string | True | The number of shares to redeem | | max\_redemption\_period\_timestamp
`mr` | string | True | \[Filled by GRVT Backend\] Time in unix nanoseconds, beyond which the request will be force-redeemed. | | age\_category
`ac` | VaultRedemptionReqAgeCategory | True | Age category of this redemption request. | | investor\_id
`ii` | string | True | The address of the investor who submitted the request. | [VaultRedemptionReqAgeCategory](https://api-docs.grvt.io/schemas/vault_redemption_req_age_category) Denotes the age category of a given redemption request. | Value | Description | | --- | --- | | `NORMAL` = 1 | This request is at least as old as the minimum redemption period, and is eligible for automated redemption. | | `URGENT` = 2 | This request is nearing the maxmimum redemption period and will be factored into pre-order check margin requirements. | | `OVERDUE` = 3 | This request has exceeded the maximum redemption period and will be considered for forced redemptions. | | `PRE_MIN` = 4 | This request has yet to exceed the minimum redemption period, and is not yet eligible for automated redemption. | Back to top --- # Vault investor summary - Gravity Markets API Docs Vault investor summary ====================== [VaultInvestorSummary](https://api-docs.grvt.io/schemas/vault_investor_summary) Vault investor summary information. This struct contains the summary of investments in a vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The unique identifier of the vault sub account. | | num\_lp\_tokens
`nl` | string | True | The number of Vault LP tokens held by the investor. | | avg\_entry\_price
`ae` | string | True | The average entry price (in USD) of the vault LP tokens. | | current\_price
`cp` | string | True | The current price (in USD) of the vault LP tokens. | | total\_equity
`te` | string | True | The current valuation (in USD) of all held vault LP tokens. | | all\_time\_realized\_pnl
`at` | string | True | The all-time realized PnL (in USD) that the investor has received from the vault. | | pending\_redemption
`pr` | VaultRedemption | False
`None` | The singleton pending redemption (omitted if none). | | can\_burn
`cb` | boolean | False
`true` | True if the requesting account is authorized to burn tokens on this vault, omitted otherwise. | [VaultRedemption](https://api-docs.grvt.io/schemas/vault_redemption) Vault redemption information. This struct contains information about a pending redemption from a vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | num\_lp\_tokens
`nl` | string | True | The number of LP Tokens requested for redemption. | | request\_valuation
`rv` | string | True | The valuation (in USD) of the redemption request. | | request\_time
`rt` | string | True | \[Filled by GRVT Backend\] Time at which the redemption request was received by GRVT in unix nanoseconds | | max\_redemption\_period\_timestamp
`mr` | string | True | \[Filled by GRVT Backend\] Time in unix nanoseconds, beyond which the request will be force-redeemed. | | cancel\_blocked
`cb` | boolean | False
`true` | Omitted for redemption requests to non-cross exchange vaults. True if cancellation is blocked within the CEV allocation allowance for the user's current tier (e.g. because the user has already transferred out the spot balance underlying the redemption request). | Back to top --- # Vault redemption request - Gravity Markets API Docs Vault redemption request ======================== [VaultRedemptionRequest](https://api-docs.grvt.io/schemas/vault_redemption_request) Representation of a pending redemption request for a given vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_time
`rt` | string | True | \[Filled by GRVT Backend\] Time at which the redemption request was received by GRVT in unix nanoseconds | | num\_lp\_tokens
`nl` | string | True | The number of shares to redeem | | max\_redemption\_period\_timestamp
`mr` | string | True | \[Filled by GRVT Backend\] Time in unix nanoseconds, beyond which the request will be force-redeemed. | | age\_category
`ac` | VaultRedemptionReqAgeCategory | True | Age category of this redemption request. | | is\_manager
`im` | boolean | False
`None` | `true` if this request belongs to the vault manager, omitted otherwise. | | eligible\_for\_auto\_redemption\_timestamp
`ef` | string | True | \[Filled by GRVT Backend\] Time in unix nanoseconds, beyond which the request will be eligible for automated redemption. | [VaultRedemptionReqAgeCategory](https://api-docs.grvt.io/schemas/vault_redemption_req_age_category) Denotes the age category of a given redemption request. | Value | Description | | --- | --- | | `NORMAL` = 1 | This request is at least as old as the minimum redemption period, and is eligible for automated redemption. | | `URGENT` = 2 | This request is nearing the maxmimum redemption period and will be factored into pre-order check margin requirements. | | `OVERDUE` = 3 | This request has exceeded the maximum redemption period and will be considered for forced redemptions. | | `PRE_MIN` = 4 | This request has yet to exceed the minimum redemption period, and is not yet eligible for automated redemption. | Back to top --- # Ws list streams result - Gravity Markets API Docs Ws list streams result ====================== [WSListStreamsResult](https://api-docs.grvt.io/schemas/ws_list_streams_result) Returns a list of all rooms the client has subscribed to. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream\_reference
`sr` | \[StreamReference\] | True | The list of stream references the connection is connected to | [StreamReference](https://api-docs.grvt.io/schemas/stream_reference) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of selectors for the stream | Back to top --- # Ws transfer feed selector v1 - Gravity Markets API Docs Ws transfer feed selector v1 ============================ [WSTransferFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_transfer_feed_selector_v1) Subscribes to a feed of transfers. This will execute when there is any transfer to or from the selected account. To subscribe to a main account, specify the account ID (eg. `0x9fe3758b67ce7a2875ee4b452f01a5282d84ed8a`). To subscribe to a sub account, specify the main account and the sub account dash separated (eg. `0x9fe3758b67ce7a2875ee4b452f01a5282d84ed8a-1920109784202388`). | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | main\_account\_id
`ma` | string | True | The main account ID to request for | | sub\_account\_id
`sa` | string | False
`'0'` | The sub account ID to request for | Back to top --- # Ws unsubscribe params - Gravity Markets API Docs Ws unsubscribe params ===================== [WSUnsubscribeParams](https://api-docs.grvt.io/schemas/ws_unsubscribe_params) All V1 Websocket Unsubscription Requests are housed in this wrapper. You may specify a stream, a list of feeds and whether those feeds use global sequence numbers to unsubscribe from. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to unsubscribe from (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to unsubscribe from | Back to top --- # Ws trade feed selector v1 - Gravity Markets API Docs Ws trade feed selector v1 ========================= [WSTradeFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_trade_feed_selector_v1) Subscribes to a stream of Public Trades for an instrument. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | limit
`l` | integer | True | The limit to query for. Valid values are (50, 200, 500, 1000). Default is 50 | Back to top --- # Snap funding account summary - Gravity Markets API Docs Snap funding account summary ============================ [SnapFundingAccountSummary](https://api-docs.grvt.io/schemas/snap_funding_account_summary) The funding account summary, that reports the total equity and spot balances of a funding (main) account | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | True | Time at which the event was emitted in unix nanoseconds | | start\_interval
`si` | string | True | The start of the interval in unix nanoseconds | | 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](https://api-docs.grvt.io/schemas/spot_balance) | 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](https://api-docs.grvt.io/schemas/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 | Back to top --- # Withdrawal history - Gravity Markets API Docs Withdrawal history ================== [WithdrawalHistory](https://api-docs.grvt.io/schemas/withdrawal_history) | 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` | string | 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 | | l\_1\_hash
`l1` | string | False
`''` | The finalized withdrawal transaction hash on L1, empty if the withdrawal is 'pending'. | | l\_2\_hash
`l2` | string | True | The transaction hash on L2 | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | Back to top --- # Withdrawal - Gravity Markets API Docs Withdrawal ========== [Withdrawal](https://api-docs.grvt.io/schemas/withdrawal) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | 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` | string | 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 | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | Back to top --- # Ws candlestick feed data v1 - Gravity Markets API Docs Ws candlestick feed data v1 =========================== [WSCandlestickFeedDataV1](https://api-docs.grvt.io/schemas/ws_candlestick_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | Candlestick | True | A candlestick entry matching the request filters | [Candlestick](https://api-docs.grvt.io/schemas/candlestick) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | open\_time
`ot` | string | True | Open time of kline bar in unix nanoseconds | | close\_time
`ct` | string | True | Close time of kline bar in unix nanosecond | | open
`o` | string | True | The open price, expressed in underlying currency resolution units | | close
`c` | string | True | The close price, expressed in underlying currency resolution units | | high
`h` | string | True | The high price, expressed in underlying currency resolution units | | low
`l` | string | True | The low price, expressed in underlying currency resolution units | | volume\_b
`vb` | string | True | The underlying volume transacted, expressed in base asset decimal units | | volume\_q
`vq` | string | True | The quote volume transacted, expressed in quote asset decimal units | | trades
`t` | integer | True | The number of trades transacted | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | Back to top --- # Ws deposit feed data v1 - Gravity Markets API Docs Ws deposit feed data v1 ======================= [WSDepositFeedDataV1](https://api-docs.grvt.io/schemas/ws_deposit_feed_data_v1) Subscribes to a feed of deposit updates. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The websocket channel to which the response is sent | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | Deposit | True | The Deposit object | [Deposit](https://api-docs.grvt.io/schemas/deposit) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | tx\_hash
`th` | string | True | The hash of the bridgemint event producing the deposit | | to\_account\_id
`ta` | string | True | The account to deposit into | | currency
`c` | string | True | The token currency to deposit | | num\_tokens
`nt` | string | True | The number of tokens to deposit | Back to top --- # Ws mini ticker feed data v1 - Gravity Markets API Docs Ws mini ticker feed data v1 =========================== [WSMiniTickerFeedDataV1](https://api-docs.grvt.io/schemas/ws_mini_ticker_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | MiniTicker | True | A mini ticker matching the request filter | [MiniTicker](https://api-docs.grvt.io/schemas/mini_ticker) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | False
`None` | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | False
`None` | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | mark\_price
`mp` | string | False
`None` | The mark price of the instrument, expressed in `9` decimals | | index\_price
`ip` | string | False
`None` | The index price of the instrument, expressed in `9` decimals | | last\_price
`lp` | string | False
`None` | The last traded price of the instrument (also close price), expressed in `9` decimals | | last\_size
`ls` | string | False
`None` | The number of assets traded in the last trade, expressed in base asset decimal units | | mid\_price
`mp1` | string | False
`None` | The mid price of the instrument, expressed in `9` decimals | | best\_bid\_price
`bb` | string | False
`None` | The best bid price of the instrument, expressed in `9` decimals | | best\_bid\_size
`bb1` | string | False
`None` | The number of assets offered on the best bid price of the instrument, expressed in base asset decimal units | | best\_ask\_price
`ba` | string | False
`None` | The best ask price of the instrument, expressed in `9` decimals | | best\_ask\_size
`ba1` | string | False
`None` | The number of assets offered on the best ask price of the instrument, expressed in base asset decimal units | Back to top --- # Ws order group feed data v1 - Gravity Markets API Docs Ws order group feed data v1 =========================== [WSOrderGroupFeedDataV1](https://api-docs.grvt.io/schemas/ws_order_group_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | ClientOrderIDsByGroup | True | The order object being created or updated | [ClientOrderIDsByGroup](https://api-docs.grvt.io/schemas/client_order_i_ds_by_group) Grouping for the client order id and their associated groups. This is used to define TP/SL pairs or other order groupings after loading the list of Open Orders. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | group\_id
`gi` | string | True | The group this order belongs to. It can be used to define TP/SL pairs or other order groupings | | client\_order\_id
`co` | \[string\] | True | List of client order IDs in the group | | sub\_account\_id
`sa` | string | True | The sub account ID that these orders belong to | Back to top --- # Order state feed - Gravity Markets API Docs Order state feed ================ [OrderStateFeed](https://api-docs.grvt.io/schemas/order_state_feed) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | order\_id
`oi` | string | True | A unique 128-bit identifier for the order, deterministically generated within the GRVT backend | | client\_order\_id
`co` | string | True | A unique identifier for the active order within a subaccount, specified by the client | | order\_state
`os` | OrderState | True | The order state object being created or updated | [OrderState](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | Back to top --- # Query epoch badge response - Gravity Markets API Docs Query epoch badge response ========================== [QueryEpochBadgeResponse](https://api-docs.grvt.io/schemas/query_epoch_badge_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[EpochBadge\] | True | The list of epoch badges | | next
`n` | string | True | The cursor to indicate when to start the query from | [EpochBadge](https://api-docs.grvt.io/schemas/epoch_badge) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | account\_id
`ai` | string | True | The off chain account id | | main\_account\_id
`ma` | string | True | The account ID | | type
`t` | RewardProgramType | True | The type of the reward program | | epoch
`e` | integer | True | The epoch number | | epoch\_start\_time
`es` | string | True | The start time of the epoch | | epoch\_end\_time
`ee` | string | True | The end time of the epoch | | badge
`b` | EpochBadgeType | True | The type of the badge | | distributed\_badges
`db` | \[EpochBadgeType\] | True | The distributed badges | | total\_point
`tp` | string | True | Total point | | rank
`r` | integer | True | Rank | | claimed\_at
`ca` | string | True | The time when the badge was claimed, or the epoch end time if the user has already completed the KYC process | [RewardProgramType](https://api-docs.grvt.io/schemas/reward_program_type) | Value | Description | | --- | --- | | `ECOSYSTEM` = 1 | | | `TRADER` = 2 | | | `LP` = 3 | | [EpochBadgeType](https://api-docs.grvt.io/schemas/epoch_badge_type) | Value | Description | | --- | --- | | `CHAMPION` = 1 | Champion | | `LEGEND` = 2 | Legend | | `VETERAN` = 3 | Veteran | | `ELITE` = 4 | Elite | | `MASTER` = 5 | Master | | `EXPERT` = 6 | Expert | | `WARRIOR` = 7 | Warrior | | `SERGEANT` = 8 | Sergeant | | `RANGER` = 9 | Ranger | | `CHALLENGER` = 10 | Challenger | | `APPRENTICE` = 11 | Apprentice | | `ROOKIE` = 12 | Rookie | [EpochBadgeType](https://api-docs.grvt.io/schemas/epoch_badge_type) | Value | Description | | --- | --- | | `CHAMPION` = 1 | Champion | | `LEGEND` = 2 | Legend | | `VETERAN` = 3 | Veteran | | `ELITE` = 4 | Elite | | `MASTER` = 5 | Master | | `EXPERT` = 6 | Expert | | `WARRIOR` = 7 | Warrior | | `SERGEANT` = 8 | Sergeant | | `RANGER` = 9 | Ranger | | `CHALLENGER` = 10 | Challenger | | `APPRENTICE` = 11 | Apprentice | | `ROOKIE` = 12 | Rookie | Back to top --- # Query epoch badge point distribution response - Gravity Markets API Docs Query epoch badge point distribution response ============================================= [QueryEpochBadgePointDistributionResponse](https://api-docs.grvt.io/schemas/query_epoch_badge_point_distribution_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[EpochBadgePointDistribution\] | True | The list of epoch badges | [EpochBadgePointDistribution](https://api-docs.grvt.io/schemas/epoch_badge_point_distribution) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | badge
`b` | EpochBadgeType | True | The type of the badge | | epoch
`e` | integer | True | The epoch number | | type
`t` | RewardProgramType | True | The type of the reward program | | min\_point
`mp` | string | True | The minimum point to get the badge | | max\_point
`mp1` | string | True | The maximum point to get the badge | | min\_rank
`mr` | integer | True | The minimum rank to get the badge | | max\_rank
`mr1` | integer | True | The maximum rank to get the badge | | total\_point
`tp` | string | True | The total point to get the badge | | count
`c` | integer | True | The number of users to get the badge | [EpochBadgeType](https://api-docs.grvt.io/schemas/epoch_badge_type) | Value | Description | | --- | --- | | `CHAMPION` = 1 | Champion | | `LEGEND` = 2 | Legend | | `VETERAN` = 3 | Veteran | | `ELITE` = 4 | Elite | | `MASTER` = 5 | Master | | `EXPERT` = 6 | Expert | | `WARRIOR` = 7 | Warrior | | `SERGEANT` = 8 | Sergeant | | `RANGER` = 9 | Ranger | | `CHALLENGER` = 10 | Challenger | | `APPRENTICE` = 11 | Apprentice | | `ROOKIE` = 12 | Rookie | [RewardProgramType](https://api-docs.grvt.io/schemas/reward_program_type) | Value | Description | | --- | --- | | `ECOSYSTEM` = 1 | | | `TRADER` = 2 | | | `LP` = 3 | | Back to top --- # Ws ticker feed data v1 - Gravity Markets API Docs Ws ticker feed data v1 ====================== [WSTickerFeedDataV1](https://api-docs.grvt.io/schemas/ws_ticker_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | Ticker | True | A ticker matching the request filter | [Ticker](https://api-docs.grvt.io/schemas/ticker) Derived data such as the below, will not be included by default: \- 24 hour volume (`buyVolume + sellVolume`) \- 24 hour taker buy/sell ratio (`buyVolume / sellVolume`) \- 24 hour average trade price (`volumeQ / volumeU`) \- 24 hour average trade volume (`volume / trades`) \- 24 hour percentage change (`24hStatChange / 24hStat`) \- 48 hour statistics (`2 * 24hStat - 24hStatChange`) To query for an extended ticker payload, leverage the `greeks` and the `derived` flags. Ticker extensions are currently under design to offer you more convenience. These flags are only supported on the `Ticker Snapshot` WS endpoint, and on the `Ticker` API endpoint. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | False
`None` | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | False
`None` | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | mark\_price
`mp` | string | False
`None` | The mark price of the instrument, expressed in `9` decimals | | index\_price
`ip` | string | False
`None` | The index price of the instrument, expressed in `9` decimals | | last\_price
`lp` | string | False
`None` | The last traded price of the instrument (also close price), expressed in `9` decimals | | last\_size
`ls` | string | False
`None` | The number of assets traded in the last trade, expressed in base asset decimal units | | mid\_price
`mp1` | string | False
`None` | The mid price of the instrument, expressed in `9` decimals | | best\_bid\_price
`bb` | string | False
`None` | The best bid price of the instrument, expressed in `9` decimals | | best\_bid\_size
`bb1` | string | False
`None` | The number of assets offered on the best bid price of the instrument, expressed in base asset decimal units | | best\_ask\_price
`ba` | string | False
`None` | The best ask price of the instrument, expressed in `9` decimals | | best\_ask\_size
`ba1` | string | False
`None` | The number of assets offered on the best ask price of the instrument, expressed in base asset decimal units | | funding\_rate\_8h\_curr
`fr` | string | False
`None` | DEPRECATED: To be removed in a future release. Please refer to the field `funding_rate` instead, for the funding rate being applied over `funding_interval_hours` (interval ending at `next_funding_time`). | | funding\_rate\_8h\_avg
`fr1` | string | False
`None` | DEPRECATED: To be removed in a future release. Please refer to the field `funding_rate` instead, for the funding rate being applied over `funding_interval_hours` (interval ending at `next_funding_time`). | | interest\_rate
`ir` | string | False
`None` | The interest rate of the underlying, expressed in centibeeps (1/100th of a basis point) | | forward\_price
`fp` | string | False
`None` | \[Options\] The forward price of the option, expressed in `9` decimals | | buy\_volume\_24h\_b
`bv` | string | False
`None` | The 24 hour taker buy volume of the instrument, expressed in base asset decimal units | | sell\_volume\_24h\_b
`sv` | string | False
`None` | The 24 hour taker sell volume of the instrument, expressed in base asset decimal units | | buy\_volume\_24h\_q
`bv1` | string | False
`None` | The 24 hour taker buy volume of the instrument, expressed in quote asset decimal units | | sell\_volume\_24h\_q
`sv1` | string | False
`None` | The 24 hour taker sell volume of the instrument, expressed in quote asset decimal units | | high\_price
`hp` | string | False
`None` | The 24 hour highest traded price of the instrument, expressed in `9` decimals | | low\_price
`lp1` | string | False
`None` | The 24 hour lowest traded price of the instrument, expressed in `9` decimals | | open\_price
`op` | string | False
`None` | The 24 hour first traded price of the instrument, expressed in `9` decimals | | open\_interest
`oi` | string | False
`None` | The open interest in the instrument, expressed in base asset decimal units | | long\_short\_ratio
`ls1` | string | False
`None` | The ratio of accounts that are net long vs net short on this instrument | | funding\_rate
`fr2` | string | False
`None` | The current indicative funding rate for the active interval, expressed in centibeeps | | next\_funding\_time
`nf` | string | False
`None` | Timestamp in nanoseconds when the current funding interval ends | Back to top --- # Api latest snap sub accounts response - Gravity Markets API Docs Api latest snap sub accounts response ===================================== [ApiLatestSnapSubAccountsResponse](https://api-docs.grvt.io/schemas/api_latest_snap_sub_accounts_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[SubAccount\] | True | The sub account history matching the request sub account | [SubAccount](https://api-docs.grvt.io/schemas/sub_account) | 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](https://api-docs.grvt.io/schemas/margin_type) | 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](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/spot_balance) | 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](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/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 | Back to top --- # Transfer history - Gravity Markets API Docs Transfer history ================ [TransferHistory](https://api-docs.grvt.io/schemas/transfer_history) | 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` | string | 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 | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [TransferType](https://api-docs.grvt.io/schemas/transfer_type) | Value | Description | | --- | --- | | `UNSPECIFIED` = 0 | Default transfer that has nothing to do with bridging | | `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 | | `ADHOC_INCENTIVE` = 6 | Transfer type for adhoc incentive | | `REFERRAL_INCENTIVE` = 7 | Transfer type for referral incentive | | `TRADING_DEPOSIT_YIELD_INCENTIVE` = 8 | Transfer type for trading deposit yield incentive | Back to top --- # Ws unsubscribe all result - Gravity Markets API Docs Ws unsubscribe all result ========================= [WSUnsubscribeAllResult](https://api-docs.grvt.io/schemas/ws_unsubscribe_all_result) Returns a list of all rooms the client has unsubscribed from. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream\_reference
`sr` | \[StreamReference\] | True | The list of stream references unsubscribed from | [StreamReference](https://api-docs.grvt.io/schemas/stream_reference) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of selectors for the stream | Back to top --- # Api sub account history response - Gravity Markets API Docs Api sub account history response ================================ [ApiSubAccountHistoryResponse](https://api-docs.grvt.io/schemas/api_sub_account_history_response) | 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](https://api-docs.grvt.io/schemas/sub_account) | 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` | string | 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`) | | is\_vault
`iv` | boolean | False
`None` | Whether this sub account is a vault | | vault\_im\_additions
`vi` | string | False
`None` | Total amount of IM (reported in `settle_currency`) deducted from the vault due to redemptions nearing the end of their redemption period | | derisk\_margin
`dm` | string | True | The derisk margin of this sub account | | derisk\_to\_maintenance\_margin\_ratio
`dt` | string | True | The derisk margin to maintenance margin ratio of this sub account | | total\_cross\_equity
`tc` | string | True | The total equity of this sub account for cross margin | | cross\_unrealized\_pnl
`cu` | string | True | The unrealized PnL of this sub account for cross margin | [MarginType](https://api-docs.grvt.io/schemas/margin_type) | 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 | [SpotBalance](https://api-docs.grvt.io/schemas/spot_balance) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | currency
`c` | string | 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`) | [Positions](https://api-docs.grvt.io/schemas/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 | | cumulative\_fee
`cf` | string | True | The cumulative fee paid on the position, expressed in quote asset decimal units | | cumulative\_realized\_funding\_payment
`cr` | string | True | The cumulative realized funding payment of the position, expressed in quote asset decimal units. Positive if paid, negative if received | | margin\_type
`mt` | PositionMarginType | True | The margin type of the position | | isolated\_balance
`ib` | string | False
`None` | \[IsolatedOnly\] The wallet balance reserved for this isolated margin position, expressed in quote asset decimal units. If this positions is liquidated, this is the maximal balance that can be lost | | isolated\_im
`ii` | string | False
`None` | \[IsolatedOnly\] The initial margin of the isolated margin position, expressed in quote asset decimal units. The `total_equity` required to open more size in the position | | isolated\_mm
`im` | string | False
`None` | \[IsolatedOnly\] The maintenance margin of the isolated margin position, expressed in quote asset decimal units. The `total_equity` required to avoid liquidation of the position | [PositionMarginType](https://api-docs.grvt.io/schemas/position_margin_type) | Value | Description | | --- | --- | | `ISOLATED` = 1 | Isolated Margin Mode: each position is allocated a fixed amount of collateral | | `CROSS` = 2 | Cross Margin Mode: uses all available funds in your account as collateral across all cross margin positions | Back to top --- # Api sub account summary response - Gravity Markets API Docs Api sub account summary response ================================ [ApiSubAccountSummaryResponse](https://api-docs.grvt.io/schemas/api_sub_account_summary_response) 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](https://api-docs.grvt.io/schemas/sub_account) | 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` | string | 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`) | | is\_vault
`iv` | boolean | False
`None` | Whether this sub account is a vault | | vault\_im\_additions
`vi` | string | False
`None` | Total amount of IM (reported in `settle_currency`) deducted from the vault due to redemptions nearing the end of their redemption period | | derisk\_margin
`dm` | string | True | The derisk margin of this sub account | | derisk\_to\_maintenance\_margin\_ratio
`dt` | string | True | The derisk margin to maintenance margin ratio of this sub account | | total\_cross\_equity
`tc` | string | True | The total equity of this sub account for cross margin | | cross\_unrealized\_pnl
`cu` | string | True | The unrealized PnL of this sub account for cross margin | [MarginType](https://api-docs.grvt.io/schemas/margin_type) | 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 | [SpotBalance](https://api-docs.grvt.io/schemas/spot_balance) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | currency
`c` | string | 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`) | [Positions](https://api-docs.grvt.io/schemas/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 | | cumulative\_fee
`cf` | string | True | The cumulative fee paid on the position, expressed in quote asset decimal units | | cumulative\_realized\_funding\_payment
`cr` | string | True | The cumulative realized funding payment of the position, expressed in quote asset decimal units. Positive if paid, negative if received | | margin\_type
`mt` | PositionMarginType | True | The margin type of the position | | isolated\_balance
`ib` | string | False
`None` | \[IsolatedOnly\] The wallet balance reserved for this isolated margin position, expressed in quote asset decimal units. If this positions is liquidated, this is the maximal balance that can be lost | | isolated\_im
`ii` | string | False
`None` | \[IsolatedOnly\] The initial margin of the isolated margin position, expressed in quote asset decimal units. The `total_equity` required to open more size in the position | | isolated\_mm
`im` | string | False
`None` | \[IsolatedOnly\] The maintenance margin of the isolated margin position, expressed in quote asset decimal units. The `total_equity` required to avoid liquidation of the position | [PositionMarginType](https://api-docs.grvt.io/schemas/position_margin_type) | Value | Description | | --- | --- | | `ISOLATED` = 1 | Isolated Margin Mode: each position is allocated a fixed amount of collateral | | `CROSS` = 2 | Cross Margin Mode: uses all available funds in your account as collateral across all cross margin positions | Back to top --- # Ws candlestick feed selector v1 - Gravity Markets API Docs Ws candlestick feed selector v1 =============================== [WSCandlestickFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_candlestick_feed_selector_v1) Subscribes to a stream of Kline/Candlestick updates for an instrument. A Kline is uniquely identified by its open time. A new Kline is published every interval (if it exists). Upon subscription, the server will send the 5 most recent Kline for the requested interval. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | interval
`i1` | CandlestickInterval | True | The interval of each candlestick | | type
`t` | CandlestickType | True | The type of candlestick data to retrieve | [CandlestickInterval](https://api-docs.grvt.io/schemas/candlestick_interval) | Value | Description | | --- | --- | | `CI_1_M` = 1 | 1 minute | | `CI_3_M` = 2 | 3 minutes | | `CI_5_M` = 3 | 5 minutes | | `CI_15_M` = 4 | 15 minutes | | `CI_30_M` = 5 | 30 minutes | | `CI_1_H` = 6 | 1 hour | | `CI_2_H` = 7 | 2 hour | | `CI_4_H` = 8 | 4 hour | | `CI_6_H` = 9 | 6 hour | | `CI_8_H` = 10 | 8 hour | | `CI_12_H` = 11 | 12 hour | | `CI_1_D` = 12 | 1 day | | `CI_3_D` = 13 | 3 days | | `CI_5_D` = 14 | 5 days | | `CI_1_W` = 15 | 1 week | | `CI_2_W` = 16 | 2 weeks | | `CI_3_W` = 17 | 3 weeks | | `CI_4_W` = 18 | 4 weeks | [CandlestickType](https://api-docs.grvt.io/schemas/candlestick_type) | Value | Description | | --- | --- | | `TRADE` = 1 | Tracks traded prices | | `MARK` = 2 | Tracks mark prices | | `INDEX` = 3 | Tracks index prices | | `MID` = 4 | Tracks book mid prices | Back to top --- # Ws orderbook levels feed data v1 - Gravity Markets API Docs Ws orderbook levels feed data v1 ================================ [WSOrderbookLevelsFeedDataV1](https://api-docs.grvt.io/schemas/ws_orderbook_levels_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | OrderbookLevels | True | An orderbook levels object matching the request filter | [OrderbookLevels](https://api-docs.grvt.io/schemas/orderbook_levels) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | True | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | bids
`b` | \[OrderbookLevel\] | True | The list of best bids up till query depth | | asks
`a` | \[OrderbookLevel\] | True | The list of best asks up till query depth | [OrderbookLevel](https://api-docs.grvt.io/schemas/orderbook_level) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | price
`p` | string | True | The price of the level, expressed in `9` decimals | | size
`s` | string | True | The number of assets offered, expressed in base asset decimal units | | num\_orders
`no` | integer | True | The number of open orders at this level | [OrderbookLevel](https://api-docs.grvt.io/schemas/orderbook_level) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | price
`p` | string | True | The price of the level, expressed in `9` decimals | | size
`s` | string | True | The number of assets offered, expressed in base asset decimal units | | num\_orders
`no` | integer | True | The number of open orders at this level | Back to top --- # Ws positions feed data v1 - Gravity Markets API Docs Ws positions feed data v1 ========================= [WSPositionsFeedDataV1](https://api-docs.grvt.io/schemas/ws_positions_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | Positions | True | A Position being created or updated matching the request filter | [Positions](https://api-docs.grvt.io/schemas/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 | | cumulative\_fee
`cf` | string | True | The cumulative fee paid on the position, expressed in quote asset decimal units | | cumulative\_realized\_funding\_payment
`cr` | string | True | The cumulative realized funding payment of the position, expressed in quote asset decimal units. Positive if paid, negative if received | | margin\_type
`mt` | PositionMarginType | True | The margin type of the position | | isolated\_balance
`ib` | string | False
`None` | \[IsolatedOnly\] The wallet balance reserved for this isolated margin position, expressed in quote asset decimal units. If this positions is liquidated, this is the maximal balance that can be lost | | isolated\_im
`ii` | string | False
`None` | \[IsolatedOnly\] The initial margin of the isolated margin position, expressed in quote asset decimal units. The `total_equity` required to open more size in the position | | isolated\_mm
`im` | string | False
`None` | \[IsolatedOnly\] The maintenance margin of the isolated margin position, expressed in quote asset decimal units. The `total_equity` required to avoid liquidation of the position | [PositionMarginType](https://api-docs.grvt.io/schemas/position_margin_type) | Value | Description | | --- | --- | | `ISOLATED` = 1 | Isolated Margin Mode: each position is allocated a fixed amount of collateral | | `CROSS` = 2 | Cross Margin Mode: uses all available funds in your account as collateral across all cross margin positions | Back to top --- # Ws trade feed data v1 - Gravity Markets API Docs Ws trade feed data v1 ===================== [WSTradeFeedDataV1](https://api-docs.grvt.io/schemas/ws_trade_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | Trade | True | A public trade matching the request filter | [Trade](https://api-docs.grvt.io/schemas/trade) All private RFQs and Private AXEs will be filtered out from the responses | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | True | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | is\_taker\_buyer
`it` | boolean | True | If taker was the buyer 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 | | 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`. | | venue
`v` | Venue | True | The venue where the trade occurred | | is\_rpi
`ir1` | boolean | True | If the trade is a RPI trade | [Venue](https://api-docs.grvt.io/schemas/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 | Back to top --- # Trigger order metadata - Gravity Markets API Docs Trigger order metadata ====================== [TriggerOrderMetadata](https://api-docs.grvt.io/schemas/trigger_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_type) 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](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_by) 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 | | `MID` = 3 | MID - Order is activated when the mid price reaches the trigger price | | `MARK` = 4 | MARK - Order is activated when the mark price reaches the trigger price | Back to top --- # Ws withdrawal feed data v1 - Gravity Markets API Docs Ws withdrawal feed data v1 ========================== [WSWithdrawalFeedDataV1](https://api-docs.grvt.io/schemas/ws_withdrawal_feed_data_v1) Subscribes to a feed of withdrawal updates. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The websocket channel to which the response is sent | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | Withdrawal | True | The Withdrawal object | [Withdrawal](https://api-docs.grvt.io/schemas/withdrawal) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | 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` | string | 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 | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | Back to top --- # Order metadata - Gravity Markets API Docs Order metadata ============== [OrderMetadata](https://api-docs.grvt.io/schemas/order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_type) 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](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_by) 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 | | `MID` = 3 | MID - Order is activated when the mid price reaches the trigger price | | `MARK` = 4 | MARK - Order is activated when the mark price reaches the trigger price | [BrokerTag](https://api-docs.grvt.io/schemas/broker_tag) 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 | Back to top --- # Sub account - Gravity Markets API Docs Sub account =========== [SubAccount](https://api-docs.grvt.io/schemas/sub_account) | 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` | string | 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`) | | is\_vault
`iv` | boolean | False
`None` | Whether this sub account is a vault | | vault\_im\_additions
`vi` | string | False
`None` | Total amount of IM (reported in `settle_currency`) deducted from the vault due to redemptions nearing the end of their redemption period | | derisk\_margin
`dm` | string | True | The derisk margin of this sub account | | derisk\_to\_maintenance\_margin\_ratio
`dt` | string | True | The derisk margin to maintenance margin ratio of this sub account | | total\_cross\_equity
`tc` | string | True | The total equity of this sub account for cross margin | | cross\_unrealized\_pnl
`cu` | string | True | The unrealized PnL of this sub account for cross margin | [MarginType](https://api-docs.grvt.io/schemas/margin_type) | 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 | [SpotBalance](https://api-docs.grvt.io/schemas/spot_balance) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | currency
`c` | string | 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`) | [Positions](https://api-docs.grvt.io/schemas/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 | | cumulative\_fee
`cf` | string | True | The cumulative fee paid on the position, expressed in quote asset decimal units | | cumulative\_realized\_funding\_payment
`cr` | string | True | The cumulative realized funding payment of the position, expressed in quote asset decimal units. Positive if paid, negative if received | | margin\_type
`mt` | PositionMarginType | True | The margin type of the position | | isolated\_balance
`ib` | string | False
`None` | \[IsolatedOnly\] The wallet balance reserved for this isolated margin position, expressed in quote asset decimal units. If this positions is liquidated, this is the maximal balance that can be lost | | isolated\_im
`ii` | string | False
`None` | \[IsolatedOnly\] The initial margin of the isolated margin position, expressed in quote asset decimal units. The `total_equity` required to open more size in the position | | isolated\_mm
`im` | string | False
`None` | \[IsolatedOnly\] The maintenance margin of the isolated margin position, expressed in quote asset decimal units. The `total_equity` required to avoid liquidation of the position | [PositionMarginType](https://api-docs.grvt.io/schemas/position_margin_type) | Value | Description | | --- | --- | | `ISOLATED` = 1 | Isolated Margin Mode: each position is allocated a fixed amount of collateral | | `CROSS` = 2 | Cross Margin Mode: uses all available funds in your account as collateral across all cross margin positions | Back to top --- # Transfer - Gravity Markets API Docs Transfer ======== [Transfer](https://api-docs.grvt.io/schemas/transfer) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | 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 | | transfer\_type
`tt` | TransferType | True | The type of transfer | | transfer\_metadata
`tm` | string | True | The metadata of the transfer | [Currency](https://api-docs.grvt.io/schemas/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 | [Signature](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/transfer_type) | 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 | Back to top --- # Ws cancel feed data v1 - Gravity Markets API Docs Ws cancel feed data v1 ====================== [WSCancelFeedDataV1](https://api-docs.grvt.io/schemas/ws_cancel_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | CancelStatusFeed | True | Data relating to the status of the cancellation attempt | [CancelStatusFeed](https://api-docs.grvt.io/schemas/cancel_status_feed) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The subaccount ID that requested the cancellation | | client\_order\_id
`co` | string | True | A unique identifier for the active order within a subaccount, specified by the client | | order\_id
`oi` | string | True | A unique 128-bit identifier for the order, deterministically generated within the GRVT backend | | reason
`r` | OrderRejectReason | True | The user-provided reason for cancelling the order | | update\_time
`ut` | string | False
`0` | \[Filled by GRVT Backend\] Time at which the cancellation status was updated by GRVT in unix nanoseconds | | cancel\_status
`cs` | CancelStatus | True | Status of the cancellation attempt | [OrderRejectReason](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | [CancelStatus](https://api-docs.grvt.io/schemas/cancel_status) | Value | Description | | --- | --- | | `EXPIRED` = 1 | Cancellation has expired because corresponding order had not arrived within the defined time-to-live window. | | `DROPPED_DUPLICATE` = 2 | This cancellation request was dropped because its TTL window overlaps with another cancellation request for the same order. | Back to top --- # Ws fill feed data v1 - Gravity Markets API Docs Ws fill feed data v1 ==================== [WSFillFeedDataV1](https://api-docs.grvt.io/schemas/ws_fill_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The websocket channel to which the response is sent | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | Fill | True | A private trade matching the request filter | [Fill](https://api-docs.grvt.io/schemas/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 | | is\_liquidation
`il` | boolean | True | If the trade was a liquidation | | 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 | | builder
`b1` | string | True | The main account ID of the builder. referred to Order.builder | | builder\_fee\_rate
`bf` | string | True | Builder fee percentage charged for this order. referred to Order.builder builderFee | | builder\_fee
`bf1` | string | True | The builder fee paid on the trade, expressed in quote asset decimal unit. referred to Trade.builderFee | [Venue](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/broker_tag) 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 | Back to top --- # Ws transfer feed data v1 - Gravity Markets API Docs Ws transfer feed data v1 ======================== [WSTransferFeedDataV1](https://api-docs.grvt.io/schemas/ws_transfer_feed_data_v1) Subscribes to a feed of transfer updates. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The websocket channel to which the response is sent | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | TransferHistory | True | The transfer history matching the requested filters | [TransferHistory](https://api-docs.grvt.io/schemas/transfer_history) | 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` | string | 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 | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [TransferType](https://api-docs.grvt.io/schemas/transfer_type) | Value | Description | | --- | --- | | `UNSPECIFIED` = 0 | Default transfer that has nothing to do with bridging | | `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 | | `ADHOC_INCENTIVE` = 6 | Transfer type for adhoc incentive | | `REFERRAL_INCENTIVE` = 7 | Transfer type for referral incentive | | `TRADING_DEPOSIT_YIELD_INCENTIVE` = 8 | Transfer type for trading deposit yield incentive | Back to top --- # Ws order state feed data v1 - Gravity Markets API Docs Ws order state feed data v1 =========================== [WSOrderStateFeedDataV1](https://api-docs.grvt.io/schemas/ws_order_state_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | OrderStateFeed | True | The Order State Feed | [OrderStateFeed](https://api-docs.grvt.io/schemas/order_state_feed) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | order\_id
`oi` | string | True | A unique 128-bit identifier for the order, deterministically generated within the GRVT backend | | client\_order\_id
`co` | string | True | A unique identifier for the active order within a subaccount, specified by the client | | order\_state
`os` | OrderState | True | The order state object being created or updated | [OrderState](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | Back to top --- # Api cancel order response - Gravity Markets API Docs Api cancel order response ========================= [ApiCancelOrderResponse](https://api-docs.grvt.io/schemas/api_cancel_order_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | Order | True | The cancelled order | [Order](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/time_in_force) | | 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 | [OrderLeg](https://api-docs.grvt.io/schemas/order_leg) | 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](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_type) 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](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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. | [TriggerBy](https://api-docs.grvt.io/schemas/trigger_by) 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](https://api-docs.grvt.io/schemas/broker_tag) 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](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | Back to top --- # Api query trading performance request - Gravity Markets API Docs Api query trading performance request ===================================== [ApiQueryTradingPerformanceRequest](https://api-docs.grvt.io/schemas/api_query_trading_performance_request) Request to retrieve the trading volume | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | False
`all` | Optional: The subaccount ID to filter by | | asset
`a` | unknown | True | The asset to filter by | Back to top --- # Api query trading performance response - Gravity Markets API Docs Api query trading performance response ====================================== [ApiQueryTradingPerformanceResponse](https://api-docs.grvt.io/schemas/api_query_trading_performance_response) Response to retrieve the trading volume | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | trading\_volume
`tv` | string | True | Trading volume in USDT | | realized\_pnl
`rp` | string | True | Realized PnL in USDT | Back to top --- # Api set initial leverage response - Gravity Markets API Docs Api set initial leverage response ================================= [ApiSetInitialLeverageResponse](https://api-docs.grvt.io/schemas/api_set_initial_leverage_response) 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 | Back to top --- # Api set sub account position margin config response - Gravity Markets API Docs Api set sub account position margin config response =================================================== [ApiSetSubAccountPositionMarginConfigResponse](https://api-docs.grvt.io/schemas/api_set_sub_account_position_margin_config_response) The response to set the margin type and leverage for a position | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | ack
`a` | boolean | True | Whether the margin type and leverage was acked | Back to top --- # Api socialized loss status response - Gravity Markets API Docs Api socialized loss status response =================================== [ApiSocializedLossStatusResponse](https://api-docs.grvt.io/schemas/api_socialized_loss_status_response) The socialized loss status. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | is\_active
`ia` | boolean | True | Whether the socialized loss is active | | haircut\_ratio
`hr` | string | True | The socialized loss haircut ratio in centi-beeps | Back to top --- # Api sub account summary request - Gravity Markets API Docs Api sub account summary request =============================== [ApiSubAccountSummaryRequest](https://api-docs.grvt.io/schemas/api_sub_account_summary_request) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The subaccount ID to filter by | Back to top --- # Api bulk orders request - Gravity Markets API Docs Api bulk orders request ======================= [ApiBulkOrdersRequest](https://api-docs.grvt.io/schemas/api_bulk_orders_request) Usage Parameters _Rate Limits \- If N orders are created, it will consume N create\_order rate limit tokens \- If M orders are cancelled, it will consume 1 cancel\_order rate limit tokens • Usage Pattern \- This can be used as BulkCreate if no cancellations are supplied \- This can be used as BulkCancel if no creations are supplied \- This can be used as BulkReplace if both creations and cancellations are supplied _Order Replacement \- For a pair of create and cancel payloads at the same index: \* If they belong to the same inst/side/price \* And the created order has an order\_size smaller than the book\_size of the cancelled order \* The created order will replace the cancelled order, and retain its priority in the orderbook \- For instance, to replace 2 orders, place 1 order, and cancel 2 orders: \* orders = \* order\_ids = _Speed Bump \- The highest speed\_bump level applies across all sub-payloads and will be applied on the BulkOrder \- To ensure that creations/cancellations are not speed bumped, ensure that all orders have post\_only = true _Restrictions \- This is only available to API users \- All create orders must use the same instrument \- TPSL (Take Profit / Stop Loss) orders are not supported | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The subaccount ID of the user creating the request | | orders
`o` | \[Order\] | True | Orders to create or replace, supply up to 20 orders | | order\_i\_ds
`oi` | \[string\] | True | The order IDs of the orders to cancel or replace, supply up to 20 orderIDs (if both orderIDs and clientOrderIDs are provided, we will reject the payload) | | client\_order\_i\_ds
`co` | \[string\] | True | The client order IDs of the orders to cancel or replace, supply up to 20 clientOrderIDs (if both orderIDs and clientOrderIDs are provided, we will reject the payload) | | 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_id`s 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. | [Order](https://api-docs.grvt.io/schemas/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 | | builder
`b` | string | True | The main account ID of the builder | | builder\_fee
`bf` | string | True | Builder fee charged for this order | [TimeInForce](https://api-docs.grvt.io/schemas/time_in_force) | | 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](https://api-docs.grvt.io/schemas/order_leg) | 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](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [OrderMetadata](https://api-docs.grvt.io/schemas/order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_type) 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](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_by) 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 | | `MID` = 3 | MID - Order is activated when the mid price reaches the trigger price | | `MARK` = 4 | MARK - Order is activated when the mark price reaches the trigger price | [BrokerTag](https://api-docs.grvt.io/schemas/broker_tag) 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](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | Back to top --- # Api create bulk orders response - Gravity Markets API Docs Api create bulk orders response =============================== [ApiCreateBulkOrdersResponse](https://api-docs.grvt.io/schemas/api_create_bulk_orders_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[Order\] | True | The created orders in same order as requested | [Order](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/time_in_force) | | 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 | [OrderLeg](https://api-docs.grvt.io/schemas/order_leg) | 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](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_type) 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](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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. | [TriggerBy](https://api-docs.grvt.io/schemas/trigger_by) 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](https://api-docs.grvt.io/schemas/broker_tag) 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](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | Back to top --- # Api create order request - Gravity Markets API Docs Api create order request ======================== [ApiCreateOrderRequest](https://api-docs.grvt.io/schemas/api_create_order_request) 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](https://api-docs.grvt.io/schemas/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 | | builder
`b` | string | True | The main account ID of the builder | | builder\_fee
`bf` | string | True | Builder fee charged for this order | [TimeInForce](https://api-docs.grvt.io/schemas/time_in_force) | | 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](https://api-docs.grvt.io/schemas/order_leg) | 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](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [OrderMetadata](https://api-docs.grvt.io/schemas/order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_type) 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](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_by) 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 | | `MID` = 3 | MID - Order is activated when the mid price reaches the trigger price | | `MARK` = 4 | MARK - Order is activated when the mark price reaches the trigger price | [BrokerTag](https://api-docs.grvt.io/schemas/broker_tag) 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](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | Back to top --- # Api create bulk orders request - Gravity Markets API Docs Api create bulk orders request ============================== [ApiCreateBulkOrdersRequest](https://api-docs.grvt.io/schemas/api_create_bulk_orders_request) Create multiple orders simultaneously for this trading account. This endpoint supports the following order scenarios: \- One-Cancels-Other (OCO) orders combining TP/SL \- One-Sends-Other (OSO) orders Usage: \- For OCO (TP/SL pair): Send exactly 2 orders in the same request - one Take Profit and one Stop Loss order \- For OSO: Send exactly one main order and one contingent order (TP and/or SL) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | orders
`o` | \[Order\] | True | The orders to create | [Order](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/time_in_force) | | 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 | [OrderLeg](https://api-docs.grvt.io/schemas/order_leg) | 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](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_type) 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](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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. | [TriggerBy](https://api-docs.grvt.io/schemas/trigger_by) 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](https://api-docs.grvt.io/schemas/broker_tag) 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](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | Back to top --- # Api create order response - Gravity Markets API Docs Api create order response ========================= [ApiCreateOrderResponse](https://api-docs.grvt.io/schemas/api_create_order_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | Order | True | The created order | [Order](https://api-docs.grvt.io/schemas/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 | | builder
`b` | string | True | The main account ID of the builder | | builder\_fee
`bf` | string | True | Builder fee charged for this order | [TimeInForce](https://api-docs.grvt.io/schemas/time_in_force) | | 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](https://api-docs.grvt.io/schemas/order_leg) | 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](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [OrderMetadata](https://api-docs.grvt.io/schemas/order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_type) 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](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_by) 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 | | `MID` = 3 | MID - Order is activated when the mid price reaches the trigger price | | `MARK` = 4 | MARK - Order is activated when the mark price reaches the trigger price | [BrokerTag](https://api-docs.grvt.io/schemas/broker_tag) 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](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | Back to top --- # Api trade request - Gravity Markets API Docs Api trade request ================= [ApiTradeRequest](https://api-docs.grvt.io/schemas/api_trade_request) Retrieves up to 1000 of the most recent trades in any given instrument. Do not use this to poll for data -- a websocket subscription is much more performant, and useful. This endpoint offers public trading data, use the Trading APIs instead to query for your personalized trade tape. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | limit
`l` | integer | True | The limit to query for. Defaults to 500; Max 1000 | Back to top --- # Api transfer ack - Gravity Markets API Docs Api transfer ack ================ [ApiTransferAck](https://api-docs.grvt.io/schemas/api_transfer_ack) | 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. | Back to top --- # Api vault investor summary request - Gravity Markets API Docs Api vault investor summary request ================================== [ApiVaultInvestorSummaryRequest](https://api-docs.grvt.io/schemas/api_vault_investor_summary_request) Request payload for fetching the summary of a vault investor. This API allows a client to retrieve the summary of investments in a specific vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_id
`vi` | string | True | The unique identifier of the vault to fetch the summary for. | Back to top --- # Api vault redeem cancel request - Gravity Markets API Docs Api vault redeem cancel request =============================== [ApiVaultRedeemCancelRequest](https://api-docs.grvt.io/schemas/api_vault_redeem_cancel_request) Request payload for canceling a vault redemption. This API allows a client to cancel a previously initiated redemption from a vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_id
`vi` | string | True | The unique identifier of the vault to cancel the redemption from. | Back to top --- # Approximate lp point - Gravity Markets API Docs Approximate lp point ==================== [ApproximateLPPoint](https://api-docs.grvt.io/schemas/approximate_lp_point) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | off\_chain\_account\_id
`oc` | string | True | The off chain account id | | liquidity\_score
`ls` | string | True | Liquidity score | | rank
`r` | integer | True | The rank of user in the LP leaderboard | Back to top --- # Asset max qty - Gravity Markets API Docs Asset max qty ============= [AssetMaxQty](https://api-docs.grvt.io/schemas/asset_max_qty) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | asset
`a` | string | True | The asset associated with the max quantity | | max\_buy\_qty
`mb` | string | True | The maximum buy quantity | | max\_sell\_qty
`ms` | string | True | The maximum sell quantity | Back to top --- # Bridge type - Gravity Markets API Docs Bridge type =========== [BridgeType](https://api-docs.grvt.io/schemas/bridge_type) | Value | Description | | --- | --- | | `XY` = 1 | XY Bridge type | | `RHINO` = 2 | Rhino Bridge type | Back to top --- # Broker tag - Gravity Markets API Docs Broker tag ========== [BrokerTag](https://api-docs.grvt.io/schemas/broker_tag) 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 | Back to top --- # Cancel status - Gravity Markets API Docs Cancel status ============= [CancelStatus](https://api-docs.grvt.io/schemas/cancel_status) | Value | Description | | --- | --- | | `EXPIRED` = 1 | Cancellation has expired because corresponding order had not arrived within the defined time-to-live window. | | `DROPPED_DUPLICATE` = 2 | This cancellation request was dropped because its TTL window overlaps with another cancellation request for the same order. | Back to top --- # Api bulk orders response - Gravity Markets API Docs Api bulk orders response ======================== [ApiBulkOrdersResponse](https://api-docs.grvt.io/schemas/api_bulk_orders_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | orders
`o` | \[Order\] | True | The orders in same order as requested | | cancel\_acks
`ca` | \[Ack\] | True | A list of acks for the cancelled orders | [Order](https://api-docs.grvt.io/schemas/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 | | builder
`b` | string | True | The main account ID of the builder | | builder\_fee
`bf` | string | True | Builder fee charged for this order | [TimeInForce](https://api-docs.grvt.io/schemas/time_in_force) | | 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](https://api-docs.grvt.io/schemas/order_leg) | 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](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [OrderMetadata](https://api-docs.grvt.io/schemas/order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_type) 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](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_by) 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 | | `MID` = 3 | MID - Order is activated when the mid price reaches the trigger price | | `MARK` = 4 | MARK - Order is activated when the mark price reaches the trigger price | [BrokerTag](https://api-docs.grvt.io/schemas/broker_tag) 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](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | [Ack](https://api-docs.grvt.io/schemas/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 | Back to top --- # Api get order response - Gravity Markets API Docs Api get order response ====================== [ApiGetOrderResponse](https://api-docs.grvt.io/schemas/api_get_order_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | Order | True | The order object for the requested filter | [Order](https://api-docs.grvt.io/schemas/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 | | builder
`b` | string | True | The main account ID of the builder | | builder\_fee
`bf` | string | True | Builder fee charged for this order | [TimeInForce](https://api-docs.grvt.io/schemas/time_in_force) | | 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](https://api-docs.grvt.io/schemas/order_leg) | 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](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [OrderMetadata](https://api-docs.grvt.io/schemas/order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_type) 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](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_by) 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 | | `MID` = 3 | MID - Order is activated when the mid price reaches the trigger price | | `MARK` = 4 | MARK - Order is activated when the mark price reaches the trigger price | [BrokerTag](https://api-docs.grvt.io/schemas/broker_tag) 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](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | Back to top --- # Api open orders response - Gravity Markets API Docs Api open orders response ======================== [ApiOpenOrdersResponse](https://api-docs.grvt.io/schemas/api_open_orders_response) 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](https://api-docs.grvt.io/schemas/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 | | builder
`b` | string | True | The main account ID of the builder | | builder\_fee
`bf` | string | True | Builder fee charged for this order | [TimeInForce](https://api-docs.grvt.io/schemas/time_in_force) | | 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](https://api-docs.grvt.io/schemas/order_leg) | 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](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [OrderMetadata](https://api-docs.grvt.io/schemas/order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_type) 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](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_by) 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 | | `MID` = 3 | MID - Order is activated when the mid price reaches the trigger price | | `MARK` = 4 | MARK - Order is activated when the mark price reaches the trigger price | [BrokerTag](https://api-docs.grvt.io/schemas/broker_tag) 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](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | Back to top --- # Api order history response - Gravity Markets API Docs Api order history response ========================== [ApiOrderHistoryResponse](https://api-docs.grvt.io/schemas/api_order_history_response) | 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](https://api-docs.grvt.io/schemas/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 | | builder
`b` | string | True | The main account ID of the builder | | builder\_fee
`bf` | string | True | Builder fee charged for this order | [TimeInForce](https://api-docs.grvt.io/schemas/time_in_force) | | 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](https://api-docs.grvt.io/schemas/order_leg) | 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](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [OrderMetadata](https://api-docs.grvt.io/schemas/order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_type) 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](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_by) 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 | | `MID` = 3 | MID - Order is activated when the mid price reaches the trigger price | | `MARK` = 4 | MARK - Order is activated when the mark price reaches the trigger price | [BrokerTag](https://api-docs.grvt.io/schemas/broker_tag) 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](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | Back to top --- # Api pre order check request - Gravity Markets API Docs Api pre order check request =========================== [ApiPreOrderCheckRequest](https://api-docs.grvt.io/schemas/api_pre_order_check_request) Get pre-order check information for a new order | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The subaccount ID of orders to query | | orders
`o` | \[Order\] | True | The order to do pre-order check | [Order](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/time_in_force) | | 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 | [OrderLeg](https://api-docs.grvt.io/schemas/order_leg) | 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](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_type) 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](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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. | [TriggerBy](https://api-docs.grvt.io/schemas/trigger_by) 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](https://api-docs.grvt.io/schemas/broker_tag) 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](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | Back to top --- # Order - Gravity Markets API Docs Order ===== [Order](https://api-docs.grvt.io/schemas/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 | | builder
`b` | string | True | The main account ID of the builder | | builder\_fee
`bf` | string | True | Builder fee charged for this order | [TimeInForce](https://api-docs.grvt.io/schemas/time_in_force) | | 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](https://api-docs.grvt.io/schemas/order_leg) | 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](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [OrderMetadata](https://api-docs.grvt.io/schemas/order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_type) 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](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_by) 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 | | `MID` = 3 | MID - Order is activated when the mid price reaches the trigger price | | `MARK` = 4 | MARK - Order is activated when the mark price reaches the trigger price | [BrokerTag](https://api-docs.grvt.io/schemas/broker_tag) 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](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | Back to top --- # Ws order feed data v1 - Gravity Markets API Docs Ws order feed data v1 ===================== [WSOrderFeedDataV1](https://api-docs.grvt.io/schemas/ws_order_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | Order | True | The order object being created or updated | [Order](https://api-docs.grvt.io/schemas/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 | | builder
`b` | string | True | The main account ID of the builder | | builder\_fee
`bf` | string | True | Builder fee charged for this order | [TimeInForce](https://api-docs.grvt.io/schemas/time_in_force) | | 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](https://api-docs.grvt.io/schemas/order_leg) | 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](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [OrderMetadata](https://api-docs.grvt.io/schemas/order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_type) 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](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_by) 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 | | `MID` = 3 | MID - Order is activated when the mid price reaches the trigger price | | `MARK` = 4 | MARK - Order is activated when the mark price reaches the trigger price | [BrokerTag](https://api-docs.grvt.io/schemas/broker_tag) 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](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | Back to top --- # Market Data Websocket - Gravity Markets API Docs [Skip to content](https://api-docs.grvt.io/market_data_streams/#marketdata-websocket-streams) MarketData Websocket Streams ============================ Ticker ------ ### Mini Ticker Snap `STREAM: v1.mini.s` Feed SelectorFeed DataErrorsTry it out [WSMiniTickerFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_mini_ticker_feed_selector_v1) Subscribes to a mini ticker feed for a single instrument. The `mini.s` channel offers simpler integration. To experience higher publishing rates, please use the `mini.d` channel. Unlike the `mini.d` channel which publishes an initial snapshot, then only streams deltas after, the `mini.s` channel publishes full snapshots at each feed. The Delta feed will work as follows: * On subscription, the server will send a full snapshot of the mini ticker. * After the snapshot, the server will only send deltas of the mini ticker. * The server will send a delta if any of the fields in the mini ticker have changed. Field Semantics: * \[DeltaOnly\] If a field is not updated, {} * If a field is updated, {field: '123'} * If a field is set to zero, {field: '0'} * If a field is set to null, {field: ''} | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | rate
`r` | integer | True | The minimal rate at which we publish feeds (in milliseconds)
Delta (0 - `raw`, 50, 100, 200, 500, 1000, 5000)
Snapshot (200, 500, 1000, 5000) | JSONRPC Wrappers [JSONRPCRequest](https://api-docs.grvt.io/schemas/jsonrpc_request) All Websocket JSON RPC Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | method
`m` | string | True | The method to use for the request (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | | params
`p` | object | True | The parameters for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | [WSSubscribeParams](https://api-docs.grvt.io/schemas/ws_subscribe_params) All V1 Websocket Subscription Requests are housed in this wrapper. You may specify a stream and a list of feeds to subscribe to. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. Sequence numbers can be either gateway-specific or global: \- **Gateway Unique Sequence Number**: Increments by one per stream, resets to 0 on gateway restart. \- **Global Unique Sequence Number**: A cluster-wide unique number assigned to each cluster payload, does not reset on gateway restarts, and can be used to track and identify message order across streams using `sequence_number` and `prev_sequence_number` in the feed response. Set `useGlobalSequenceNumber = true` if you need a persistent, unique identifier across all streams or ordering across multiple feeds. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to subscribe to | [WSSubscribeResult](https://api-docs.grvt.io/schemas/ws_subscribe_result) To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | [WSUnsubscribeParams](https://api-docs.grvt.io/schemas/ws_unsubscribe_params) All V1 Websocket Unsubscription Requests are housed in this wrapper. You may specify a stream, a list of feeds and whether those feeds use global sequence numbers to unsubscribe from. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to unsubscribe from (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to unsubscribe from | [WSUnsubscribeResult](https://api-docs.grvt.io/schemas/ws_unsubscribe_result) Returns a confirmation of all unsubscribes | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | [WSSubscribeRequestV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_request_v1_legacy) All V1 Websocket Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | feed
`f` | \[string\] | True | The list of feeds to subscribe to | | method
`m` | string | True | The method to use for the request (eg: subscribe / unsubscribe) | | is\_full
`if` | boolean | False
`false` | Whether the request is for full data or lite data | [WSSubscribeResponseV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_response_v1_legacy) All V1 Websocket Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | Subscribe **Full Subscribe Request** `{ "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.mini.s", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 }` **Full Subscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.mini.s", "subs": ["BTC_USDT_Perp@500"], "unsubs": [], "num_snapshots": [10], "first_sequence_number": [872634876] }, "id": 123, "method": "subscribe" }` Unsubscribe **Full Unsubscribe Request** `{ "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.mini.s", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 }` **Full Unsubscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.mini.s", "unsubs": ["BTC_USDT_Perp@500"] }, "id": 123, "method": "subscribe" }` Legacy Subscribe **Full Subscribe Request** `{ "request_id":1, "stream":"v1.mini.s", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true }` **Full Subscribe Response** `{ "request_id":1, "stream":"v1.mini.s", "subs":["BTC_USDT_Perp@500"], "unsubs":[], "num_snapshots":[1], "first_sequence_number":[2813] }` [WSMiniTickerFeedDataV1](https://api-docs.grvt.io/schemas/ws_mini_ticker_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | MiniTicker | True | A mini ticker matching the request filter | [MiniTicker](https://api-docs.grvt.io/schemas/mini_ticker) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | False
`None` | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | False
`None` | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | mark\_price
`mp` | string | False
`None` | The mark price of the instrument, expressed in `9` decimals | | index\_price
`ip` | string | False
`None` | The index price of the instrument, expressed in `9` decimals | | last\_price
`lp` | string | False
`None` | The last traded price of the instrument (also close price), expressed in `9` decimals | | last\_size
`ls` | string | False
`None` | The number of assets traded in the last trade, expressed in base asset decimal units | | mid\_price
`mp1` | string | False
`None` | The mid price of the instrument, expressed in `9` decimals | | best\_bid\_price
`bb` | string | False
`None` | The best bid price of the instrument, expressed in `9` decimals | | best\_bid\_size
`bb1` | string | False
`None` | The number of assets offered on the best bid price of the instrument, expressed in base asset decimal units | | best\_ask\_price
`ba` | string | False
`None` | The best ask price of the instrument, expressed in `9` decimals | | best\_ask\_size
`ba1` | string | False
`None` | The number of assets offered on the best ask price of the instrument, expressed in base asset decimal units | Success **Full Feed Response** `{ "stream": "v1.mini.s", "selector": "BTC_USDT_Perp", "sequence_number": "872634876", "feed": { "event_time": "1697788800000000000", "instrument": "BTC_USDT_Perp", "mark_price": "65038.01", "index_price": "65038.01", "last_price": "65038.01", "last_size": "123456.78", "mid_price": "65038.01", "best_bid_price": "65038.01", "best_bid_size": "123456.78", "best_ask_price": "65038.01", "best_ask_size": "123456.78" } }` **Lite Feed Response** `{ "s": "v1.mini.s", "s1": "BTC_USDT_Perp", "sn": "872634876", "f": { "et": "1697788800000000000", "i": "BTC_USDT_Perp", "mp": "65038.01", "ip": "65038.01", "lp": "65038.01", "ls": "123456.78", "mp1": "65038.01", "bb": "65038.01", "bb1": "123456.78", "ba": "65038.01", "ba1": "123456.78" } }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 1002 | 500 | Internal Server Error | | 1004 | 404 | Data Not Found | | 1101 | 400 | Feed Format must be in the format of @ | | 1102 | 400 | Wrong number of primary selectors | | 1103 | 400 | Wrong number of secondary selectors | | 3000 | 400 | Instrument is invalid | | 3030 | 400 | Feed rate is invalid | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | Error **Full Error Response** `{ "jsonrpc": "2.0", "error": { "code": 1002, "message": "Internal Server Error" }, "id": 123, "method": "subscribe" }` **Lite Error Response** `{ "j": "2.0", "e": { "c": 1002, "m": "Internal Server Error" }, "i": 123, "m": "subscribe" }` **Legacy Error Response** `{ "code":1002, "message":"Internal Server Error", "status":500 }` DEVSTAGINGTESTNETPROD Subscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.mini.s", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.mini.s", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.mini.s", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.mini.s", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.mini.s", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.mini.s", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.mini.s", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.mini.s", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.mini.s", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.mini.s", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.mini.s", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.mini.s", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.mini.s", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.mini.s", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.mini.s", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.mini.s", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.mini.s", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.mini.s", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.mini.s", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.mini.s", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.mini.s", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.mini.s", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.mini.s", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.mini.s", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` * * * ### Mini Ticker Delta `STREAM: v1.mini.d` Feed SelectorFeed DataErrorsTry it out [WSMiniTickerFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_mini_ticker_feed_selector_v1) Subscribes to a mini ticker feed for a single instrument. The `mini.s` channel offers simpler integration. To experience higher publishing rates, please use the `mini.d` channel. Unlike the `mini.d` channel which publishes an initial snapshot, then only streams deltas after, the `mini.s` channel publishes full snapshots at each feed. The Delta feed will work as follows: * On subscription, the server will send a full snapshot of the mini ticker. * After the snapshot, the server will only send deltas of the mini ticker. * The server will send a delta if any of the fields in the mini ticker have changed. Field Semantics: * \[DeltaOnly\] If a field is not updated, {} * If a field is updated, {field: '123'} * If a field is set to zero, {field: '0'} * If a field is set to null, {field: ''} | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | rate
`r` | integer | True | The minimal rate at which we publish feeds (in milliseconds)
Delta (0 - `raw`, 50, 100, 200, 500, 1000, 5000)
Snapshot (200, 500, 1000, 5000) | JSONRPC Wrappers [JSONRPCRequest](https://api-docs.grvt.io/schemas/jsonrpc_request) All Websocket JSON RPC Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | method
`m` | string | True | The method to use for the request (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | | params
`p` | object | True | The parameters for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | [WSSubscribeParams](https://api-docs.grvt.io/schemas/ws_subscribe_params) All V1 Websocket Subscription Requests are housed in this wrapper. You may specify a stream and a list of feeds to subscribe to. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. Sequence numbers can be either gateway-specific or global: \- **Gateway Unique Sequence Number**: Increments by one per stream, resets to 0 on gateway restart. \- **Global Unique Sequence Number**: A cluster-wide unique number assigned to each cluster payload, does not reset on gateway restarts, and can be used to track and identify message order across streams using `sequence_number` and `prev_sequence_number` in the feed response. Set `useGlobalSequenceNumber = true` if you need a persistent, unique identifier across all streams or ordering across multiple feeds. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to subscribe to | [WSSubscribeResult](https://api-docs.grvt.io/schemas/ws_subscribe_result) To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | [WSUnsubscribeParams](https://api-docs.grvt.io/schemas/ws_unsubscribe_params) All V1 Websocket Unsubscription Requests are housed in this wrapper. You may specify a stream, a list of feeds and whether those feeds use global sequence numbers to unsubscribe from. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to unsubscribe from (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to unsubscribe from | [WSUnsubscribeResult](https://api-docs.grvt.io/schemas/ws_unsubscribe_result) Returns a confirmation of all unsubscribes | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | [WSSubscribeRequestV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_request_v1_legacy) All V1 Websocket Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | feed
`f` | \[string\] | True | The list of feeds to subscribe to | | method
`m` | string | True | The method to use for the request (eg: subscribe / unsubscribe) | | is\_full
`if` | boolean | False
`false` | Whether the request is for full data or lite data | [WSSubscribeResponseV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_response_v1_legacy) All V1 Websocket Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | Subscribe **Full Subscribe Request** `{ "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.mini.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 }` **Full Subscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.mini.d", "subs": ["BTC_USDT_Perp@500"], "unsubs": [], "num_snapshots": [10], "first_sequence_number": [872634876] }, "id": 123, "method": "subscribe" }` Unsubscribe **Full Unsubscribe Request** `{ "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.mini.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 }` **Full Unsubscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.mini.d", "unsubs": ["BTC_USDT_Perp@500"] }, "id": 123, "method": "subscribe" }` Legacy Subscribe **Full Subscribe Request** `{ "request_id":1, "stream":"v1.mini.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true }` **Full Subscribe Response** `{ "request_id":1, "stream":"v1.mini.d", "subs":["BTC_USDT_Perp@500"], "unsubs":[], "num_snapshots":[1], "first_sequence_number":[2813] }` [WSMiniTickerFeedDataV1](https://api-docs.grvt.io/schemas/ws_mini_ticker_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | MiniTicker | True | A mini ticker matching the request filter | [MiniTicker](https://api-docs.grvt.io/schemas/mini_ticker) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | False
`None` | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | False
`None` | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | mark\_price
`mp` | string | False
`None` | The mark price of the instrument, expressed in `9` decimals | | index\_price
`ip` | string | False
`None` | The index price of the instrument, expressed in `9` decimals | | last\_price
`lp` | string | False
`None` | The last traded price of the instrument (also close price), expressed in `9` decimals | | last\_size
`ls` | string | False
`None` | The number of assets traded in the last trade, expressed in base asset decimal units | | mid\_price
`mp1` | string | False
`None` | The mid price of the instrument, expressed in `9` decimals | | best\_bid\_price
`bb` | string | False
`None` | The best bid price of the instrument, expressed in `9` decimals | | best\_bid\_size
`bb1` | string | False
`None` | The number of assets offered on the best bid price of the instrument, expressed in base asset decimal units | | best\_ask\_price
`ba` | string | False
`None` | The best ask price of the instrument, expressed in `9` decimals | | best\_ask\_size
`ba1` | string | False
`None` | The number of assets offered on the best ask price of the instrument, expressed in base asset decimal units | Success **Full Feed Response** `{ "stream": "v1.mini.d", "selector": "BTC_USDT_Perp", "sequence_number": "872634876", "feed": { "event_time": "1697788800000000000", "instrument": "BTC_USDT_Perp", "mark_price": "65038.01", "index_price": "65038.01", "last_price": "65038.01", "last_size": "123456.78", "mid_price": "65038.01", "best_bid_price": "65038.01", "best_bid_size": "123456.78", "best_ask_price": "65038.01", "best_ask_size": "123456.78" } }` **Lite Feed Response** `{ "s": "v1.mini.d", "s1": "BTC_USDT_Perp", "sn": "872634876", "f": { "et": "1697788800000000000", "i": "BTC_USDT_Perp", "mp": "65038.01", "ip": "65038.01", "lp": "65038.01", "ls": "123456.78", "mp1": "65038.01", "bb": "65038.01", "bb1": "123456.78", "ba": "65038.01", "ba1": "123456.78" } }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 1002 | 500 | Internal Server Error | | 1004 | 404 | Data Not Found | | 1101 | 400 | Feed Format must be in the format of @ | | 1102 | 400 | Wrong number of primary selectors | | 1103 | 400 | Wrong number of secondary selectors | | 3000 | 400 | Instrument is invalid | | 3030 | 400 | Feed rate is invalid | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | Error **Full Error Response** `{ "jsonrpc": "2.0", "error": { "code": 1002, "message": "Internal Server Error" }, "id": 123, "method": "subscribe" }` **Lite Error Response** `{ "j": "2.0", "e": { "c": 1002, "m": "Internal Server Error" }, "i": 123, "m": "subscribe" }` **Legacy Error Response** `{ "code":1002, "message":"Internal Server Error", "status":500 }` DEVSTAGINGTESTNETPROD Subscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.mini.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.mini.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.mini.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.mini.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.mini.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.mini.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.mini.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.mini.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.mini.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.mini.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.mini.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.mini.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.mini.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.mini.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.mini.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.mini.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.mini.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.mini.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.mini.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.mini.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.mini.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.mini.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.mini.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.mini.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` * * * ### Ticker Snap `STREAM: v1.ticker.s` Feed SelectorFeed DataErrorsTry it out [WSTickerFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_ticker_feed_selector_v1) Subscribes to a ticker feed for a single instrument. The `ticker.s` channel offers simpler integration. To experience higher publishing rates, please use the `ticker.d` channel. Unlike the `ticker.d` channel which publishes an initial snapshot, then only streams deltas after, the `ticker.s` channel publishes full snapshots at each feed. The Delta feed will work as follows: * On subscription, the server will send a full snapshot of the ticker. * After the snapshot, the server will only send deltas of the ticker. * The server will send a delta if any of the fields in the ticker have changed. Field Semantics: * \[DeltaOnly\] If a field is not updated, {} * If a field is updated, {field: '123'} * If a field is set to zero, {field: '0'} * If a field is set to null, {field: ''} | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | rate
`r` | integer | True | The minimal rate at which we publish feeds (in milliseconds)
Delta (100, 200, 500, 1000, 5000)
Snapshot (500, 1000, 5000) | JSONRPC Wrappers [JSONRPCRequest](https://api-docs.grvt.io/schemas/jsonrpc_request) All Websocket JSON RPC Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | method
`m` | string | True | The method to use for the request (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | | params
`p` | object | True | The parameters for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | [WSSubscribeParams](https://api-docs.grvt.io/schemas/ws_subscribe_params) All V1 Websocket Subscription Requests are housed in this wrapper. You may specify a stream and a list of feeds to subscribe to. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. Sequence numbers can be either gateway-specific or global: \- **Gateway Unique Sequence Number**: Increments by one per stream, resets to 0 on gateway restart. \- **Global Unique Sequence Number**: A cluster-wide unique number assigned to each cluster payload, does not reset on gateway restarts, and can be used to track and identify message order across streams using `sequence_number` and `prev_sequence_number` in the feed response. Set `useGlobalSequenceNumber = true` if you need a persistent, unique identifier across all streams or ordering across multiple feeds. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to subscribe to | [WSSubscribeResult](https://api-docs.grvt.io/schemas/ws_subscribe_result) To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | [WSUnsubscribeParams](https://api-docs.grvt.io/schemas/ws_unsubscribe_params) All V1 Websocket Unsubscription Requests are housed in this wrapper. You may specify a stream, a list of feeds and whether those feeds use global sequence numbers to unsubscribe from. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to unsubscribe from (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to unsubscribe from | [WSUnsubscribeResult](https://api-docs.grvt.io/schemas/ws_unsubscribe_result) Returns a confirmation of all unsubscribes | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | [WSSubscribeRequestV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_request_v1_legacy) All V1 Websocket Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | feed
`f` | \[string\] | True | The list of feeds to subscribe to | | method
`m` | string | True | The method to use for the request (eg: subscribe / unsubscribe) | | is\_full
`if` | boolean | False
`false` | Whether the request is for full data or lite data | [WSSubscribeResponseV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_response_v1_legacy) All V1 Websocket Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | Subscribe **Full Subscribe Request** `{ "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.ticker.s", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 }` **Full Subscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.ticker.s", "subs": ["BTC_USDT_Perp@500"], "unsubs": [], "num_snapshots": [10], "first_sequence_number": [872634876] }, "id": 123, "method": "subscribe" }` Unsubscribe **Full Unsubscribe Request** `{ "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.ticker.s", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 }` **Full Unsubscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.ticker.s", "unsubs": ["BTC_USDT_Perp@500"] }, "id": 123, "method": "subscribe" }` Legacy Subscribe **Full Subscribe Request** `{ "request_id":1, "stream":"v1.ticker.s", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true }` **Full Subscribe Response** `{ "request_id":1, "stream":"v1.ticker.s", "subs":["BTC_USDT_Perp@500"], "unsubs":[], "num_snapshots":[1], "first_sequence_number":[2813] }` [WSTickerFeedDataV1](https://api-docs.grvt.io/schemas/ws_ticker_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | Ticker | True | A ticker matching the request filter | [Ticker](https://api-docs.grvt.io/schemas/ticker) Derived data such as the below, will not be included by default: \- 24 hour volume (`buyVolume + sellVolume`) \- 24 hour taker buy/sell ratio (`buyVolume / sellVolume`) \- 24 hour average trade price (`volumeQ / volumeU`) \- 24 hour average trade volume (`volume / trades`) \- 24 hour percentage change (`24hStatChange / 24hStat`) \- 48 hour statistics (`2 * 24hStat - 24hStatChange`) To query for an extended ticker payload, leverage the `greeks` and the `derived` flags. Ticker extensions are currently under design to offer you more convenience. These flags are only supported on the `Ticker Snapshot` WS endpoint, and on the `Ticker` API endpoint. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | False
`None` | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | False
`None` | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | mark\_price
`mp` | string | False
`None` | The mark price of the instrument, expressed in `9` decimals | | index\_price
`ip` | string | False
`None` | The index price of the instrument, expressed in `9` decimals | | last\_price
`lp` | string | False
`None` | The last traded price of the instrument (also close price), expressed in `9` decimals | | last\_size
`ls` | string | False
`None` | The number of assets traded in the last trade, expressed in base asset decimal units | | mid\_price
`mp1` | string | False
`None` | The mid price of the instrument, expressed in `9` decimals | | best\_bid\_price
`bb` | string | False
`None` | The best bid price of the instrument, expressed in `9` decimals | | best\_bid\_size
`bb1` | string | False
`None` | The number of assets offered on the best bid price of the instrument, expressed in base asset decimal units | | best\_ask\_price
`ba` | string | False
`None` | The best ask price of the instrument, expressed in `9` decimals | | best\_ask\_size
`ba1` | string | False
`None` | The number of assets offered on the best ask price of the instrument, expressed in base asset decimal units | | funding\_rate\_8h\_curr
`fr` | string | False
`None` | DEPRECATED: To be removed in a future release. Please refer to the field `funding_rate` instead, for the funding rate being applied over `funding_interval_hours` (interval ending at `next_funding_time`). | | funding\_rate\_8h\_avg
`fr1` | string | False
`None` | DEPRECATED: To be removed in a future release. Please refer to the field `funding_rate` instead, for the funding rate being applied over `funding_interval_hours` (interval ending at `next_funding_time`). | | interest\_rate
`ir` | string | False
`None` | The interest rate of the underlying, expressed in centibeeps (1/100th of a basis point) | | forward\_price
`fp` | string | False
`None` | \[Options\] The forward price of the option, expressed in `9` decimals | | buy\_volume\_24h\_b
`bv` | string | False
`None` | The 24 hour taker buy volume of the instrument, expressed in base asset decimal units | | sell\_volume\_24h\_b
`sv` | string | False
`None` | The 24 hour taker sell volume of the instrument, expressed in base asset decimal units | | buy\_volume\_24h\_q
`bv1` | string | False
`None` | The 24 hour taker buy volume of the instrument, expressed in quote asset decimal units | | sell\_volume\_24h\_q
`sv1` | string | False
`None` | The 24 hour taker sell volume of the instrument, expressed in quote asset decimal units | | high\_price
`hp` | string | False
`None` | The 24 hour highest traded price of the instrument, expressed in `9` decimals | | low\_price
`lp1` | string | False
`None` | The 24 hour lowest traded price of the instrument, expressed in `9` decimals | | open\_price
`op` | string | False
`None` | The 24 hour first traded price of the instrument, expressed in `9` decimals | | open\_interest
`oi` | string | False
`None` | The open interest in the instrument, expressed in base asset decimal units | | long\_short\_ratio
`ls1` | string | False
`None` | The ratio of accounts that are net long vs net short on this instrument | | funding\_rate
`fr2` | string | False
`None` | The current indicative funding rate for the active interval, expressed in centibeeps | | next\_funding\_time
`nf` | string | False
`None` | Timestamp in nanoseconds when the current funding interval ends | Success **Full Feed Response** `{ "stream": "v1.ticker.s", "selector": "BTC_USDT_Perp", "sequence_number": "872634876", "feed": { "event_time": "1697788800000000000", "instrument": "BTC_USDT_Perp", "mark_price": "65038.01", "index_price": "65038.01", "last_price": "65038.01", "last_size": "123456.78", "mid_price": "65038.01", "best_bid_price": "65038.01", "best_bid_size": "123456.78", "best_ask_price": "65038.01", "best_ask_size": "123456.78", "funding_rate_8h_curr": 0.0003, "funding_rate_8h_avg": 0.0003, "interest_rate": 0.0003, "forward_price": "65038.01", "buy_volume_24h_b": "123456.78", "sell_volume_24h_b": "123456.78", "buy_volume_24h_q": "123456.78", "sell_volume_24h_q": "123456.78", "high_price": "65038.01", "low_price": "65038.01", "open_price": "65038.01", "open_interest": "123456.78", "long_short_ratio": "0.5", "funding_rate": 0.0003, "next_funding_time": "1697788800000000000" } }` **Lite Feed Response** `{ "s": "v1.ticker.s", "s1": "BTC_USDT_Perp", "sn": "872634876", "f": { "et": "1697788800000000000", "i": "BTC_USDT_Perp", "mp": "65038.01", "ip": "65038.01", "lp": "65038.01", "ls": "123456.78", "mp1": "65038.01", "bb": "65038.01", "bb1": "123456.78", "ba": "65038.01", "ba1": "123456.78", "fr": 0.0003, "fr1": 0.0003, "ir": 0.0003, "fp": "65038.01", "bv": "123456.78", "sv": "123456.78", "bv1": "123456.78", "sv1": "123456.78", "hp": "65038.01", "lp1": "65038.01", "op": "65038.01", "oi": "123456.78", "ls1": "0.5", "fr2": 0.0003, "nf": "1697788800000000000" } }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 1002 | 500 | Internal Server Error | | 1004 | 404 | Data Not Found | | 1101 | 400 | Feed Format must be in the format of @ | | 1102 | 400 | Wrong number of primary selectors | | 1103 | 400 | Wrong number of secondary selectors | | 3000 | 400 | Instrument is invalid | | 3030 | 400 | Feed rate is invalid | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | Error **Full Error Response** `{ "jsonrpc": "2.0", "error": { "code": 1002, "message": "Internal Server Error" }, "id": 123, "method": "subscribe" }` **Lite Error Response** `{ "j": "2.0", "e": { "c": 1002, "m": "Internal Server Error" }, "i": 123, "m": "subscribe" }` **Legacy Error Response** `{ "code":1002, "message":"Internal Server Error", "status":500 }` DEVSTAGINGTESTNETPROD Subscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.ticker.s", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.ticker.s", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.ticker.s", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.ticker.s", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.ticker.s", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.ticker.s", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.ticker.s", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.ticker.s", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.ticker.s", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.ticker.s", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.ticker.s", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.ticker.s", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.ticker.s", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.ticker.s", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.ticker.s", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.ticker.s", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.ticker.s", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.ticker.s", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.ticker.s", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.ticker.s", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.ticker.s", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.ticker.s", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.ticker.s", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.ticker.s", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` * * * ### Ticker Delta `STREAM: v1.ticker.d` Feed SelectorFeed DataErrorsTry it out [WSTickerFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_ticker_feed_selector_v1) Subscribes to a ticker feed for a single instrument. The `ticker.s` channel offers simpler integration. To experience higher publishing rates, please use the `ticker.d` channel. Unlike the `ticker.d` channel which publishes an initial snapshot, then only streams deltas after, the `ticker.s` channel publishes full snapshots at each feed. The Delta feed will work as follows: * On subscription, the server will send a full snapshot of the ticker. * After the snapshot, the server will only send deltas of the ticker. * The server will send a delta if any of the fields in the ticker have changed. Field Semantics: * \[DeltaOnly\] If a field is not updated, {} * If a field is updated, {field: '123'} * If a field is set to zero, {field: '0'} * If a field is set to null, {field: ''} | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | rate
`r` | integer | True | The minimal rate at which we publish feeds (in milliseconds)
Delta (100, 200, 500, 1000, 5000)
Snapshot (500, 1000, 5000) | JSONRPC Wrappers [JSONRPCRequest](https://api-docs.grvt.io/schemas/jsonrpc_request) All Websocket JSON RPC Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | method
`m` | string | True | The method to use for the request (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | | params
`p` | object | True | The parameters for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | [WSSubscribeParams](https://api-docs.grvt.io/schemas/ws_subscribe_params) All V1 Websocket Subscription Requests are housed in this wrapper. You may specify a stream and a list of feeds to subscribe to. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. Sequence numbers can be either gateway-specific or global: \- **Gateway Unique Sequence Number**: Increments by one per stream, resets to 0 on gateway restart. \- **Global Unique Sequence Number**: A cluster-wide unique number assigned to each cluster payload, does not reset on gateway restarts, and can be used to track and identify message order across streams using `sequence_number` and `prev_sequence_number` in the feed response. Set `useGlobalSequenceNumber = true` if you need a persistent, unique identifier across all streams or ordering across multiple feeds. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to subscribe to | [WSSubscribeResult](https://api-docs.grvt.io/schemas/ws_subscribe_result) To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | [WSUnsubscribeParams](https://api-docs.grvt.io/schemas/ws_unsubscribe_params) All V1 Websocket Unsubscription Requests are housed in this wrapper. You may specify a stream, a list of feeds and whether those feeds use global sequence numbers to unsubscribe from. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to unsubscribe from (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to unsubscribe from | [WSUnsubscribeResult](https://api-docs.grvt.io/schemas/ws_unsubscribe_result) Returns a confirmation of all unsubscribes | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | [WSSubscribeRequestV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_request_v1_legacy) All V1 Websocket Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | feed
`f` | \[string\] | True | The list of feeds to subscribe to | | method
`m` | string | True | The method to use for the request (eg: subscribe / unsubscribe) | | is\_full
`if` | boolean | False
`false` | Whether the request is for full data or lite data | [WSSubscribeResponseV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_response_v1_legacy) All V1 Websocket Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | Subscribe **Full Subscribe Request** `{ "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.ticker.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 }` **Full Subscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.ticker.d", "subs": ["BTC_USDT_Perp@500"], "unsubs": [], "num_snapshots": [10], "first_sequence_number": [872634876] }, "id": 123, "method": "subscribe" }` Unsubscribe **Full Unsubscribe Request** `{ "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.ticker.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 }` **Full Unsubscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.ticker.d", "unsubs": ["BTC_USDT_Perp@500"] }, "id": 123, "method": "subscribe" }` Legacy Subscribe **Full Subscribe Request** `{ "request_id":1, "stream":"v1.ticker.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true }` **Full Subscribe Response** `{ "request_id":1, "stream":"v1.ticker.d", "subs":["BTC_USDT_Perp@500"], "unsubs":[], "num_snapshots":[1], "first_sequence_number":[2813] }` [WSTickerFeedDataV1](https://api-docs.grvt.io/schemas/ws_ticker_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | Ticker | True | A ticker matching the request filter | [Ticker](https://api-docs.grvt.io/schemas/ticker) Derived data such as the below, will not be included by default: \- 24 hour volume (`buyVolume + sellVolume`) \- 24 hour taker buy/sell ratio (`buyVolume / sellVolume`) \- 24 hour average trade price (`volumeQ / volumeU`) \- 24 hour average trade volume (`volume / trades`) \- 24 hour percentage change (`24hStatChange / 24hStat`) \- 48 hour statistics (`2 * 24hStat - 24hStatChange`) To query for an extended ticker payload, leverage the `greeks` and the `derived` flags. Ticker extensions are currently under design to offer you more convenience. These flags are only supported on the `Ticker Snapshot` WS endpoint, and on the `Ticker` API endpoint. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | False
`None` | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | False
`None` | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | mark\_price
`mp` | string | False
`None` | The mark price of the instrument, expressed in `9` decimals | | index\_price
`ip` | string | False
`None` | The index price of the instrument, expressed in `9` decimals | | last\_price
`lp` | string | False
`None` | The last traded price of the instrument (also close price), expressed in `9` decimals | | last\_size
`ls` | string | False
`None` | The number of assets traded in the last trade, expressed in base asset decimal units | | mid\_price
`mp1` | string | False
`None` | The mid price of the instrument, expressed in `9` decimals | | best\_bid\_price
`bb` | string | False
`None` | The best bid price of the instrument, expressed in `9` decimals | | best\_bid\_size
`bb1` | string | False
`None` | The number of assets offered on the best bid price of the instrument, expressed in base asset decimal units | | best\_ask\_price
`ba` | string | False
`None` | The best ask price of the instrument, expressed in `9` decimals | | best\_ask\_size
`ba1` | string | False
`None` | The number of assets offered on the best ask price of the instrument, expressed in base asset decimal units | | funding\_rate\_8h\_curr
`fr` | string | False
`None` | DEPRECATED: To be removed in a future release. Please refer to the field `funding_rate` instead, for the funding rate being applied over `funding_interval_hours` (interval ending at `next_funding_time`). | | funding\_rate\_8h\_avg
`fr1` | string | False
`None` | DEPRECATED: To be removed in a future release. Please refer to the field `funding_rate` instead, for the funding rate being applied over `funding_interval_hours` (interval ending at `next_funding_time`). | | interest\_rate
`ir` | string | False
`None` | The interest rate of the underlying, expressed in centibeeps (1/100th of a basis point) | | forward\_price
`fp` | string | False
`None` | \[Options\] The forward price of the option, expressed in `9` decimals | | buy\_volume\_24h\_b
`bv` | string | False
`None` | The 24 hour taker buy volume of the instrument, expressed in base asset decimal units | | sell\_volume\_24h\_b
`sv` | string | False
`None` | The 24 hour taker sell volume of the instrument, expressed in base asset decimal units | | buy\_volume\_24h\_q
`bv1` | string | False
`None` | The 24 hour taker buy volume of the instrument, expressed in quote asset decimal units | | sell\_volume\_24h\_q
`sv1` | string | False
`None` | The 24 hour taker sell volume of the instrument, expressed in quote asset decimal units | | high\_price
`hp` | string | False
`None` | The 24 hour highest traded price of the instrument, expressed in `9` decimals | | low\_price
`lp1` | string | False
`None` | The 24 hour lowest traded price of the instrument, expressed in `9` decimals | | open\_price
`op` | string | False
`None` | The 24 hour first traded price of the instrument, expressed in `9` decimals | | open\_interest
`oi` | string | False
`None` | The open interest in the instrument, expressed in base asset decimal units | | long\_short\_ratio
`ls1` | string | False
`None` | The ratio of accounts that are net long vs net short on this instrument | | funding\_rate
`fr2` | string | False
`None` | The current indicative funding rate for the active interval, expressed in centibeeps | | next\_funding\_time
`nf` | string | False
`None` | Timestamp in nanoseconds when the current funding interval ends | Success **Full Feed Response** `{ "stream": "v1.ticker.d", "selector": "BTC_USDT_Perp", "sequence_number": "872634876", "feed": { "event_time": "1697788800000000000", "instrument": "BTC_USDT_Perp", "mark_price": "65038.01", "index_price": "65038.01", "last_price": "65038.01", "last_size": "123456.78", "mid_price": "65038.01", "best_bid_price": "65038.01", "best_bid_size": "123456.78", "best_ask_price": "65038.01", "best_ask_size": "123456.78", "funding_rate_8h_curr": 0.0003, "funding_rate_8h_avg": 0.0003, "interest_rate": 0.0003, "forward_price": "65038.01", "buy_volume_24h_b": "123456.78", "sell_volume_24h_b": "123456.78", "buy_volume_24h_q": "123456.78", "sell_volume_24h_q": "123456.78", "high_price": "65038.01", "low_price": "65038.01", "open_price": "65038.01", "open_interest": "123456.78", "long_short_ratio": "0.5", "funding_rate": 0.0003, "next_funding_time": "1697788800000000000" } }` **Lite Feed Response** `{ "s": "v1.ticker.d", "s1": "BTC_USDT_Perp", "sn": "872634876", "f": { "et": "1697788800000000000", "i": "BTC_USDT_Perp", "mp": "65038.01", "ip": "65038.01", "lp": "65038.01", "ls": "123456.78", "mp1": "65038.01", "bb": "65038.01", "bb1": "123456.78", "ba": "65038.01", "ba1": "123456.78", "fr": 0.0003, "fr1": 0.0003, "ir": 0.0003, "fp": "65038.01", "bv": "123456.78", "sv": "123456.78", "bv1": "123456.78", "sv1": "123456.78", "hp": "65038.01", "lp1": "65038.01", "op": "65038.01", "oi": "123456.78", "ls1": "0.5", "fr2": 0.0003, "nf": "1697788800000000000" } }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 1002 | 500 | Internal Server Error | | 1004 | 404 | Data Not Found | | 1101 | 400 | Feed Format must be in the format of @ | | 1102 | 400 | Wrong number of primary selectors | | 1103 | 400 | Wrong number of secondary selectors | | 3000 | 400 | Instrument is invalid | | 3030 | 400 | Feed rate is invalid | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | Error **Full Error Response** `{ "jsonrpc": "2.0", "error": { "code": 1002, "message": "Internal Server Error" }, "id": 123, "method": "subscribe" }` **Lite Error Response** `{ "j": "2.0", "e": { "c": 1002, "m": "Internal Server Error" }, "i": 123, "m": "subscribe" }` **Legacy Error Response** `{ "code":1002, "message":"Internal Server Error", "status":500 }` DEVSTAGINGTESTNETPROD Subscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.ticker.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.ticker.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.ticker.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.ticker.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.ticker.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.ticker.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.ticker.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.ticker.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.ticker.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.ticker.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.ticker.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.ticker.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.ticker.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.ticker.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.ticker.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.ticker.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.ticker.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.ticker.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.ticker.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.ticker.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.ticker.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.ticker.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.ticker.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.ticker.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` * * * Orderbook --------- ### Orderbook Snap `STREAM: v1.book.s` Feed SelectorFeed DataErrorsTry it out [WSOrderbookLevelsFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_orderbook_levels_feed_selector_v1) Subscribes to aggregated orderbook updates for a single instrument. The `book.s` channel offers simpler integration. To experience higher publishing rates, please use the `book.d` channel. Unlike the `book.d` channel which publishes an initial snapshot, then only streams deltas after, the `book.s` channel publishes full snapshots at each feed. The Delta feed will work as follows: * On subscription, the server will send a full snapshot of all levels of the Orderbook. * After the snapshot, the server will only send levels that have changed in value. Subscription Pattern: * Delta - `instrument@rate` * Snapshot - `instrument@rate-depth` Field Semantics: * \[DeltaOnly\] If a level is not updated, level not published * If a level is updated, {size: '123'} * If a level is set to zero, {size: '0'} * Incoming levels will be published as soon as price moves * Outgoing levels will be published with `size = 0` | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | rate
`r` | integer | True | The minimal rate at which we publish feeds (in milliseconds)
Delta (50, 100, 500, 1000)
Snapshot (500, 1000) | | depth
`d` | integer | False
`'0'` | Depth of the order book to be retrieved
Delta(0 - `unlimited`)
Snapshot(10, 50, 100, 500) | JSONRPC Wrappers [JSONRPCRequest](https://api-docs.grvt.io/schemas/jsonrpc_request) All Websocket JSON RPC Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | method
`m` | string | True | The method to use for the request (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | | params
`p` | object | True | The parameters for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | [WSSubscribeParams](https://api-docs.grvt.io/schemas/ws_subscribe_params) All V1 Websocket Subscription Requests are housed in this wrapper. You may specify a stream and a list of feeds to subscribe to. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. Sequence numbers can be either gateway-specific or global: \- **Gateway Unique Sequence Number**: Increments by one per stream, resets to 0 on gateway restart. \- **Global Unique Sequence Number**: A cluster-wide unique number assigned to each cluster payload, does not reset on gateway restarts, and can be used to track and identify message order across streams using `sequence_number` and `prev_sequence_number` in the feed response. Set `useGlobalSequenceNumber = true` if you need a persistent, unique identifier across all streams or ordering across multiple feeds. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to subscribe to | [WSSubscribeResult](https://api-docs.grvt.io/schemas/ws_subscribe_result) To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | [WSUnsubscribeParams](https://api-docs.grvt.io/schemas/ws_unsubscribe_params) All V1 Websocket Unsubscription Requests are housed in this wrapper. You may specify a stream, a list of feeds and whether those feeds use global sequence numbers to unsubscribe from. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to unsubscribe from (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to unsubscribe from | [WSUnsubscribeResult](https://api-docs.grvt.io/schemas/ws_unsubscribe_result) Returns a confirmation of all unsubscribes | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | [WSSubscribeRequestV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_request_v1_legacy) All V1 Websocket Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | feed
`f` | \[string\] | True | The list of feeds to subscribe to | | method
`m` | string | True | The method to use for the request (eg: subscribe / unsubscribe) | | is\_full
`if` | boolean | False
`false` | Whether the request is for full data or lite data | [WSSubscribeResponseV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_response_v1_legacy) All V1 Websocket Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | Subscribe **Full Subscribe Request** `{ "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.book.s", "selectors": ["BTC_USDT_Perp@500-50"] }, "id": 123 }` **Full Subscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.book.s", "subs": ["BTC_USDT_Perp@500-50"], "unsubs": [], "num_snapshots": [10], "first_sequence_number": [872634876] }, "id": 123, "method": "subscribe" }` Unsubscribe **Full Unsubscribe Request** `{ "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.book.s", "selectors": ["BTC_USDT_Perp@500-50"] }, "id": 123 }` **Full Unsubscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.book.s", "unsubs": ["BTC_USDT_Perp@500-50"] }, "id": 123, "method": "subscribe" }` Legacy Subscribe **Full Subscribe Request** `{ "request_id":1, "stream":"v1.book.s", "feed":["BTC_USDT_Perp@500-50"], "method":"subscribe", "is_full":true }` **Full Subscribe Response** `{ "request_id":1, "stream":"v1.book.s", "subs":["BTC_USDT_Perp@500-50"], "unsubs":[], "num_snapshots":[1], "first_sequence_number":[2813] }` [WSOrderbookLevelsFeedDataV1](https://api-docs.grvt.io/schemas/ws_orderbook_levels_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | OrderbookLevels | True | An orderbook levels object matching the request filter | [OrderbookLevels](https://api-docs.grvt.io/schemas/orderbook_levels) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | True | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | bids
`b` | \[OrderbookLevel\] | True | The list of best bids up till query depth | | asks
`a` | \[OrderbookLevel\] | True | The list of best asks up till query depth | [OrderbookLevel](https://api-docs.grvt.io/schemas/orderbook_level) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | price
`p` | string | True | The price of the level, expressed in `9` decimals | | size
`s` | string | True | The number of assets offered, expressed in base asset decimal units | | num\_orders
`no` | integer | True | The number of open orders at this level | [OrderbookLevel](https://api-docs.grvt.io/schemas/orderbook_level) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | price
`p` | string | True | The price of the level, expressed in `9` decimals | | size
`s` | string | True | The number of assets offered, expressed in base asset decimal units | | num\_orders
`no` | integer | True | The number of open orders at this level | Success **Full Feed Response** `{ "stream": "v1.book.s", "selector": "BTC_USDT_Perp", "sequence_number": "872634876", "feed": { "event_time": "1697788800000000000", "instrument": "BTC_USDT_Perp", "bids": [{ "price": "65038.01", "size": "3456.78", "num_orders": 123 }], "asks": [{ "price": "65038.01", "size": "3456.78", "num_orders": 123 }] } }` **Lite Feed Response** `{ "s": "v1.book.s", "s1": "BTC_USDT_Perp", "sn": "872634876", "f": { "et": "1697788800000000000", "i": "BTC_USDT_Perp", "b": [{ "p": "65038.01", "s": "3456.78", "no": 123 }], "a": [{ "p": "65038.01", "s": "3456.78", "no": 123 }] } }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 1002 | 500 | Internal Server Error | | 1004 | 404 | Data Not Found | | 1101 | 400 | Feed Format must be in the format of @ | | 1102 | 400 | Wrong number of primary selectors | | 1103 | 400 | Wrong number of secondary selectors | | 3000 | 400 | Instrument is invalid | | 3030 | 400 | Feed rate is invalid | | 3031 | 400 | Depth is invalid | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | Error **Full Error Response** `{ "jsonrpc": "2.0", "error": { "code": 1002, "message": "Internal Server Error" }, "id": 123, "method": "subscribe" }` **Lite Error Response** `{ "j": "2.0", "e": { "c": 1002, "m": "Internal Server Error" }, "i": 123, "m": "subscribe" }` **Legacy Error Response** `{ "code":1002, "message":"Internal Server Error", "status":500 }` DEVSTAGINGTESTNETPROD Subscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.book.s", "selectors": ["BTC_USDT_Perp@500-50"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.book.s", "selectors": ["BTC_USDT_Perp@500-50"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.book.s", "feed":["BTC_USDT_Perp@500-50"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.book.s", "s1": ["BTC_USDT_Perp@500-50"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.book.s", "s1": ["BTC_USDT_Perp@500-50"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.book.s", "feed":["BTC_USDT_Perp@500-50"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.book.s", "selectors": ["BTC_USDT_Perp@500-50"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.book.s", "selectors": ["BTC_USDT_Perp@500-50"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.book.s", "feed":["BTC_USDT_Perp@500-50"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.book.s", "s1": ["BTC_USDT_Perp@500-50"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.book.s", "s1": ["BTC_USDT_Perp@500-50"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.book.s", "feed":["BTC_USDT_Perp@500-50"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.book.s", "selectors": ["BTC_USDT_Perp@500-50"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.book.s", "selectors": ["BTC_USDT_Perp@500-50"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.book.s", "feed":["BTC_USDT_Perp@500-50"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.book.s", "s1": ["BTC_USDT_Perp@500-50"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.book.s", "s1": ["BTC_USDT_Perp@500-50"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.book.s", "feed":["BTC_USDT_Perp@500-50"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.book.s", "selectors": ["BTC_USDT_Perp@500-50"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.book.s", "selectors": ["BTC_USDT_Perp@500-50"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.book.s", "feed":["BTC_USDT_Perp@500-50"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.book.s", "s1": ["BTC_USDT_Perp@500-50"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.book.s", "s1": ["BTC_USDT_Perp@500-50"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.book.s", "feed":["BTC_USDT_Perp@500-50"], "method":"subscribe", "is_full":false } ' -w 360` * * * ### Orderbook Delta `STREAM: v1.book.d` Feed SelectorFeed DataErrorsTry it out [WSOrderbookLevelsFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_orderbook_levels_feed_selector_v1) Subscribes to aggregated orderbook updates for a single instrument. The `book.s` channel offers simpler integration. To experience higher publishing rates, please use the `book.d` channel. Unlike the `book.d` channel which publishes an initial snapshot, then only streams deltas after, the `book.s` channel publishes full snapshots at each feed. The Delta feed will work as follows: * On subscription, the server will send a full snapshot of all levels of the Orderbook. * After the snapshot, the server will only send levels that have changed in value. Subscription Pattern: * Delta - `instrument@rate` * Snapshot - `instrument@rate-depth` Field Semantics: * \[DeltaOnly\] If a level is not updated, level not published * If a level is updated, {size: '123'} * If a level is set to zero, {size: '0'} * Incoming levels will be published as soon as price moves * Outgoing levels will be published with `size = 0` | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | rate
`r` | integer | True | The minimal rate at which we publish feeds (in milliseconds)
Delta (50, 100, 500, 1000)
Snapshot (500, 1000) | | depth
`d` | integer | False
`'0'` | Depth of the order book to be retrieved
Delta(0 - `unlimited`)
Snapshot(10, 50, 100, 500) | JSONRPC Wrappers [JSONRPCRequest](https://api-docs.grvt.io/schemas/jsonrpc_request) All Websocket JSON RPC Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | method
`m` | string | True | The method to use for the request (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | | params
`p` | object | True | The parameters for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | [WSSubscribeParams](https://api-docs.grvt.io/schemas/ws_subscribe_params) All V1 Websocket Subscription Requests are housed in this wrapper. You may specify a stream and a list of feeds to subscribe to. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. Sequence numbers can be either gateway-specific or global: \- **Gateway Unique Sequence Number**: Increments by one per stream, resets to 0 on gateway restart. \- **Global Unique Sequence Number**: A cluster-wide unique number assigned to each cluster payload, does not reset on gateway restarts, and can be used to track and identify message order across streams using `sequence_number` and `prev_sequence_number` in the feed response. Set `useGlobalSequenceNumber = true` if you need a persistent, unique identifier across all streams or ordering across multiple feeds. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to subscribe to | [WSSubscribeResult](https://api-docs.grvt.io/schemas/ws_subscribe_result) To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | [WSUnsubscribeParams](https://api-docs.grvt.io/schemas/ws_unsubscribe_params) All V1 Websocket Unsubscription Requests are housed in this wrapper. You may specify a stream, a list of feeds and whether those feeds use global sequence numbers to unsubscribe from. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to unsubscribe from (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to unsubscribe from | [WSUnsubscribeResult](https://api-docs.grvt.io/schemas/ws_unsubscribe_result) Returns a confirmation of all unsubscribes | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | [WSSubscribeRequestV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_request_v1_legacy) All V1 Websocket Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | feed
`f` | \[string\] | True | The list of feeds to subscribe to | | method
`m` | string | True | The method to use for the request (eg: subscribe / unsubscribe) | | is\_full
`if` | boolean | False
`false` | Whether the request is for full data or lite data | [WSSubscribeResponseV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_response_v1_legacy) All V1 Websocket Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | Subscribe **Full Subscribe Request** `{ "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.book.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 }` **Full Subscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.book.d", "subs": ["BTC_USDT_Perp@500"], "unsubs": [], "num_snapshots": [10], "first_sequence_number": [872634876] }, "id": 123, "method": "subscribe" }` Unsubscribe **Full Unsubscribe Request** `{ "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.book.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 }` **Full Unsubscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.book.d", "unsubs": ["BTC_USDT_Perp@500"] }, "id": 123, "method": "subscribe" }` Legacy Subscribe **Full Subscribe Request** `{ "request_id":1, "stream":"v1.book.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true }` **Full Subscribe Response** `{ "request_id":1, "stream":"v1.book.d", "subs":["BTC_USDT_Perp@500"], "unsubs":[], "num_snapshots":[1], "first_sequence_number":[2813] }` [WSOrderbookLevelsFeedDataV1](https://api-docs.grvt.io/schemas/ws_orderbook_levels_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | OrderbookLevels | True | An orderbook levels object matching the request filter | [OrderbookLevels](https://api-docs.grvt.io/schemas/orderbook_levels) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | True | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | bids
`b` | \[OrderbookLevel\] | True | The list of best bids up till query depth | | asks
`a` | \[OrderbookLevel\] | True | The list of best asks up till query depth | [OrderbookLevel](https://api-docs.grvt.io/schemas/orderbook_level) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | price
`p` | string | True | The price of the level, expressed in `9` decimals | | size
`s` | string | True | The number of assets offered, expressed in base asset decimal units | | num\_orders
`no` | integer | True | The number of open orders at this level | [OrderbookLevel](https://api-docs.grvt.io/schemas/orderbook_level) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | price
`p` | string | True | The price of the level, expressed in `9` decimals | | size
`s` | string | True | The number of assets offered, expressed in base asset decimal units | | num\_orders
`no` | integer | True | The number of open orders at this level | Success **Full Feed Response** `{ "stream": "v1.book.d", "selector": "BTC_USDT_Perp", "sequence_number": "872634876", "feed": { "event_time": "1697788800000000000", "instrument": "BTC_USDT_Perp", "bids": [{ "price": "65038.01", "size": "3456.78", "num_orders": 123 }], "asks": [{ "price": "65038.01", "size": "3456.78", "num_orders": 123 }] } }` **Lite Feed Response** `{ "s": "v1.book.d", "s1": "BTC_USDT_Perp", "sn": "872634876", "f": { "et": "1697788800000000000", "i": "BTC_USDT_Perp", "b": [{ "p": "65038.01", "s": "3456.78", "no": 123 }], "a": [{ "p": "65038.01", "s": "3456.78", "no": 123 }] } }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 1002 | 500 | Internal Server Error | | 1004 | 404 | Data Not Found | | 1101 | 400 | Feed Format must be in the format of @ | | 1102 | 400 | Wrong number of primary selectors | | 1103 | 400 | Wrong number of secondary selectors | | 3000 | 400 | Instrument is invalid | | 3030 | 400 | Feed rate is invalid | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | Error **Full Error Response** `{ "jsonrpc": "2.0", "error": { "code": 1002, "message": "Internal Server Error" }, "id": 123, "method": "subscribe" }` **Lite Error Response** `{ "j": "2.0", "e": { "c": 1002, "m": "Internal Server Error" }, "i": 123, "m": "subscribe" }` **Legacy Error Response** `{ "code":1002, "message":"Internal Server Error", "status":500 }` DEVSTAGINGTESTNETPROD Subscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.book.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.book.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.book.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.book.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.book.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.book.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.book.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.book.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.book.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.book.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.book.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.book.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.book.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.book.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.book.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.book.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.book.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.book.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.book.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.book.d", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.book.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.book.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.book.d", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.book.d", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` * * * Trade ----- ### Trade `STREAM: v1.trade` Feed SelectorFeed DataErrorsTry it out [WSTradeFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_trade_feed_selector_v1) Subscribes to a stream of Public Trades for an instrument. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | limit
`l` | integer | True | The limit to query for. Valid values are (50, 200, 500, 1000). Default is 50 | JSONRPC Wrappers [JSONRPCRequest](https://api-docs.grvt.io/schemas/jsonrpc_request) All Websocket JSON RPC Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | method
`m` | string | True | The method to use for the request (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | | params
`p` | object | True | The parameters for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | [WSSubscribeParams](https://api-docs.grvt.io/schemas/ws_subscribe_params) All V1 Websocket Subscription Requests are housed in this wrapper. You may specify a stream and a list of feeds to subscribe to. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. Sequence numbers can be either gateway-specific or global: \- **Gateway Unique Sequence Number**: Increments by one per stream, resets to 0 on gateway restart. \- **Global Unique Sequence Number**: A cluster-wide unique number assigned to each cluster payload, does not reset on gateway restarts, and can be used to track and identify message order across streams using `sequence_number` and `prev_sequence_number` in the feed response. Set `useGlobalSequenceNumber = true` if you need a persistent, unique identifier across all streams or ordering across multiple feeds. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to subscribe to | [WSSubscribeResult](https://api-docs.grvt.io/schemas/ws_subscribe_result) To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | [WSUnsubscribeParams](https://api-docs.grvt.io/schemas/ws_unsubscribe_params) All V1 Websocket Unsubscription Requests are housed in this wrapper. You may specify a stream, a list of feeds and whether those feeds use global sequence numbers to unsubscribe from. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to unsubscribe from (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to unsubscribe from | [WSUnsubscribeResult](https://api-docs.grvt.io/schemas/ws_unsubscribe_result) Returns a confirmation of all unsubscribes | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | [WSSubscribeRequestV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_request_v1_legacy) All V1 Websocket Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | feed
`f` | \[string\] | True | The list of feeds to subscribe to | | method
`m` | string | True | The method to use for the request (eg: subscribe / unsubscribe) | | is\_full
`if` | boolean | False
`false` | Whether the request is for full data or lite data | [WSSubscribeResponseV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_response_v1_legacy) All V1 Websocket Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | Subscribe **Full Subscribe Request** `{ "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.trade", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 }` **Full Subscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.trade", "subs": ["BTC_USDT_Perp@500"], "unsubs": [], "num_snapshots": [10], "first_sequence_number": [872634876] }, "id": 123, "method": "subscribe" }` Unsubscribe **Full Unsubscribe Request** `{ "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.trade", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 }` **Full Unsubscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.trade", "unsubs": ["BTC_USDT_Perp@500"] }, "id": 123, "method": "subscribe" }` Legacy Subscribe **Full Subscribe Request** `{ "request_id":1, "stream":"v1.trade", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true }` **Full Subscribe Response** `{ "request_id":1, "stream":"v1.trade", "subs":["BTC_USDT_Perp@500"], "unsubs":[], "num_snapshots":[1], "first_sequence_number":[2813] }` [WSTradeFeedDataV1](https://api-docs.grvt.io/schemas/ws_trade_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | Trade | True | A public trade matching the request filter | [Trade](https://api-docs.grvt.io/schemas/trade) All private RFQs and Private AXEs will be filtered out from the responses | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | True | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | is\_taker\_buyer
`it` | boolean | True | If taker was the buyer 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 | | 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`. | | venue
`v` | Venue | True | The venue where the trade occurred | | is\_rpi
`ir1` | boolean | True | If the trade is a RPI trade | [Venue](https://api-docs.grvt.io/schemas/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 | Success **Full Feed Response** `{ "stream": "v1.trade", "selector": "BTC_USDT_Perp", "sequence_number": "872634876", "feed": { "event_time": "1697788800000000000", "instrument": "BTC_USDT_Perp", "is_taker_buyer": true, "size": "123456.78", "price": "65038.01", "mark_price": "65038.01", "index_price": "65038.01", "interest_rate": 0.0003, "forward_price": "65038.01", "trade_id": "209358-2", "venue": "ORDERBOOK", "is_rpi": false } }` **Lite Feed Response** `{ "s": "v1.trade", "s1": "BTC_USDT_Perp", "sn": "872634876", "f": { "et": "1697788800000000000", "i": "BTC_USDT_Perp", "it": true, "s": "123456.78", "p": "65038.01", "mp": "65038.01", "ip": "65038.01", "ir": 0.0003, "fp": "65038.01", "ti": "209358-2", "v": "ORDERBOOK", "ir1": false } }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 1002 | 500 | Internal Server Error | | 1101 | 400 | Feed Format must be in the format of @ | | 1102 | 400 | Wrong number of primary selectors | | 1103 | 400 | Wrong number of secondary selectors | | 3000 | 400 | Instrument is invalid | | 3011 | 400 | Limit exceeds min or max value | | 3013 | 400 | Exact limit value is not supported | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | Error **Full Error Response** `{ "jsonrpc": "2.0", "error": { "code": 1002, "message": "Internal Server Error" }, "id": 123, "method": "subscribe" }` **Lite Error Response** `{ "j": "2.0", "e": { "c": 1002, "m": "Internal Server Error" }, "i": 123, "m": "subscribe" }` **Legacy Error Response** `{ "code":1002, "message":"Internal Server Error", "status":500 }` DEVSTAGINGTESTNETPROD Subscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.trade", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.trade", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.trade", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.trade", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.trade", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.trade", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.trade", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.trade", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.trade", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.trade", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.trade", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.trade", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.trade", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.trade", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.trade", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.trade", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.trade", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.trade", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.trade", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.trade", "selectors": ["BTC_USDT_Perp@500"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.trade", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.trade", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.trade", "s1": ["BTC_USDT_Perp@500"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.trade", "feed":["BTC_USDT_Perp@500"], "method":"subscribe", "is_full":false } ' -w 360` * * * Candlestick ----------- ### Candlestick `STREAM: v1.candle` Feed SelectorFeed DataErrorsTry it out [WSCandlestickFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_candlestick_feed_selector_v1) Subscribes to a stream of Kline/Candlestick updates for an instrument. A Kline is uniquely identified by its open time. A new Kline is published every interval (if it exists). Upon subscription, the server will send the 5 most recent Kline for the requested interval. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | interval
`i1` | CandlestickInterval | True | The interval of each candlestick | | type
`t` | CandlestickType | True | The type of candlestick data to retrieve | [CandlestickInterval](https://api-docs.grvt.io/schemas/candlestick_interval) | Value | Description | | --- | --- | | `CI_1_M` = 1 | 1 minute | | `CI_3_M` = 2 | 3 minutes | | `CI_5_M` = 3 | 5 minutes | | `CI_15_M` = 4 | 15 minutes | | `CI_30_M` = 5 | 30 minutes | | `CI_1_H` = 6 | 1 hour | | `CI_2_H` = 7 | 2 hour | | `CI_4_H` = 8 | 4 hour | | `CI_6_H` = 9 | 6 hour | | `CI_8_H` = 10 | 8 hour | | `CI_12_H` = 11 | 12 hour | | `CI_1_D` = 12 | 1 day | | `CI_3_D` = 13 | 3 days | | `CI_5_D` = 14 | 5 days | | `CI_1_W` = 15 | 1 week | | `CI_2_W` = 16 | 2 weeks | | `CI_3_W` = 17 | 3 weeks | | `CI_4_W` = 18 | 4 weeks | [CandlestickType](https://api-docs.grvt.io/schemas/candlestick_type) | Value | Description | | --- | --- | | `TRADE` = 1 | Tracks traded prices | | `MARK` = 2 | Tracks mark prices | | `INDEX` = 3 | Tracks index prices | | `MID` = 4 | Tracks book mid prices | JSONRPC Wrappers [JSONRPCRequest](https://api-docs.grvt.io/schemas/jsonrpc_request) All Websocket JSON RPC Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | method
`m` | string | True | The method to use for the request (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | | params
`p` | object | True | The parameters for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | [WSSubscribeParams](https://api-docs.grvt.io/schemas/ws_subscribe_params) All V1 Websocket Subscription Requests are housed in this wrapper. You may specify a stream and a list of feeds to subscribe to. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. Sequence numbers can be either gateway-specific or global: \- **Gateway Unique Sequence Number**: Increments by one per stream, resets to 0 on gateway restart. \- **Global Unique Sequence Number**: A cluster-wide unique number assigned to each cluster payload, does not reset on gateway restarts, and can be used to track and identify message order across streams using `sequence_number` and `prev_sequence_number` in the feed response. Set `useGlobalSequenceNumber = true` if you need a persistent, unique identifier across all streams or ordering across multiple feeds. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to subscribe to | [WSSubscribeResult](https://api-docs.grvt.io/schemas/ws_subscribe_result) To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | [WSUnsubscribeParams](https://api-docs.grvt.io/schemas/ws_unsubscribe_params) All V1 Websocket Unsubscription Requests are housed in this wrapper. You may specify a stream, a list of feeds and whether those feeds use global sequence numbers to unsubscribe from. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to unsubscribe from (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to unsubscribe from | [WSUnsubscribeResult](https://api-docs.grvt.io/schemas/ws_unsubscribe_result) Returns a confirmation of all unsubscribes | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | [WSSubscribeRequestV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_request_v1_legacy) All V1 Websocket Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | feed
`f` | \[string\] | True | The list of feeds to subscribe to | | method
`m` | string | True | The method to use for the request (eg: subscribe / unsubscribe) | | is\_full
`if` | boolean | False
`false` | Whether the request is for full data or lite data | [WSSubscribeResponseV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_response_v1_legacy) All V1 Websocket Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | Subscribe **Full Subscribe Request** `{ "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.candle", "selectors": ["BTC_USDT_Perp@CI_1_M-TRADE"] }, "id": 123 }` **Full Subscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.candle", "subs": ["BTC_USDT_Perp@CI_1_M-TRADE"], "unsubs": [], "num_snapshots": [10], "first_sequence_number": [872634876] }, "id": 123, "method": "subscribe" }` Unsubscribe **Full Unsubscribe Request** `{ "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.candle", "selectors": ["BTC_USDT_Perp@CI_1_M-TRADE"] }, "id": 123 }` **Full Unsubscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.candle", "unsubs": ["BTC_USDT_Perp@CI_1_M-TRADE"] }, "id": 123, "method": "subscribe" }` Legacy Subscribe **Full Subscribe Request** `{ "request_id":1, "stream":"v1.candle", "feed":["BTC_USDT_Perp@CI_1_M-TRADE"], "method":"subscribe", "is_full":true }` **Full Subscribe Response** `{ "request_id":1, "stream":"v1.candle", "subs":["BTC_USDT_Perp@CI_1_M-TRADE"], "unsubs":[], "num_snapshots":[1], "first_sequence_number":[2813] }` [WSCandlestickFeedDataV1](https://api-docs.grvt.io/schemas/ws_candlestick_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | Candlestick | True | A candlestick entry matching the request filters | [Candlestick](https://api-docs.grvt.io/schemas/candlestick) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | open\_time
`ot` | string | True | Open time of kline bar in unix nanoseconds | | close\_time
`ct` | string | True | Close time of kline bar in unix nanosecond | | open
`o` | string | True | The open price, expressed in underlying currency resolution units | | close
`c` | string | True | The close price, expressed in underlying currency resolution units | | high
`h` | string | True | The high price, expressed in underlying currency resolution units | | low
`l` | string | True | The low price, expressed in underlying currency resolution units | | volume\_b
`vb` | string | True | The underlying volume transacted, expressed in base asset decimal units | | volume\_q
`vq` | string | True | The quote volume transacted, expressed in quote asset decimal units | | trades
`t` | integer | True | The number of trades transacted | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | Success **Full Feed Response** `{ "stream": "v1.candle", "selector": "BTC_USDT_Perp", "sequence_number": "872634876", "feed": { "open_time": "1697788800000000000", "close_time": "1697788800000000000", "open": "123456.78", "close": "123456.78", "high": "123456.78", "low": "123456.78", "volume_b": "123456.78", "volume_q": "123456.78", "trades": 123456, "instrument": "BTC_USDT_Perp" } }` **Lite Feed Response** `{ "s": "v1.candle", "s1": "BTC_USDT_Perp", "sn": "872634876", "f": { "ot": "1697788800000000000", "ct": "1697788800000000000", "o": "123456.78", "c": "123456.78", "h": "123456.78", "l": "123456.78", "vb": "123456.78", "vq": "123456.78", "t": 123456, "i": "BTC_USDT_Perp" } }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 1002 | 500 | Internal Server Error | | 1101 | 400 | Feed Format must be in the format of @ | | 1102 | 400 | Wrong number of primary selectors | | 1103 | 400 | Wrong number of secondary selectors | | 3000 | 400 | Instrument is invalid | | 3040 | 400 | Candlestick interval is invalid | | 3041 | 400 | Candlestick type is invalid | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | Error **Full Error Response** `{ "jsonrpc": "2.0", "error": { "code": 1002, "message": "Internal Server Error" }, "id": 123, "method": "subscribe" }` **Lite Error Response** `{ "j": "2.0", "e": { "c": 1002, "m": "Internal Server Error" }, "i": 123, "m": "subscribe" }` **Legacy Error Response** `{ "code":1002, "message":"Internal Server Error", "status":500 }` DEVSTAGINGTESTNETPROD Subscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.candle", "selectors": ["BTC_USDT_Perp@CI_1_M-TRADE"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.candle", "selectors": ["BTC_USDT_Perp@CI_1_M-TRADE"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.candle", "feed":["BTC_USDT_Perp@CI_1_M-TRADE"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.candle", "s1": ["BTC_USDT_Perp@CI_1_M-TRADE"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.candle", "s1": ["BTC_USDT_Perp@CI_1_M-TRADE"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.candle", "feed":["BTC_USDT_Perp@CI_1_M-TRADE"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.candle", "selectors": ["BTC_USDT_Perp@CI_1_M-TRADE"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.candle", "selectors": ["BTC_USDT_Perp@CI_1_M-TRADE"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.candle", "feed":["BTC_USDT_Perp@CI_1_M-TRADE"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.candle", "s1": ["BTC_USDT_Perp@CI_1_M-TRADE"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.candle", "s1": ["BTC_USDT_Perp@CI_1_M-TRADE"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws" \ -x ' { "request_id":1, "stream":"v1.candle", "feed":["BTC_USDT_Perp@CI_1_M-TRADE"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.candle", "selectors": ["BTC_USDT_Perp@CI_1_M-TRADE"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.candle", "selectors": ["BTC_USDT_Perp@CI_1_M-TRADE"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.testnet.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.candle", "feed":["BTC_USDT_Perp@CI_1_M-TRADE"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.candle", "s1": ["BTC_USDT_Perp@CI_1_M-TRADE"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.candle", "s1": ["BTC_USDT_Perp@CI_1_M-TRADE"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.testnet.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.candle", "feed":["BTC_USDT_Perp@CI_1_M-TRADE"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.candle", "selectors": ["BTC_USDT_Perp@CI_1_M-TRADE"] }, "id": 123 } ' -w 360` Unsubscribe Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.candle", "selectors": ["BTC_USDT_Perp@CI_1_M-TRADE"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://market-data.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.candle", "feed":["BTC_USDT_Perp@CI_1_M-TRADE"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "subscribe", "p": { "s": "v1.candle", "s1": ["BTC_USDT_Perp@CI_1_M-TRADE"] }, "i": 123 } ' -w 360` Unsubscribe Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "unsubscribe", "p": { "s": "v1.candle", "s1": ["BTC_USDT_Perp@CI_1_M-TRADE"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://market-data.grvt.io/ws" \ -x ' { "request_id":1, "stream":"v1.candle", "feed":["BTC_USDT_Perp@CI_1_M-TRADE"], "method":"subscribe", "is_full":false } ' -w 360` * * * Back to top --- # Market Data API - Gravity Markets API Docs [Skip to content](https://api-docs.grvt.io/market_data_api/#marketdata-apis) MarketData APIs =============== All requests should be made using the `POST` HTTP method. Instrument ---------- ### Get Instrument `FULL ENDPOINT: full/v1/instrument LITE ENDPOINT: lite/v1/instrument` RequestResponseErrorsTry it out [ApiGetInstrumentRequest](https://api-docs.grvt.io/schemas/api_get_instrument_request) Fetch a single instrument by supplying the asset or instrument name | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | Query **Full Request** `{ "instrument": "BTC_USDT_Perp" }` **Lite Request** `{ "i": "BTC_USDT_Perp" }` [ApiGetInstrumentResponse](https://api-docs.grvt.io/schemas/api_get_instrument_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | InstrumentDisplay | True | The instrument matching the request asset | [InstrumentDisplay](https://api-docs.grvt.io/schemas/instrument_display) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | instrument\_hash
`ih` | string | True | The asset ID used for instrument signing. | | base
`b` | string | True | The base currency | | quote
`q` | string | True | The quote currency | | kind
`k` | Kind | True | The kind of instrument | | venues
`v` | \[Venue\] | True | Venues that this instrument can be traded at | | settlement\_period
`sp1` | InstrumentSettlementPeriod | True | The settlement period of the instrument | | base\_decimals
`bd` | integer | True | The smallest denomination of the base asset supported by GRVT (+3 represents 0.001, -3 represents 1000, 0 represents 1) | | quote\_decimals
`qd` | integer | True | The smallest denomination of the quote asset supported by GRVT (+3 represents 0.001, -3 represents 1000, 0 represents 1) | | tick\_size
`ts` | string | True | The size of a single tick, expressed in price decimal units | | min\_size
`ms` | string | True | The minimum contract size, expressed in base asset decimal units | | create\_time
`ct` | string | True | Creation time in unix nanoseconds | | max\_position\_size
`mp` | string | True | The maximum position size, expressed in base asset decimal units | | funding\_interval\_hours
`fi` | integer | False
`None` | Defines the funding interval to be applied. | | adjusted\_funding\_rate\_cap
`af` | string | False
`None` | Funding rate cap over the defined `intervalHours`. | | adjusted\_funding\_rate\_floor
`af1` | string | False
`None` | Funding rate floor over the defined `intervalHours`. | | min\_notional
`mn` | string | True | The minimum order notional value, expressed in quote currency decimal units | [Kind](https://api-docs.grvt.io/schemas/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 | [Venue](https://api-docs.grvt.io/schemas/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 | [InstrumentSettlementPeriod](https://api-docs.grvt.io/schemas/instrument_settlement_period) | Value | Description | | --- | --- | | `PERPETUAL` = 1 | Instrument settles through perpetual funding cycles | | `DAILY` = 2 | Instrument settles at an expiry date, marked as a daily instrument | | `WEEKLY` = 3 | Instrument settles at an expiry date, marked as a weekly instrument | | `MONTHLY` = 4 | Instrument settles at an expiry date, marked as a monthly instrument | | `QUARTERLY` = 5 | Instrument settles at an expiry date, marked as a quarterly instrument | Success **Full Response** `{ "result": { "instrument": "BTC_USDT_Perp", "instrument_hash": "0x030501", "base": "BTC", "quote": "USDT", "kind": "PERPETUAL", "venues": ["ORDERBOOK"], "settlement_period": "PERPETUAL", "base_decimals": 3, "quote_decimals": 3, "tick_size": "0.01", "min_size": "0.01", "create_time": "1697788800000000000", "max_position_size": "100.0", "funding_interval_hours": null, "adjusted_funding_rate_cap": 2.5, "adjusted_funding_rate_floor": -2.5, "min_notional": "20.0" } }` **Lite Response** `{ "r": { "i": "BTC_USDT_Perp", "ih": "0x030501", "b": "BTC", "q": "USDT", "k": "PERPETUAL", "v": ["ORDERBOOK"], "sp1": "PERPETUAL", "bd": 3, "qd": 3, "ts": "0.01", "ms": "0.01", "ct": "1697788800000000000", "mp": "100.0", "fi": null, "af": 2.5, "af1": -2.5, "mn": "20.0" } }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 1002 | 500 | Internal Server Error | | 1003 | 400 | Request could not be processed due to malformed syntax | | 1004 | 404 | Data Not Found | | 1006 | 429 | You have surpassed the allocated rate limit for your tier | Failure **Full Error Response** `{ "request_id":1, "code":1002, "message":"Internal Server Error", "status":500 }` **Lite Error Response** `{ "ri":1, "c":1002, "m":"Internal Server Error", "s":500 }` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://market-data.dev.gravitymarkets.io/full/v1/instrument' \ --data '{ "instrument": "BTC_USDT_Perp" } '` JSONRPC Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/instrument", "params": { "instrument": "BTC_USDT_Perp" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.dev.gravitymarkets.io/lite/v1/instrument' \ --data '{ "i": "BTC_USDT_Perp" } '` JSONRPC Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/instrument", "p": { "i": "BTC_USDT_Perp" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.staging.gravitymarkets.io/full/v1/instrument' \ --data '{ "instrument": "BTC_USDT_Perp" } '` JSONRPC Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/instrument", "params": { "instrument": "BTC_USDT_Perp" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.staging.gravitymarkets.io/lite/v1/instrument' \ --data '{ "i": "BTC_USDT_Perp" } '` JSONRPC Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/instrument", "p": { "i": "BTC_USDT_Perp" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.testnet.grvt.io/full/v1/instrument' \ --data '{ "instrument": "BTC_USDT_Perp" } '` JSONRPC Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/instrument", "params": { "instrument": "BTC_USDT_Perp" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.testnet.grvt.io/lite/v1/instrument' \ --data '{ "i": "BTC_USDT_Perp" } '` JSONRPC Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/instrument", "p": { "i": "BTC_USDT_Perp" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.grvt.io/full/v1/instrument' \ --data '{ "instrument": "BTC_USDT_Perp" } '` JSONRPC Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/instrument", "params": { "instrument": "BTC_USDT_Perp" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.grvt.io/lite/v1/instrument' \ --data '{ "i": "BTC_USDT_Perp" } '` JSONRPC Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/instrument", "p": { "i": "BTC_USDT_Perp" }, "i": 123 } ' -w 360` * * * ### Get All Instruments `FULL ENDPOINT: full/v1/all_instruments LITE ENDPOINT: lite/v1/all_instruments` RequestResponseErrorsTry it out [ApiGetAllInstrumentsRequest](https://api-docs.grvt.io/schemas/api_get_all_instruments_request) Fetch all instruments | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | is\_active
`ia` | boolean | False
`false` | Fetch only active instruments | Query **Full Request** `{ "is_active": true }` **Lite Request** `{ "ia": true }` [ApiGetAllInstrumentsResponse](https://api-docs.grvt.io/schemas/api_get_all_instruments_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[InstrumentDisplay\] | True | List of instruments | [InstrumentDisplay](https://api-docs.grvt.io/schemas/instrument_display) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | instrument\_hash
`ih` | string | True | The asset ID used for instrument signing. | | base
`b` | string | True | The base currency | | quote
`q` | string | True | The quote currency | | kind
`k` | Kind | True | The kind of instrument | | venues
`v` | \[Venue\] | True | Venues that this instrument can be traded at | | settlement\_period
`sp1` | InstrumentSettlementPeriod | True | The settlement period of the instrument | | base\_decimals
`bd` | integer | True | The smallest denomination of the base asset supported by GRVT (+3 represents 0.001, -3 represents 1000, 0 represents 1) | | quote\_decimals
`qd` | integer | True | The smallest denomination of the quote asset supported by GRVT (+3 represents 0.001, -3 represents 1000, 0 represents 1) | | tick\_size
`ts` | string | True | The size of a single tick, expressed in price decimal units | | min\_size
`ms` | string | True | The minimum contract size, expressed in base asset decimal units | | create\_time
`ct` | string | True | Creation time in unix nanoseconds | | max\_position\_size
`mp` | string | True | The maximum position size, expressed in base asset decimal units | | funding\_interval\_hours
`fi` | integer | False
`None` | Defines the funding interval to be applied. | | adjusted\_funding\_rate\_cap
`af` | string | False
`None` | Funding rate cap over the defined `intervalHours`. | | adjusted\_funding\_rate\_floor
`af1` | string | False
`None` | Funding rate floor over the defined `intervalHours`. | | min\_notional
`mn` | string | True | The minimum order notional value, expressed in quote currency decimal units | [Kind](https://api-docs.grvt.io/schemas/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 | [Venue](https://api-docs.grvt.io/schemas/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 | [InstrumentSettlementPeriod](https://api-docs.grvt.io/schemas/instrument_settlement_period) | Value | Description | | --- | --- | | `PERPETUAL` = 1 | Instrument settles through perpetual funding cycles | | `DAILY` = 2 | Instrument settles at an expiry date, marked as a daily instrument | | `WEEKLY` = 3 | Instrument settles at an expiry date, marked as a weekly instrument | | `MONTHLY` = 4 | Instrument settles at an expiry date, marked as a monthly instrument | | `QUARTERLY` = 5 | Instrument settles at an expiry date, marked as a quarterly instrument | Success **Full Response** `{ "result": [{ "instrument": "BTC_USDT_Perp", "instrument_hash": "0x030501", "base": "BTC", "quote": "USDT", "kind": "PERPETUAL", "venues": ["ORDERBOOK"], "settlement_period": "PERPETUAL", "base_decimals": 3, "quote_decimals": 3, "tick_size": "0.01", "min_size": "0.01", "create_time": "1697788800000000000", "max_position_size": "100.0", "funding_interval_hours": null, "adjusted_funding_rate_cap": 2.5, "adjusted_funding_rate_floor": -2.5, "min_notional": "20.0" }] }` **Lite Response** `{ "r": [{ "i": "BTC_USDT_Perp", "ih": "0x030501", "b": "BTC", "q": "USDT", "k": "PERPETUAL", "v": ["ORDERBOOK"], "sp1": "PERPETUAL", "bd": 3, "qd": 3, "ts": "0.01", "ms": "0.01", "ct": "1697788800000000000", "mp": "100.0", "fi": null, "af": 2.5, "af1": -2.5, "mn": "20.0" }] }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 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 | Failure **Full Error Response** `{ "request_id":1, "code":1002, "message":"Internal Server Error", "status":500 }` **Lite Error Response** `{ "ri":1, "c":1002, "m":"Internal Server Error", "s":500 }` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://market-data.dev.gravitymarkets.io/full/v1/all_instruments' \ --data '{ "is_active": true } '` JSONRPC Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/all_instruments", "params": { "is_active": true }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.dev.gravitymarkets.io/lite/v1/all_instruments' \ --data '{ "ia": true } '` JSONRPC Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/all_instruments", "p": { "ia": true }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.staging.gravitymarkets.io/full/v1/all_instruments' \ --data '{ "is_active": true } '` JSONRPC Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/all_instruments", "params": { "is_active": true }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.staging.gravitymarkets.io/lite/v1/all_instruments' \ --data '{ "ia": true } '` JSONRPC Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/all_instruments", "p": { "ia": true }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.testnet.grvt.io/full/v1/all_instruments' \ --data '{ "is_active": true } '` JSONRPC Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/all_instruments", "params": { "is_active": true }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.testnet.grvt.io/lite/v1/all_instruments' \ --data '{ "ia": true } '` JSONRPC Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/all_instruments", "p": { "ia": true }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.grvt.io/full/v1/all_instruments' \ --data '{ "is_active": true } '` JSONRPC Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/all_instruments", "params": { "is_active": true }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.grvt.io/lite/v1/all_instruments' \ --data '{ "ia": true } '` JSONRPC Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/all_instruments", "p": { "ia": true }, "i": 123 } ' -w 360` * * * ### Get Filtered Instruments `FULL ENDPOINT: full/v1/instruments LITE ENDPOINT: lite/v1/instruments` RequestResponseErrorsTry it out [ApiGetFilteredInstrumentsRequest](https://api-docs.grvt.io/schemas/api_get_filtered_instruments_request) Fetch a list of instruments based on the filters provided | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | 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` | \[string\] | 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` | \[string\] | False
`all` | The quote filter to apply. If nil, this defaults to all quotes. Otherwise, only entries matching the filter will be returned | | is\_active
`ia` | boolean | False
`false` | Request for active instruments only | | limit
`l` | integer | False
`500` | The limit to query for. Defaults to 500; Max 100000 | [Kind](https://api-docs.grvt.io/schemas/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 | Query **Full Request** `{ "kind": ["PERPETUAL"], "base": ["BTC", "ETH"], "quote": ["USDT", "USDC"], "is_active": true, "limit": 500 }` **Lite Request** `{ "k": ["PERPETUAL"], "b": ["BTC", "ETH"], "q": ["USDT", "USDC"], "ia": true, "l": 500 }` [ApiGetFilteredInstrumentsResponse](https://api-docs.grvt.io/schemas/api_get_filtered_instruments_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[InstrumentDisplay\] | True | The instruments matching the request filter | [InstrumentDisplay](https://api-docs.grvt.io/schemas/instrument_display) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | instrument\_hash
`ih` | string | True | The asset ID used for instrument signing. | | base
`b` | string | True | The base currency | | quote
`q` | string | True | The quote currency | | kind
`k` | Kind | True | The kind of instrument | | venues
`v` | \[Venue\] | True | Venues that this instrument can be traded at | | settlement\_period
`sp1` | InstrumentSettlementPeriod | True | The settlement period of the instrument | | base\_decimals
`bd` | integer | True | The smallest denomination of the base asset supported by GRVT (+3 represents 0.001, -3 represents 1000, 0 represents 1) | | quote\_decimals
`qd` | integer | True | The smallest denomination of the quote asset supported by GRVT (+3 represents 0.001, -3 represents 1000, 0 represents 1) | | tick\_size
`ts` | string | True | The size of a single tick, expressed in price decimal units | | min\_size
`ms` | string | True | The minimum contract size, expressed in base asset decimal units | | create\_time
`ct` | string | True | Creation time in unix nanoseconds | | max\_position\_size
`mp` | string | True | The maximum position size, expressed in base asset decimal units | | funding\_interval\_hours
`fi` | integer | False
`None` | Defines the funding interval to be applied. | | adjusted\_funding\_rate\_cap
`af` | string | False
`None` | Funding rate cap over the defined `intervalHours`. | | adjusted\_funding\_rate\_floor
`af1` | string | False
`None` | Funding rate floor over the defined `intervalHours`. | | min\_notional
`mn` | string | True | The minimum order notional value, expressed in quote currency decimal units | [Kind](https://api-docs.grvt.io/schemas/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 | [Venue](https://api-docs.grvt.io/schemas/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 | [InstrumentSettlementPeriod](https://api-docs.grvt.io/schemas/instrument_settlement_period) | Value | Description | | --- | --- | | `PERPETUAL` = 1 | Instrument settles through perpetual funding cycles | | `DAILY` = 2 | Instrument settles at an expiry date, marked as a daily instrument | | `WEEKLY` = 3 | Instrument settles at an expiry date, marked as a weekly instrument | | `MONTHLY` = 4 | Instrument settles at an expiry date, marked as a monthly instrument | | `QUARTERLY` = 5 | Instrument settles at an expiry date, marked as a quarterly instrument | Success **Full Response** `{ "result": [{ "instrument": "BTC_USDT_Perp", "instrument_hash": "0x030501", "base": "BTC", "quote": "USDT", "kind": "PERPETUAL", "venues": ["ORDERBOOK"], "settlement_period": "PERPETUAL", "base_decimals": 3, "quote_decimals": 3, "tick_size": "0.01", "min_size": "0.01", "create_time": "1697788800000000000", "max_position_size": "100.0", "funding_interval_hours": null, "adjusted_funding_rate_cap": 2.5, "adjusted_funding_rate_floor": -2.5, "min_notional": "20.0" }] }` **Lite Response** `{ "r": [{ "i": "BTC_USDT_Perp", "ih": "0x030501", "b": "BTC", "q": "USDT", "k": "PERPETUAL", "v": ["ORDERBOOK"], "sp1": "PERPETUAL", "bd": 3, "qd": 3, "ts": "0.01", "ms": "0.01", "ct": "1697788800000000000", "mp": "100.0", "fi": null, "af": 2.5, "af1": -2.5, "mn": "20.0" }] }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 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 | Failure **Full Error Response** `{ "request_id":1, "code":1002, "message":"Internal Server Error", "status":500 }` **Lite Error Response** `{ "ri":1, "c":1002, "m":"Internal Server Error", "s":500 }` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://market-data.dev.gravitymarkets.io/full/v1/instruments' \ --data '{ "kind": ["PERPETUAL"], "base": ["BTC", "ETH"], "quote": ["USDT", "USDC"], "is_active": true, "limit": 500 } '` JSONRPC Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/instruments", "params": { "kind": ["PERPETUAL"], "base": ["BTC", "ETH"], "quote": ["USDT", "USDC"], "is_active": true, "limit": 500 }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.dev.gravitymarkets.io/lite/v1/instruments' \ --data '{ "k": ["PERPETUAL"], "b": ["BTC", "ETH"], "q": ["USDT", "USDC"], "ia": true, "l": 500 } '` JSONRPC Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/instruments", "p": { "k": ["PERPETUAL"], "b": ["BTC", "ETH"], "q": ["USDT", "USDC"], "ia": true, "l": 500 }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.staging.gravitymarkets.io/full/v1/instruments' \ --data '{ "kind": ["PERPETUAL"], "base": ["BTC", "ETH"], "quote": ["USDT", "USDC"], "is_active": true, "limit": 500 } '` JSONRPC Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/instruments", "params": { "kind": ["PERPETUAL"], "base": ["BTC", "ETH"], "quote": ["USDT", "USDC"], "is_active": true, "limit": 500 }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.staging.gravitymarkets.io/lite/v1/instruments' \ --data '{ "k": ["PERPETUAL"], "b": ["BTC", "ETH"], "q": ["USDT", "USDC"], "ia": true, "l": 500 } '` JSONRPC Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/instruments", "p": { "k": ["PERPETUAL"], "b": ["BTC", "ETH"], "q": ["USDT", "USDC"], "ia": true, "l": 500 }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.testnet.grvt.io/full/v1/instruments' \ --data '{ "kind": ["PERPETUAL"], "base": ["BTC", "ETH"], "quote": ["USDT", "USDC"], "is_active": true, "limit": 500 } '` JSONRPC Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/instruments", "params": { "kind": ["PERPETUAL"], "base": ["BTC", "ETH"], "quote": ["USDT", "USDC"], "is_active": true, "limit": 500 }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.testnet.grvt.io/lite/v1/instruments' \ --data '{ "k": ["PERPETUAL"], "b": ["BTC", "ETH"], "q": ["USDT", "USDC"], "ia": true, "l": 500 } '` JSONRPC Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/instruments", "p": { "k": ["PERPETUAL"], "b": ["BTC", "ETH"], "q": ["USDT", "USDC"], "ia": true, "l": 500 }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.grvt.io/full/v1/instruments' \ --data '{ "kind": ["PERPETUAL"], "base": ["BTC", "ETH"], "quote": ["USDT", "USDC"], "is_active": true, "limit": 500 } '` JSONRPC Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/instruments", "params": { "kind": ["PERPETUAL"], "base": ["BTC", "ETH"], "quote": ["USDT", "USDC"], "is_active": true, "limit": 500 }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.grvt.io/lite/v1/instruments' \ --data '{ "k": ["PERPETUAL"], "b": ["BTC", "ETH"], "q": ["USDT", "USDC"], "ia": true, "l": 500 } '` JSONRPC Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/instruments", "p": { "k": ["PERPETUAL"], "b": ["BTC", "ETH"], "q": ["USDT", "USDC"], "ia": true, "l": 500 }, "i": 123 } ' -w 360` * * * ### Get Currency `FULL ENDPOINT: full/v1/currency LITE ENDPOINT: lite/v1/currency` RequestResponseErrorsTry it out [ApiGetCurrencyRequest](https://api-docs.grvt.io/schemas/api_get_currency_request) Fetch all currencies | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | | | | | Query **Full Request** `{ }` **Lite Request** `{ }` [ApiGetCurrencyResponse](https://api-docs.grvt.io/schemas/api_get_currency_response) The list of currencies | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[CurrencyDetail\] | True | The list of currencies | [CurrencyDetail](https://api-docs.grvt.io/schemas/currency_detail) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | id
`i` | integer | True | The integer value of the currency | | symbol
`s` | string | True | The name of the currency | | balance\_decimals
`bd` | integer | True | The balance decimals of the currency | | quantity\_multiplier
`qm` | string | True | The quantity multiplier of the currency | Success **Full Response** `{ "result": [{ "id": 3, "symbol": "USDT", "balance_decimals": 6, "quantity_multiplier": 1000000 }] }` **Lite Response** `{ "r": [{ "i": 3, "s": "USDT", "bd": 6, "qm": 1000000 }] }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 1002 | 500 | Internal Server Error | | 1003 | 400 | Request could not be processed due to malformed syntax | | 1004 | 404 | Data Not Found | | 1006 | 429 | You have surpassed the allocated rate limit for your tier | Failure **Full Error Response** `{ "request_id":1, "code":1002, "message":"Internal Server Error", "status":500 }` **Lite Error Response** `{ "ri":1, "c":1002, "m":"Internal Server Error", "s":500 }` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://market-data.dev.gravitymarkets.io/full/v1/currency' \ --data '{ } '` JSONRPC Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/currency", "params": { }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.dev.gravitymarkets.io/lite/v1/currency' \ --data '{ } '` JSONRPC Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/currency", "p": { }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.staging.gravitymarkets.io/full/v1/currency' \ --data '{ } '` JSONRPC Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/currency", "params": { }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.staging.gravitymarkets.io/lite/v1/currency' \ --data '{ } '` JSONRPC Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/currency", "p": { }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.testnet.grvt.io/full/v1/currency' \ --data '{ } '` JSONRPC Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/currency", "params": { }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.testnet.grvt.io/lite/v1/currency' \ --data '{ } '` JSONRPC Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/currency", "p": { }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.grvt.io/full/v1/currency' \ --data '{ } '` JSONRPC Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/currency", "params": { }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.grvt.io/lite/v1/currency' \ --data '{ } '` JSONRPC Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/currency", "p": { }, "i": 123 } ' -w 360` * * * ### Get Margin Rules `FULL ENDPOINT: full/v1/margin_rules LITE ENDPOINT: lite/v1/margin_rules` RequestResponseErrorsTry it out [ApiGetMarginRulesRequest](https://api-docs.grvt.io/schemas/api_get_margin_rules_request) API request payload to get margin rules for a particular instrument | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The instrument to query margin rules for | Query **Full Request** `{ "instrument": "BTC_USDT_Perp" }` **Lite Request** `{ "i": "BTC_USDT_Perp" }` [ApiGetMarginRulesResponse](https://api-docs.grvt.io/schemas/api_get_margin_rules_response) API response payload for margin rules of a particular instrument | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The instrument name | | max\_position\_size
`mp` | string | True | The maximum position size, expressed in base asset decimal units | | risk\_brackets
`rb` | \[RiskBracket\] | True | List of risk brackets defining margin requirements at different notional tiers | [RiskBracket](https://api-docs.grvt.io/schemas/risk_bracket) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | tier
`t` | integer | True | 1-indexed tier number | | notional\_floor
`nf` | string | True | Lower bound of notional value (inclusive) in quote currency | | notional\_cap
`nc` | string | False
`None` | Upper bound of notional value (exclusive) in quote currency, omitted for last tier | | maintenance\_margin\_rate
`mm` | string | True | Maintenance margin rate as a decimal (e.g., '0.01' for 1%) | | initial\_margin\_rate
`im` | string | True | Initial margin rate as a decimal (e.g., '0.02' for 2%) | | max\_leverage
`ml` | integer | True | Maximum leverage allowed at this tier (floor of 1 / initial\_margin\_rate) | | cumulative\_maintenance\_amount
`cm` | string | True | Cumulative maintenance margin amount in quote currency | Success **Full Response** `{ "instrument": "BTC_USDT_Perp", "max_position_size": "100.0", "risk_brackets": [{ "tier": 1, "notional_floor": "0", "notional_cap": "600000", "maintenance_margin_rate": "0.01", "initial_margin_rate": "0.02", "max_leverage": 50, "cumulative_maintenance_amount": "0" }] }` **Lite Response** `{ "i": "BTC_USDT_Perp", "mp": "100.0", "rb": [{ "t": 1, "nf": "0", "nc": "600000", "mm": "0.01", "im": "0.02", "ml": 50, "cm": "0" }] }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 1002 | 500 | Internal Server Error | | 1003 | 400 | Request could not be processed due to malformed syntax | | 3000 | 400 | Instrument is invalid | | 1004 | 404 | Data Not Found | | 1006 | 429 | You have surpassed the allocated rate limit for your tier | Failure **Full Error Response** `{ "request_id":1, "code":1002, "message":"Internal Server Error", "status":500 }` **Lite Error Response** `{ "ri":1, "c":1002, "m":"Internal Server Error", "s":500 }` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://market-data.dev.gravitymarkets.io/full/v1/margin_rules' \ --data '{ "instrument": "BTC_USDT_Perp" } '` JSONRPC Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/margin_rules", "params": { "instrument": "BTC_USDT_Perp" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.dev.gravitymarkets.io/lite/v1/margin_rules' \ --data '{ "i": "BTC_USDT_Perp" } '` JSONRPC Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/margin_rules", "p": { "i": "BTC_USDT_Perp" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.staging.gravitymarkets.io/full/v1/margin_rules' \ --data '{ "instrument": "BTC_USDT_Perp" } '` JSONRPC Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/margin_rules", "params": { "instrument": "BTC_USDT_Perp" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.staging.gravitymarkets.io/lite/v1/margin_rules' \ --data '{ "i": "BTC_USDT_Perp" } '` JSONRPC Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/margin_rules", "p": { "i": "BTC_USDT_Perp" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.testnet.grvt.io/full/v1/margin_rules' \ --data '{ "instrument": "BTC_USDT_Perp" } '` JSONRPC Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/margin_rules", "params": { "instrument": "BTC_USDT_Perp" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.testnet.grvt.io/lite/v1/margin_rules' \ --data '{ "i": "BTC_USDT_Perp" } '` JSONRPC Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/margin_rules", "p": { "i": "BTC_USDT_Perp" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.grvt.io/full/v1/margin_rules' \ --data '{ "instrument": "BTC_USDT_Perp" } '` JSONRPC Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/margin_rules", "params": { "instrument": "BTC_USDT_Perp" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.grvt.io/lite/v1/margin_rules' \ --data '{ "i": "BTC_USDT_Perp" } '` JSONRPC Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/margin_rules", "p": { "i": "BTC_USDT_Perp" }, "i": 123 } ' -w 360` * * * Ticker ------ ### Mini Ticker `FULL ENDPOINT: full/v1/mini LITE ENDPOINT: lite/v1/mini` RequestResponseErrorsTry it out [ApiMiniTickerRequest](https://api-docs.grvt.io/schemas/api_mini_ticker_request) Retrieves a single mini ticker value for a single instrument. Please do not use this to repeatedly poll for data -- a websocket subscription is much more performant, and useful. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | Query **Full Request** `{ "instrument": "BTC_USDT_Perp" }` **Lite Request** `{ "i": "BTC_USDT_Perp" }` [ApiMiniTickerResponse](https://api-docs.grvt.io/schemas/api_mini_ticker_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | MiniTicker | True | The mini ticker matching the request asset | [MiniTicker](https://api-docs.grvt.io/schemas/mini_ticker) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | False
`None` | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | False
`None` | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | mark\_price
`mp` | string | False
`None` | The mark price of the instrument, expressed in `9` decimals | | index\_price
`ip` | string | False
`None` | The index price of the instrument, expressed in `9` decimals | | last\_price
`lp` | string | False
`None` | The last traded price of the instrument (also close price), expressed in `9` decimals | | last\_size
`ls` | string | False
`None` | The number of assets traded in the last trade, expressed in base asset decimal units | | mid\_price
`mp1` | string | False
`None` | The mid price of the instrument, expressed in `9` decimals | | best\_bid\_price
`bb` | string | False
`None` | The best bid price of the instrument, expressed in `9` decimals | | best\_bid\_size
`bb1` | string | False
`None` | The number of assets offered on the best bid price of the instrument, expressed in base asset decimal units | | best\_ask\_price
`ba` | string | False
`None` | The best ask price of the instrument, expressed in `9` decimals | | best\_ask\_size
`ba1` | string | False
`None` | The number of assets offered on the best ask price of the instrument, expressed in base asset decimal units | Success **Full Response** `{ "result": { "event_time": "1697788800000000000", "instrument": "BTC_USDT_Perp", "mark_price": "65038.01", "index_price": "65038.01", "last_price": "65038.01", "last_size": "123456.78", "mid_price": "65038.01", "best_bid_price": "65038.01", "best_bid_size": "123456.78", "best_ask_price": "65038.01", "best_ask_size": "123456.78" } }` **Lite Response** `{ "r": { "et": "1697788800000000000", "i": "BTC_USDT_Perp", "mp": "65038.01", "ip": "65038.01", "lp": "65038.01", "ls": "123456.78", "mp1": "65038.01", "bb": "65038.01", "bb1": "123456.78", "ba": "65038.01", "ba1": "123456.78" } }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 1002 | 500 | Internal Server Error | | 1003 | 400 | Request could not be processed due to malformed syntax | | 1004 | 404 | Data Not Found | | 1006 | 429 | You have surpassed the allocated rate limit for your tier | Failure **Full Error Response** `{ "request_id":1, "code":1002, "message":"Internal Server Error", "status":500 }` **Lite Error Response** `{ "ri":1, "c":1002, "m":"Internal Server Error", "s":500 }` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://market-data.dev.gravitymarkets.io/full/v1/mini' \ --data '{ "instrument": "BTC_USDT_Perp" } '` JSONRPC Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/mini", "params": { "instrument": "BTC_USDT_Perp" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.dev.gravitymarkets.io/lite/v1/mini' \ --data '{ "i": "BTC_USDT_Perp" } '` JSONRPC Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/mini", "p": { "i": "BTC_USDT_Perp" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.staging.gravitymarkets.io/full/v1/mini' \ --data '{ "instrument": "BTC_USDT_Perp" } '` JSONRPC Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/mini", "params": { "instrument": "BTC_USDT_Perp" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.staging.gravitymarkets.io/lite/v1/mini' \ --data '{ "i": "BTC_USDT_Perp" } '` JSONRPC Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/mini", "p": { "i": "BTC_USDT_Perp" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.testnet.grvt.io/full/v1/mini' \ --data '{ "instrument": "BTC_USDT_Perp" } '` JSONRPC Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/mini", "params": { "instrument": "BTC_USDT_Perp" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.testnet.grvt.io/lite/v1/mini' \ --data '{ "i": "BTC_USDT_Perp" } '` JSONRPC Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/mini", "p": { "i": "BTC_USDT_Perp" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.grvt.io/full/v1/mini' \ --data '{ "instrument": "BTC_USDT_Perp" } '` JSONRPC Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/mini", "params": { "instrument": "BTC_USDT_Perp" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.grvt.io/lite/v1/mini' \ --data '{ "i": "BTC_USDT_Perp" } '` JSONRPC Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/mini", "p": { "i": "BTC_USDT_Perp" }, "i": 123 } ' -w 360` * * * ### Ticker `FULL ENDPOINT: full/v1/ticker LITE ENDPOINT: lite/v1/ticker` RequestResponseErrorsTry it out [ApiTickerRequest](https://api-docs.grvt.io/schemas/api_ticker_request) Retrieves a single ticker value for a single instrument. Please do not use this to repeatedly poll for data -- a websocket subscription is much more performant, and useful. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | Query **Full Request** `{ "instrument": "BTC_USDT_Perp" }` **Lite Request** `{ "i": "BTC_USDT_Perp" }` [ApiTickerResponse](https://api-docs.grvt.io/schemas/api_ticker_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | Ticker | True | The mini ticker matching the request asset | [Ticker](https://api-docs.grvt.io/schemas/ticker) Derived data such as the below, will not be included by default: \- 24 hour volume (`buyVolume + sellVolume`) \- 24 hour taker buy/sell ratio (`buyVolume / sellVolume`) \- 24 hour average trade price (`volumeQ / volumeU`) \- 24 hour average trade volume (`volume / trades`) \- 24 hour percentage change (`24hStatChange / 24hStat`) \- 48 hour statistics (`2 * 24hStat - 24hStatChange`) To query for an extended ticker payload, leverage the `greeks` and the `derived` flags. Ticker extensions are currently under design to offer you more convenience. These flags are only supported on the `Ticker Snapshot` WS endpoint, and on the `Ticker` API endpoint. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | False
`None` | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | False
`None` | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | mark\_price
`mp` | string | False
`None` | The mark price of the instrument, expressed in `9` decimals | | index\_price
`ip` | string | False
`None` | The index price of the instrument, expressed in `9` decimals | | last\_price
`lp` | string | False
`None` | The last traded price of the instrument (also close price), expressed in `9` decimals | | last\_size
`ls` | string | False
`None` | The number of assets traded in the last trade, expressed in base asset decimal units | | mid\_price
`mp1` | string | False
`None` | The mid price of the instrument, expressed in `9` decimals | | best\_bid\_price
`bb` | string | False
`None` | The best bid price of the instrument, expressed in `9` decimals | | best\_bid\_size
`bb1` | string | False
`None` | The number of assets offered on the best bid price of the instrument, expressed in base asset decimal units | | best\_ask\_price
`ba` | string | False
`None` | The best ask price of the instrument, expressed in `9` decimals | | best\_ask\_size
`ba1` | string | False
`None` | The number of assets offered on the best ask price of the instrument, expressed in base asset decimal units | | funding\_rate\_8h\_curr
`fr` | string | False
`None` | DEPRECATED: To be removed in a future release. Please refer to the field `funding_rate` instead, for the funding rate being applied over `funding_interval_hours` (interval ending at `next_funding_time`). | | funding\_rate\_8h\_avg
`fr1` | string | False
`None` | DEPRECATED: To be removed in a future release. Please refer to the field `funding_rate` instead, for the funding rate being applied over `funding_interval_hours` (interval ending at `next_funding_time`). | | interest\_rate
`ir` | string | False
`None` | The interest rate of the underlying, expressed in centibeeps (1/100th of a basis point) | | forward\_price
`fp` | string | False
`None` | \[Options\] The forward price of the option, expressed in `9` decimals | | buy\_volume\_24h\_b
`bv` | string | False
`None` | The 24 hour taker buy volume of the instrument, expressed in base asset decimal units | | sell\_volume\_24h\_b
`sv` | string | False
`None` | The 24 hour taker sell volume of the instrument, expressed in base asset decimal units | | buy\_volume\_24h\_q
`bv1` | string | False
`None` | The 24 hour taker buy volume of the instrument, expressed in quote asset decimal units | | sell\_volume\_24h\_q
`sv1` | string | False
`None` | The 24 hour taker sell volume of the instrument, expressed in quote asset decimal units | | high\_price
`hp` | string | False
`None` | The 24 hour highest traded price of the instrument, expressed in `9` decimals | | low\_price
`lp1` | string | False
`None` | The 24 hour lowest traded price of the instrument, expressed in `9` decimals | | open\_price
`op` | string | False
`None` | The 24 hour first traded price of the instrument, expressed in `9` decimals | | open\_interest
`oi` | string | False
`None` | The open interest in the instrument, expressed in base asset decimal units | | long\_short\_ratio
`ls1` | string | False
`None` | The ratio of accounts that are net long vs net short on this instrument | | funding\_rate
`fr2` | string | False
`None` | The current indicative funding rate for the active interval, expressed in centibeeps | | next\_funding\_time
`nf` | string | False
`None` | Timestamp in nanoseconds when the current funding interval ends | Success **Full Response** `{ "result": { "event_time": "1697788800000000000", "instrument": "BTC_USDT_Perp", "mark_price": "65038.01", "index_price": "65038.01", "last_price": "65038.01", "last_size": "123456.78", "mid_price": "65038.01", "best_bid_price": "65038.01", "best_bid_size": "123456.78", "best_ask_price": "65038.01", "best_ask_size": "123456.78", "funding_rate_8h_curr": 0.0003, "funding_rate_8h_avg": 0.0003, "interest_rate": 0.0003, "forward_price": "65038.01", "buy_volume_24h_b": "123456.78", "sell_volume_24h_b": "123456.78", "buy_volume_24h_q": "123456.78", "sell_volume_24h_q": "123456.78", "high_price": "65038.01", "low_price": "65038.01", "open_price": "65038.01", "open_interest": "123456.78", "long_short_ratio": "0.5", "funding_rate": 0.0003, "next_funding_time": "1697788800000000000" } }` **Lite Response** `{ "r": { "et": "1697788800000000000", "i": "BTC_USDT_Perp", "mp": "65038.01", "ip": "65038.01", "lp": "65038.01", "ls": "123456.78", "mp1": "65038.01", "bb": "65038.01", "bb1": "123456.78", "ba": "65038.01", "ba1": "123456.78", "fr": 0.0003, "fr1": 0.0003, "ir": 0.0003, "fp": "65038.01", "bv": "123456.78", "sv": "123456.78", "bv1": "123456.78", "sv1": "123456.78", "hp": "65038.01", "lp1": "65038.01", "op": "65038.01", "oi": "123456.78", "ls1": "0.5", "fr2": 0.0003, "nf": "1697788800000000000" } }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 1002 | 500 | Internal Server Error | | 1003 | 400 | Request could not be processed due to malformed syntax | | 1004 | 404 | Data Not Found | | 1006 | 429 | You have surpassed the allocated rate limit for your tier | Failure **Full Error Response** `{ "request_id":1, "code":1002, "message":"Internal Server Error", "status":500 }` **Lite Error Response** `{ "ri":1, "c":1002, "m":"Internal Server Error", "s":500 }` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://market-data.dev.gravitymarkets.io/full/v1/ticker' \ --data '{ "instrument": "BTC_USDT_Perp" } '` JSONRPC Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/ticker", "params": { "instrument": "BTC_USDT_Perp" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.dev.gravitymarkets.io/lite/v1/ticker' \ --data '{ "i": "BTC_USDT_Perp" } '` JSONRPC Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/ticker", "p": { "i": "BTC_USDT_Perp" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.staging.gravitymarkets.io/full/v1/ticker' \ --data '{ "instrument": "BTC_USDT_Perp" } '` JSONRPC Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/ticker", "params": { "instrument": "BTC_USDT_Perp" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.staging.gravitymarkets.io/lite/v1/ticker' \ --data '{ "i": "BTC_USDT_Perp" } '` JSONRPC Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/ticker", "p": { "i": "BTC_USDT_Perp" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.testnet.grvt.io/full/v1/ticker' \ --data '{ "instrument": "BTC_USDT_Perp" } '` JSONRPC Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/ticker", "params": { "instrument": "BTC_USDT_Perp" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.testnet.grvt.io/lite/v1/ticker' \ --data '{ "i": "BTC_USDT_Perp" } '` JSONRPC Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/ticker", "p": { "i": "BTC_USDT_Perp" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.grvt.io/full/v1/ticker' \ --data '{ "instrument": "BTC_USDT_Perp" } '` JSONRPC Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/ticker", "params": { "instrument": "BTC_USDT_Perp" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.grvt.io/lite/v1/ticker' \ --data '{ "i": "BTC_USDT_Perp" } '` JSONRPC Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/ticker", "p": { "i": "BTC_USDT_Perp" }, "i": 123 } ' -w 360` * * * Orderbook --------- ### Orderbook Levels `FULL ENDPOINT: full/v1/book LITE ENDPOINT: lite/v1/book` RequestResponseErrorsTry it out [ApiOrderbookLevelsRequest](https://api-docs.grvt.io/schemas/api_orderbook_levels_request) Retrieves aggregated price depth for a single instrument, with a maximum depth of 10 levels. Do not use this to poll for data -- a websocket subscription is much more performant, and useful. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | depth
`d` | integer | True | Depth of the order book to be retrieved (10, 50, 100, 500) | Query **Full Request** `{ "instrument": "BTC_USDT_Perp", "depth": 50 }` **Lite Request** `{ "i": "BTC_USDT_Perp", "d": 50 }` [ApiOrderbookLevelsResponse](https://api-docs.grvt.io/schemas/api_orderbook_levels_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | OrderbookLevels | True | The orderbook levels objects matching the request asset | [OrderbookLevels](https://api-docs.grvt.io/schemas/orderbook_levels) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | True | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | bids
`b` | \[OrderbookLevel\] | True | The list of best bids up till query depth | | asks
`a` | \[OrderbookLevel\] | True | The list of best asks up till query depth | [OrderbookLevel](https://api-docs.grvt.io/schemas/orderbook_level) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | price
`p` | string | True | The price of the level, expressed in `9` decimals | | size
`s` | string | True | The number of assets offered, expressed in base asset decimal units | | num\_orders
`no` | integer | True | The number of open orders at this level | [OrderbookLevel](https://api-docs.grvt.io/schemas/orderbook_level) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | price
`p` | string | True | The price of the level, expressed in `9` decimals | | size
`s` | string | True | The number of assets offered, expressed in base asset decimal units | | num\_orders
`no` | integer | True | The number of open orders at this level | Success **Full Response** `{ "result": { "event_time": "1697788800000000000", "instrument": "BTC_USDT_Perp", "bids": [{ "price": "65038.01", "size": "3456.78", "num_orders": 123 }], "asks": [{ "price": "65038.01", "size": "3456.78", "num_orders": 123 }] } }` **Lite Response** `{ "r": { "et": "1697788800000000000", "i": "BTC_USDT_Perp", "b": [{ "p": "65038.01", "s": "3456.78", "no": 123 }], "a": [{ "p": "65038.01", "s": "3456.78", "no": 123 }] } }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 1002 | 500 | Internal Server Error | | 1003 | 400 | Request could not be processed due to malformed syntax | | 1004 | 404 | Data Not Found | | 3000 | 400 | Instrument is invalid | | 3031 | 400 | Depth is invalid | | 1006 | 429 | You have surpassed the allocated rate limit for your tier | Failure **Full Error Response** `{ "request_id":1, "code":1002, "message":"Internal Server Error", "status":500 }` **Lite Error Response** `{ "ri":1, "c":1002, "m":"Internal Server Error", "s":500 }` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://market-data.dev.gravitymarkets.io/full/v1/book' \ --data '{ "instrument": "BTC_USDT_Perp", "depth": 50 } '` JSONRPC Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/book", "params": { "instrument": "BTC_USDT_Perp", "depth": 50 }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.dev.gravitymarkets.io/lite/v1/book' \ --data '{ "i": "BTC_USDT_Perp", "d": 50 } '` JSONRPC Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/book", "p": { "i": "BTC_USDT_Perp", "d": 50 }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.staging.gravitymarkets.io/full/v1/book' \ --data '{ "instrument": "BTC_USDT_Perp", "depth": 50 } '` JSONRPC Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/book", "params": { "instrument": "BTC_USDT_Perp", "depth": 50 }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.staging.gravitymarkets.io/lite/v1/book' \ --data '{ "i": "BTC_USDT_Perp", "d": 50 } '` JSONRPC Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/book", "p": { "i": "BTC_USDT_Perp", "d": 50 }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.testnet.grvt.io/full/v1/book' \ --data '{ "instrument": "BTC_USDT_Perp", "depth": 50 } '` JSONRPC Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/book", "params": { "instrument": "BTC_USDT_Perp", "depth": 50 }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.testnet.grvt.io/lite/v1/book' \ --data '{ "i": "BTC_USDT_Perp", "d": 50 } '` JSONRPC Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/book", "p": { "i": "BTC_USDT_Perp", "d": 50 }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.grvt.io/full/v1/book' \ --data '{ "instrument": "BTC_USDT_Perp", "depth": 50 } '` JSONRPC Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/book", "params": { "instrument": "BTC_USDT_Perp", "depth": 50 }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.grvt.io/lite/v1/book' \ --data '{ "i": "BTC_USDT_Perp", "d": 50 } '` JSONRPC Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/book", "p": { "i": "BTC_USDT_Perp", "d": 50 }, "i": 123 } ' -w 360` * * * Trade ----- ### Trade `FULL ENDPOINT: full/v1/trade LITE ENDPOINT: lite/v1/trade` RequestResponseErrorsTry it out [ApiTradeRequest](https://api-docs.grvt.io/schemas/api_trade_request) Retrieves up to 1000 of the most recent trades in any given instrument. Do not use this to poll for data -- a websocket subscription is much more performant, and useful. This endpoint offers public trading data, use the Trading APIs instead to query for your personalized trade tape. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | limit
`l` | integer | True | The limit to query for. Defaults to 500; Max 1000 | Query **Full Request** `{ "instrument": "BTC_USDT_Perp", "limit": 500 }` **Lite Request** `{ "i": "BTC_USDT_Perp", "l": 500 }` [ApiTradeResponse](https://api-docs.grvt.io/schemas/api_trade_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[Trade\] | True | The public trades matching the request asset | [Trade](https://api-docs.grvt.io/schemas/trade) All private RFQs and Private AXEs will be filtered out from the responses | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | True | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | is\_taker\_buyer
`it` | boolean | True | If taker was the buyer 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 | | 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`. | | venue
`v` | Venue | True | The venue where the trade occurred | | is\_rpi
`ir1` | boolean | True | If the trade is a RPI trade | [Venue](https://api-docs.grvt.io/schemas/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 | Success **Full Response** `{ "result": [{ "event_time": "1697788800000000000", "instrument": "BTC_USDT_Perp", "is_taker_buyer": true, "size": "123456.78", "price": "65038.01", "mark_price": "65038.01", "index_price": "65038.01", "interest_rate": 0.0003, "forward_price": "65038.01", "trade_id": "209358-2", "venue": "ORDERBOOK", "is_rpi": false }] }` **Lite Response** `{ "r": [{ "et": "1697788800000000000", "i": "BTC_USDT_Perp", "it": true, "s": "123456.78", "p": "65038.01", "mp": "65038.01", "ip": "65038.01", "ir": 0.0003, "fp": "65038.01", "ti": "209358-2", "v": "ORDERBOOK", "ir1": false }] }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 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 | Failure **Full Error Response** `{ "request_id":1, "code":1002, "message":"Internal Server Error", "status":500 }` **Lite Error Response** `{ "ri":1, "c":1002, "m":"Internal Server Error", "s":500 }` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://market-data.dev.gravitymarkets.io/full/v1/trade' \ --data '{ "instrument": "BTC_USDT_Perp", "limit": 500 } '` JSONRPC Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/trade", "params": { "instrument": "BTC_USDT_Perp", "limit": 500 }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.dev.gravitymarkets.io/lite/v1/trade' \ --data '{ "i": "BTC_USDT_Perp", "l": 500 } '` JSONRPC Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/trade", "p": { "i": "BTC_USDT_Perp", "l": 500 }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.staging.gravitymarkets.io/full/v1/trade' \ --data '{ "instrument": "BTC_USDT_Perp", "limit": 500 } '` JSONRPC Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/trade", "params": { "instrument": "BTC_USDT_Perp", "limit": 500 }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.staging.gravitymarkets.io/lite/v1/trade' \ --data '{ "i": "BTC_USDT_Perp", "l": 500 } '` JSONRPC Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/trade", "p": { "i": "BTC_USDT_Perp", "l": 500 }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.testnet.grvt.io/full/v1/trade' \ --data '{ "instrument": "BTC_USDT_Perp", "limit": 500 } '` JSONRPC Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/trade", "params": { "instrument": "BTC_USDT_Perp", "limit": 500 }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.testnet.grvt.io/lite/v1/trade' \ --data '{ "i": "BTC_USDT_Perp", "l": 500 } '` JSONRPC Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/trade", "p": { "i": "BTC_USDT_Perp", "l": 500 }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.grvt.io/full/v1/trade' \ --data '{ "instrument": "BTC_USDT_Perp", "limit": 500 } '` JSONRPC Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/trade", "params": { "instrument": "BTC_USDT_Perp", "limit": 500 }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.grvt.io/lite/v1/trade' \ --data '{ "i": "BTC_USDT_Perp", "l": 500 } '` JSONRPC Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/trade", "p": { "i": "BTC_USDT_Perp", "l": 500 }, "i": 123 } ' -w 360` * * * ### Trade History `FULL ENDPOINT: full/v1/trade_history LITE ENDPOINT: lite/v1/trade_history` RequestResponseErrorsTry it out [ApiTradeHistoryRequest](https://api-docs.grvt.io/schemas/api_trade_history_request) Perform historical lookup of public trades in any given instrument. This endpoint offers public trading data, use the Trading APIs instead to query for your personalized trade tape. Only data from the last three months will be retained. 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 | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | 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 | Query **Full Request** `{ "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" }` **Lite Request** `{ "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" }` [ApiTradeHistoryResponse](https://api-docs.grvt.io/schemas/api_trade_history_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[Trade\] | True | The public trades matching the request asset | | next
`n` | string | False
`''` | The cursor to indicate when to start the next query from | [Trade](https://api-docs.grvt.io/schemas/trade) All private RFQs and Private AXEs will be filtered out from the responses | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | True | Time at which the event was emitted in unix nanoseconds | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | is\_taker\_buyer
`it` | boolean | True | If taker was the buyer 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 | | 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`. | | venue
`v` | Venue | True | The venue where the trade occurred | | is\_rpi
`ir1` | boolean | True | If the trade is a RPI trade | [Venue](https://api-docs.grvt.io/schemas/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 | Success **Full Response** `{ "result": [{ "event_time": "1697788800000000000", "instrument": "BTC_USDT_Perp", "is_taker_buyer": true, "size": "123456.78", "price": "65038.01", "mark_price": "65038.01", "index_price": "65038.01", "interest_rate": 0.0003, "forward_price": "65038.01", "trade_id": "209358-2", "venue": "ORDERBOOK", "is_rpi": false }], "next": "Qw0918=" }` **Lite Response** `{ "r": [{ "et": "1697788800000000000", "i": "BTC_USDT_Perp", "it": true, "s": "123456.78", "p": "65038.01", "mp": "65038.01", "ip": "65038.01", "ir": 0.0003, "fp": "65038.01", "ti": "209358-2", "v": "ORDERBOOK", "ir1": false }], "n": "Qw0918=" }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 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 | Failure **Full Error Response** `{ "request_id":1, "code":1002, "message":"Internal Server Error", "status":500 }` **Lite Error Response** `{ "ri":1, "c":1002, "m":"Internal Server Error", "s":500 }` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://market-data.dev.gravitymarkets.io/full/v1/trade_history' \ --data '{ "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" } '` JSONRPC Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/trade_history", "params": { "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.dev.gravitymarkets.io/lite/v1/trade_history' \ --data '{ "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" } '` JSONRPC Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/trade_history", "p": { "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.staging.gravitymarkets.io/full/v1/trade_history' \ --data '{ "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" } '` JSONRPC Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/trade_history", "params": { "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.staging.gravitymarkets.io/lite/v1/trade_history' \ --data '{ "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" } '` JSONRPC Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/trade_history", "p": { "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.testnet.grvt.io/full/v1/trade_history' \ --data '{ "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" } '` JSONRPC Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/trade_history", "params": { "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.testnet.grvt.io/lite/v1/trade_history' \ --data '{ "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" } '` JSONRPC Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/trade_history", "p": { "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.grvt.io/full/v1/trade_history' \ --data '{ "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" } '` JSONRPC Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/trade_history", "params": { "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.grvt.io/lite/v1/trade_history' \ --data '{ "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" } '` JSONRPC Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/trade_history", "p": { "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" }, "i": 123 } ' -w 360` * * * Candlestick ----------- ### Candlestick `FULL ENDPOINT: full/v1/kline LITE ENDPOINT: lite/v1/kline` RequestResponseErrorsTry it out [ApiCandlestickRequest](https://api-docs.grvt.io/schemas/api_candlestick_request) Kline/Candlestick bars for an instrument. Klines are uniquely identified by their instrument, type, interval, and open time. 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 | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | interval
`i1` | CandlestickInterval | True | The interval of each candlestick | | type
`t` | CandlestickType | True | The type of candlestick data to retrieve | | start\_time
`st` | string | False
`0` | Start time of kline data in unix nanoseconds | | end\_time
`et` | string | False
`now()` | End time of kline data 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 query from | [CandlestickInterval](https://api-docs.grvt.io/schemas/candlestick_interval) | Value | Description | | --- | --- | | `CI_1_M` = 1 | 1 minute | | `CI_3_M` = 2 | 3 minutes | | `CI_5_M` = 3 | 5 minutes | | `CI_15_M` = 4 | 15 minutes | | `CI_30_M` = 5 | 30 minutes | | `CI_1_H` = 6 | 1 hour | | `CI_2_H` = 7 | 2 hour | | `CI_4_H` = 8 | 4 hour | | `CI_6_H` = 9 | 6 hour | | `CI_8_H` = 10 | 8 hour | | `CI_12_H` = 11 | 12 hour | | `CI_1_D` = 12 | 1 day | | `CI_3_D` = 13 | 3 days | | `CI_5_D` = 14 | 5 days | | `CI_1_W` = 15 | 1 week | | `CI_2_W` = 16 | 2 weeks | | `CI_3_W` = 17 | 3 weeks | | `CI_4_W` = 18 | 4 weeks | [CandlestickType](https://api-docs.grvt.io/schemas/candlestick_type) | Value | Description | | --- | --- | | `TRADE` = 1 | Tracks traded prices | | `MARK` = 2 | Tracks mark prices | | `INDEX` = 3 | Tracks index prices | | `MID` = 4 | Tracks book mid prices | Query **Full Request** `{ "instrument": "BTC_USDT_Perp", "interval": "CI_1_M", "type": "TRADE", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" }` **Lite Request** `{ "i": "BTC_USDT_Perp", "i1": "CI_1_M", "t": "TRADE", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" }` [ApiCandlestickResponse](https://api-docs.grvt.io/schemas/api_candlestick_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[Candlestick\] | True | The candlestick result set for given interval | | next
`n` | string | False
`''` | The cursor to indicate when to start the next query from | [Candlestick](https://api-docs.grvt.io/schemas/candlestick) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | open\_time
`ot` | string | True | Open time of kline bar in unix nanoseconds | | close\_time
`ct` | string | True | Close time of kline bar in unix nanosecond | | open
`o` | string | True | The open price, expressed in underlying currency resolution units | | close
`c` | string | True | The close price, expressed in underlying currency resolution units | | high
`h` | string | True | The high price, expressed in underlying currency resolution units | | low
`l` | string | True | The low price, expressed in underlying currency resolution units | | volume\_b
`vb` | string | True | The underlying volume transacted, expressed in base asset decimal units | | volume\_q
`vq` | string | True | The quote volume transacted, expressed in quote asset decimal units | | trades
`t` | integer | True | The number of trades transacted | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | Success **Full Response** `{ "result": [{ "open_time": "1697788800000000000", "close_time": "1697788800000000000", "open": "123456.78", "close": "123456.78", "high": "123456.78", "low": "123456.78", "volume_b": "123456.78", "volume_q": "123456.78", "trades": 123456, "instrument": "BTC_USDT_Perp" }], "next": "Qw0918=" }` **Lite Response** `{ "r": [{ "ot": "1697788800000000000", "ct": "1697788800000000000", "o": "123456.78", "c": "123456.78", "h": "123456.78", "l": "123456.78", "vb": "123456.78", "vq": "123456.78", "t": 123456, "i": "BTC_USDT_Perp" }], "n": "Qw0918=" }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 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 | Failure **Full Error Response** `{ "request_id":1, "code":1002, "message":"Internal Server Error", "status":500 }` **Lite Error Response** `{ "ri":1, "c":1002, "m":"Internal Server Error", "s":500 }` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://market-data.dev.gravitymarkets.io/full/v1/kline' \ --data '{ "instrument": "BTC_USDT_Perp", "interval": "CI_1_M", "type": "TRADE", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" } '` JSONRPC Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/kline", "params": { "instrument": "BTC_USDT_Perp", "interval": "CI_1_M", "type": "TRADE", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.dev.gravitymarkets.io/lite/v1/kline' \ --data '{ "i": "BTC_USDT_Perp", "i1": "CI_1_M", "t": "TRADE", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" } '` JSONRPC Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/kline", "p": { "i": "BTC_USDT_Perp", "i1": "CI_1_M", "t": "TRADE", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.staging.gravitymarkets.io/full/v1/kline' \ --data '{ "instrument": "BTC_USDT_Perp", "interval": "CI_1_M", "type": "TRADE", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" } '` JSONRPC Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/kline", "params": { "instrument": "BTC_USDT_Perp", "interval": "CI_1_M", "type": "TRADE", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.staging.gravitymarkets.io/lite/v1/kline' \ --data '{ "i": "BTC_USDT_Perp", "i1": "CI_1_M", "t": "TRADE", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" } '` JSONRPC Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/kline", "p": { "i": "BTC_USDT_Perp", "i1": "CI_1_M", "t": "TRADE", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.testnet.grvt.io/full/v1/kline' \ --data '{ "instrument": "BTC_USDT_Perp", "interval": "CI_1_M", "type": "TRADE", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" } '` JSONRPC Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/kline", "params": { "instrument": "BTC_USDT_Perp", "interval": "CI_1_M", "type": "TRADE", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.testnet.grvt.io/lite/v1/kline' \ --data '{ "i": "BTC_USDT_Perp", "i1": "CI_1_M", "t": "TRADE", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" } '` JSONRPC Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/kline", "p": { "i": "BTC_USDT_Perp", "i1": "CI_1_M", "t": "TRADE", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.grvt.io/full/v1/kline' \ --data '{ "instrument": "BTC_USDT_Perp", "interval": "CI_1_M", "type": "TRADE", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" } '` JSONRPC Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/kline", "params": { "instrument": "BTC_USDT_Perp", "interval": "CI_1_M", "type": "TRADE", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.grvt.io/lite/v1/kline' \ --data '{ "i": "BTC_USDT_Perp", "i1": "CI_1_M", "t": "TRADE", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" } '` JSONRPC Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/kline", "p": { "i": "BTC_USDT_Perp", "i1": "CI_1_M", "t": "TRADE", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" }, "i": 123 } ' -w 360` * * * Settlement ---------- ### Funding Rate `FULL ENDPOINT: full/v1/funding LITE ENDPOINT: lite/v1/funding` RequestResponseErrorsTry it out [ApiFundingRateRequest](https://api-docs.grvt.io/schemas/api_funding_rate_request) Lookup the historical funding rate of a perpetual future. 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 | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | start\_time
`st` | string | False
`0` | Start time of funding rate in unix nanoseconds | | end\_time
`et` | string | False
`now()` | End time of funding rate 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 query from | | agg\_type
`at` | FundingRateAggregationType | False
`'FUNDING_INTERVAL'` | Aggregation method for historical funding rate observations. Defaults to using the instrument-specific funding interval. | [FundingRateAggregationType](https://api-docs.grvt.io/schemas/funding_rate_aggregation_type) Specifies different methods of aggregating historical funding rates | Value | Description | | --- | --- | | `FUNDING_INTERVAL` = 1 | Default value -- one record returned per funding interval. Query instruments endpoint to learn funding interval of each instrument. | | `ONE_HOURLY` = 2 | Returns one record per hour -- normalizes all funding rates to 1h durations, so `fundingRate` value is cumulative and can exceed a funding interval's configured cap / floor. | | `FOUR_HOURLY` = 3 | Returns one record per 4 hours -- normalizes all funding rates to 4h durations, so `fundingRate` value is cumulative and can exceed a funding interval's configured cap / floor. | | `EIGHT_HOURLY` = 4 | Returns one record for eight hours -- normalizes all funding rates to 8h durations, so `fundingRate` value is cumulative and can exceed a funding interval's configured cap / floor. | Query **Full Request** `{ "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "", "agg_type": "FUNDING_INTERVAL" }` **Lite Request** `{ "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "", "at": "FUNDING_INTERVAL" }` [ApiFundingRateResponse](https://api-docs.grvt.io/schemas/api_funding_rate_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[ApiFundingRate\] | True | The funding rate result set for given interval | | next
`n` | string | False
`''` | The cursor to indicate when to start the next query from | [ApiFundingRate](https://api-docs.grvt.io/schemas/api_funding_rate) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The readable instrument name:

* Perpetual: `ETH_USDT_Perp`
* Future: `BTC_USDT_Fut_20Oct23`
* Call: `ETH_USDT_Call_20Oct23_2800`
* Put: `ETH_USDT_Put_20Oct23_2800` | | funding\_rate
`fr` | string | True | The funding rate of the instrument, expressed in percentage points | | funding\_time
`ft` | string | True | The funding timestamp of the funding rate, expressed in unix nanoseconds | | mark\_price
`mp` | string | True | The mark price of the instrument at funding timestamp, expressed in `9` decimals | | funding\_rate\_8\_h\_avg
`fr1` | string | True | Deprecated: Refer to `funding_rate` instead. Will be removed in a future release. | | funding\_interval\_hours
`fi` | integer | True | Funding interval in hours (e.g. 1/4/8/etc). | Success **Full Response** `{ "result": [{ "instrument": "BTC_USDT_Perp", "funding_rate": 0.0003, "funding_time": "1697788800000000000", "mark_price": "65038.01", "funding_rate_8_h_avg": 0.0003, "funding_interval_hours": 8 }], "next": "Qw0918=" }` **Lite Response** `{ "r": [{ "i": "BTC_USDT_Perp", "fr": 0.0003, "ft": "1697788800000000000", "mp": "65038.01", "fr1": 0.0003, "fi": 8 }], "n": "Qw0918=" }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 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 | Failure **Full Error Response** `{ "request_id":1, "code":1002, "message":"Internal Server Error", "status":500 }` **Lite Error Response** `{ "ri":1, "c":1002, "m":"Internal Server Error", "s":500 }` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://market-data.dev.gravitymarkets.io/full/v1/funding' \ --data '{ "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "", "agg_type": "FUNDING_INTERVAL" } '` JSONRPC Full `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/funding", "params": { "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "", "agg_type": "FUNDING_INTERVAL" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.dev.gravitymarkets.io/lite/v1/funding' \ --data '{ "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "", "at": "FUNDING_INTERVAL" } '` JSONRPC Lite `wscat -c "wss://market-data.dev.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/funding", "p": { "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "", "at": "FUNDING_INTERVAL" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.staging.gravitymarkets.io/full/v1/funding' \ --data '{ "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "", "agg_type": "FUNDING_INTERVAL" } '` JSONRPC Full `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/funding", "params": { "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "", "agg_type": "FUNDING_INTERVAL" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.staging.gravitymarkets.io/lite/v1/funding' \ --data '{ "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "", "at": "FUNDING_INTERVAL" } '` JSONRPC Lite `wscat -c "wss://market-data.staging.gravitymarkets.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/funding", "p": { "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "", "at": "FUNDING_INTERVAL" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.testnet.grvt.io/full/v1/funding' \ --data '{ "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "", "agg_type": "FUNDING_INTERVAL" } '` JSONRPC Full `wscat -c "wss://market-data.testnet.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/funding", "params": { "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "", "agg_type": "FUNDING_INTERVAL" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.testnet.grvt.io/lite/v1/funding' \ --data '{ "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "", "at": "FUNDING_INTERVAL" } '` JSONRPC Lite `wscat -c "wss://market-data.testnet.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/funding", "p": { "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "", "at": "FUNDING_INTERVAL" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://market-data.grvt.io/full/v1/funding' \ --data '{ "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "", "agg_type": "FUNDING_INTERVAL" } '` JSONRPC Full `wscat -c "wss://market-data.grvt.io/ws/full" \ -x ' { "jsonrpc": "2.0", "method": "v1/funding", "params": { "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "", "agg_type": "FUNDING_INTERVAL" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://market-data.grvt.io/lite/v1/funding' \ --data '{ "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "", "at": "FUNDING_INTERVAL" } '` JSONRPC Lite `wscat -c "wss://market-data.grvt.io/ws/lite" \ -x ' { "j": "2.0", "m": "v1/funding", "p": { "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "", "at": "FUNDING_INTERVAL" }, "i": 123 } ' -w 360` * * * Back to top --- # Trading Websocket - Gravity Markets API Docs [Skip to content](https://api-docs.grvt.io/trading_streams/#trading-websocket-streams) Trading Websocket Streams ========================= Order ----- ### Order `STREAM: v1.order` Feed SelectorFeed DataErrorsTry it out [WSOrderFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_order_feed_selector_v1) Subscribes to a feed of order updates pertaining to orders made by your account. Each Order can be uniquely identified by its `order_id` or `client_order_id`. To subscribe to all orders, specify an empty `instrument` (eg. `2345123`). Otherwise, specify the `instrument` to only receive orders for that instrument (eg. `2345123-BTC_USDT_Perp`). | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The subaccount ID to filter by | | instrument
`i` | string | False
`'all'` | The instrument filter to apply. | JSONRPC Wrappers [JSONRPCRequest](https://api-docs.grvt.io/schemas/jsonrpc_request) All Websocket JSON RPC Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | method
`m` | string | True | The method to use for the request (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | | params
`p` | object | True | The parameters for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | [WSSubscribeParams](https://api-docs.grvt.io/schemas/ws_subscribe_params) All V1 Websocket Subscription Requests are housed in this wrapper. You may specify a stream and a list of feeds to subscribe to. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. Sequence numbers can be either gateway-specific or global: \- **Gateway Unique Sequence Number**: Increments by one per stream, resets to 0 on gateway restart. \- **Global Unique Sequence Number**: A cluster-wide unique number assigned to each cluster payload, does not reset on gateway restarts, and can be used to track and identify message order across streams using `sequence_number` and `prev_sequence_number` in the feed response. Set `useGlobalSequenceNumber = true` if you need a persistent, unique identifier across all streams or ordering across multiple feeds. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to subscribe to | [WSSubscribeResult](https://api-docs.grvt.io/schemas/ws_subscribe_result) To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | [WSUnsubscribeParams](https://api-docs.grvt.io/schemas/ws_unsubscribe_params) All V1 Websocket Unsubscription Requests are housed in this wrapper. You may specify a stream, a list of feeds and whether those feeds use global sequence numbers to unsubscribe from. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to unsubscribe from (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to unsubscribe from | [WSUnsubscribeResult](https://api-docs.grvt.io/schemas/ws_unsubscribe_result) Returns a confirmation of all unsubscribes | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | [WSSubscribeRequestV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_request_v1_legacy) All V1 Websocket Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | feed
`f` | \[string\] | True | The list of feeds to subscribe to | | method
`m` | string | True | The method to use for the request (eg: subscribe / unsubscribe) | | is\_full
`if` | boolean | False
`false` | Whether the request is for full data or lite data | [WSSubscribeResponseV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_response_v1_legacy) All V1 Websocket Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | Subscribe **Full Subscribe Request** `{ "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.order", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 }` **Full Subscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.order", "subs": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "unsubs": [], "num_snapshots": [10], "first_sequence_number": [872634876] }, "id": 123, "method": "subscribe" }` Unsubscribe **Full Unsubscribe Request** `{ "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.order", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 }` **Full Unsubscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.order", "unsubs": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123, "method": "subscribe" }` Legacy Subscribe **Full Subscribe Request** `{ "request_id":1, "stream":"v1.order", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":true }` **Full Subscribe Response** `{ "request_id":1, "stream":"v1.order", "subs":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "unsubs":[], "num_snapshots":[1], "first_sequence_number":[2813] }` [WSOrderFeedDataV1](https://api-docs.grvt.io/schemas/ws_order_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | Order | True | The order object being created or updated | [Order](https://api-docs.grvt.io/schemas/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 | | builder
`b` | string | True | The main account ID of the builder | | builder\_fee
`bf` | string | True | Builder fee charged for this order | [TimeInForce](https://api-docs.grvt.io/schemas/time_in_force) | | 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](https://api-docs.grvt.io/schemas/order_leg) | 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](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [OrderMetadata](https://api-docs.grvt.io/schemas/order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_type) 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](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_by) 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 | | `MID` = 3 | MID - Order is activated when the mid price reaches the trigger price | | `MARK` = 4 | MARK - Order is activated when the mark price reaches the trigger price | [BrokerTag](https://api-docs.grvt.io/schemas/broker_tag) 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](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | Success **Full Feed Response** `{ "stream": "v1.order", "selector": "BTC_USDT_Perp", "sequence_number": "872634876", "feed": { "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, "chain_id": "325" }, "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"] }, "builder": "'$GRVT_MAIN_ACCOUNT_ID'", "builder_fee": 0.001 } }` **Lite Feed Response** `{ "s": "v1.order", "s1": "BTC_USDT_Perp", "sn": "872634876", "f": { "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, "ci": "325" }, "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"] }, "b": "'$GRVT_MAIN_ACCOUNT_ID'", "bf": 0.001 } }` 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 | | 1008 | 401 | Your IP has not been whitelisted for access | | 1101 | 400 | Feed Format must be in the format of @ | | 1102 | 400 | Wrong number of primary selectors | | 1103 | 400 | Wrong number of secondary selectors | | 3000 | 400 | Instrument is invalid | | 3020 | 400 | Sub account ID must be an uint64 integer | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | Error **Full Error Response** `{ "jsonrpc": "2.0", "error": { "code": 1000, "message": "You need to authenticate prior to using this functionality" }, "id": 123, "method": "subscribe" }` **Lite Error Response** `{ "j": "2.0", "e": { "c": 1000, "m": "You need to authenticate prior to using this functionality" }, "i": 123, "m": "subscribe" }` **Legacy Error Response** `{ "code":1000, "message":"You need to authenticate prior to using this functionality", "status":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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD Subscribe 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": "subscribe", "params": { "stream": "v1.order", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.order", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.dev.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.order", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.order", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.order", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.dev.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.order", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.order", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.order", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.staging.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.order", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.order", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.order", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.staging.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.order", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.order", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.order", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.testnet.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.order", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.order", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.order", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.testnet.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.order", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.order", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.order", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.order", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.order", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.order", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.order", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":false } ' -w 360` * * * ### Order State `STREAM: v1.state` Feed SelectorFeed DataErrorsTry it out [WSOrderStateFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_order_state_feed_selector_v1) Subscribes to a feed of order updates pertaining to orders made by your account. Unlike the Order Stream, this only streams state updates, drastically improving throughput, and latency. Each Order can be uniquely identified by its `order_id` or `client_order_id`. To subscribe to all orders, specify an empty `instrument` (eg. `2345123`). Otherwise, specify the `instrument` to only receive orders for that instrument (eg. `2345123-BTC_USDT_Perp`). | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The subaccount ID to filter by | | instrument
`i` | string | False
`'all'` | The instrument filter to apply. | JSONRPC Wrappers [JSONRPCRequest](https://api-docs.grvt.io/schemas/jsonrpc_request) All Websocket JSON RPC Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | method
`m` | string | True | The method to use for the request (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | | params
`p` | object | True | The parameters for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | [WSSubscribeParams](https://api-docs.grvt.io/schemas/ws_subscribe_params) All V1 Websocket Subscription Requests are housed in this wrapper. You may specify a stream and a list of feeds to subscribe to. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. Sequence numbers can be either gateway-specific or global: \- **Gateway Unique Sequence Number**: Increments by one per stream, resets to 0 on gateway restart. \- **Global Unique Sequence Number**: A cluster-wide unique number assigned to each cluster payload, does not reset on gateway restarts, and can be used to track and identify message order across streams using `sequence_number` and `prev_sequence_number` in the feed response. Set `useGlobalSequenceNumber = true` if you need a persistent, unique identifier across all streams or ordering across multiple feeds. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to subscribe to | [WSSubscribeResult](https://api-docs.grvt.io/schemas/ws_subscribe_result) To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | [WSUnsubscribeParams](https://api-docs.grvt.io/schemas/ws_unsubscribe_params) All V1 Websocket Unsubscription Requests are housed in this wrapper. You may specify a stream, a list of feeds and whether those feeds use global sequence numbers to unsubscribe from. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to unsubscribe from (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to unsubscribe from | [WSUnsubscribeResult](https://api-docs.grvt.io/schemas/ws_unsubscribe_result) Returns a confirmation of all unsubscribes | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | [WSSubscribeRequestV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_request_v1_legacy) All V1 Websocket Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | feed
`f` | \[string\] | True | The list of feeds to subscribe to | | method
`m` | string | True | The method to use for the request (eg: subscribe / unsubscribe) | | is\_full
`if` | boolean | False
`false` | Whether the request is for full data or lite data | [WSSubscribeResponseV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_response_v1_legacy) All V1 Websocket Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | Subscribe **Full Subscribe Request** `{ "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.state", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 }` **Full Subscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.state", "subs": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "unsubs": [], "num_snapshots": [10], "first_sequence_number": [872634876] }, "id": 123, "method": "subscribe" }` Unsubscribe **Full Unsubscribe Request** `{ "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.state", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 }` **Full Unsubscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.state", "unsubs": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123, "method": "subscribe" }` Legacy Subscribe **Full Subscribe Request** `{ "request_id":1, "stream":"v1.state", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":true }` **Full Subscribe Response** `{ "request_id":1, "stream":"v1.state", "subs":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "unsubs":[], "num_snapshots":[1], "first_sequence_number":[2813] }` [WSOrderStateFeedDataV1](https://api-docs.grvt.io/schemas/ws_order_state_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | OrderStateFeed | True | The Order State Feed | [OrderStateFeed](https://api-docs.grvt.io/schemas/order_state_feed) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | order\_id
`oi` | string | True | A unique 128-bit identifier for the order, deterministically generated within the GRVT backend | | client\_order\_id
`co` | string | True | A unique identifier for the active order within a subaccount, specified by the client | | order\_state
`os` | OrderState | True | The order state object being created or updated | [OrderState](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | Success **Full Feed Response** `{ "stream": "v1.state", "selector": "BTC_USDT_Perp", "sequence_number": "872634876", "feed": { "order_id": "10000101000203040506", "client_order_id": "23042", "order_state": { "status": "PENDING", "reject_reason": "CLIENT_CANCEL", "book_size": ["10.5"], "traded_size": ["1.5"], "update_time": "1697788800000000000", "avg_fill_price": ["60000.4"] } } }` **Lite Feed Response** `{ "s": "v1.state", "s1": "BTC_USDT_Perp", "sn": "872634876", "f": { "oi": "10000101000203040506", "co": "23042", "os": { "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 | | 1008 | 401 | Your IP has not been whitelisted for access | | 1101 | 400 | Feed Format must be in the format of @ | | 1102 | 400 | Wrong number of primary selectors | | 1103 | 400 | Wrong number of secondary selectors | | 3000 | 400 | Instrument is invalid | | 3020 | 400 | Sub account ID must be an uint64 integer | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | Error **Full Error Response** `{ "jsonrpc": "2.0", "error": { "code": 1000, "message": "You need to authenticate prior to using this functionality" }, "id": 123, "method": "subscribe" }` **Lite Error Response** `{ "j": "2.0", "e": { "c": 1000, "m": "You need to authenticate prior to using this functionality" }, "i": 123, "m": "subscribe" }` **Legacy Error Response** `{ "code":1000, "message":"You need to authenticate prior to using this functionality", "status":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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD Subscribe 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": "subscribe", "params": { "stream": "v1.state", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.state", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.dev.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.state", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.state", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.state", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.dev.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.state", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.state", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.state", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.staging.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.state", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.state", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.state", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.staging.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.state", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.state", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.state", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.testnet.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.state", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.state", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.state", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.testnet.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.state", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.state", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.state", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.state", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.state", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.state", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.state", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":false } ' -w 360` * * * ### Cancel Status `STREAM: v1.cancel` Feed SelectorFeed DataErrorsTry it out [WSCancelFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_cancel_feed_selector_v1) Subscribes to a feed of time-to-live expiry events for order cancellations requested by a given subaccount. **This stream presently only provides expiry updates for cancel-order requests set with a valid TTL value**. Successful order cancellations will reflect as updates published to the [order-state stream](https://api-docs.grvt.io/trading_streams/#order-state) . _A future release will expand the functionality of this stream to provide more general status updates on order cancellation requests._ Each Order can be uniquely identified by its `client_order_id`. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The subaccount ID to filter by | JSONRPC Wrappers [JSONRPCRequest](https://api-docs.grvt.io/schemas/jsonrpc_request) All Websocket JSON RPC Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | method
`m` | string | True | The method to use for the request (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | | params
`p` | object | True | The parameters for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | [WSSubscribeParams](https://api-docs.grvt.io/schemas/ws_subscribe_params) All V1 Websocket Subscription Requests are housed in this wrapper. You may specify a stream and a list of feeds to subscribe to. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. Sequence numbers can be either gateway-specific or global: \- **Gateway Unique Sequence Number**: Increments by one per stream, resets to 0 on gateway restart. \- **Global Unique Sequence Number**: A cluster-wide unique number assigned to each cluster payload, does not reset on gateway restarts, and can be used to track and identify message order across streams using `sequence_number` and `prev_sequence_number` in the feed response. Set `useGlobalSequenceNumber = true` if you need a persistent, unique identifier across all streams or ordering across multiple feeds. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to subscribe to | [WSSubscribeResult](https://api-docs.grvt.io/schemas/ws_subscribe_result) To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | [WSUnsubscribeParams](https://api-docs.grvt.io/schemas/ws_unsubscribe_params) All V1 Websocket Unsubscription Requests are housed in this wrapper. You may specify a stream, a list of feeds and whether those feeds use global sequence numbers to unsubscribe from. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to unsubscribe from (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to unsubscribe from | [WSUnsubscribeResult](https://api-docs.grvt.io/schemas/ws_unsubscribe_result) Returns a confirmation of all unsubscribes | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | [WSSubscribeRequestV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_request_v1_legacy) All V1 Websocket Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | feed
`f` | \[string\] | True | The list of feeds to subscribe to | | method
`m` | string | True | The method to use for the request (eg: subscribe / unsubscribe) | | is\_full
`if` | boolean | False
`false` | Whether the request is for full data or lite data | [WSSubscribeResponseV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_response_v1_legacy) All V1 Websocket Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | Subscribe **Full Subscribe Request** `{ "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.cancel", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123 }` **Full Subscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.cancel", "subs": ["'$GRVT_SUB_ACCOUNT_ID'"], "unsubs": [], "num_snapshots": [10], "first_sequence_number": [872634876] }, "id": 123, "method": "subscribe" }` Unsubscribe **Full Unsubscribe Request** `{ "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.cancel", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123 }` **Full Unsubscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.cancel", "unsubs": ["'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123, "method": "subscribe" }` Legacy Subscribe **Full Subscribe Request** `{ "request_id":1, "stream":"v1.cancel", "feed":["'$GRVT_SUB_ACCOUNT_ID'"], "method":"subscribe", "is_full":true }` **Full Subscribe Response** `{ "request_id":1, "stream":"v1.cancel", "subs":["'$GRVT_SUB_ACCOUNT_ID'"], "unsubs":[], "num_snapshots":[1], "first_sequence_number":[2813] }` [WSCancelFeedDataV1](https://api-docs.grvt.io/schemas/ws_cancel_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | CancelStatusFeed | True | Data relating to the status of the cancellation attempt | [CancelStatusFeed](https://api-docs.grvt.io/schemas/cancel_status_feed) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The subaccount ID that requested the cancellation | | client\_order\_id
`co` | string | True | A unique identifier for the active order within a subaccount, specified by the client | | order\_id
`oi` | string | True | A unique 128-bit identifier for the order, deterministically generated within the GRVT backend | | reason
`r` | OrderRejectReason | True | The user-provided reason for cancelling the order | | update\_time
`ut` | string | False
`0` | \[Filled by GRVT Backend\] Time at which the cancellation status was updated by GRVT in unix nanoseconds | | cancel\_status
`cs` | CancelStatus | True | Status of the cancellation attempt | [OrderRejectReason](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | [CancelStatus](https://api-docs.grvt.io/schemas/cancel_status) | Value | Description | | --- | --- | | `EXPIRED` = 1 | Cancellation has expired because corresponding order had not arrived within the defined time-to-live window. | | `DROPPED_DUPLICATE` = 2 | This cancellation request was dropped because its TTL window overlaps with another cancellation request for the same order. | Success **Full Feed Response** `{ "stream": "v1.cancel", "selector": "'$GRVT_SUB_ACCOUNT_ID'", "sequence_number": "872634876", "feed": { "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "client_order_id": "23042", "order_id": "10000101000203040506", "reason": "UNSPECIFIED", "update_time": "1697788800000000000", "cancel_status": "EXPIRED" } }` **Lite Feed Response** `{ "s": "v1.cancel", "s1": "'$GRVT_SUB_ACCOUNT_ID'", "sn": "872634876", "f": { "sa": "'$GRVT_SUB_ACCOUNT_ID'", "co": "23042", "oi": "10000101000203040506", "r": "UNSPECIFIED", "ut": "1697788800000000000", "cs": "EXPIRED" } }` 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 | | 1008 | 401 | Your IP has not been whitelisted for access | | 1101 | 400 | Feed Format must be in the format of @ | | 1102 | 400 | Wrong number of primary selectors | | 1103 | 400 | Wrong number of secondary selectors | | 3000 | 400 | Instrument is invalid | | 3020 | 400 | Sub account ID must be an uint64 integer | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | Error **Full Error Response** `{ "jsonrpc": "2.0", "error": { "code": 1000, "message": "You need to authenticate prior to using this functionality" }, "id": 123, "method": "subscribe" }` **Lite Error Response** `{ "j": "2.0", "e": { "c": 1000, "m": "You need to authenticate prior to using this functionality" }, "i": 123, "m": "subscribe" }` **Legacy Error Response** `{ "code":1000, "message":"You need to authenticate prior to using this functionality", "status":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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD Subscribe 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": "subscribe", "params": { "stream": "v1.cancel", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.cancel", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.dev.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.cancel", "feed":["'$GRVT_SUB_ACCOUNT_ID'"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.cancel", "s1": ["'$GRVT_SUB_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.cancel", "s1": ["'$GRVT_SUB_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.dev.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.cancel", "feed":["'$GRVT_SUB_ACCOUNT_ID'"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.cancel", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.cancel", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.staging.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.cancel", "feed":["'$GRVT_SUB_ACCOUNT_ID'"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.cancel", "s1": ["'$GRVT_SUB_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.cancel", "s1": ["'$GRVT_SUB_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.staging.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.cancel", "feed":["'$GRVT_SUB_ACCOUNT_ID'"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.cancel", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.cancel", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.testnet.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.cancel", "feed":["'$GRVT_SUB_ACCOUNT_ID'"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.cancel", "s1": ["'$GRVT_SUB_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.cancel", "s1": ["'$GRVT_SUB_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.testnet.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.cancel", "feed":["'$GRVT_SUB_ACCOUNT_ID'"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.cancel", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.cancel", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.cancel", "feed":["'$GRVT_SUB_ACCOUNT_ID'"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.cancel", "s1": ["'$GRVT_SUB_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.cancel", "s1": ["'$GRVT_SUB_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.cancel", "feed":["'$GRVT_SUB_ACCOUNT_ID'"], "method":"subscribe", "is_full":false } ' -w 360` * * * Execution --------- ### Fill `STREAM: v1.fill` Feed SelectorFeed DataErrorsTry it out [WSFillFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_fill_feed_selector_v1) Subscribes to a feed of private trade updates. This happens when a trade is executed. To subscribe to all private trades, specify an empty `instrument` (eg. `2345123`). Otherwise, specify the `instrument` to only receive private trades for that instrument (eg. `2345123-BTC_USDT_Perp`). | 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 instrument filter to apply. | JSONRPC Wrappers [JSONRPCRequest](https://api-docs.grvt.io/schemas/jsonrpc_request) All Websocket JSON RPC Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | method
`m` | string | True | The method to use for the request (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | | params
`p` | object | True | The parameters for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | [WSSubscribeParams](https://api-docs.grvt.io/schemas/ws_subscribe_params) All V1 Websocket Subscription Requests are housed in this wrapper. You may specify a stream and a list of feeds to subscribe to. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. Sequence numbers can be either gateway-specific or global: \- **Gateway Unique Sequence Number**: Increments by one per stream, resets to 0 on gateway restart. \- **Global Unique Sequence Number**: A cluster-wide unique number assigned to each cluster payload, does not reset on gateway restarts, and can be used to track and identify message order across streams using `sequence_number` and `prev_sequence_number` in the feed response. Set `useGlobalSequenceNumber = true` if you need a persistent, unique identifier across all streams or ordering across multiple feeds. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to subscribe to | [WSSubscribeResult](https://api-docs.grvt.io/schemas/ws_subscribe_result) To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | [WSUnsubscribeParams](https://api-docs.grvt.io/schemas/ws_unsubscribe_params) All V1 Websocket Unsubscription Requests are housed in this wrapper. You may specify a stream, a list of feeds and whether those feeds use global sequence numbers to unsubscribe from. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to unsubscribe from (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to unsubscribe from | [WSUnsubscribeResult](https://api-docs.grvt.io/schemas/ws_unsubscribe_result) Returns a confirmation of all unsubscribes | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | [WSSubscribeRequestV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_request_v1_legacy) All V1 Websocket Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | feed
`f` | \[string\] | True | The list of feeds to subscribe to | | method
`m` | string | True | The method to use for the request (eg: subscribe / unsubscribe) | | is\_full
`if` | boolean | False
`false` | Whether the request is for full data or lite data | [WSSubscribeResponseV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_response_v1_legacy) All V1 Websocket Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | Subscribe **Full Subscribe Request** `{ "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.fill", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 }` **Full Subscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.fill", "subs": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "unsubs": [], "num_snapshots": [10], "first_sequence_number": [872634876] }, "id": 123, "method": "subscribe" }` Unsubscribe **Full Unsubscribe Request** `{ "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.fill", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 }` **Full Unsubscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.fill", "unsubs": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123, "method": "subscribe" }` Legacy Subscribe **Full Subscribe Request** `{ "request_id":1, "stream":"v1.fill", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":true }` **Full Subscribe Response** `{ "request_id":1, "stream":"v1.fill", "subs":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "unsubs":[], "num_snapshots":[1], "first_sequence_number":[2813] }` [WSFillFeedDataV1](https://api-docs.grvt.io/schemas/ws_fill_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The websocket channel to which the response is sent | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | Fill | True | A private trade matching the request filter | [Fill](https://api-docs.grvt.io/schemas/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 | | is\_liquidation
`il` | boolean | True | If the trade was a liquidation | | 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 | | builder
`b1` | string | True | The main account ID of the builder. referred to Order.builder | | builder\_fee\_rate
`bf` | string | True | Builder fee percentage charged for this order. referred to Order.builder builderFee | | builder\_fee
`bf1` | string | True | The builder fee paid on the trade, expressed in quote asset decimal unit. referred to Trade.builderFee | [Venue](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/broker_tag) 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 Feed Response** `{ "stream": "v1.fill", "selector": "BTC_USDT_Perp", "sequence_number": "872634876", "feed": { "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", "is_liquidation": false, "client_order_id": "23042", "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "broker": "UNSPECIFIED", "is_rpi": false, "builder": "'$GRVT_MAIN_ACCOUNT_ID'", "builder_fee_rate": 0.001, "builder_fee": "0.2" } }` **Lite Feed Response** `{ "s": "v1.fill", "s1": "BTC_USDT_Perp", "sn": "872634876", "f": { "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", "il": false, "co": "23042", "s1": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "b": "UNSPECIFIED", "ir1": false, "b1": "'$GRVT_MAIN_ACCOUNT_ID'", "bf": 0.001, "bf1": "0.2" } }` 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 | | 1008 | 401 | Your IP has not been whitelisted for access | | 1101 | 400 | Feed Format must be in the format of @ | | 1102 | 400 | Wrong number of primary selectors | | 1103 | 400 | Wrong number of secondary selectors | | 3000 | 400 | Instrument is invalid | | 3020 | 400 | Sub account ID must be an uint64 integer | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | Error **Full Error Response** `{ "jsonrpc": "2.0", "error": { "code": 1000, "message": "You need to authenticate prior to using this functionality" }, "id": 123, "method": "subscribe" }` **Lite Error Response** `{ "j": "2.0", "e": { "c": 1000, "m": "You need to authenticate prior to using this functionality" }, "i": 123, "m": "subscribe" }` **Legacy Error Response** `{ "code":1000, "message":"You need to authenticate prior to using this functionality", "status":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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD Subscribe 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": "subscribe", "params": { "stream": "v1.fill", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.fill", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.dev.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.fill", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.fill", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.fill", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.dev.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.fill", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.fill", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.fill", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.staging.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.fill", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.fill", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.fill", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.staging.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.fill", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.fill", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.fill", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.testnet.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.fill", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.fill", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.fill", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.testnet.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.fill", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.fill", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.fill", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.fill", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.fill", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.fill", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.fill", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":false } ' -w 360` * * * ### Positions `STREAM: v1.position` Feed SelectorFeed DataErrorsTry it out [WSPositionsFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_positions_feed_selector_v1) Subscribes to a feed of position updates. Updates get published when a trade is executed, and when leverage configurations are changed for instruments with ongoing positions. To subscribe to all positions, specify an empty `instrument` (eg. `2345123`). Otherwise, specify the `instrument` to only receive positions for that instrument (eg. `2345123-BTC_USDT_Perp`). | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The subaccount ID to filter by | | instrument
`i` | string | False
`'all'` | The instrument filter to apply. | JSONRPC Wrappers [JSONRPCRequest](https://api-docs.grvt.io/schemas/jsonrpc_request) All Websocket JSON RPC Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | method
`m` | string | True | The method to use for the request (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | | params
`p` | object | True | The parameters for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | [WSSubscribeParams](https://api-docs.grvt.io/schemas/ws_subscribe_params) All V1 Websocket Subscription Requests are housed in this wrapper. You may specify a stream and a list of feeds to subscribe to. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. Sequence numbers can be either gateway-specific or global: \- **Gateway Unique Sequence Number**: Increments by one per stream, resets to 0 on gateway restart. \- **Global Unique Sequence Number**: A cluster-wide unique number assigned to each cluster payload, does not reset on gateway restarts, and can be used to track and identify message order across streams using `sequence_number` and `prev_sequence_number` in the feed response. Set `useGlobalSequenceNumber = true` if you need a persistent, unique identifier across all streams or ordering across multiple feeds. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to subscribe to | [WSSubscribeResult](https://api-docs.grvt.io/schemas/ws_subscribe_result) To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | [WSUnsubscribeParams](https://api-docs.grvt.io/schemas/ws_unsubscribe_params) All V1 Websocket Unsubscription Requests are housed in this wrapper. You may specify a stream, a list of feeds and whether those feeds use global sequence numbers to unsubscribe from. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to unsubscribe from (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to unsubscribe from | [WSUnsubscribeResult](https://api-docs.grvt.io/schemas/ws_unsubscribe_result) Returns a confirmation of all unsubscribes | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | [WSSubscribeRequestV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_request_v1_legacy) All V1 Websocket Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | feed
`f` | \[string\] | True | The list of feeds to subscribe to | | method
`m` | string | True | The method to use for the request (eg: subscribe / unsubscribe) | | is\_full
`if` | boolean | False
`false` | Whether the request is for full data or lite data | [WSSubscribeResponseV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_response_v1_legacy) All V1 Websocket Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | Subscribe **Full Subscribe Request** `{ "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.position", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 }` **Full Subscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.position", "subs": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "unsubs": [], "num_snapshots": [10], "first_sequence_number": [872634876] }, "id": 123, "method": "subscribe" }` Unsubscribe **Full Unsubscribe Request** `{ "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.position", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 }` **Full Unsubscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.position", "unsubs": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123, "method": "subscribe" }` Legacy Subscribe **Full Subscribe Request** `{ "request_id":1, "stream":"v1.position", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":true }` **Full Subscribe Response** `{ "request_id":1, "stream":"v1.position", "subs":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "unsubs":[], "num_snapshots":[1], "first_sequence_number":[2813] }` [WSPositionsFeedDataV1](https://api-docs.grvt.io/schemas/ws_positions_feed_data_v1) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | Stream name | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | Positions | True | A Position being created or updated matching the request filter | [Positions](https://api-docs.grvt.io/schemas/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 | | cumulative\_fee
`cf` | string | True | The cumulative fee paid on the position, expressed in quote asset decimal units | | cumulative\_realized\_funding\_payment
`cr` | string | True | The cumulative realized funding payment of the position, expressed in quote asset decimal units. Positive if paid, negative if received | | margin\_type
`mt` | PositionMarginType | True | The margin type of the position | | isolated\_balance
`ib` | string | False
`None` | \[IsolatedOnly\] The wallet balance reserved for this isolated margin position, expressed in quote asset decimal units. If this positions is liquidated, this is the maximal balance that can be lost | | isolated\_im
`ii` | string | False
`None` | \[IsolatedOnly\] The initial margin of the isolated margin position, expressed in quote asset decimal units. The `total_equity` required to open more size in the position | | isolated\_mm
`im` | string | False
`None` | \[IsolatedOnly\] The maintenance margin of the isolated margin position, expressed in quote asset decimal units. The `total_equity` required to avoid liquidation of the position | [PositionMarginType](https://api-docs.grvt.io/schemas/position_margin_type) | Value | Description | | --- | --- | | `ISOLATED` = 1 | Isolated Margin Mode: each position is allocated a fixed amount of collateral | | `CROSS` = 2 | Cross Margin Mode: uses all available funds in your account as collateral across all cross margin positions | Success **Full Feed Response** `{ "stream": "v1.position", "selector": "BTC_USDT_Perp", "sequence_number": "872634876", "feed": { "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", "cumulative_fee": "100000.20", "cumulative_realized_funding_payment": "100000.20", "margin_type": "cross", "isolated_balance": "100000.20", "isolated_im": "100000.20", "isolated_mm": "100000.20" } }` **Lite Feed Response** `{ "s": "v1.position", "s1": "BTC_USDT_Perp", "sn": "872634876", "f": { "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", "cf": "100000.20", "cr": "100000.20", "mt": "cross", "ib": "100000.20", "ii": "100000.20", "im": "100000.20" } }` 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 | | 1008 | 401 | Your IP has not been whitelisted for access | | 1101 | 400 | Feed Format must be in the format of @ | | 1102 | 400 | Wrong number of primary selectors | | 1103 | 400 | Wrong number of secondary selectors | | 3000 | 400 | Instrument is invalid | | 3020 | 400 | Sub account ID must be an uint64 integer | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | Error **Full Error Response** `{ "jsonrpc": "2.0", "error": { "code": 1000, "message": "You need to authenticate prior to using this functionality" }, "id": 123, "method": "subscribe" }` **Lite Error Response** `{ "j": "2.0", "e": { "c": 1000, "m": "You need to authenticate prior to using this functionality" }, "i": 123, "m": "subscribe" }` **Legacy Error Response** `{ "code":1000, "message":"You need to authenticate prior to using this functionality", "status":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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD Subscribe 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": "subscribe", "params": { "stream": "v1.position", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.position", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.dev.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.position", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.position", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.position", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.dev.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.position", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.position", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.position", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.staging.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.position", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.position", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.position", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.staging.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.position", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.position", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.position", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.testnet.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.position", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.position", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.position", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.testnet.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.position", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.position", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.position", "selectors": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.position", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.position", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.position", "s1": ["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.position", "feed":["'$GRVT_SUB_ACCOUNT_ID'-BTC_USDT_Perp"], "method":"subscribe", "is_full":false } ' -w 360` * * * Transfer -------- ### Deposit `STREAM: v1.deposit` Feed SelectorFeed DataErrorsTry it out [WSDepositFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_deposit_feed_selector_v1) Subscribes to a feed of deposits. This will execute when there is any deposit to selected account. To subscribe to a main account, specify the account ID (eg. `0x9fe3758b67ce7a2875ee4b452f01a5282d84ed8a`). | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | main\_account\_id
`ma` | string | True | The main account ID to request for | JSONRPC Wrappers [JSONRPCRequest](https://api-docs.grvt.io/schemas/jsonrpc_request) All Websocket JSON RPC Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | method
`m` | string | True | The method to use for the request (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | | params
`p` | object | True | The parameters for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | [WSSubscribeParams](https://api-docs.grvt.io/schemas/ws_subscribe_params) All V1 Websocket Subscription Requests are housed in this wrapper. You may specify a stream and a list of feeds to subscribe to. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. Sequence numbers can be either gateway-specific or global: \- **Gateway Unique Sequence Number**: Increments by one per stream, resets to 0 on gateway restart. \- **Global Unique Sequence Number**: A cluster-wide unique number assigned to each cluster payload, does not reset on gateway restarts, and can be used to track and identify message order across streams using `sequence_number` and `prev_sequence_number` in the feed response. Set `useGlobalSequenceNumber = true` if you need a persistent, unique identifier across all streams or ordering across multiple feeds. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to subscribe to | [WSSubscribeResult](https://api-docs.grvt.io/schemas/ws_subscribe_result) To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | [WSUnsubscribeParams](https://api-docs.grvt.io/schemas/ws_unsubscribe_params) All V1 Websocket Unsubscription Requests are housed in this wrapper. You may specify a stream, a list of feeds and whether those feeds use global sequence numbers to unsubscribe from. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to unsubscribe from (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to unsubscribe from | [WSUnsubscribeResult](https://api-docs.grvt.io/schemas/ws_unsubscribe_result) Returns a confirmation of all unsubscribes | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | [WSSubscribeRequestV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_request_v1_legacy) All V1 Websocket Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | feed
`f` | \[string\] | True | The list of feeds to subscribe to | | method
`m` | string | True | The method to use for the request (eg: subscribe / unsubscribe) | | is\_full
`if` | boolean | False
`false` | Whether the request is for full data or lite data | [WSSubscribeResponseV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_response_v1_legacy) All V1 Websocket Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | Subscribe **Full Subscribe Request** `{ "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.deposit", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123 }` **Full Subscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.deposit", "subs": ["'$GRVT_MAIN_ACCOUNT_ID'"], "unsubs": [], "num_snapshots": [10], "first_sequence_number": [872634876] }, "id": 123, "method": "subscribe" }` Unsubscribe **Full Unsubscribe Request** `{ "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.deposit", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123 }` **Full Unsubscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.deposit", "unsubs": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123, "method": "subscribe" }` Legacy Subscribe **Full Subscribe Request** `{ "request_id":1, "stream":"v1.deposit", "feed":["'$GRVT_MAIN_ACCOUNT_ID'"], "method":"subscribe", "is_full":true }` **Full Subscribe Response** `{ "request_id":1, "stream":"v1.deposit", "subs":["'$GRVT_MAIN_ACCOUNT_ID'"], "unsubs":[], "num_snapshots":[1], "first_sequence_number":[2813] }` [WSDepositFeedDataV1](https://api-docs.grvt.io/schemas/ws_deposit_feed_data_v1) Subscribes to a feed of deposit updates. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The websocket channel to which the response is sent | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | Deposit | True | The Deposit object | [Deposit](https://api-docs.grvt.io/schemas/deposit) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | tx\_hash
`th` | string | True | The hash of the bridgemint event producing the deposit | | to\_account\_id
`ta` | string | True | The account to deposit into | | currency
`c` | string | True | The token currency to deposit | | num\_tokens
`nt` | string | True | The number of tokens to deposit | Success **Full Feed Response** `{ "stream": "v1.deposit", "selector": "BTC_USDT_Perp", "sequence_number": "872634876", "feed": { "tx_hash": "0x1234567890123456789012345678901234567890123456789012345678901234", "to_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "currency": "USDT", "num_tokens": "10.50" } }` **Lite Feed Response** `{ "s": "v1.deposit", "s1": "BTC_USDT_Perp", "sn": "872634876", "f": { "th": "0x1234567890123456789012345678901234567890123456789012345678901234", "ta": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "c": "USDT", "nt": "10.50" } }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 1001 | 403 | You are not authorized to access this functionality | | 1008 | 401 | Your IP has not been whitelisted for access | | 1101 | 400 | Feed Format must be in the format of @ | | 1102 | 400 | Wrong number of primary selectors | | 1103 | 400 | Wrong number of secondary selectors | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | Error **Full Error Response** `{ "jsonrpc": "2.0", "error": { "code": 1001, "message": "You are not authorized to access this functionality" }, "id": 123, "method": "subscribe" }` **Lite Error Response** `{ "j": "2.0", "e": { "c": 1001, "m": "You are not authorized to access this functionality" }, "i": 123, "m": "subscribe" }` **Legacy Error Response** `{ "code":1001, "message":"You are not authorized to access this functionality", "status":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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD Subscribe 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": "subscribe", "params": { "stream": "v1.deposit", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.deposit", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.dev.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.deposit", "feed":["'$GRVT_MAIN_ACCOUNT_ID'"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.deposit", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.deposit", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.dev.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.deposit", "feed":["'$GRVT_MAIN_ACCOUNT_ID'"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.deposit", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.deposit", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.staging.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.deposit", "feed":["'$GRVT_MAIN_ACCOUNT_ID'"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.deposit", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.deposit", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.staging.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.deposit", "feed":["'$GRVT_MAIN_ACCOUNT_ID'"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.deposit", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.deposit", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.testnet.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.deposit", "feed":["'$GRVT_MAIN_ACCOUNT_ID'"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.deposit", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.deposit", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.testnet.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.deposit", "feed":["'$GRVT_MAIN_ACCOUNT_ID'"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.deposit", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.deposit", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.deposit", "feed":["'$GRVT_MAIN_ACCOUNT_ID'"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.deposit", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.deposit", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.deposit", "feed":["'$GRVT_MAIN_ACCOUNT_ID'"], "method":"subscribe", "is_full":false } ' -w 360` * * * ### Transfer `STREAM: v1.transfer` Feed SelectorFeed DataErrorsTry it out [WSTransferFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_transfer_feed_selector_v1) Subscribes to a feed of transfers. This will execute when there is any transfer to or from the selected account. To subscribe to a main account, specify the account ID (eg. `0x9fe3758b67ce7a2875ee4b452f01a5282d84ed8a`). To subscribe to a sub account, specify the main account and the sub account dash separated (eg. `0x9fe3758b67ce7a2875ee4b452f01a5282d84ed8a-1920109784202388`). | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | main\_account\_id
`ma` | string | True | The main account ID to request for | | sub\_account\_id
`sa` | string | False
`'0'` | The sub account ID to request for | JSONRPC Wrappers [JSONRPCRequest](https://api-docs.grvt.io/schemas/jsonrpc_request) All Websocket JSON RPC Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | method
`m` | string | True | The method to use for the request (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | | params
`p` | object | True | The parameters for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | [WSSubscribeParams](https://api-docs.grvt.io/schemas/ws_subscribe_params) All V1 Websocket Subscription Requests are housed in this wrapper. You may specify a stream and a list of feeds to subscribe to. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. Sequence numbers can be either gateway-specific or global: \- **Gateway Unique Sequence Number**: Increments by one per stream, resets to 0 on gateway restart. \- **Global Unique Sequence Number**: A cluster-wide unique number assigned to each cluster payload, does not reset on gateway restarts, and can be used to track and identify message order across streams using `sequence_number` and `prev_sequence_number` in the feed response. Set `useGlobalSequenceNumber = true` if you need a persistent, unique identifier across all streams or ordering across multiple feeds. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to subscribe to | [WSSubscribeResult](https://api-docs.grvt.io/schemas/ws_subscribe_result) To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | [WSUnsubscribeParams](https://api-docs.grvt.io/schemas/ws_unsubscribe_params) All V1 Websocket Unsubscription Requests are housed in this wrapper. You may specify a stream, a list of feeds and whether those feeds use global sequence numbers to unsubscribe from. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to unsubscribe from (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to unsubscribe from | [WSUnsubscribeResult](https://api-docs.grvt.io/schemas/ws_unsubscribe_result) Returns a confirmation of all unsubscribes | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | [WSSubscribeRequestV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_request_v1_legacy) All V1 Websocket Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | feed
`f` | \[string\] | True | The list of feeds to subscribe to | | method
`m` | string | True | The method to use for the request (eg: subscribe / unsubscribe) | | is\_full
`if` | boolean | False
`false` | Whether the request is for full data or lite data | [WSSubscribeResponseV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_response_v1_legacy) All V1 Websocket Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | Subscribe **Full Subscribe Request** `{ "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.transfer", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123 }` **Full Subscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.transfer", "subs": ["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"], "unsubs": [], "num_snapshots": [10], "first_sequence_number": [872634876] }, "id": 123, "method": "subscribe" }` Unsubscribe **Full Unsubscribe Request** `{ "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.transfer", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123 }` **Full Unsubscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.transfer", "unsubs": ["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123, "method": "subscribe" }` Legacy Subscribe **Full Subscribe Request** `{ "request_id":1, "stream":"v1.transfer", "feed":["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"], "method":"subscribe", "is_full":true }` **Full Subscribe Response** `{ "request_id":1, "stream":"v1.transfer", "subs":["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"], "unsubs":[], "num_snapshots":[1], "first_sequence_number":[2813] }` [WSTransferFeedDataV1](https://api-docs.grvt.io/schemas/ws_transfer_feed_data_v1) Subscribes to a feed of transfer updates. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The websocket channel to which the response is sent | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | TransferHistory | True | The transfer history matching the requested filters | [TransferHistory](https://api-docs.grvt.io/schemas/transfer_history) | 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` | string | 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 | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [TransferType](https://api-docs.grvt.io/schemas/transfer_type) | Value | Description | | --- | --- | | `UNSPECIFIED` = 0 | Default transfer that has nothing to do with bridging | | `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 | | `ADHOC_INCENTIVE` = 6 | Transfer type for adhoc incentive | | `REFERRAL_INCENTIVE` = 7 | Transfer type for referral incentive | | `TRADING_DEPOSIT_YIELD_INCENTIVE` = 8 | Transfer type for trading deposit yield incentive | Success **Full Feed Response** `{ "stream": "v1.transfer", "selector": "BTC_USDT_Perp", "sequence_number": "872634876", "feed": { "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, "chain_id": "325" }, "event_time": "1697788800000000000", "transfer_type": "UNSPECIFIED", "transfer_metadata": null } }` **Lite Feed Response** `{ "s": "v1.transfer", "s1": "BTC_USDT_Perp", "sn": "872634876", "f": { "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, "ci": "325" }, "et": "1697788800000000000", "tt": "UNSPECIFIED", "tm": null } }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 1001 | 403 | You are not authorized to access this functionality | | 1008 | 401 | Your IP has not been whitelisted for access | | 1101 | 400 | Feed Format must be in the format of @ | | 1102 | 400 | Wrong number of primary selectors | | 1103 | 400 | Wrong number of secondary selectors | | 3020 | 400 | Sub account ID must be an uint64 integer | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | Error **Full Error Response** `{ "jsonrpc": "2.0", "error": { "code": 1001, "message": "You are not authorized to access this functionality" }, "id": 123, "method": "subscribe" }` **Lite Error Response** `{ "j": "2.0", "e": { "c": 1001, "m": "You are not authorized to access this functionality" }, "i": 123, "m": "subscribe" }` **Legacy Error Response** `{ "code":1001, "message":"You are not authorized to access this functionality", "status":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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD Subscribe 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": "subscribe", "params": { "stream": "v1.transfer", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.transfer", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.dev.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.transfer", "feed":["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.transfer", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.transfer", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.dev.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.transfer", "feed":["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.transfer", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.transfer", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.staging.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.transfer", "feed":["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.transfer", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.transfer", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.staging.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.transfer", "feed":["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.transfer", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.transfer", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.testnet.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.transfer", "feed":["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.transfer", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.transfer", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.testnet.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.transfer", "feed":["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.transfer", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.transfer", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.transfer", "feed":["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.transfer", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.transfer", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.transfer", "feed":["'$GRVT_MAIN_ACCOUNT_ID'-'$GRVT_SUB_ACCOUNT_ID'"], "method":"subscribe", "is_full":false } ' -w 360` * * * ### Withdrawal `STREAM: v1.withdrawal` Feed SelectorFeed DataErrorsTry it out [WSWithdrawalFeedSelectorV1](https://api-docs.grvt.io/schemas/ws_withdrawal_feed_selector_v1) Subscribes to a feed of withdrawals. This will execute when there is any withdrawal from the selected account. To subscribe to a main account, specify the account ID (eg. `0x9fe3758b67ce7a2875ee4b452f01a5282d84ed8a`). | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | main\_account\_id
`ma` | string | True | The main account ID to request for | JSONRPC Wrappers [JSONRPCRequest](https://api-docs.grvt.io/schemas/jsonrpc_request) All Websocket JSON RPC Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | method
`m` | string | True | The method to use for the request (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | | params
`p` | object | True | The parameters for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | [WSSubscribeParams](https://api-docs.grvt.io/schemas/ws_subscribe_params) All V1 Websocket Subscription Requests are housed in this wrapper. You may specify a stream and a list of feeds to subscribe to. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. Sequence numbers can be either gateway-specific or global: \- **Gateway Unique Sequence Number**: Increments by one per stream, resets to 0 on gateway restart. \- **Global Unique Sequence Number**: A cluster-wide unique number assigned to each cluster payload, does not reset on gateway restarts, and can be used to track and identify message order across streams using `sequence_number` and `prev_sequence_number` in the feed response. Set `useGlobalSequenceNumber = true` if you need a persistent, unique identifier across all streams or ordering across multiple feeds. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to subscribe to | [WSSubscribeResult](https://api-docs.grvt.io/schemas/ws_subscribe_result) To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | [WSUnsubscribeParams](https://api-docs.grvt.io/schemas/ws_unsubscribe_params) All V1 Websocket Unsubscription Requests are housed in this wrapper. You may specify a stream, a list of feeds and whether those feeds use global sequence numbers to unsubscribe from. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to unsubscribe from (eg: ticker.s / ticker.d) | | selectors
`s1` | \[string\] | True | The list of feeds to unsubscribe from | [WSUnsubscribeResult](https://api-docs.grvt.io/schemas/ws_unsubscribe_result) Returns a confirmation of all unsubscribes | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | [WSSubscribeRequestV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_request_v1_legacy) All V1 Websocket Requests are housed in this wrapper. You may specify a stream, and a list of feeds to subscribe to. If a `request_id` is supplied in this JSON RPC request, it will be propagated back to any relevant JSON RPC responses (including error). When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | feed
`f` | \[string\] | True | The list of feeds to subscribe to | | method
`m` | string | True | The method to use for the request (eg: subscribe / unsubscribe) | | is\_full
`if` | boolean | False
`false` | Whether the request is for full data or lite data | [WSSubscribeResponseV1Legacy](https://api-docs.grvt.io/schemas/ws_subscribe_response_v1_legacy) All V1 Websocket Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. To ensure you always know if you have missed any payloads, GRVT servers apply the following heuristics to sequence numbers: * All snapshot payloads will have a sequence number of `0`. All delta payloads will have a sequence number of `1+`. So its easy to distinguish between snapshots, and deltas * Num snapshots returned in Response (per stream): You can ensure that you received the right number of snapshots * First sequence number returned in Response (per stream): You can ensure that you received the first stream, without gaps from snapshots * Sequence numbers should always monotonically increase by `1`. If it decreases, or increases by more than `1`. Please reconnect * Duplicate sequence numbers are possible due to network retries. If you receive a duplicate, please ignore it, or idempotently re-update it. When subscribing to the same primary selector again, the previous secondary selector will be replaced. See `Overview` page for more details. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_id
`ri` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned | | stream
`s` | string | True | The channel to subscribe to (eg: ticker.s / ticker.d) | | subs
`s1` | \[string\] | True | The list of feeds subscribed to | | unsubs
`u` | \[string\] | True | The list of feeds unsubscribed from | | num\_snapshots
`ns` | \[integer\] | True | The number of snapshot payloads to expect for each subscribed feed. Returned in same order as `subs` | | first\_sequence\_number
`fs` | \[string\] | True | The first sequence number to expect for each subscribed feed. Returned in same order as `subs` | Subscribe **Full Subscribe Request** `{ "jsonrpc": "2.0", "method": "subscribe", "params": { "stream": "v1.withdrawal", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123 }` **Full Subscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.withdrawal", "subs": ["'$GRVT_MAIN_ACCOUNT_ID'"], "unsubs": [], "num_snapshots": [10], "first_sequence_number": [872634876] }, "id": 123, "method": "subscribe" }` Unsubscribe **Full Unsubscribe Request** `{ "jsonrpc": "2.0", "method": "unsubscribe", "params": { "stream": "v1.withdrawal", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123 }` **Full Unsubscribe Response** `{ "jsonrpc": "2.0", "result": { "stream": "v1.withdrawal", "unsubs": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123, "method": "subscribe" }` Legacy Subscribe **Full Subscribe Request** `{ "request_id":1, "stream":"v1.withdrawal", "feed":["'$GRVT_MAIN_ACCOUNT_ID'"], "method":"subscribe", "is_full":true }` **Full Subscribe Response** `{ "request_id":1, "stream":"v1.withdrawal", "subs":["'$GRVT_MAIN_ACCOUNT_ID'"], "unsubs":[], "num_snapshots":[1], "first_sequence_number":[2813] }` [WSWithdrawalFeedDataV1](https://api-docs.grvt.io/schemas/ws_withdrawal_feed_data_v1) Subscribes to a feed of withdrawal updates. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | stream
`s` | string | True | The websocket channel to which the response is sent | | selector
`s1` | string | True | Primary selector | | sequence\_number
`sn` | string | True | A sequence number used to determine message order within a stream.
\- If `useGlobalSequenceNumber` is **false**, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts.
\- If `useGlobalSequenceNumber` is **true**, this returns the global sequence number, which uniquely identifies messages across the cluster.
\- A single cluster payload can be multiplexed into multiple stream payloads.
\- To distinguish each stream payload, a `dedupCounter` is included.
\- The returned sequence number is computed as: `cluster_sequence_number * 10^5 + dedupCounter`. | | feed
`f` | Withdrawal | True | The Withdrawal object | [Withdrawal](https://api-docs.grvt.io/schemas/withdrawal) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | 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` | string | 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 | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | Success **Full Feed Response** `{ "stream": "v1.withdrawal", "selector": "BTC_USDT_Perp", "sequence_number": "872634876", "feed": { "from_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "to_eth_address": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "currency": "USDT", "num_tokens": "10.50", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } }` **Lite Feed Response** `{ "s": "v1.withdrawal", "s1": "BTC_USDT_Perp", "sn": "872634876", "f": { "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "te": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "c": "USDT", "nt": "10.50", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 1001 | 403 | You are not authorized to access this functionality | | 1008 | 401 | Your IP has not been whitelisted for access | | 1101 | 400 | Feed Format must be in the format of @ | | 1102 | 400 | Wrong number of primary selectors | | 1103 | 400 | Wrong number of secondary selectors | [JSONRPCResponse](https://api-docs.grvt.io/schemas/jsonrpc_response) All Websocket JSON RPC Responses are housed in this wrapper. It returns a confirmation of the JSON RPC subscribe request. If a `request_id` is supplied in the JSON RPC request, it will be propagated back in this JSON RPC response. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | jsonrpc
`j` | string | True | The JSON RPC version to use for the request | | result
`r` | object | False
`null` | The result for the request | | error
`e` | Error | False
`null` | The error for the request | | id
`i` | integer | False
`0` | Optional Field which is used to match the response by the client.
If not passed, this field will not be returned.
Range: 0 to 4,294,967,295 (uint32) | | method
`m` | string | True | The method used in the request for this response (eg: `subscribe` / `unsubscribe` / `v1/instrument` ) | [Error](https://api-docs.grvt.io/schemas/error) An error response | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | code
`c` | integer | True | The error code for the request | | message
`m` | string | True | The error message for the request | Error **Full Error Response** `{ "jsonrpc": "2.0", "error": { "code": 1001, "message": "You are not authorized to access this functionality" }, "id": 123, "method": "subscribe" }` **Lite Error Response** `{ "j": "2.0", "e": { "c": 1001, "m": "You are not authorized to access this functionality" }, "i": 123, "m": "subscribe" }` **Legacy Error Response** `{ "code":1001, "message":"You are not authorized to access this functionality", "status":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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD Subscribe 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": "subscribe", "params": { "stream": "v1.withdrawal", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.withdrawal", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.dev.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.withdrawal", "feed":["'$GRVT_MAIN_ACCOUNT_ID'"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.withdrawal", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.withdrawal", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.dev.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.withdrawal", "feed":["'$GRVT_MAIN_ACCOUNT_ID'"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.withdrawal", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.withdrawal", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.staging.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.withdrawal", "feed":["'$GRVT_MAIN_ACCOUNT_ID'"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.withdrawal", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.withdrawal", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.staging.gravitymarkets.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.withdrawal", "feed":["'$GRVT_MAIN_ACCOUNT_ID'"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.withdrawal", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.withdrawal", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.testnet.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.withdrawal", "feed":["'$GRVT_MAIN_ACCOUNT_ID'"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.withdrawal", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.withdrawal", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.testnet.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.withdrawal", "feed":["'$GRVT_MAIN_ACCOUNT_ID'"], "method":"subscribe", "is_full":false } ' -w 360` Subscribe 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": "subscribe", "params": { "stream": "v1.withdrawal", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "params": { "stream": "v1.withdrawal", "selectors": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "id": 123 } ' -w 360` Legacy Subscribe Full `wscat -c "wss://trades.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.withdrawal", "feed":["'$GRVT_MAIN_ACCOUNT_ID'"], "method":"subscribe", "is_full":true } ' -w 360` Subscribe 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": "subscribe", "p": { "s": "v1.withdrawal", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Unsubscribe 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": "unsubscribe", "p": { "s": "v1.withdrawal", "s1": ["'$GRVT_MAIN_ACCOUNT_ID'"] }, "i": 123 } ' -w 360` Legacy Subscribe Lite `wscat -c "wss://trades.grvt.io/ws" \ -H "Cookie: $GRVT_COOKIE" \ -H "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ -x ' { "request_id":1, "stream":"v1.withdrawal", "feed":["'$GRVT_MAIN_ACCOUNT_ID'"], "method":"subscribe", "is_full":false } ' -w 360` * * * Back to top --- # Trading API - Gravity Markets API Docs [Skip to content](https://api-docs.grvt.io/trading_api/#trading-apis) 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` RequestResponseErrorsTry it out [ApiCreateOrderRequest](https://api-docs.grvt.io/schemas/api_create_order_request) 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](https://api-docs.grvt.io/schemas/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 | | builder
`b` | string | True | The main account ID of the builder | | builder\_fee
`bf` | string | True | Builder fee charged for this order | [TimeInForce](https://api-docs.grvt.io/schemas/time_in_force) | | 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](https://api-docs.grvt.io/schemas/order_leg) | 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](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [OrderMetadata](https://api-docs.grvt.io/schemas/order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_type) 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](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_by) 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 | | `MID` = 3 | MID - Order is activated when the mid price reaches the trigger price | | `MARK` = 4 | MARK - Order is activated when the mark price reaches the trigger price | [BrokerTag](https://api-docs.grvt.io/schemas/broker_tag) 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](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | 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, "chain_id": "325" }, "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" }, "builder": "'$GRVT_MAIN_ACCOUNT_ID'", "builder_fee": 0.001 } }` **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, "ci": "325" }, "m": { "co": "23042", "ct": "1697788800000000000", "t": { "tt": "TAKE_PROFIT", "t": { "tb": "LAST", "tp": "65038.10", "cp": false } }, "b": "BROKER_CODE" }, "b": "'$GRVT_MAIN_ACCOUNT_ID'", "bf": 0.001 } }` [ApiCreateOrderResponse](https://api-docs.grvt.io/schemas/api_create_order_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | Order | True | The created order | [Order](https://api-docs.grvt.io/schemas/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 | | builder
`b` | string | True | The main account ID of the builder | | builder\_fee
`bf` | string | True | Builder fee charged for this order | [TimeInForce](https://api-docs.grvt.io/schemas/time_in_force) | | 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](https://api-docs.grvt.io/schemas/order_leg) | 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](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [OrderMetadata](https://api-docs.grvt.io/schemas/order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_type) 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](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_by) 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 | | `MID` = 3 | MID - Order is activated when the mid price reaches the trigger price | | `MARK` = 4 | MARK - Order is activated when the mark price reaches the trigger price | [BrokerTag](https://api-docs.grvt.io/schemas/broker_tag) 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](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | 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, "chain_id": "325" }, "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"] }, "builder": "'$GRVT_MAIN_ACCOUNT_ID'", "builder_fee": 0.001 } }` **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, "ci": "325" }, "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"] }, "b": "'$GRVT_MAIN_ACCOUNT_ID'", "bf": 0.001 } }` 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 | | 1012 | 400 | Invalid signature chain ID | | 2000 | 403 | Signature is from an unauthorized signer | | 2001 | 403 | Signature has expired | | 2002 | 403 | Signature does not match payload | | 2003 | 403 | Order sub account does not match logged in user | | 2004 | 403 | Signature is from an expired session key | | 2006 | 403 | Signature R/S must have exactly 64 characters long without 0x prefix | | 2005 | 403 | Signature V must be 27/28 | | 2007 | 403 | 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 | | 2066 | 400 | Order below minimum notional. Please try again with a higher price or size. | | 2067 | 400 | Order below minimum notional. Please try reducing your position again with a higher price or size. | | 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 | | 2117 | 400 | Position linked TPSL orders must be created from web or mobile clients | | 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 | | 2402 | 400 | Reduce only order size exceeds maximum allowed value | 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD 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, "chain_id": "325" }, "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" }, "builder": "'$GRVT_MAIN_ACCOUNT_ID'", "builder_fee": 0.001 } } '` 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, "chain_id": "325" }, "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" }, "builder": "'$GRVT_MAIN_ACCOUNT_ID'", "builder_fee": 0.001 } }, "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, "ci": "325" }, "m": { "co": "23042", "ct": "1697788800000000000", "t": { "tt": "TAKE_PROFIT", "t": { "tb": "LAST", "tp": "65038.10", "cp": false } }, "b": "BROKER_CODE" }, "b": "'$GRVT_MAIN_ACCOUNT_ID'", "bf": 0.001 } } '` 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, "ci": "325" }, "m": { "co": "23042", "ct": "1697788800000000000", "t": { "tt": "TAKE_PROFIT", "t": { "tb": "LAST", "tp": "65038.10", "cp": false } }, "b": "BROKER_CODE" }, "b": "'$GRVT_MAIN_ACCOUNT_ID'", "bf": 0.001 } }, "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, "chain_id": "325" }, "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" }, "builder": "'$GRVT_MAIN_ACCOUNT_ID'", "builder_fee": 0.001 } } '` 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, "chain_id": "325" }, "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" }, "builder": "'$GRVT_MAIN_ACCOUNT_ID'", "builder_fee": 0.001 } }, "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, "ci": "325" }, "m": { "co": "23042", "ct": "1697788800000000000", "t": { "tt": "TAKE_PROFIT", "t": { "tb": "LAST", "tp": "65038.10", "cp": false } }, "b": "BROKER_CODE" }, "b": "'$GRVT_MAIN_ACCOUNT_ID'", "bf": 0.001 } } '` 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, "ci": "325" }, "m": { "co": "23042", "ct": "1697788800000000000", "t": { "tt": "TAKE_PROFIT", "t": { "tb": "LAST", "tp": "65038.10", "cp": false } }, "b": "BROKER_CODE" }, "b": "'$GRVT_MAIN_ACCOUNT_ID'", "bf": 0.001 } }, "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, "chain_id": "325" }, "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" }, "builder": "'$GRVT_MAIN_ACCOUNT_ID'", "builder_fee": 0.001 } } '` 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, "chain_id": "325" }, "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" }, "builder": "'$GRVT_MAIN_ACCOUNT_ID'", "builder_fee": 0.001 } }, "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, "ci": "325" }, "m": { "co": "23042", "ct": "1697788800000000000", "t": { "tt": "TAKE_PROFIT", "t": { "tb": "LAST", "tp": "65038.10", "cp": false } }, "b": "BROKER_CODE" }, "b": "'$GRVT_MAIN_ACCOUNT_ID'", "bf": 0.001 } } '` 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, "ci": "325" }, "m": { "co": "23042", "ct": "1697788800000000000", "t": { "tt": "TAKE_PROFIT", "t": { "tb": "LAST", "tp": "65038.10", "cp": false } }, "b": "BROKER_CODE" }, "b": "'$GRVT_MAIN_ACCOUNT_ID'", "bf": 0.001 } }, "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, "chain_id": "325" }, "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" }, "builder": "'$GRVT_MAIN_ACCOUNT_ID'", "builder_fee": 0.001 } } '` 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, "chain_id": "325" }, "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" }, "builder": "'$GRVT_MAIN_ACCOUNT_ID'", "builder_fee": 0.001 } }, "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, "ci": "325" }, "m": { "co": "23042", "ct": "1697788800000000000", "t": { "tt": "TAKE_PROFIT", "t": { "tb": "LAST", "tp": "65038.10", "cp": false } }, "b": "BROKER_CODE" }, "b": "'$GRVT_MAIN_ACCOUNT_ID'", "bf": 0.001 } } '` 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, "ci": "325" }, "m": { "co": "23042", "ct": "1697788800000000000", "t": { "tt": "TAKE_PROFIT", "t": { "tb": "LAST", "tp": "65038.10", "cp": false } }, "b": "BROKER_CODE" }, "b": "'$GRVT_MAIN_ACCOUNT_ID'", "bf": 0.001 } }, "i": 123 } ' -w 360` * * * ### Cancel Order `FULL ENDPOINT: full/v1/cancel_order LITE ENDPOINT: lite/v1/cancel_order` RequestResponseErrorsTry it out [ApiCancelOrderRequest](https://api-docs.grvt.io/schemas/api_cancel_order_request) 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_id`s 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](https://api-docs.grvt.io/schemas/ack_response) 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](https://api-docs.grvt.io/schemas/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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD 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` RequestResponseErrorsTry it out [ApiCancelAllOrdersRequest](https://api-docs.grvt.io/schemas/api_cancel_all_orders_request) 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` | \[string\] | 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` | \[string\] | False
`all` | The quote filter to apply. If nil, this defaults to all quotes. Otherwise, only entries matching the filter will be cancelled | [Kind](https://api-docs.grvt.io/schemas/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 | 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](https://api-docs.grvt.io/schemas/ack_response) 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](https://api-docs.grvt.io/schemas/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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD 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` RequestResponseErrorsTry it out [ApiGetOrderRequest](https://api-docs.grvt.io/schemas/api_get_order_request) 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](https://api-docs.grvt.io/schemas/api_get_order_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | Order | True | The order object for the requested filter | [Order](https://api-docs.grvt.io/schemas/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 | | builder
`b` | string | True | The main account ID of the builder | | builder\_fee
`bf` | string | True | Builder fee charged for this order | [TimeInForce](https://api-docs.grvt.io/schemas/time_in_force) | | 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](https://api-docs.grvt.io/schemas/order_leg) | 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](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [OrderMetadata](https://api-docs.grvt.io/schemas/order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_type) 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](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_by) 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 | | `MID` = 3 | MID - Order is activated when the mid price reaches the trigger price | | `MARK` = 4 | MARK - Order is activated when the mark price reaches the trigger price | [BrokerTag](https://api-docs.grvt.io/schemas/broker_tag) 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](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | 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, "chain_id": "325" }, "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"] }, "builder": "'$GRVT_MAIN_ACCOUNT_ID'", "builder_fee": 0.001 } }` **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, "ci": "325" }, "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"] }, "b": "'$GRVT_MAIN_ACCOUNT_ID'", "bf": 0.001 } }` 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD 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` RequestResponseErrorsTry it out [ApiOpenOrdersRequest](https://api-docs.grvt.io/schemas/api_open_orders_request) | 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` | \[string\] | 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` | \[string\] | False
`all` | The quote filter to apply. If nil, this defaults to all quotes. Otherwise, only entries matching the filter will be returned | [Kind](https://api-docs.grvt.io/schemas/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 | 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](https://api-docs.grvt.io/schemas/api_open_orders_response) 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](https://api-docs.grvt.io/schemas/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 | | builder
`b` | string | True | The main account ID of the builder | | builder\_fee
`bf` | string | True | Builder fee charged for this order | [TimeInForce](https://api-docs.grvt.io/schemas/time_in_force) | | 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](https://api-docs.grvt.io/schemas/order_leg) | 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](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [OrderMetadata](https://api-docs.grvt.io/schemas/order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_type) 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](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_by) 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 | | `MID` = 3 | MID - Order is activated when the mid price reaches the trigger price | | `MARK` = 4 | MARK - Order is activated when the mark price reaches the trigger price | [BrokerTag](https://api-docs.grvt.io/schemas/broker_tag) 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](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | 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, "chain_id": "325" }, "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"] }, "builder": "'$GRVT_MAIN_ACCOUNT_ID'", "builder_fee": 0.001 }] }` **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, "ci": "325" }, "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"] }, "b": "'$GRVT_MAIN_ACCOUNT_ID'", "bf": 0.001 }] }` 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD 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` RequestResponseErrorsTry it out [ApiOrderHistoryRequest](https://api-docs.grvt.io/schemas/api_order_history_request) 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` | \[string\] | 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` | \[string\] | 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](https://api-docs.grvt.io/schemas/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 | 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](https://api-docs.grvt.io/schemas/api_order_history_response) | 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](https://api-docs.grvt.io/schemas/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 | | builder
`b` | string | True | The main account ID of the builder | | builder\_fee
`bf` | string | True | Builder fee charged for this order | [TimeInForce](https://api-docs.grvt.io/schemas/time_in_force) | | 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](https://api-docs.grvt.io/schemas/order_leg) | 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](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [OrderMetadata](https://api-docs.grvt.io/schemas/order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_type) 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](https://api-docs.grvt.io/schemas/tpsl_order_metadata) 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](https://api-docs.grvt.io/schemas/trigger_by) 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 | | `MID` = 3 | MID - Order is activated when the mid price reaches the trigger price | | `MARK` = 4 | MARK - Order is activated when the mark price reaches the trigger price | [BrokerTag](https://api-docs.grvt.io/schemas/broker_tag) 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](https://api-docs.grvt.io/schemas/order_state) | 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](https://api-docs.grvt.io/schemas/order_status) | 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](https://api-docs.grvt.io/schemas/order_reject_reason) | 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 | | `DERISK_MUST_BE_IOC` = 33 | the derisk order must be an IOC order | | `DERISK_MUST_BE_REDUCE_ONLY` = 34 | the derisk order must be a reduce-only order | | `DERISK_NOT_SUPPORTED` = 35 | derisk is not supported | | `INVALID_ORDER_TYPE` = 36 | the order type is invalid | | `CURRENCY_NOT_DEFINED` = 37 | the currency is not defined | | `INVALID_CHAIN_ID` = 38 | the chain ID is invalid | | `BUILDER_ORDER_FEE_EXCEED` = 39 | Builder fee exceed the limit | | `BUILDER_ORDER_FEE_NEGATIVE` = 40 | Builder fee is below 0 | | `BUILDER_ORDER_BUILDER_NOT_AUTHORIZED` = 41 | Builder is not an authorized builder for client | | `BUILDER_ORDER_BUILDER_NOT_EXIST` = 42 | Builder does not exist | 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, "chain_id": "325" }, "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"] }, "builder": "'$GRVT_MAIN_ACCOUNT_ID'", "builder_fee": 0.001 }], "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, "ci": "325" }, "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"] }, "b": "'$GRVT_MAIN_ACCOUNT_ID'", "bf": 0.001 }], "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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD 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` RequestResponseErrorsTry it out [ApiCancelOnDisconnectRequest](https://api-docs.grvt.io/schemas/api_cancel_on_disconnect_request) 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](https://api-docs.grvt.io/schemas/ack_response) 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](https://api-docs.grvt.io/schemas/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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD 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` RequestResponseErrorsTry it out [ApiFillHistoryRequest](https://api-docs.grvt.io/schemas/api_fill_history_request) 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` | \[string\] | 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` | \[string\] | 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](https://api-docs.grvt.io/schemas/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 | 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](https://api-docs.grvt.io/schemas/api_fill_history_response) | 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](https://api-docs.grvt.io/schemas/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 | | is\_liquidation
`il` | boolean | True | If the trade was a liquidation | | 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 | | builder
`b1` | string | True | The main account ID of the builder. referred to Order.builder | | builder\_fee\_rate
`bf` | string | True | Builder fee percentage charged for this order. referred to Order.builder builderFee | | builder\_fee
`bf1` | string | True | The builder fee paid on the trade, expressed in quote asset decimal unit. referred to Trade.builderFee | [Venue](https://api-docs.grvt.io/schemas/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](https://api-docs.grvt.io/schemas/broker_tag) 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", "is_liquidation": false, "client_order_id": "23042", "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "broker": "UNSPECIFIED", "is_rpi": false, "builder": "'$GRVT_MAIN_ACCOUNT_ID'", "builder_fee_rate": 0.001, "builder_fee": "0.2" }], "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", "il": false, "co": "23042", "s1": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "b": "UNSPECIFIED", "ir1": false, "b1": "'$GRVT_MAIN_ACCOUNT_ID'", "bf": 0.001, "bf1": "0.2" }], "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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD 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` * * * ### Funding Payment History `FULL ENDPOINT: full/v1/funding_payment_history LITE ENDPOINT: lite/v1/funding_payment_history` RequestResponseErrorsTry it out [ApiFundingPaymentHistoryRequest](https://api-docs.grvt.io/schemas/api_funding_payment_history_request) 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 | | 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` | \[string\] | 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` | \[string\] | False
`all` | The quote filter to apply. If nil, this defaults to all quotes. Otherwise, only entries matching the filter will be returned | [Kind](https://api-docs.grvt.io/schemas/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 | Query **Full Request** `{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "", "kind": ["PERPETUAL"], "base": ["BTC", "ETH"], "quote": ["USDT", "USDC"] }` **Lite Request** `{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "", "k": ["PERPETUAL"], "b": ["BTC", "ETH"], "q": ["USDT", "USDC"] }` [ApiFundingPaymentHistoryResponse](https://api-docs.grvt.io/schemas/api_funding_payment_history_response) | 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](https://api-docs.grvt.io/schemas/funding_payment) | 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` | string | 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`. | 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD 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": "", "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/funding_payment_history", "params": { "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "", "kind": ["PERPETUAL"], "base": ["BTC", "ETH"], "quote": ["USDT", "USDC"] }, "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": "", "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/funding_payment_history", "p": { "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "", "k": ["PERPETUAL"], "b": ["BTC", "ETH"], "q": ["USDT", "USDC"] }, "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": "", "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/funding_payment_history", "params": { "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "", "kind": ["PERPETUAL"], "base": ["BTC", "ETH"], "quote": ["USDT", "USDC"] }, "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": "", "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/funding_payment_history", "p": { "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "", "k": ["PERPETUAL"], "b": ["BTC", "ETH"], "q": ["USDT", "USDC"] }, "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": "", "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/funding_payment_history", "params": { "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "", "kind": ["PERPETUAL"], "base": ["BTC", "ETH"], "quote": ["USDT", "USDC"] }, "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": "", "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/funding_payment_history", "p": { "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "", "k": ["PERPETUAL"], "b": ["BTC", "ETH"], "q": ["USDT", "USDC"] }, "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": "", "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/funding_payment_history", "params": { "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "", "kind": ["PERPETUAL"], "base": ["BTC", "ETH"], "quote": ["USDT", "USDC"] }, "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": "", "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/funding_payment_history", "p": { "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "", "k": ["PERPETUAL"], "b": ["BTC", "ETH"], "q": ["USDT", "USDC"] }, "i": 123 } ' -w 360` * * * Position -------- ### Positions `FULL ENDPOINT: full/v1/positions LITE ENDPOINT: lite/v1/positions` RequestResponseErrorsTry it out [ApiPositionsRequest](https://api-docs.grvt.io/schemas/api_positions_request) 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` | \[string\] | 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` | \[string\] | False
`all` | The quote filter to apply. If nil, this defaults to all quotes. Otherwise, only entries matching the filter will be returned | [Kind](https://api-docs.grvt.io/schemas/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 | 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](https://api-docs.grvt.io/schemas/api_positions_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[Positions\] | True | The positions matching the request filter | [Positions](https://api-docs.grvt.io/schemas/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 | | cumulative\_fee
`cf` | string | True | The cumulative fee paid on the position, expressed in quote asset decimal units | | cumulative\_realized\_funding\_payment
`cr` | string | True | The cumulative realized funding payment of the position, expressed in quote asset decimal units. Positive if paid, negative if received | | margin\_type
`mt` | PositionMarginType | True | The margin type of the position | | isolated\_balance
`ib` | string | False
`None` | \[IsolatedOnly\] The wallet balance reserved for this isolated margin position, expressed in quote asset decimal units. If this positions is liquidated, this is the maximal balance that can be lost | | isolated\_im
`ii` | string | False
`None` | \[IsolatedOnly\] The initial margin of the isolated margin position, expressed in quote asset decimal units. The `total_equity` required to open more size in the position | | isolated\_mm
`im` | string | False
`None` | \[IsolatedOnly\] The maintenance margin of the isolated margin position, expressed in quote asset decimal units. The `total_equity` required to avoid liquidation of the position | [PositionMarginType](https://api-docs.grvt.io/schemas/position_margin_type) | Value | Description | | --- | --- | | `ISOLATED` = 1 | Isolated Margin Mode: each position is allocated a fixed amount of collateral | | `CROSS` = 2 | Cross Margin Mode: uses all available funds in your account as collateral across all cross margin positions | 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", "cumulative_fee": "100000.20", "cumulative_realized_funding_payment": "100000.20", "margin_type": "cross", "isolated_balance": "100000.20", "isolated_im": "100000.20", "isolated_mm": "100000.20" }] }` **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", "cf": "100000.20", "cr": "100000.20", "mt": "cross", "ib": "100000.20", "ii": "100000.20", "im": "100000.20" }] }` 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD 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` * * * ### Set Position Config `FULL ENDPOINT: full/v1/set_position_config LITE ENDPOINT: lite/v1/set_position_config` RequestResponseErrorsTry it out [ApiSetSubAccountPositionMarginConfigRequest](https://api-docs.grvt.io/schemas/api_set_sub_account_position_margin_config_request) Sets the margin type and leverage configuration for a specific position (instrument) within a sub account. This configuration is applied per-instrument, allowing different margin settings for different positions. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The sub account ID to set the margin type and leverage for | | instrument
`i` | string | True | The instrument of the position to set the margin type and leverage for | | margin\_type
`mt` | PositionMarginType | True | The margin type to set for the position | | leverage
`l` | string | True | The leverage to set for the position | | signature
`s` | Signature | True | The signature of this operation | [PositionMarginType](https://api-docs.grvt.io/schemas/position_margin_type) | Value | Description | | --- | --- | | `ISOLATED` = 1 | Isolated Margin Mode: each position is allocated a fixed amount of collateral | | `CROSS` = 2 | Cross Margin Mode: uses all available funds in your account as collateral across all cross margin positions | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | Query **Full Request** `{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "margin_type": "ISOLATED", "leverage": "1.5", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }` **Lite Request** `{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "mt": "ISOLATED", "l": "1.5", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }` [ApiSetSubAccountPositionMarginConfigResponse](https://api-docs.grvt.io/schemas/api_set_sub_account_position_margin_config_response) The response to set the margin type and leverage for a position | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | ack
`a` | boolean | True | Whether the margin type and leverage was acked | Success **Full Response** `{ "ack": "true" }` **Lite Response** `{ "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 | | 1004 | 404 | Data Not Found | | 2102 | 400 | Margin type change failed, has open position for this instrument | | 2103 | 400 | Margin type change failed, has open orders for this instrument | | 2101 | 400 | Vaults cannot configure leverage | | 2104 | 400 | Margin type not supported | | 2105 | 400 | Margin type change failed | | 2100 | 400 | Invalid initial leverage | | 2107 | 400 | Attempted to set leverage below minimum | | 2108 | 400 | Attempted to set leverage above maximum | 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://trades.dev.gravitymarkets.io/full/v1/set_position_config' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "margin_type": "ISOLATED", "leverage": "1.5", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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_position_config", "params": { "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "margin_type": "ISOLATED", "leverage": "1.5", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/set_position_config' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "mt": "ISOLATED", "l": "1.5", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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_position_config", "p": { "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "mt": "ISOLATED", "l": "1.5", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.staging.gravitymarkets.io/full/v1/set_position_config' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "margin_type": "ISOLATED", "leverage": "1.5", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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_position_config", "params": { "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "margin_type": "ISOLATED", "leverage": "1.5", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/set_position_config' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "mt": "ISOLATED", "l": "1.5", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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_position_config", "p": { "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "mt": "ISOLATED", "l": "1.5", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.testnet.grvt.io/full/v1/set_position_config' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "margin_type": "ISOLATED", "leverage": "1.5", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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_position_config", "params": { "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "margin_type": "ISOLATED", "leverage": "1.5", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.testnet.grvt.io/lite/v1/set_position_config' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "mt": "ISOLATED", "l": "1.5", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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_position_config", "p": { "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "mt": "ISOLATED", "l": "1.5", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.grvt.io/full/v1/set_position_config' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "margin_type": "ISOLATED", "leverage": "1.5", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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_position_config", "params": { "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "margin_type": "ISOLATED", "leverage": "1.5", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.grvt.io/lite/v1/set_position_config' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "mt": "ISOLATED", "l": "1.5", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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_position_config", "p": { "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "mt": "ISOLATED", "l": "1.5", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` * * * ### Add Position Margin `FULL ENDPOINT: full/v1/add_position_margin LITE ENDPOINT: lite/v1/add_position_margin` RequestResponseErrorsTry it out [ApiAddIsolatedPositionMarginRequest](https://api-docs.grvt.io/schemas/api_add_isolated_position_margin_request) The request to add margin to a isolated position | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The sub account ID to add isolated margin in or remove margin from | | instrument
`i` | string | True | The instrument to add margin into, or remove margin from | | amount
`a` | string | True | The amount of margin to add to the position, positive to add, negative to remove, expressed in quote asset decimal units | | signature
`s` | Signature | True | The signature of this operation | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | Query **Full Request** `{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "amount": "123456.78", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }` **Lite Request** `{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "a": "123456.78", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }` [ApiAddIsolatedPositionMarginResponse](https://api-docs.grvt.io/schemas/api_add_isolated_position_margin_response) The response to add margin to a isolated position | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | success
`s` | boolean | True | Whether the margin mode and 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 | | 7450 | 400 | Add margin failed | | 7451 | 400 | Add margin to empty position | | 7452 | 400 | Add margin to non isolated position | | 7453 | 400 | Max addable amount exceeded | | 7454 | 400 | Max removable amount exceeded | 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://trades.dev.gravitymarkets.io/full/v1/add_position_margin' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "amount": "123456.78", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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/add_position_margin", "params": { "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "amount": "123456.78", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/add_position_margin' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "a": "123456.78", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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/add_position_margin", "p": { "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "a": "123456.78", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.staging.gravitymarkets.io/full/v1/add_position_margin' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "amount": "123456.78", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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/add_position_margin", "params": { "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "amount": "123456.78", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/add_position_margin' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "a": "123456.78", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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/add_position_margin", "p": { "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "a": "123456.78", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.testnet.grvt.io/full/v1/add_position_margin' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "amount": "123456.78", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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/add_position_margin", "params": { "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "amount": "123456.78", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.testnet.grvt.io/lite/v1/add_position_margin' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "a": "123456.78", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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/add_position_margin", "p": { "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "a": "123456.78", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.grvt.io/full/v1/add_position_margin' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "amount": "123456.78", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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/add_position_margin", "params": { "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp", "amount": "123456.78", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.grvt.io/lite/v1/add_position_margin' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "a": "123456.78", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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/add_position_margin", "p": { "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp", "a": "123456.78", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` * * * ### Get Position Margin Limits `FULL ENDPOINT: full/v1/get_position_margin_limits LITE ENDPOINT: lite/v1/get_position_margin_limits` RequestResponseErrorsTry it out [ApiGetIsolatedPositionMarginLimitsRequest](https://api-docs.grvt.io/schemas/api_get_isolated_position_margin_limits_request) The request to get the max addable and removable amount for an isolated position | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The sub account ID to get the margin limits for | | instrument
`i` | string | True | The isolated position asset to get the margin limits for | Query **Full Request** `{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp" }` **Lite Request** `{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp" }` [ApiGetIsolatedPositionMarginLimitsResponse](https://api-docs.grvt.io/schemas/api_get_isolated_position_margin_limits_response) The response to get the max addable and removable amount for an isolated position request | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | instrument
`i` | string | True | The isolated position asset | | max\_addable\_amount
`ma` | string | True | The max addable amount that can be added to the isolated position, expressed in quote asset decimal units | | max\_removable\_amount
`mr` | string | True | The max removable amount that can be removed from the isolated position, expressed in quote asset decimal units | Success **Full Response** `{ "instrument": "BTC_USDT_Perp", "max_addable_amount": "123456.78", "max_removable_amount": "123456.78" }` **Lite Response** `{ "i": "BTC_USDT_Perp", "ma": "123456.78", "mr": "123456.78" }` 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 | | 7455 | 400 | Not isolated margin position | 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://trades.dev.gravitymarkets.io/full/v1/get_position_margin_limits' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp" } '` 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_position_margin_limits", "params": { "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/get_position_margin_limits' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp" } '` 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_position_margin_limits", "p": { "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.staging.gravitymarkets.io/full/v1/get_position_margin_limits' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp" } '` 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_position_margin_limits", "params": { "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/get_position_margin_limits' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp" } '` 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_position_margin_limits", "p": { "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.testnet.grvt.io/full/v1/get_position_margin_limits' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp" } '` 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_position_margin_limits", "params": { "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.testnet.grvt.io/lite/v1/get_position_margin_limits' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp" } '` 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_position_margin_limits", "p": { "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.grvt.io/full/v1/get_position_margin_limits' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp" } '` 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_position_margin_limits", "params": { "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "instrument": "BTC_USDT_Perp" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.grvt.io/lite/v1/get_position_margin_limits' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp" } '` 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_position_margin_limits", "p": { "sa": "'$GRVT_SUB_ACCOUNT_ID'", "i": "BTC_USDT_Perp" }, "i": 123 } ' -w 360` * * * Transfer -------- ### Deposit History `FULL ENDPOINT: full/v1/deposit_history LITE ENDPOINT: lite/v1/deposit_history` RequestResponseErrorsTry it out [ApiDepositHistoryRequest](https://api-docs.grvt.io/schemas/api_deposit_history_request) The request to get the historical deposits of an account The history is returned in reverse chronological order Both finalized and pending deposits are returned, and pending deposits are indicated by an empty `confirmedTime` field. 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` | \[string\] | 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. | 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](https://api-docs.grvt.io/schemas/api_deposit_history_response) | 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](https://api-docs.grvt.io/schemas/deposit_history) | 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` | string | 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, empty if the deposit is pending. | | from\_address
`fa` | string | True | The address of the sender | 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD 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` RequestResponseErrorsTry it out [ApiTransferRequest](https://api-docs.grvt.io/schemas/api_transfer_request) 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` | string | 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 | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [TransferType](https://api-docs.grvt.io/schemas/transfer_type) | Value | Description | | --- | --- | | `UNSPECIFIED` = 0 | Default transfer that has nothing to do with bridging | | `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 | | `ADHOC_INCENTIVE` = 6 | Transfer type for adhoc incentive | | `REFERRAL_INCENTIVE` = 7 | Transfer type for referral incentive | | `TRADING_DEPOSIT_YIELD_INCENTIVE` = 8 | Transfer type for trading deposit yield incentive | 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, "chain_id": "325" }, "transfer_type": "UNSPECIFIED", "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, "ci": "325" }, "tt": "UNSPECIFIED", "tm": "{\"provider\":\"XY\",\"direction\":\"WITHDRAWAL\",\"provider_tx_id\":\"txn123456\",\"chainid\":\"42161\",\"endpoint\":\"0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0\"}" }` [ApiTransferResponse](https://api-docs.grvt.io/schemas/api_transfer_response) Used to acknowledge a transfer request outcome | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | ApiTransferAck | True | The Transfer response object | [ApiTransferAck](https://api-docs.grvt.io/schemas/api_transfer_ack) | 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. | | 7100 | 500 | Unknown transaction type | | 7101 | 400 | Transfer account not found | | 7102 | 400 | Transfer sub-account not found | | 7103 | 500 | Charged trading fee below the config minimum | 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD 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, "chain_id": "325" }, "transfer_type": "UNSPECIFIED", "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, "chain_id": "325" }, "transfer_type": "UNSPECIFIED", "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, "ci": "325" }, "tt": "UNSPECIFIED", "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, "ci": "325" }, "tt": "UNSPECIFIED", "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, "chain_id": "325" }, "transfer_type": "UNSPECIFIED", "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, "chain_id": "325" }, "transfer_type": "UNSPECIFIED", "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, "ci": "325" }, "tt": "UNSPECIFIED", "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, "ci": "325" }, "tt": "UNSPECIFIED", "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, "chain_id": "325" }, "transfer_type": "UNSPECIFIED", "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, "chain_id": "325" }, "transfer_type": "UNSPECIFIED", "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, "ci": "325" }, "tt": "UNSPECIFIED", "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, "ci": "325" }, "tt": "UNSPECIFIED", "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, "chain_id": "325" }, "transfer_type": "UNSPECIFIED", "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, "chain_id": "325" }, "transfer_type": "UNSPECIFIED", "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, "ci": "325" }, "tt": "UNSPECIFIED", "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, "ci": "325" }, "tt": "UNSPECIFIED", "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` RequestResponseErrorsTry it out [ApiTransferHistoryRequest](https://api-docs.grvt.io/schemas/api_transfer_history_request) 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` | \[string\] | 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. | | transfer\_types
`tt` | \[TransferType\] | False
`[]` | The transfer type to filters for. If the list is empty, return all transfer types. | [TransferType](https://api-docs.grvt.io/schemas/transfer_type) | Value | Description | | --- | --- | | `UNSPECIFIED` = 0 | Default transfer that has nothing to do with bridging | | `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 | | `ADHOC_INCENTIVE` = 6 | Transfer type for adhoc incentive | | `REFERRAL_INCENTIVE` = 7 | Transfer type for referral incentive | | `TRADING_DEPOSIT_YIELD_INCENTIVE` = 8 | Transfer type for trading deposit yield incentive | Query **Full Request** `{ "currency": ["USDT", "USDC"], "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "", "tx_id": "1028403", "main_account_id": null, "transfer_types": ["UNSPECIFIED"] }` **Lite Request** `{ "c": ["USDT", "USDC"], "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c1": "", "ti": "1028403", "ma": null, "tt": ["UNSPECIFIED"] }` [ApiTransferHistoryResponse](https://api-docs.grvt.io/schemas/api_transfer_history_response) | 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](https://api-docs.grvt.io/schemas/transfer_history) | 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` | string | 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 | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | [TransferType](https://api-docs.grvt.io/schemas/transfer_type) | Value | Description | | --- | --- | | `UNSPECIFIED` = 0 | Default transfer that has nothing to do with bridging | | `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 | | `ADHOC_INCENTIVE` = 6 | Transfer type for adhoc incentive | | `REFERRAL_INCENTIVE` = 7 | Transfer type for referral incentive | | `TRADING_DEPOSIT_YIELD_INCENTIVE` = 8 | Transfer type for trading deposit yield incentive | 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, "chain_id": "325" }, "event_time": "1697788800000000000", "transfer_type": "UNSPECIFIED", "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, "ci": "325" }, "et": "1697788800000000000", "tt": "UNSPECIFIED", "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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD 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, "transfer_types": ["UNSPECIFIED"] } '` 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, "transfer_types": ["UNSPECIFIED"] }, "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, "tt": ["UNSPECIFIED"] } '` 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, "tt": ["UNSPECIFIED"] }, "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, "transfer_types": ["UNSPECIFIED"] } '` 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, "transfer_types": ["UNSPECIFIED"] }, "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, "tt": ["UNSPECIFIED"] } '` 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, "tt": ["UNSPECIFIED"] }, "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, "transfer_types": ["UNSPECIFIED"] } '` 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, "transfer_types": ["UNSPECIFIED"] }, "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, "tt": ["UNSPECIFIED"] } '` 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, "tt": ["UNSPECIFIED"] }, "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, "transfer_types": ["UNSPECIFIED"] } '` 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, "transfer_types": ["UNSPECIFIED"] }, "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, "tt": ["UNSPECIFIED"] } '` 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, "tt": ["UNSPECIFIED"] }, "i": 123 } ' -w 360` * * * ### Withdrawal `FULL ENDPOINT: full/v1/withdrawal LITE ENDPOINT: lite/v1/withdrawal` RequestResponseErrorsTry it out [ApiWithdrawalRequest](https://api-docs.grvt.io/schemas/api_withdrawal_request) 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` | string | 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 | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | 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, "chain_id": "325" } }` **Lite Request** `{ "fa": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "te": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "c": "USDT", "nt": "1500.0", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }` [AckResponse](https://api-docs.grvt.io/schemas/ack_response) 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](https://api-docs.grvt.io/schemas/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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD 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, "chain_id": "325" } } '` 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, "chain_id": "325" } }, "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, "ci": "325" } } '` 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, "ci": "325" } }, "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, "chain_id": "325" } } '` 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, "chain_id": "325" } }, "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, "ci": "325" } } '` 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, "ci": "325" } }, "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, "chain_id": "325" } } '` 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, "chain_id": "325" } }, "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, "ci": "325" } } '` 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, "ci": "325" } }, "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, "chain_id": "325" } } '` 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, "chain_id": "325" } }, "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, "ci": "325" } } '` 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, "ci": "325" } }, "i": 123 } ' -w 360` * * * ### Withdrawal History `FULL ENDPOINT: full/v1/withdrawal_history LITE ENDPOINT: lite/v1/withdrawal_history` RequestResponseErrorsTry it out [ApiWithdrawalHistoryRequest](https://api-docs.grvt.io/schemas/api_withdrawal_history_request) The request to get the historical withdrawals of an account The history is returned in reverse chronological order Both finalized and pending withdrawals are returned, and pending withdrawals are indicated by an empty `l1Hash` field. 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` | \[string\] | 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. | 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](https://api-docs.grvt.io/schemas/api_withdrawal_history_response) | 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](https://api-docs.grvt.io/schemas/withdrawal_history) | 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` | string | 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 | | l\_1\_hash
`l1` | string | False
`''` | The finalized withdrawal transaction hash on L1, empty if the withdrawal is 'pending'. | | l\_2\_hash
`l2` | string | True | The transaction hash on L2 | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | 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, "chain_id": "325" }, "event_time": "1697788800000000000", "l_1_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "l_2_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" }], "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, "ci": "325" }, "et": "1697788800000000000", "l1": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "l2": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" }], "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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD 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` RequestResponseErrorsTry it out [ApiSubAccountSummaryRequest](https://api-docs.grvt.io/schemas/api_sub_account_summary_request) | 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](https://api-docs.grvt.io/schemas/api_sub_account_summary_response) 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](https://api-docs.grvt.io/schemas/sub_account) | 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` | string | 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`) | | is\_vault
`iv` | boolean | False
`None` | Whether this sub account is a vault | | vault\_im\_additions
`vi` | string | False
`None` | Total amount of IM (reported in `settle_currency`) deducted from the vault due to redemptions nearing the end of their redemption period | | derisk\_margin
`dm` | string | True | The derisk margin of this sub account | | derisk\_to\_maintenance\_margin\_ratio
`dt` | string | True | The derisk margin to maintenance margin ratio of this sub account | | total\_cross\_equity
`tc` | string | True | The total equity of this sub account for cross margin | | cross\_unrealized\_pnl
`cu` | string | True | The unrealized PnL of this sub account for cross margin | [MarginType](https://api-docs.grvt.io/schemas/margin_type) | 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 | [SpotBalance](https://api-docs.grvt.io/schemas/spot_balance) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | currency
`c` | string | 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`) | [Positions](https://api-docs.grvt.io/schemas/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 | | cumulative\_fee
`cf` | string | True | The cumulative fee paid on the position, expressed in quote asset decimal units | | cumulative\_realized\_funding\_payment
`cr` | string | True | The cumulative realized funding payment of the position, expressed in quote asset decimal units. Positive if paid, negative if received | | margin\_type
`mt` | PositionMarginType | True | The margin type of the position | | isolated\_balance
`ib` | string | False
`None` | \[IsolatedOnly\] The wallet balance reserved for this isolated margin position, expressed in quote asset decimal units. If this positions is liquidated, this is the maximal balance that can be lost | | isolated\_im
`ii` | string | False
`None` | \[IsolatedOnly\] The initial margin of the isolated margin position, expressed in quote asset decimal units. The `total_equity` required to open more size in the position | | isolated\_mm
`im` | string | False
`None` | \[IsolatedOnly\] The maintenance margin of the isolated margin position, expressed in quote asset decimal units. The `total_equity` required to avoid liquidation of the position | [PositionMarginType](https://api-docs.grvt.io/schemas/position_margin_type) | Value | Description | | --- | --- | | `ISOLATED` = 1 | Isolated Margin Mode: each position is allocated a fixed amount of collateral | | `CROSS` = 2 | Cross Margin Mode: uses all available funds in your account as collateral across all cross margin positions | 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", "cumulative_fee": "100000.20", "cumulative_realized_funding_payment": "100000.20", "margin_type": "cross", "isolated_balance": "100000.20", "isolated_im": "100000.20", "isolated_mm": "100000.20" }], "settle_index_price": "1.0000102", "is_vault": null, "vault_im_additions": "123456.78", "derisk_margin": "185185.77", "derisk_to_maintenance_margin_ratio": "1.5", "total_cross_equity": "123456.78", "cross_unrealized_pnl": "123456.78" } }` **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", "cf": "100000.20", "cr": "100000.20", "mt": "cross", "ib": "100000.20", "ii": "100000.20", "im": "100000.20" }], "si": "1.0000102", "iv": null, "vi": "123456.78", "dm": "185185.77", "dt": "1.5", "tc": "123456.78", "cu": "123456.78" } }` 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD 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` RequestResponseErrorsTry it out [ApiSubAccountHistoryRequest](https://api-docs.grvt.io/schemas/api_sub_account_history_request) 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](https://api-docs.grvt.io/schemas/api_sub_account_history_response) | 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](https://api-docs.grvt.io/schemas/sub_account) | 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` | string | 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`) | | is\_vault
`iv` | boolean | False
`None` | Whether this sub account is a vault | | vault\_im\_additions
`vi` | string | False
`None` | Total amount of IM (reported in `settle_currency`) deducted from the vault due to redemptions nearing the end of their redemption period | | derisk\_margin
`dm` | string | True | The derisk margin of this sub account | | derisk\_to\_maintenance\_margin\_ratio
`dt` | string | True | The derisk margin to maintenance margin ratio of this sub account | | total\_cross\_equity
`tc` | string | True | The total equity of this sub account for cross margin | | cross\_unrealized\_pnl
`cu` | string | True | The unrealized PnL of this sub account for cross margin | [MarginType](https://api-docs.grvt.io/schemas/margin_type) | 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 | [SpotBalance](https://api-docs.grvt.io/schemas/spot_balance) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | currency
`c` | string | 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`) | [Positions](https://api-docs.grvt.io/schemas/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 | | cumulative\_fee
`cf` | string | True | The cumulative fee paid on the position, expressed in quote asset decimal units | | cumulative\_realized\_funding\_payment
`cr` | string | True | The cumulative realized funding payment of the position, expressed in quote asset decimal units. Positive if paid, negative if received | | margin\_type
`mt` | PositionMarginType | True | The margin type of the position | | isolated\_balance
`ib` | string | False
`None` | \[IsolatedOnly\] The wallet balance reserved for this isolated margin position, expressed in quote asset decimal units. If this positions is liquidated, this is the maximal balance that can be lost | | isolated\_im
`ii` | string | False
`None` | \[IsolatedOnly\] The initial margin of the isolated margin position, expressed in quote asset decimal units. The `total_equity` required to open more size in the position | | isolated\_mm
`im` | string | False
`None` | \[IsolatedOnly\] The maintenance margin of the isolated margin position, expressed in quote asset decimal units. The `total_equity` required to avoid liquidation of the position | [PositionMarginType](https://api-docs.grvt.io/schemas/position_margin_type) | Value | Description | | --- | --- | | `ISOLATED` = 1 | Isolated Margin Mode: each position is allocated a fixed amount of collateral | | `CROSS` = 2 | Cross Margin Mode: uses all available funds in your account as collateral across all cross margin positions | 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", "cumulative_fee": "100000.20", "cumulative_realized_funding_payment": "100000.20", "margin_type": "cross", "isolated_balance": "100000.20", "isolated_im": "100000.20", "isolated_mm": "100000.20" }], "settle_index_price": "1.0000102", "is_vault": null, "vault_im_additions": "123456.78", "derisk_margin": "185185.77", "derisk_to_maintenance_margin_ratio": "1.5", "total_cross_equity": "123456.78", "cross_unrealized_pnl": "123456.78" }], "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", "cf": "100000.20", "cr": "100000.20", "mt": "cross", "ib": "100000.20", "ii": "100000.20", "im": "100000.20" }], "si": "1.0000102", "iv": null, "vi": "123456.78", "dm": "185185.77", "dt": "1.5", "tc": "123456.78", "cu": "123456.78" }], "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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD 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` RequestResponseErrorsTry it out [EmptyRequest](https://api-docs.grvt.io/schemas/empty_request) Used for requests that do not require any parameters | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | | | | | Query **Full Request** `{ }` **Lite Request** `{ }` [ApiAggregatedAccountSummaryResponse](https://api-docs.grvt.io/schemas/api_aggregated_account_summary_response) 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](https://api-docs.grvt.io/schemas/aggregated_account_summary) | 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 | | vault\_investments
`vi` | \[VaultInvestment\] | True | The list of vault investments held by this main account | | total\_sub\_account\_balance
`ts` | string | True | Deprecated: Use totalSubAccountEquity instead | | total\_sub\_account\_equity
`ts1` | string | True | Total equity of the sub accounts, denominated in USD | | total\_vault\_investments\_balance
`tv` | string | True | Total amount of the vault investments, denominated in USD | | total\_sub\_account\_available\_balance
`ts2` | string | True | Total available balance of the main account, denominated in USD | | total\_usd\_notional\_invested
`tu` | string | True | Total entry (initial investment) amount of the open investments, denominated in USD | [SpotBalance](https://api-docs.grvt.io/schemas/spot_balance) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | currency
`c` | string | 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`) | [VaultInvestment](https://api-docs.grvt.io/schemas/vault_investment) Summarizes a vault investment held by a funding account | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_id
`vi` | string | True | The trading account ID of the vault invested in. | | num\_lp\_tokens
`nl` | string | True | The number of shares held by the investor. | | share\_price
`sp` | string | True | The current share price (in USD) of this vault investment. | | usd\_notional\_invested
`un` | string | True | The USD notional invested in this vault investment. | Success **Full Response** `{ "result": { "main_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "total_equity": "3945034.23", "spot_balances": [{ "currency": "USDT", "balance": "123456.78", "index_price": "1.0000102" }], "vault_investments": [{ "vault_id": 123456789, "num_lp_tokens": 1000000, "share_price": 1000000, "usd_notional_invested": 1000000 }], "total_sub_account_balance": "3945034.23", "total_sub_account_equity": "3945034.23", "total_vault_investments_balance": "3945034.23", "total_sub_account_available_balance": "3945034.23", "total_usd_notional_invested": "3945034.23" } }` **Lite Response** `{ "r": { "ma": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "te": "3945034.23", "sb": [{ "c": "USDT", "b": "123456.78", "ip": "1.0000102" }], "vi": [{ "vi": 123456789, "nl": 1000000, "sp": 1000000, "un": 1000000 }], "ts": "3945034.23", "ts1": "3945034.23", "tv": "3945034.23", "ts2": "3945034.23", "tu": "3945034.23" } }` 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD 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` RequestResponseErrorsTry it out [EmptyRequest](https://api-docs.grvt.io/schemas/empty_request) Used for requests that do not require any parameters | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | | | | | Query **Full Request** `{ }` **Lite Request** `{ }` [ApiFundingAccountSummaryResponse](https://api-docs.grvt.io/schemas/api_funding_account_summary_response) 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 | | tier
`t` | ClientTier | True | Client fee tier at the time of query | [FundingAccountSummary](https://api-docs.grvt.io/schemas/funding_account_summary) 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 | | vault\_investments
`vi` | \[VaultInvestment\] | True | The list of vault investments held by this main account | [SpotBalance](https://api-docs.grvt.io/schemas/spot_balance) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | currency
`c` | string | 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`) | [VaultInvestment](https://api-docs.grvt.io/schemas/vault_investment) Summarizes a vault investment held by a funding account | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_id
`vi` | string | True | The trading account ID of the vault invested in. | | num\_lp\_tokens
`nl` | string | True | The number of shares held by the investor. | | share\_price
`sp` | string | True | The current share price (in USD) of this vault investment. | | usd\_notional\_invested
`un` | string | True | The USD notional invested in this vault investment. | [ClientTier](https://api-docs.grvt.io/schemas/client_tier) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | tier
`t` | integer | True | | | futures\_taker\_fee
`ft` | integer | True | | | futures\_maker\_fee
`fm` | integer | True | | | options\_taker\_fee
`ot` | integer | True | | | options\_maker\_fee
`om` | integer | True | | Success **Full Response** `{ "result": { "main_account_id": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "total_equity": "3945034.23", "spot_balances": [{ "currency": "USDT", "balance": "123456.78", "index_price": "1.0000102" }], "vault_investments": [{ "vault_id": 123456789, "num_lp_tokens": 1000000, "share_price": 1000000, "usd_notional_invested": 1000000 }] }, "tier": { "tier": null, "futures_taker_fee": null, "futures_maker_fee": null, "options_taker_fee": null, "options_maker_fee": null } }` **Lite Response** `{ "r": { "ma": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "te": "3945034.23", "sb": [{ "c": "USDT", "b": "123456.78", "ip": "1.0000102" }], "vi": [{ "vi": 123456789, "nl": 1000000, "sp": 1000000, "un": 1000000 }] }, "t": { "t": null, "ft": null, "fm": null, "ot": null, "om": null } }` 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD 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` * * * DeriskMMRatio ------------- ### Set Derisk M M Ratio `FULL ENDPOINT: full/v1/set_derisk_mm_ratio LITE ENDPOINT: lite/v1/set_derisk_mm_ratio` RequestResponseErrorsTry it out [ApiSetDeriskToMaintenanceMarginRatioRequest](https://api-docs.grvt.io/schemas/api_set_derisk_to_maintenance_margin_ratio_request) The request to set the derisk margin to maintenance margin ratio 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 | | ratio
`r` | string | True | The derisk margin to maintenance margin ratio of this sub account | | signature
`s` | Signature | True | The signature of this operation | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | Query **Full Request** `{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "ratio": "1.5", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }` **Lite Request** `{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "r": "1.5", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }` [ApiSetDeriskToMaintenanceMarginRatioResponse](https://api-docs.grvt.io/schemas/api_set_derisk_to_maintenance_margin_ratio_response) The response to set the derisk margin to maintenance margin ratio of a sub account | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | success
`s` | boolean | True | Whether the derisk margin to maintenance margin ratio 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 | | 6100 | 400 | Derisk MM Ratio is out of range | 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://trades.dev.gravitymarkets.io/full/v1/set_derisk_mm_ratio' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "ratio": "1.5", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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_derisk_mm_ratio", "params": { "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "ratio": "1.5", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/set_derisk_mm_ratio' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "r": "1.5", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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_derisk_mm_ratio", "p": { "sa": "'$GRVT_SUB_ACCOUNT_ID'", "r": "1.5", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.staging.gravitymarkets.io/full/v1/set_derisk_mm_ratio' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "ratio": "1.5", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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_derisk_mm_ratio", "params": { "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "ratio": "1.5", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/set_derisk_mm_ratio' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "r": "1.5", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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_derisk_mm_ratio", "p": { "sa": "'$GRVT_SUB_ACCOUNT_ID'", "r": "1.5", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.testnet.grvt.io/full/v1/set_derisk_mm_ratio' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "ratio": "1.5", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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_derisk_mm_ratio", "params": { "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "ratio": "1.5", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.testnet.grvt.io/lite/v1/set_derisk_mm_ratio' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "r": "1.5", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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_derisk_mm_ratio", "p": { "sa": "'$GRVT_SUB_ACCOUNT_ID'", "r": "1.5", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.grvt.io/full/v1/set_derisk_mm_ratio' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "ratio": "1.5", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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_derisk_mm_ratio", "params": { "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "ratio": "1.5", "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.grvt.io/lite/v1/set_derisk_mm_ratio' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "r": "1.5", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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_derisk_mm_ratio", "p": { "sa": "'$GRVT_SUB_ACCOUNT_ID'", "r": "1.5", "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` * * * Account ------- ### Get Sub Accounts `FULL ENDPOINT: full/v1/get_sub_accounts LITE ENDPOINT: lite/v1/get_sub_accounts` RequestResponseErrorsTry it out [EmptyRequest](https://api-docs.grvt.io/schemas/empty_request) Used for requests that do not require any parameters | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | | | | | Query **Full Request** `{ }` **Lite Request** `{ }` [ApiGetSubAccountsResponse](https://api-docs.grvt.io/schemas/api_get_sub_accounts_response) Response payload containing all sub-accounts accessible within the given auth session | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_ids
`sa` | \[string\] | True | List of sub-account IDs accessible to the session | Success **Full Response** `{ "sub_account_ids": ["4724219064482495","2095919380","1170592370"] }` **Lite Response** `{ "sa": ["4724219064482495","2095919380","1170592370"] }` Error Codes | Code | HttpStatus | Description | | --- | --- | --- | | 1000 | 401 | You need to authenticate prior to using this functionality | | 1002 | 500 | Internal Server Error | | 1006 | 429 | You have surpassed the allocated rate limit for your tier | 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://trades.dev.gravitymarkets.io/full/v1/get_sub_accounts' \ --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/get_sub_accounts", "params": { }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/get_sub_accounts' \ --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/get_sub_accounts", "p": { }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.staging.gravitymarkets.io/full/v1/get_sub_accounts' \ --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/get_sub_accounts", "params": { }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/get_sub_accounts' \ --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/get_sub_accounts", "p": { }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.testnet.grvt.io/full/v1/get_sub_accounts' \ --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/get_sub_accounts", "params": { }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.testnet.grvt.io/lite/v1/get_sub_accounts' \ --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/get_sub_accounts", "p": { }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.grvt.io/full/v1/get_sub_accounts' \ --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/get_sub_accounts", "params": { }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.grvt.io/lite/v1/get_sub_accounts' \ --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/get_sub_accounts", "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` RequestResponseErrorsTry it out [ApiGetAllInitialLeverageRequest](https://api-docs.grvt.io/schemas/api_get_all_initial_leverage_request) 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](https://api-docs.grvt.io/schemas/api_get_all_initial_leverage_response) 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](https://api-docs.grvt.io/schemas/initial_leverage_result) | 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 this instrument | | min\_leverage
`ml` | string | True | The min leverage user can set for this instrument | | max\_leverage
`ml1` | string | True | The max leverage user can set for this instrument | | margin\_type
`mt` | PositionMarginType | True | The margin type of this instrument | [PositionMarginType](https://api-docs.grvt.io/schemas/position_margin_type) | Value | Description | | --- | --- | | `ISOLATED` = 1 | Isolated Margin Mode: each position is allocated a fixed amount of collateral | | `CROSS` = 2 | Cross Margin Mode: uses all available funds in your account as collateral across all cross margin positions | Success **Full Response** `{ "results": [{ "instrument": "BTC_USDT_Perp", "leverage": "10", "min_leverage": "10", "max_leverage": "50", "margin_type": "ISOLATED" }] }` **Lite Response** `{ "r": [{ "i": "BTC_USDT_Perp", "l": "10", "ml": "10", "ml1": "50", "mt": "ISOLATED" }] }` 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD 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` RequestResponseErrorsTry it out [ApiSetInitialLeverageRequest](https://api-docs.grvt.io/schemas/api_set_initial_leverage_request) 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](https://api-docs.grvt.io/schemas/api_set_initial_leverage_response) 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 | | 2101 | 400 | Vaults cannot configure 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD 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` * * * Vault ----- ### Vault Burn Tokens `FULL ENDPOINT: full/v1/vault_burn_tokens LITE ENDPOINT: lite/v1/vault_burn_tokens` RequestResponseErrorsTry it out [ApiVaultBurnTokensRequest](https://api-docs.grvt.io/schemas/api_vault_burn_tokens_request) Request payload for burning tokens in a vault. This API allows a client to burn a specified amount of tokens in a particular vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_id
`vi` | string | True | The unique identifier of the vault to burn tokens from. | | currency
`c` | string | True | The currency used for the burn. This should be the vault's quote currency. | | num\_tokens
`nt` | string | True | The number of tokens to burn. | | signature
`s` | Signature | True | The digital signature from the investing account.
This signature must be generated by the main account ID and is used to verify the authenticity of the request.
The signature must comply with AccountPermExternalTransfer permission. | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | Query **Full Request** `{ "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }` **Lite Request** `{ "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }` [AckResponse](https://api-docs.grvt.io/schemas/ack_response) 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](https://api-docs.grvt.io/schemas/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 | | 1009 | 503 | We are temporarily deactivating this API endpoint, please try again later | | 2000 | 403 | Signature is from an unauthorized signer | | 2001 | 403 | Signature has expired | | 2002 | 403 | Signature does not match payload | | 2004 | 403 | Signature is from an expired session key | | 2006 | 403 | Signature R/S must have exactly 64 characters long without 0x prefix | | 2005 | 403 | Signature V must be 27/28 | | 2007 | 403 | Signature S must be in the lower half of the curve | | 2008 | 403 | Signature exceeds maximum allowed duration. | | 7000 | 400 | Vault ID provided is invalid and does not belong to any vault | | 7005 | 400 | You are attempting to burn more vault tokens than you own. | | 7006 | 400 | You are attempting to burn vault tokens whilst having an active redemption 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://trades.dev.gravitymarkets.io/full/v1/vault_burn_tokens' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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/vault_burn_tokens", "params": { "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/vault_burn_tokens' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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/vault_burn_tokens", "p": { "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.staging.gravitymarkets.io/full/v1/vault_burn_tokens' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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/vault_burn_tokens", "params": { "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/vault_burn_tokens' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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/vault_burn_tokens", "p": { "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.testnet.grvt.io/full/v1/vault_burn_tokens' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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/vault_burn_tokens", "params": { "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.testnet.grvt.io/lite/v1/vault_burn_tokens' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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/vault_burn_tokens", "p": { "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.grvt.io/full/v1/vault_burn_tokens' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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/vault_burn_tokens", "params": { "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.grvt.io/lite/v1/vault_burn_tokens' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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/vault_burn_tokens", "p": { "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` * * * ### Vault Invest `FULL ENDPOINT: full/v1/vault_invest LITE ENDPOINT: lite/v1/vault_invest` RequestResponseErrorsTry it out [ApiVaultInvestRequest](https://api-docs.grvt.io/schemas/api_vault_invest_request) Request payload for investing in a vault. This API allows a client to invest a specified amount of tokens in a particular vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_id
`vi` | string | True | The unique identifier of the vault to invest in. | | currency
`c` | string | True | The currency used for the investment. This should be the vault's quote currency. | | num\_tokens
`nt` | string | True | The investment sum, in terms of the token currency specified (i.e., `numTokens` of '1000' with `tokenCurrency` of 'USDT' denotes investment of 1,000 USDT). | | signature
`s` | Signature | True | The digital signature from the investing account.
This signature must be generated by the main account ID and is used to verify the authenticity of the request.
The signature must comply with AccountPermExternalTransfer permission. | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | Query **Full Request** `{ "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }` **Lite Request** `{ "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }` [AckResponse](https://api-docs.grvt.io/schemas/ack_response) 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](https://api-docs.grvt.io/schemas/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 | | 1009 | 503 | We are temporarily deactivating this API endpoint, please try again later | | 2000 | 403 | Signature is from an unauthorized signer | | 2001 | 403 | Signature has expired | | 2002 | 403 | Signature does not match payload | | 2004 | 403 | Signature is from an expired session key | | 2006 | 403 | Signature R/S must have exactly 64 characters long without 0x prefix | | 2005 | 403 | Signature V must be 27/28 | | 2007 | 403 | Signature S must be in the lower half of the curve | | 2008 | 403 | Signature exceeds maximum allowed duration. | | 4000 | 400 | Insufficient balance to complete transfer | | 7000 | 400 | Vault ID provided is invalid and does not belong to any vault | | 7003 | 400 | This vault has been delisted/closed. | | 7004 | 400 | This investment would cause the vault to exceed its valuation cap. | 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://trades.dev.gravitymarkets.io/full/v1/vault_invest' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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/vault_invest", "params": { "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/vault_invest' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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/vault_invest", "p": { "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.staging.gravitymarkets.io/full/v1/vault_invest' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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/vault_invest", "params": { "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/vault_invest' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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/vault_invest", "p": { "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.testnet.grvt.io/full/v1/vault_invest' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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/vault_invest", "params": { "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.testnet.grvt.io/lite/v1/vault_invest' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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/vault_invest", "p": { "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.grvt.io/full/v1/vault_invest' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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/vault_invest", "params": { "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.grvt.io/lite/v1/vault_invest' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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/vault_invest", "p": { "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` * * * ### Vault Investor Summary `FULL ENDPOINT: full/v1/vault_investor_summary LITE ENDPOINT: lite/v1/vault_investor_summary` RequestResponseErrorsTry it out [ApiVaultInvestorSummaryRequest](https://api-docs.grvt.io/schemas/api_vault_investor_summary_request) Request payload for fetching the summary of a vault investor. This API allows a client to retrieve the summary of investments in a specific vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_id
`vi` | string | True | The unique identifier of the vault to fetch the summary for. | Query **Full Request** `{ "vault_id": "3477045127917224" }` **Lite Request** `{ "vi": "3477045127917224" }` [ApiVaultInvestorSummaryResponse](https://api-docs.grvt.io/schemas/api_vault_investor_summary_response) Response payload for the summary of a vault investor. This API provides the summary of investments in a specific vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_investor\_summary
`vi` | \[VaultInvestorSummary\] | True | The summary of investments in the vault. | [VaultInvestorSummary](https://api-docs.grvt.io/schemas/vault_investor_summary) Vault investor summary information. This struct contains the summary of investments in a vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | sub\_account\_id
`sa` | string | True | The unique identifier of the vault sub account. | | num\_lp\_tokens
`nl` | string | True | The number of Vault LP tokens held by the investor. | | avg\_entry\_price
`ae` | string | True | The average entry price (in USD) of the vault LP tokens. | | current\_price
`cp` | string | True | The current price (in USD) of the vault LP tokens. | | total\_equity
`te` | string | True | The current valuation (in USD) of all held vault LP tokens. | | all\_time\_realized\_pnl
`at` | string | True | The all-time realized PnL (in USD) that the investor has received from the vault. | | pending\_redemption
`pr` | VaultRedemption | False
`None` | The singleton pending redemption (omitted if none). | | can\_burn
`cb` | boolean | False
`true` | True if the requesting account is authorized to burn tokens on this vault, omitted otherwise. | [VaultRedemption](https://api-docs.grvt.io/schemas/vault_redemption) Vault redemption information. This struct contains information about a pending redemption from a vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | num\_lp\_tokens
`nl` | string | True | The number of LP Tokens requested for redemption. | | request\_valuation
`rv` | string | True | The valuation (in USD) of the redemption request. | | request\_time
`rt` | string | True | \[Filled by GRVT Backend\] Time at which the redemption request was received by GRVT in unix nanoseconds | | max\_redemption\_period\_timestamp
`mr` | string | True | \[Filled by GRVT Backend\] Time in unix nanoseconds, beyond which the request will be force-redeemed. | | cancel\_blocked
`cb` | boolean | False
`true` | Omitted for redemption requests to non-cross exchange vaults. True if cancellation is blocked within the CEV allocation allowance for the user's current tier (e.g. because the user has already transferred out the spot balance underlying the redemption request). | Success **Full Response** `{ "vault_investor_summary": [{ "sub_account_id": "'$GRVT_SUB_ACCOUNT_ID'", "num_lp_tokens": 1000000, "avg_entry_price": 1000000, "current_price": 1000000, "total_equity": 1000000, "all_time_realized_pnl": 1000000, "pending_redemption": { "num_lp_tokens": 1000000, "request_valuation": 1000000, "request_time": "1697788800000000000", "max_redemption_period_timestamp": 1727788800000000000, "cancel_blocked": null }, "can_burn": null }] }` **Lite Response** `{ "vi": [{ "sa": "'$GRVT_SUB_ACCOUNT_ID'", "nl": 1000000, "ae": 1000000, "cp": 1000000, "te": 1000000, "at": 1000000, "pr": { "nl": 1000000, "rv": 1000000, "rt": "1697788800000000000", "mr": 1727788800000000000, "cb": null }, "cb": null }] }` 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 | | 7000 | 400 | Vault ID provided is invalid and does not belong to any vault | | 7007 | 400 | The investor is not an LP for this vault. | 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://trades.dev.gravitymarkets.io/full/v1/vault_investor_summary' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224" } '` 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/vault_investor_summary", "params": { "vault_id": "3477045127917224" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/vault_investor_summary' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224" } '` 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/vault_investor_summary", "p": { "vi": "3477045127917224" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.staging.gravitymarkets.io/full/v1/vault_investor_summary' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224" } '` 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/vault_investor_summary", "params": { "vault_id": "3477045127917224" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/vault_investor_summary' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224" } '` 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/vault_investor_summary", "p": { "vi": "3477045127917224" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.testnet.grvt.io/full/v1/vault_investor_summary' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224" } '` 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/vault_investor_summary", "params": { "vault_id": "3477045127917224" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.testnet.grvt.io/lite/v1/vault_investor_summary' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224" } '` 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/vault_investor_summary", "p": { "vi": "3477045127917224" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.grvt.io/full/v1/vault_investor_summary' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224" } '` 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/vault_investor_summary", "params": { "vault_id": "3477045127917224" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.grvt.io/lite/v1/vault_investor_summary' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224" } '` 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/vault_investor_summary", "p": { "vi": "3477045127917224" }, "i": 123 } ' -w 360` * * * ### Vault Redeem `FULL ENDPOINT: full/v1/vault_redeem LITE ENDPOINT: lite/v1/vault_redeem` RequestResponseErrorsTry it out [ApiVaultRedeemRequest](https://api-docs.grvt.io/schemas/api_vault_redeem_request) Request payload for redeeming from a vault. This API allows a client to redeem a specified amount of tokens from a particular vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_id
`vi` | string | True | The unique identifier of the vault to redeem from. | | currency
`c` | string | True | The currency used for the redemption. This should be the vault's quote currency. | | num\_tokens
`nt` | string | True | The number of shares to redeem. | | signature
`s` | Signature | True | The digital signature from the investing account.
This signature must be generated by the main account ID and is used to verify the authenticity of the request.
The signature must comply with AccountPermExternalTransfer permission. | [Signature](https://api-docs.grvt.io/schemas/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.
Range: 0 to 4,294,967,295 (uint32) | | chain\_id
`ci` | string | True | Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID. | Query **Full Request** `{ "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }` **Lite Request** `{ "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }` [AckResponse](https://api-docs.grvt.io/schemas/ack_response) 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](https://api-docs.grvt.io/schemas/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 | | 7000 | 400 | Vault ID provided is invalid and does not belong to any vault | | 7001 | 400 | Vault does not have sufficient LP token balance | | 7002 | 400 | User has an ongoing redemption | 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://trades.dev.gravitymarkets.io/full/v1/vault_redeem' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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/vault_redeem", "params": { "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/vault_redeem' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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/vault_redeem", "p": { "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.staging.gravitymarkets.io/full/v1/vault_redeem' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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/vault_redeem", "params": { "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/vault_redeem' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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/vault_redeem", "p": { "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.testnet.grvt.io/full/v1/vault_redeem' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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/vault_redeem", "params": { "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.testnet.grvt.io/lite/v1/vault_redeem' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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/vault_redeem", "p": { "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.grvt.io/full/v1/vault_redeem' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } } '` 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/vault_redeem", "params": { "vault_id": "3477045127917224", "currency": "USDT", "num_tokens": 1000000, "signature": { "signer": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "expiration": "1697788800000000000", "nonce": 1234567890, "chain_id": "325" } }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.grvt.io/lite/v1/vault_redeem' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } } '` 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/vault_redeem", "p": { "vi": "3477045127917224", "c": "USDT", "nt": 1000000, "s": { "s": "0xc73c0c2538fd9b833d20933ccc88fdaa74fcb0d0", "r": "0xb788d96fee91c7cdc35918e0441b756d4000ec1d07d900c73347d9abbc20acc8", "s1": "0x3d786193125f7c29c958647da64d0e2875ece2c3f845a591bdd7dae8c475e26d", "v": 28, "e": "1697788800000000000", "n": 1234567890, "ci": "325" } }, "i": 123 } ' -w 360` * * * ### Vault Redeem Cancel `FULL ENDPOINT: full/v1/vault_redeem_cancel LITE ENDPOINT: lite/v1/vault_redeem_cancel` RequestResponseErrorsTry it out [ApiVaultRedeemCancelRequest](https://api-docs.grvt.io/schemas/api_vault_redeem_cancel_request) Request payload for canceling a vault redemption. This API allows a client to cancel a previously initiated redemption from a vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_id
`vi` | string | True | The unique identifier of the vault to cancel the redemption from. | Query **Full Request** `{ "vault_id": "3477045127917224" }` **Lite Request** `{ "vi": "3477045127917224" }` [AckResponse](https://api-docs.grvt.io/schemas/ack_response) 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](https://api-docs.grvt.io/schemas/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 | | 7000 | 400 | Vault ID provided is invalid and does not belong to any vault | 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://trades.dev.gravitymarkets.io/full/v1/vault_redeem_cancel' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224" } '` 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/vault_redeem_cancel", "params": { "vault_id": "3477045127917224" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/vault_redeem_cancel' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224" } '` 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/vault_redeem_cancel", "p": { "vi": "3477045127917224" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.staging.gravitymarkets.io/full/v1/vault_redeem_cancel' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224" } '` 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/vault_redeem_cancel", "params": { "vault_id": "3477045127917224" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/vault_redeem_cancel' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224" } '` 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/vault_redeem_cancel", "p": { "vi": "3477045127917224" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.testnet.grvt.io/full/v1/vault_redeem_cancel' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224" } '` 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/vault_redeem_cancel", "params": { "vault_id": "3477045127917224" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.testnet.grvt.io/lite/v1/vault_redeem_cancel' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224" } '` 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/vault_redeem_cancel", "p": { "vi": "3477045127917224" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.grvt.io/full/v1/vault_redeem_cancel' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224" } '` 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/vault_redeem_cancel", "params": { "vault_id": "3477045127917224" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.grvt.io/lite/v1/vault_redeem_cancel' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224" } '` 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/vault_redeem_cancel", "p": { "vi": "3477045127917224" }, "i": 123 } ' -w 360` * * * ### Vault Redemption Queue `FULL ENDPOINT: full/v1/vault_view_redemption_queue LITE ENDPOINT: lite/v1/vault_view_redemption_queue` RequestResponseErrorsTry it out [ApiVaultViewRedemptionQueueRequest](https://api-docs.grvt.io/schemas/api_vault_view_redemption_queue_request) Request payload for a vault manager to view the redemption queue for their vault. Fetches the redemption queue for a vault, ordered by descending priority. **Urgent** redemption requests, defined as having been pending >90% of the manager-defined maximum redemption period, have top priority (following insertion order). **Non-urgent** redemption requests are otherwise prioritized by insertion order, **unless** they are >5x the size of the smallest redemption request. E.g., If FIFO ordering (all non-urgent) is 1k -> 50k -> 100k -> 20k -> 10k -> 25k, then priority ordering is 1k -> 10k -> 50k -> 20k -> 100k -> 25k. Only displays redemption requests that are eligible for automated redemption, i.e., have been pending for the manager-defined minimum redemption period. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_id
`vi` | string | True | The unique identifier of the vault to fetch the redemption queue for. | Query **Full Request** `{ "vault_id": "3477045127917224" }` **Lite Request** `{ "vi": "3477045127917224" }` [ApiVaultViewRedemptionQueueResponse](https://api-docs.grvt.io/schemas/api_vault_view_redemption_queue_response) Response payload for a vault manager to view the redemption queue for their vault, ordered by descending priority. Also includes counters for total redemption sizes pending as well as urgent (refer to API integration guide for more detail on redemption request classifications). | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | redemption\_queue
`rq` | \[VaultRedemptionRequest\] | True | Outstanding vault redemption requests, ordered by descending priority. Excludes requests that have not yet aged past the minimum redemption period. | | pending\_redemption\_token\_count
`pr` | string | True | Number of shares eligible for automated redemption (held in queue for at least the minimum redemption period). | | urgent\_redemption\_token\_count
`ur` | string | True | Number of shares nearing the maximum redemption period (>= 90% of maximum redemption period). | | auto\_redeemable\_balance
`ar` | string | True | Amount available for automated redemption request servicing (in USD). | | share\_price
`sp` | string | True | Current share price (in USD). | | pre\_min
`pm` | PreMinRedemptions | True | Dedicated section for requests yet to wait at least the minimum redemption period. | [VaultRedemptionRequest](https://api-docs.grvt.io/schemas/vault_redemption_request) Representation of a pending redemption request for a given vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_time
`rt` | string | True | \[Filled by GRVT Backend\] Time at which the redemption request was received by GRVT in unix nanoseconds | | num\_lp\_tokens
`nl` | string | True | The number of shares to redeem | | max\_redemption\_period\_timestamp
`mr` | string | True | \[Filled by GRVT Backend\] Time in unix nanoseconds, beyond which the request will be force-redeemed. | | age\_category
`ac` | VaultRedemptionReqAgeCategory | True | Age category of this redemption request. | | is\_manager
`im` | boolean | False
`None` | `true` if this request belongs to the vault manager, omitted otherwise. | | eligible\_for\_auto\_redemption\_timestamp
`ef` | string | True | \[Filled by GRVT Backend\] Time in unix nanoseconds, beyond which the request will be eligible for automated redemption. | [VaultRedemptionReqAgeCategory](https://api-docs.grvt.io/schemas/vault_redemption_req_age_category) Denotes the age category of a given redemption request. | Value | Description | | --- | --- | | `NORMAL` = 1 | This request is at least as old as the minimum redemption period, and is eligible for automated redemption. | | `URGENT` = 2 | This request is nearing the maxmimum redemption period and will be factored into pre-order check margin requirements. | | `OVERDUE` = 3 | This request has exceeded the maximum redemption period and will be considered for forced redemptions. | | `PRE_MIN` = 4 | This request has yet to exceed the minimum redemption period, and is not yet eligible for automated redemption. | [PreMinRedemptions](https://api-docs.grvt.io/schemas/pre_min_redemptions) Vault redemption queue section hidden from main view. All requests here have yet to age past the vault's minimum redemption period. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | requests
`r` | \[VaultRedemptionRequest\] | True | Pre-minimum-age redemption requests, ordered by age (first element is the oldest request that is pre-minimum-age). | | token\_count
`tc` | string | True | Number of shares in the pre-minimum-age section of the vault's redemption queue. | [VaultRedemptionRequest](https://api-docs.grvt.io/schemas/vault_redemption_request) Representation of a pending redemption request for a given vault. | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | request\_time
`rt` | string | True | \[Filled by GRVT Backend\] Time at which the redemption request was received by GRVT in unix nanoseconds | | num\_lp\_tokens
`nl` | string | True | The number of shares to redeem | | max\_redemption\_period\_timestamp
`mr` | string | True | \[Filled by GRVT Backend\] Time in unix nanoseconds, beyond which the request will be force-redeemed. | | age\_category
`ac` | VaultRedemptionReqAgeCategory | True | Age category of this redemption request. | | is\_manager
`im` | boolean | False
`None` | `true` if this request belongs to the vault manager, omitted otherwise. | | eligible\_for\_auto\_redemption\_timestamp
`ef` | string | True | \[Filled by GRVT Backend\] Time in unix nanoseconds, beyond which the request will be eligible for automated redemption. | [VaultRedemptionReqAgeCategory](https://api-docs.grvt.io/schemas/vault_redemption_req_age_category) Denotes the age category of a given redemption request. | Value | Description | | --- | --- | | `NORMAL` = 1 | This request is at least as old as the minimum redemption period, and is eligible for automated redemption. | | `URGENT` = 2 | This request is nearing the maxmimum redemption period and will be factored into pre-order check margin requirements. | | `OVERDUE` = 3 | This request has exceeded the maximum redemption period and will be considered for forced redemptions. | | `PRE_MIN` = 4 | This request has yet to exceed the minimum redemption period, and is not yet eligible for automated redemption. | Success **Full Response** `{ "redemption_queue": [{ "request_time": "1697788800000000000", "num_lp_tokens": "1000000", "max_redemption_period_timestamp": "1727788800000000000", "age_category": "NORMAL", "is_manager": true, "eligible_for_auto_redemption_timestamp": "1727788800000000000" }], "pending_redemption_token_count": "1000000", "urgent_redemption_token_count": "0", "auto_redeemable_balance": "0", "share_price": "1.25", "pre_min": { "requests": [{ "request_time": "1697788800000000000", "num_lp_tokens": "1000000", "max_redemption_period_timestamp": "1727788800000000000", "age_category": "NORMAL", "is_manager": true, "eligible_for_auto_redemption_timestamp": "1727788800000000000" }], "token_count": "1000000" } }` **Lite Response** `{ "rq": [{ "rt": "1697788800000000000", "nl": "1000000", "mr": "1727788800000000000", "ac": "NORMAL", "im": true, "ef": "1727788800000000000" }], "pr": "1000000", "ur": "0", "ar": "0", "sp": "1.25", "pm": { "r": [{ "rt": "1697788800000000000", "nl": "1000000", "mr": "1727788800000000000", "ac": "NORMAL", "im": true, "ef": "1727788800000000000" }], "tc": "1000000" } }` 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 | | 7000 | 400 | Vault ID provided is invalid and does not belong to any vault | 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://trades.dev.gravitymarkets.io/full/v1/vault_view_redemption_queue' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224" } '` 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/vault_view_redemption_queue", "params": { "vault_id": "3477045127917224" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/vault_view_redemption_queue' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224" } '` 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/vault_view_redemption_queue", "p": { "vi": "3477045127917224" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.staging.gravitymarkets.io/full/v1/vault_view_redemption_queue' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224" } '` 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/vault_view_redemption_queue", "params": { "vault_id": "3477045127917224" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/vault_view_redemption_queue' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224" } '` 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/vault_view_redemption_queue", "p": { "vi": "3477045127917224" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.testnet.grvt.io/full/v1/vault_view_redemption_queue' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224" } '` 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/vault_view_redemption_queue", "params": { "vault_id": "3477045127917224" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.testnet.grvt.io/lite/v1/vault_view_redemption_queue' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224" } '` 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/vault_view_redemption_queue", "p": { "vi": "3477045127917224" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.grvt.io/full/v1/vault_view_redemption_queue' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "3477045127917224" } '` 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/vault_view_redemption_queue", "params": { "vault_id": "3477045127917224" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.grvt.io/lite/v1/vault_view_redemption_queue' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "3477045127917224" } '` 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/vault_view_redemption_queue", "p": { "vi": "3477045127917224" }, "i": 123 } ' -w 360` * * * ### Vault Manager Investment History `FULL ENDPOINT: full/v1/vault_manager_investor_history LITE ENDPOINT: lite/v1/vault_manager_investor_history` RequestResponseErrorsTry it out [ApiQueryVaultManagerInvestorHistoryRequest](https://api-docs.grvt.io/schemas/api_query_vault_manager_investor_history_request) Request for the manager to retrieve the vault investor history for their vault | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | vault\_id
`vi` | string | True | The unique identifier of the vault to filter by | | only\_own\_investments
`oo` | boolean | True | Whether to only return investments made by the manager | | start\_time
`st` | string | False
`0` | Optional. Start time in unix nanoseconds | | end\_time
`et` | string | False
`now()` | Optional. End time in unix nanoseconds | Query **Full Request** `{ "vault_id": "2312134", "only_own_investments": true, "start_time": "1697788800000000000", "end_time": "1697788800000000000" }` **Lite Request** `{ "vi": "2312134", "oo": true, "st": "1697788800000000000", "et": "1697788800000000000" }` [ApiQueryVaultManagerInvestorHistoryResponse](https://api-docs.grvt.io/schemas/api_query_vault_manager_investor_history_response) Response to retrieve the vault summary for a given vault | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[ApiVaultInvestorHistory\] | True | The list of vault investor history belong to the manager | [ApiVaultInvestorHistory](https://api-docs.grvt.io/schemas/api_vault_investor_history) The vault investor history returned by the service to client | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | True | Time at which the event was emitted in unix nanoseconds | | off\_chain\_account\_id
`oc` | string | True | The off chain account id of the investor, only visible to the manager | | vault\_id
`vi` | string | True | The unique identifier of the vault. | | type
`t` | VaultInvestorAction | True | The type of transaction that occurred. List of types: vaultInvest, vaultBurnLpToken, vaultRedeem | | price
`p` | string | True | The price of the vault LP tokens at the time of the event. | | size
`s` | string | True | The amount of Vault LP tokens invested or redeemed. | | realized\_pnl
`rp` | string | True | The realized PnL of the vault. | | performance\_fee
`pf` | string | True | The performance fee of the vault. | [VaultInvestorAction](https://api-docs.grvt.io/schemas/vault_investor_action) | Value | Description | | --- | --- | | `UNSPECIFIED` = 0 | | | `VAULT_INVEST` = 1 | | | `VAULT_BURN_LP_TOKEN` = 2 | | | `VAULT_REDEEM` = 3 | | Success **Full Response** `{ "result": [{ "event_time": "1697788800000000000", "off_chain_account_id": "ACC:123456", "vault_id": "2312134", "type": "VAULT_INVEST", "price": "1000000", "size": "1000000", "realized_pnl": "1000000", "performance_fee": "1000000" }] }` **Lite Response** `{ "r": [{ "et": "1697788800000000000", "oc": "ACC:123456", "vi": "2312134", "t": "VAULT_INVEST", "p": "1000000", "s": "1000000", "rp": "1000000", "pf": "1000000" }] }` 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://trades.dev.gravitymarkets.io/full/v1/vault_manager_investor_history' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "2312134", "only_own_investments": true, "start_time": "1697788800000000000", "end_time": "1697788800000000000" } '` 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/vault_manager_investor_history", "params": { "vault_id": "2312134", "only_own_investments": true, "start_time": "1697788800000000000", "end_time": "1697788800000000000" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/vault_manager_investor_history' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "2312134", "oo": true, "st": "1697788800000000000", "et": "1697788800000000000" } '` 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/vault_manager_investor_history", "p": { "vi": "2312134", "oo": true, "st": "1697788800000000000", "et": "1697788800000000000" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.staging.gravitymarkets.io/full/v1/vault_manager_investor_history' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "2312134", "only_own_investments": true, "start_time": "1697788800000000000", "end_time": "1697788800000000000" } '` 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/vault_manager_investor_history", "params": { "vault_id": "2312134", "only_own_investments": true, "start_time": "1697788800000000000", "end_time": "1697788800000000000" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/vault_manager_investor_history' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "2312134", "oo": true, "st": "1697788800000000000", "et": "1697788800000000000" } '` 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/vault_manager_investor_history", "p": { "vi": "2312134", "oo": true, "st": "1697788800000000000", "et": "1697788800000000000" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.testnet.grvt.io/full/v1/vault_manager_investor_history' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "2312134", "only_own_investments": true, "start_time": "1697788800000000000", "end_time": "1697788800000000000" } '` 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/vault_manager_investor_history", "params": { "vault_id": "2312134", "only_own_investments": true, "start_time": "1697788800000000000", "end_time": "1697788800000000000" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.testnet.grvt.io/lite/v1/vault_manager_investor_history' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "2312134", "oo": true, "st": "1697788800000000000", "et": "1697788800000000000" } '` 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/vault_manager_investor_history", "p": { "vi": "2312134", "oo": true, "st": "1697788800000000000", "et": "1697788800000000000" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.grvt.io/full/v1/vault_manager_investor_history' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vault_id": "2312134", "only_own_investments": true, "start_time": "1697788800000000000", "end_time": "1697788800000000000" } '` 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/vault_manager_investor_history", "params": { "vault_id": "2312134", "only_own_investments": true, "start_time": "1697788800000000000", "end_time": "1697788800000000000" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.grvt.io/lite/v1/vault_manager_investor_history' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "vi": "2312134", "oo": true, "st": "1697788800000000000", "et": "1697788800000000000" } '` 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/vault_manager_investor_history", "p": { "vi": "2312134", "oo": true, "st": "1697788800000000000", "et": "1697788800000000000" }, "i": 123 } ' -w 360` * * * Builder ------- ### Get Authorized Builders `FULL ENDPOINT: full/v1/get_authorized_builders LITE ENDPOINT: lite/v1/get_authorized_builders` RequestResponseErrorsTry it out [EmptyRequest](https://api-docs.grvt.io/schemas/empty_request) Used for requests that do not require any parameters | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | | | | | Query **Full Request** `{ }` **Lite Request** `{ }` [ApiGetAuthorizedBuildersResponse](https://api-docs.grvt.io/schemas/api_get_authorized_builders_response) Returns list of authorized builders and the associated fee | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | results
`r` | \[ApiAuthorizedBuilder\] | True | The list of authorized builders | [ApiAuthorizedBuilder](https://api-docs.grvt.io/schemas/api_authorized_builder) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | builder\_account\_id
`ba` | string | True | The main account ID of the builder | | max\_futures\_fee\_rate
`mf` | string | True | The maximum fee rate for the authorized builder | | max\_spot\_fee\_rate
`ms` | string | True | The maximum fee rate for the authorized builder | Success **Full Response** `{ "results": [{ "builder_account_id": "'$GRVT_MAIN_ACCOUNT_ID'", "max_futures_fee_rate": 0.001, "max_spot_fee_rate": 0.0001 }] }` **Lite Response** `{ "r": [{ "ba": "'$GRVT_MAIN_ACCOUNT_ID'", "mf": 0.001, "ms": 0.0001 }] }` 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://trades.dev.gravitymarkets.io/full/v1/get_authorized_builders' \ --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/get_authorized_builders", "params": { }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/get_authorized_builders' \ --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/get_authorized_builders", "p": { }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.staging.gravitymarkets.io/full/v1/get_authorized_builders' \ --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/get_authorized_builders", "params": { }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/get_authorized_builders' \ --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/get_authorized_builders", "p": { }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.testnet.grvt.io/full/v1/get_authorized_builders' \ --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/get_authorized_builders", "params": { }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.testnet.grvt.io/lite/v1/get_authorized_builders' \ --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/get_authorized_builders", "p": { }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.grvt.io/full/v1/get_authorized_builders' \ --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/get_authorized_builders", "params": { }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.grvt.io/lite/v1/get_authorized_builders' \ --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/get_authorized_builders", "p": { }, "i": 123 } ' -w 360` * * * Execution --------- ### Builder Fill History `FULL ENDPOINT: full/v1/builder_fill_history LITE ENDPOINT: lite/v1/builder_fill_history` RequestResponseErrorsTry it out [ApiBuilderFillHistoryRequest](https://api-docs.grvt.io/schemas/api_builder_fill_history_request) The request to get the historical builder trade of a builder 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 | | --- | --- | --- | --- | | 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
`c` | string | False
`''` | The cursor to indicate when to start the next query from | Query **Full Request** `{ "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" }` **Lite Request** `{ "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" }` [ApiBuilderFillHistoryResponse](https://api-docs.grvt.io/schemas/api_builder_fill_history_response) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | result
`r` | \[BuilderFillHistory\] | True | The builder fill history matching the request builder account | | next
`n` | string | False
`''` | The cursor to indicate when to start the next query from | [BuilderFillHistory](https://api-docs.grvt.io/schemas/builder_fill_history) | Name
`Lite` | Type | Required
`Default` | Description | | --- | --- | --- | --- | | event\_time
`et` | string | True | Time at which the event was emitted in unix nanoseconds | | off\_chain\_account\_id
`oc` | string | True | The off chain account id | | 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 | | fee\_rate
`fr` | string | True | Builder fee percentage charged for this order. referred to Order.builder builderFee | | fee
`f` | string | True | The builder fee paid on the trade, expressed in quote asset decimal unit. referred to Trade.builderFee | Success **Full Response** `{ "result": [{ "event_time": "1697788800000000000", "off_chain_account_id": "ACC:123456", "instrument": "BTC_USDT_Perp", "is_buyer": true, "is_taker": true, "size": "0.30", "price": "65038.01", "mark_price": "65038.01", "index_price": "65038.01", "fee_rate": 0.001, "fee": null }], "next": "Qw0918=" }` **Lite Response** `{ "r": [{ "et": "1697788800000000000", "oc": "ACC:123456", "i": "BTC_USDT_Perp", "ib": true, "it": true, "s": "0.30", "p": "65038.01", "mp": "65038.01", "ip": "65038.01", "fr": 0.001, "f": 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="" GRVT_SUB_ACCOUNT_ID=""` 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"` DEVSTAGINGTESTNETPROD REST Full `curl --location 'https://trades.dev.gravitymarkets.io/full/v1/builder_fill_history' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "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/builder_fill_history", "params": { "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.dev.gravitymarkets.io/lite/v1/builder_fill_history' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "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/builder_fill_history", "p": { "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.staging.gravitymarkets.io/full/v1/builder_fill_history' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "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/builder_fill_history", "params": { "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.staging.gravitymarkets.io/lite/v1/builder_fill_history' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "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/builder_fill_history", "p": { "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.testnet.grvt.io/full/v1/builder_fill_history' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "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/builder_fill_history", "params": { "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.testnet.grvt.io/lite/v1/builder_fill_history' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "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/builder_fill_history", "p": { "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" }, "i": 123 } ' -w 360` REST Full `curl --location 'https://trades.grvt.io/full/v1/builder_fill_history' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "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/builder_fill_history", "params": { "start_time": "1697788800000000000", "end_time": "1697788800000000000", "limit": 500, "cursor": "" }, "id": 123 } ' -w 360` REST Lite `curl --location 'https://trades.grvt.io/lite/v1/builder_fill_history' \ --header "Cookie: $GRVT_COOKIE" \ --header "X-Grvt-Account-Id: $GRVT_ACCOUNT_ID" \ --data '{ "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/builder_fill_history", "p": { "st": "1697788800000000000", "et": "1697788800000000000", "l": 500, "c": "" }, "i": 123 } ' -w 360` * * * Back to top ---