Skip to content

[RFC] Update API docs and specs #80

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
namnguyen-grvt merged 1 commit into from
Jan 28, 2026
Merged

[RFC] Update API docs and specs #80

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 12 additions & 6 deletions artifacts/apidocs/market_data_api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,8 @@ LITE ENDPOINT: lite/v1/instrument
"max_position_size": "100.0",
"funding_interval_hours": null,
"adjusted_funding_rate_cap": 2.5,
"adjusted_funding_rate_floor": -2.5
"adjusted_funding_rate_floor": -2.5,
"min_notional": "20.0"
}
}
```
Expand All @@ -75,7 +76,8 @@ LITE ENDPOINT: lite/v1/instrument
"mp": "100.0",
"fi": null,
"af": 2.5,
"af1": -2.5
"af1": -2.5,
"mn": "20.0"
}
}
```
Expand Down Expand Up @@ -359,7 +361,8 @@ LITE ENDPOINT: lite/v1/all_instruments
"max_position_size": "100.0",
"funding_interval_hours": null,
"adjusted_funding_rate_cap": 2.5,
"adjusted_funding_rate_floor": -2.5
"adjusted_funding_rate_floor": -2.5,
"min_notional": "20.0"
}]
}
```
Expand All @@ -382,7 +385,8 @@ LITE ENDPOINT: lite/v1/all_instruments
"mp": "100.0",
"fi": null,
"af": 2.5,
"af1": -2.5
"af1": -2.5,
"mn": "20.0"
}]
}
```
Expand Down Expand Up @@ -673,7 +677,8 @@ LITE ENDPOINT: lite/v1/instruments
"max_position_size": "100.0",
"funding_interval_hours": null,
"adjusted_funding_rate_cap": 2.5,
"adjusted_funding_rate_floor": -2.5
"adjusted_funding_rate_floor": -2.5,
"min_notional": "20.0"
}]
}
```
Expand All @@ -696,7 +701,8 @@ LITE ENDPOINT: lite/v1/instruments
"mp": "100.0",
"fi": null,
"af": 2.5,
"af1": -2.5
"af1": -2.5,
"mn": "20.0"
}]
}
```
Expand Down
19 changes: 19 additions & 0 deletions artifacts/apidocs/schemas/api_add_isolated_position_margin_request.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
!!! info "[ApiAddIsolatedPositionMarginRequest](/../../schemas/api_add_isolated_position_margin_request)"
The request to add margin to a isolated position<br>

|Name<br>`Lite`|Type|Required<br>`Default`| Description |
|-|-|-|-|
|sub_account_id<br>`sa` |string|True|The sub account ID to add isolated margin in or remove margin from|
|instrument<br>`i` |string|True|The instrument to add margin into, or remove margin from|
|amount<br>`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<br>`s` |Signature|True|The signature of this operation|
??? info "[Signature](/../../schemas/signature)"
|Name<br>`Lite`|Type|Required<br>`Default`| Description |
|-|-|-|-|
|signer<br>`s` |string|True|The address (public key) of the wallet signing the payload|
|r<br>`r` |string|True|Signature R|
|s<br>`s1` |string|True|Signature S|
|v<br>`v` |integer|True|Signature V|
|expiration<br>`e` |string|True|Timestamp after which this signature expires, expressed in unix nanoseconds. Must be capped at 30 days|
|nonce<br>`n` |integer|True|Users can randomly generate this value, used as a signature deconflicting key.<br>ie. You can send the same exact instruction twice with different nonces.<br>When the same nonce is used, the same payload will generate the same signature.<br>Our system will consider the payload a duplicate, and ignore it.<br>Range: 0 to 4,294,967,295 (uint32)|
|chain_id<br>`ci` |string|True|Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID.|
6 changes: 6 additions & 0 deletions artifacts/apidocs/schemas/api_add_isolated_position_margin_response.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
!!! info "[ApiAddIsolatedPositionMarginResponse](/../../schemas/api_add_isolated_position_margin_response)"
The response to add margin to a isolated position<br>

|Name<br>`Lite`|Type|Required<br>`Default`| Description |
|-|-|-|-|
|success<br>`s` |boolean|True|Whether the margin mode and leverage was set successfully|
6 changes: 6 additions & 0 deletions artifacts/apidocs/schemas/api_authorized_builder.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
!!! info "[ApiAuthorizedBuilder](/../../schemas/api_authorized_builder)"
|Name<br>`Lite`|Type|Required<br>`Default`| Description |
|-|-|-|-|
|builder_account_id<br>`ba` |string|True|The main account ID of the builder|
|max_futures_fee_rate<br>`mf` |string|True|The maximum fee rate for the authorized builder|
|max_spot_fee_rate<br>`ms` |string|True|The maximum fee rate for the authorized builder|
9 changes: 9 additions & 0 deletions artifacts/apidocs/schemas/api_builder_fill_history_request.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
!!! info "[ApiBuilderFillHistoryRequest](/../../schemas/api_builder_fill_history_request)"
The request to get the historical builder trade of a builder<br>The history is returned in reverse chronological order<br><br>Pagination works as follows:<ul><li>We perform a reverse chronological lookup, starting from `end_time`. If `end_time` is not set, we start from the most recent data.</li><li>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.</li><li>If a `cursor` is provided, it will be used to fetch results from that point onwards.</li><li>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.</li></ul><br>

|Name<br>`Lite`|Type|Required<br>`Default`| Description |
|-|-|-|-|
|start_time<br>`st` |string|False<br>`0`|The start time to query for in unix nanoseconds|
|end_time<br>`et` |string|False<br>`now()`|The end time to query for in unix nanoseconds|
|limit<br>`l` |integer|False<br>`500`|The limit to query for. Defaults to 500; Max 1000|
|cursor<br>`c` |string|False<br>`''`|The cursor to indicate when to start the next query from|
19 changes: 19 additions & 0 deletions artifacts/apidocs/schemas/api_builder_fill_history_response.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
!!! info "[ApiBuilderFillHistoryResponse](/../../schemas/api_builder_fill_history_response)"
|Name<br>`Lite`|Type|Required<br>`Default`| Description |
|-|-|-|-|
|result<br>`r` |[BuilderFillHistory]|True|The builder fill history matching the request builder account|
|next<br>`n` |string|False<br>`''`|The cursor to indicate when to start the next query from|
??? info "[BuilderFillHistory](/../../schemas/builder_fill_history)"
|Name<br>`Lite`|Type|Required<br>`Default`| Description |
|-|-|-|-|
|event_time<br>`et` |string|True|Time at which the event was emitted in unix nanoseconds|
|off_chain_account_id<br>`oc` |string|True|The off chain account id|
|instrument<br>`i` |string|True|The instrument being represented|
|is_buyer<br>`ib` |boolean|True|The side that the subaccount took on the trade|
|is_taker<br>`it` |boolean|True|The role that the subaccount took on the trade|
|size<br>`s` |string|True|The number of assets being traded, expressed in base asset decimal units|
|price<br>`p` |string|True|The traded price, expressed in `9` decimals|
|mark_price<br>`mp` |string|True|The mark price of the instrument at point of trade, expressed in `9` decimals|
|index_price<br>`ip` |string|True|The index price of the instrument at point of trade, expressed in `9` decimals|
|fee_rate<br>`fr` |string|True|Builder fee percentage charged for this order. referred to Order.builder builderFee |
|fee<br>`f` |string|True|The builder fee paid on the trade, expressed in quote asset decimal unit. referred to Trade.builderFee|
6 changes: 6 additions & 0 deletions artifacts/apidocs/schemas/api_create_order_request.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@
|signature<br>`s` |Signature|True|The signature approving this order|
|metadata<br>`m` |OrderMetadata|True|Order Metadata, ignored by the smart contract, and unsigned by the client|
|state<br>`s1` |OrderState|False<br>`''`|[Filled by GRVT Backend] The current state of the order, ignored by the smart contract, and unsigned by the client|
|builder<br>`b` |string|True|The main account ID of the builder|
|builder_fee<br>`bf` |string|True|Builder fee charged for this order |
??? info "[TimeInForce](/../../schemas/time_in_force)"
| | Must Fill All | Can Fill Partial |
| - | - | - |
Expand Down Expand Up @@ -160,3 +162,7 @@
|`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|
6 changes: 6 additions & 0 deletions artifacts/apidocs/schemas/api_create_order_response.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@
|signature<br>`s` |Signature|True|The signature approving this order|
|metadata<br>`m` |OrderMetadata|True|Order Metadata, ignored by the smart contract, and unsigned by the client|
|state<br>`s1` |OrderState|False<br>`''`|[Filled by GRVT Backend] The current state of the order, ignored by the smart contract, and unsigned by the client|
|builder<br>`b` |string|True|The main account ID of the builder|
|builder_fee<br>`bf` |string|True|Builder fee charged for this order |
??? info "[TimeInForce](/../../schemas/time_in_force)"
| | Must Fill All | Can Fill Partial |
| - | - | - |
Expand Down Expand Up @@ -158,3 +160,7 @@
|`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|
2 changes: 1 addition & 1 deletion artifacts/apidocs/schemas/api_deposit_history_request.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
!!! info "[ApiDepositHistoryRequest](/../../schemas/api_deposit_history_request)"
The request to get the historical deposits of an account<br>The history is returned in reverse chronological order<br><br>Pagination works as follows:<ul><li>We perform a reverse chronological lookup, starting from `end_time`. If `end_time` is not set, we start from the most recent data.</li><li>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.</li><li>If a `cursor` is provided, it will be used to fetch results from that point onwards.</li><li>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.</li></ul><br>
The request to get the historical deposits of an account<br>The history is returned in reverse chronological order<br>Both finalized and pending deposits are returned, and pending deposits are indicated by an empty `confirmedTime` field.<br><br>Pagination works as follows:<ul><li>We perform a reverse chronological lookup, starting from `end_time`. If `end_time` is not set, we start from the most recent data.</li><li>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.</li><li>If a `cursor` is provided, it will be used to fetch results from that point onwards.</li><li>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.</li></ul><br>

|Name<br>`Lite`|Type|Required<br>`Default`| Description |
|-|-|-|-|
Expand Down
2 changes: 1 addition & 1 deletion artifacts/apidocs/schemas/api_deposit_history_response.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,5 +12,5 @@
|currency<br>`c` |string|True|The token currency to deposit|
|num_tokens<br>`nt` |string|True|The number of tokens to deposit|
|initiated_time<br>`it` |string|True|The timestamp when the deposit was initiated on L1 in unix nanoseconds|
|confirmed_time<br>`ct` |string|True|The timestamp when the deposit was confirmed on L2 in unix nanoseconds|
|confirmed_time<br>`ct` |string|True|The timestamp when the deposit was confirmed on L2 in unix nanoseconds, empty if the deposit is pending.|
|from_address<br>`fa` |string|True|The address of the sender|
4 changes: 4 additions & 0 deletions artifacts/apidocs/schemas/api_fill_history_response.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,14 @@
|trade_id<br>`ti` |string|True|A trade identifier, globally unique, and monotonically increasing (not by `1`).<br>All trades sharing a single taker execution share the same first component (before `-`), and `event_time`.<br>`trade_id` is guaranteed to be consistent across MarketData `Trade` and Trading `Fill`.|
|order_id<br>`oi` |string|True|An order identifier|
|venue<br>`v` |Venue|True|The venue where the trade occurred|
|is_liquidation<br>`il` |boolean|True|If the trade was a liquidation|
|client_order_id<br>`co` |string|True|A unique identifier for the active order within a subaccount, specified by the client<br>This is used to identify the order in the client's system<br>This field can be used for order amendment/cancellation, but has no bearing on the smart contract layer<br>This field will not be propagated to the smart contract, and should not be signed by the client<br>This value must be unique for all active orders in a subaccount, or amendment/cancellation will not work as expected<br>Gravity UI will generate a random clientOrderID for each order in the range [0, 2^63 - 1]<br>To prevent any conflicts, client machines should generate a random clientOrderID in the range [2^63, 2^64 - 1]<br><br>When GRVT Backend receives an order with an overlapping clientOrderID, we will reject the order with rejectReason set to overlappingClientOrderId|
|signer<br>`s1` |string|True|The address (public key) of the wallet signing the payload|
|broker<br>`b` |BrokerTag|False<br>``|Specifies the broker who brokered the order|
|is_rpi<br>`ir1` |boolean|True|If the trade is a RPI trade|
|builder<br>`b1` |string|True|The main account ID of the builder. referred to Order.builder|
|builder_fee_rate<br>`bf` |string|True|Builder fee percentage charged for this order. referred to Order.builder builderFee |
|builder_fee<br>`bf1` |string|True|The builder fee paid on the trade, expressed in quote asset decimal unit. referred to Trade.builderFee|
??? info "[Venue](/../../schemas/venue)"
The list of Trading Venues that are supported on the GRVT exchange<br>

Expand Down
12 changes: 12 additions & 0 deletions artifacts/apidocs/schemas/api_funding_payment_history_request.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,15 @@
|end_time<br>`et` |string|False<br>`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<br>`l` |integer|False<br>`500`|The limit to query for. Defaults to 500; Max 1000|
|cursor<br>`c` |string|False<br>`''`|The cursor to indicate when to start the query from|
|kind<br>`k` |[Kind]|False<br>`all`|The kind filter to apply. If nil, this defaults to all kinds. Otherwise, only entries matching the filter will be returned|
|base<br>`b` |[string]|False<br>`all`|The base filter to apply. If nil, this defaults to all bases. Otherwise, only entries matching the filter will be returned|
|quote<br>`q` |[string]|False<br>`all`|The quote filter to apply. If nil, this defaults to all quotes. Otherwise, only entries matching the filter will be returned|
??? info "[Kind](/../../schemas/kind)"
The list of asset kinds that are supported on the GRVT exchange<br>

|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|
12 changes: 9 additions & 3 deletions artifacts/apidocs/schemas/api_get_all_initial_leverage_response.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,12 @@
|Name<br>`Lite`|Type|Required<br>`Default`| Description |
|-|-|-|-|
|instrument<br>`i` |string|True|The instrument to get the leverage for|
|leverage<br>`l` |string|True|The initial leverage of the sub account|
|min_leverage<br>`ml` |string|True|The min leverage this sub account can set|
|max_leverage<br>`ml1` |string|True|The max leverage this sub account can set|
|leverage<br>`l` |string|True|The initial leverage of this instrument|
|min_leverage<br>`ml` |string|True|The min leverage user can set for this instrument|
|max_leverage<br>`ml1` |string|True|The max leverage user can set for this instrument|
|margin_type<br>`mt` |PositionMarginType|True|The margin type of this instrument|
??? info "[PositionMarginType](/../../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|
1 change: 1 addition & 0 deletions artifacts/apidocs/schemas/api_get_all_instruments_response.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
|funding_interval_hours<br>`fi` |integer|False<br>`None`|Defines the funding interval to be applied.|
|adjusted_funding_rate_cap<br>`af` |string|False<br>`None`|Funding rate cap over the defined `intervalHours`.|
|adjusted_funding_rate_floor<br>`af1` |string|False<br>`None`|Funding rate floor over the defined `intervalHours`.|
|min_notional<br>`mn` |string|True|The minimum order notional value, expressed in quote currency decimal units|
??? info "[Kind](/../../schemas/kind)"
The list of asset kinds that are supported on the GRVT exchange<br>

Expand Down
12 changes: 12 additions & 0 deletions artifacts/apidocs/schemas/api_get_authorized_builders_response.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
!!! info "[ApiGetAuthorizedBuildersResponse](/../../schemas/api_get_authorized_builders_response)"
Returns list of authorized builders and the associated fee<br>

|Name<br>`Lite`|Type|Required<br>`Default`| Description |
|-|-|-|-|
|results<br>`r` |[ApiAuthorizedBuilder]|True|The list of authorized builders|
??? info "[ApiAuthorizedBuilder](/../../schemas/api_authorized_builder)"
|Name<br>`Lite`|Type|Required<br>`Default`| Description |
|-|-|-|-|
|builder_account_id<br>`ba` |string|True|The main account ID of the builder|
|max_futures_fee_rate<br>`mf` |string|True|The maximum fee rate for the authorized builder|
|max_spot_fee_rate<br>`ms` |string|True|The maximum fee rate for the authorized builder|
1 change: 1 addition & 0 deletions artifacts/apidocs/schemas/api_get_filtered_instruments_response.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
|funding_interval_hours<br>`fi` |integer|False<br>`None`|Defines the funding interval to be applied.|
|adjusted_funding_rate_cap<br>`af` |string|False<br>`None`|Funding rate cap over the defined `intervalHours`.|
|adjusted_funding_rate_floor<br>`af1` |string|False<br>`None`|Funding rate floor over the defined `intervalHours`.|
|min_notional<br>`mn` |string|True|The minimum order notional value, expressed in quote currency decimal units|
??? info "[Kind](/../../schemas/kind)"
The list of asset kinds that are supported on the GRVT exchange<br>

Expand Down
1 change: 1 addition & 0 deletions artifacts/apidocs/schemas/api_get_instrument_response.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
|funding_interval_hours<br>`fi` |integer|False<br>`None`|Defines the funding interval to be applied.|
|adjusted_funding_rate_cap<br>`af` |string|False<br>`None`|Funding rate cap over the defined `intervalHours`.|
|adjusted_funding_rate_floor<br>`af1` |string|False<br>`None`|Funding rate floor over the defined `intervalHours`.|
|min_notional<br>`mn` |string|True|The minimum order notional value, expressed in quote currency decimal units|
??? info "[Kind](/../../schemas/kind)"
The list of asset kinds that are supported on the GRVT exchange<br>

Expand Down
7 changes: 7 additions & 0 deletions artifacts/apidocs/schemas/api_get_isolated_position_margin_limits_request.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
!!! info "[ApiGetIsolatedPositionMarginLimitsRequest](/../../schemas/api_get_isolated_position_margin_limits_request)"
The request to get the max addable and removable amount for an isolated position<br>

|Name<br>`Lite`|Type|Required<br>`Default`| Description |
|-|-|-|-|
|sub_account_id<br>`sa` |string|True|The sub account ID to get the margin limits for|
|instrument<br>`i` |string|True|The isolated position asset to get the margin limits for|
Loading
Loading