Skip to content

[RFC] Update API docs and specs #75

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
Keithagy merged 1 commit into from
Nov 10, 2025
Merged

[RFC] Update API docs and specs #75

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
60 changes: 40 additions & 20 deletions artifacts/apidocs/market_data_api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3317,7 +3317,8 @@ LITE ENDPOINT: lite/v1/funding
"start_time": "1697788800000000000",
"end_time": "1697788800000000000",
"limit": 500,
"cursor": ""
"cursor": "",
"agg_type": "FUNDING_INTERVAL"
}
```
**Lite Request**
Expand All @@ -3327,7 +3328,8 @@ LITE ENDPOINT: lite/v1/funding
"st": "1697788800000000000",
"et": "1697788800000000000",
"l": 500,
"c": ""
"c": "",
"at": "FUNDING_INTERVAL"
}
```
</section>
Expand All @@ -3345,7 +3347,8 @@ LITE ENDPOINT: lite/v1/funding
"funding_rate": 0.0003,
"funding_time": "1697788800000000000",
"mark_price": "65038.01",
"funding_rate_8_h_avg": 0.0003
"funding_rate_8_h_avg": 0.0003,
"funding_interval_hours": 8
}],
"next": "Qw0918="
}
Expand All @@ -3358,7 +3361,8 @@ LITE ENDPOINT: lite/v1/funding
"fr": 0.0003,
"ft": "1697788800000000000",
"mp": "65038.01",
"fr1": 0.0003
"fr1": 0.0003,
"fi": 8
}],
"n": "Qw0918="
}
Expand Down Expand Up @@ -3405,7 +3409,8 @@ LITE ENDPOINT: lite/v1/funding
"start_time": "1697788800000000000",
"end_time": "1697788800000000000",
"limit": 500,
"cursor": ""
"cursor": "",
"agg_type": "FUNDING_INTERVAL"
}
'
```
Expand All @@ -3421,7 +3426,8 @@ LITE ENDPOINT: lite/v1/funding
"start_time": "1697788800000000000",
"end_time": "1697788800000000000",
"limit": 500,
"cursor": ""
"cursor": "",
"agg_type": "FUNDING_INTERVAL"
},
"id": 123
}
Expand All @@ -3437,7 +3443,8 @@ LITE ENDPOINT: lite/v1/funding
"st": "1697788800000000000",
"et": "1697788800000000000",
"l": 500,
"c": ""
"c": "",
"at": "FUNDING_INTERVAL"
}
'
```
Expand All @@ -3453,7 +3460,8 @@ LITE ENDPOINT: lite/v1/funding
"st": "1697788800000000000",
"et": "1697788800000000000",
"l": 500,
"c": ""
"c": "",
"at": "FUNDING_INTERVAL"
},
"i": 123
}
Expand All @@ -3470,7 +3478,8 @@ LITE ENDPOINT: lite/v1/funding
"start_time": "1697788800000000000",
"end_time": "1697788800000000000",
"limit": 500,
"cursor": ""
"cursor": "",
"agg_type": "FUNDING_INTERVAL"
}
'
```
Expand All @@ -3486,7 +3495,8 @@ LITE ENDPOINT: lite/v1/funding
"start_time": "1697788800000000000",
"end_time": "1697788800000000000",
"limit": 500,
"cursor": ""
"cursor": "",
"agg_type": "FUNDING_INTERVAL"
},
"id": 123
}
Expand All @@ -3502,7 +3512,8 @@ LITE ENDPOINT: lite/v1/funding
"st": "1697788800000000000",
"et": "1697788800000000000",
"l": 500,
"c": ""
"c": "",
"at": "FUNDING_INTERVAL"
}
'
```
Expand All @@ -3518,7 +3529,8 @@ LITE ENDPOINT: lite/v1/funding
"st": "1697788800000000000",
"et": "1697788800000000000",
"l": 500,
"c": ""
"c": "",
"at": "FUNDING_INTERVAL"
},
"i": 123
}
Expand All @@ -3535,7 +3547,8 @@ LITE ENDPOINT: lite/v1/funding
"start_time": "1697788800000000000",
"end_time": "1697788800000000000",
"limit": 500,
"cursor": ""
"cursor": "",
"agg_type": "FUNDING_INTERVAL"
}
'
```
Expand All @@ -3551,7 +3564,8 @@ LITE ENDPOINT: lite/v1/funding
"start_time": "1697788800000000000",
"end_time": "1697788800000000000",
"limit": 500,
"cursor": ""
"cursor": "",
"agg_type": "FUNDING_INTERVAL"
},
"id": 123
}
Expand All @@ -3567,7 +3581,8 @@ LITE ENDPOINT: lite/v1/funding
"st": "1697788800000000000",
"et": "1697788800000000000",
"l": 500,
"c": ""
"c": "",
"at": "FUNDING_INTERVAL"
}
'
```
Expand All @@ -3583,7 +3598,8 @@ LITE ENDPOINT: lite/v1/funding
"st": "1697788800000000000",
"et": "1697788800000000000",
"l": 500,
"c": ""
"c": "",
"at": "FUNDING_INTERVAL"
},
"i": 123
}
Expand All @@ -3600,7 +3616,8 @@ LITE ENDPOINT: lite/v1/funding
"start_time": "1697788800000000000",
"end_time": "1697788800000000000",
"limit": 500,
"cursor": ""
"cursor": "",
"agg_type": "FUNDING_INTERVAL"
}
'
```
Expand All @@ -3616,7 +3633,8 @@ LITE ENDPOINT: lite/v1/funding
"start_time": "1697788800000000000",
"end_time": "1697788800000000000",
"limit": 500,
"cursor": ""
"cursor": "",
"agg_type": "FUNDING_INTERVAL"
},
"id": 123
}
Expand All @@ -3632,7 +3650,8 @@ LITE ENDPOINT: lite/v1/funding
"st": "1697788800000000000",
"et": "1697788800000000000",
"l": 500,
"c": ""
"c": "",
"at": "FUNDING_INTERVAL"
}
'
```
Expand All @@ -3648,7 +3667,8 @@ LITE ENDPOINT: lite/v1/funding
"st": "1697788800000000000",
"et": "1697788800000000000",
"l": 500,
"c": ""
"c": "",
"at": "FUNDING_INTERVAL"
},
"i": 123
}
Expand Down
1 change: 0 additions & 1 deletion 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 @@ -59,7 +59,6 @@
|create_time<br>`ct` |string|False<br>`0`|[Filled by GRVT Backend] Time at which the order was received by GRVT in unix nanoseconds|
|trigger<br>`t` |TriggerOrderMetadata|False<br>``|Trigger fields are used to support any type of trigger order such as TP/SL|
|broker<br>`b` |BrokerTag|False<br>``|Specifies the broker who brokered the order|
|allow_crossing<br>`ac` |boolean|False<br>`false`|Specifies if post only order is allowed to cross the orderbook|
??? info "[TriggerOrderMetadata](/../../schemas/trigger_order_metadata)"
Contains metadata related to trigger orders, such as Take Profit (TP) or Stop Loss (SL).<br><br>Trigger orders are used to automatically execute an order when a predefined price condition is met, allowing traders to implement risk management strategies.<br><br><br>

Expand Down
1 change: 0 additions & 1 deletion 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 @@ -57,7 +57,6 @@
|create_time<br>`ct` |string|False<br>`0`|[Filled by GRVT Backend] Time at which the order was received by GRVT in unix nanoseconds|
|trigger<br>`t` |TriggerOrderMetadata|False<br>``|Trigger fields are used to support any type of trigger order such as TP/SL|
|broker<br>`b` |BrokerTag|False<br>``|Specifies the broker who brokered the order|
|allow_crossing<br>`ac` |boolean|False<br>`false`|Specifies if post only order is allowed to cross the orderbook|
??? info "[TriggerOrderMetadata](/../../schemas/trigger_order_metadata)"
Contains metadata related to trigger orders, such as Take Profit (TP) or Stop Loss (SL).<br><br>Trigger orders are used to automatically execute an order when a predefined price condition is met, allowing traders to implement risk management strategies.<br><br><br>

Expand Down
9 changes: 9 additions & 0 deletions artifacts/apidocs/schemas/api_funding_rate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
!!! info "[ApiFundingRate](/../../schemas/api_funding_rate)"
|Name<br>`Lite`|Type|Required<br>`Default`| Description |
|-|-|-|-|
|instrument<br>`i` |string|True|The readable instrument name:<ul><li>Perpetual: `ETH_USDT_Perp`</li><li>Future: `BTC_USDT_Fut_20Oct23`</li><li>Call: `ETH_USDT_Call_20Oct23_2800`</li><li>Put: `ETH_USDT_Put_20Oct23_2800`</li></ul>|
|funding_rate<br>`fr` |string|True|The funding rate of the instrument, expressed in percentage points|
|funding_time<br>`ft` |string|True|The funding timestamp of the funding rate, expressed in unix nanoseconds|
|mark_price<br>`mp` |string|True|The mark price of the instrument at funding timestamp, expressed in `9` decimals|
|funding_rate_8_h_avg<br>`fr1` |string|True|Deprecated: Refer to `funding_rate` instead. Will be removed in a future release.|
|funding_interval_hours<br>`fi` |integer|True|Funding interval in hours (e.g. 1/4/8/etc).|
10 changes: 10 additions & 0 deletions artifacts/apidocs/schemas/api_funding_rate_request.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,13 @@
|end_time<br>`et` |string|False<br>`now()`|End time of funding rate 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 query from|
|agg_type<br>`at` |FundingRateAggregationType|False<br>`'FUNDING_INTERVAL'`|Aggregation method for historical funding rate observations. Defaults to using the instrument-specific funding interval.|
??? info "[FundingRateAggregationType](/../../schemas/funding_rate_aggregation_type)"
Specifies different methods of aggregating historical funding rates<br>

|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.|
7 changes: 4 additions & 3 deletions artifacts/apidocs/schemas/api_funding_rate_response.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
!!! info "[ApiFundingRateResponse](/../../schemas/api_funding_rate_response)"
|Name<br>`Lite`|Type|Required<br>`Default`| Description |
|-|-|-|-|
|result<br>`r` |[FundingRate]|True|The funding rate result set for given interval|
|result<br>`r` |[ApiFundingRate]|True|The funding rate result set for given interval|
|next<br>`n` |string|False<br>`''`|The cursor to indicate when to start the next query from|
??? info "[FundingRate](/../../schemas/funding_rate)"
??? info "[ApiFundingRate](/../../schemas/api_funding_rate)"
|Name<br>`Lite`|Type|Required<br>`Default`| Description |
|-|-|-|-|
|instrument<br>`i` |string|True|The readable instrument name:<ul><li>Perpetual: `ETH_USDT_Perp`</li><li>Future: `BTC_USDT_Fut_20Oct23`</li><li>Call: `ETH_USDT_Call_20Oct23_2800`</li><li>Put: `ETH_USDT_Put_20Oct23_2800`</li></ul>|
|funding_rate<br>`fr` |string|True|The funding rate of the instrument, expressed in percentage points|
|funding_time<br>`ft` |string|True|The funding timestamp of the funding rate, expressed in unix nanoseconds|
|mark_price<br>`mp` |string|True|The mark price of the instrument at funding timestamp, expressed in `9` decimals|
|funding_rate_8_h_avg<br>`fr1` |string|True|The 8h average funding rate of the instrument, expressed in percentage points|
|funding_rate_8_h_avg<br>`fr1` |string|True|Deprecated: Refer to `funding_rate` instead. Will be removed in a future release.|
|funding_interval_hours<br>`fi` |integer|True|Funding interval in hours (e.g. 1/4/8/etc).|
1 change: 0 additions & 1 deletion artifacts/apidocs/schemas/api_get_order_response.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,6 @@
|create_time<br>`ct` |string|False<br>`0`|[Filled by GRVT Backend] Time at which the order was received by GRVT in unix nanoseconds|
|trigger<br>`t` |TriggerOrderMetadata|False<br>``|Trigger fields are used to support any type of trigger order such as TP/SL|
|broker<br>`b` |BrokerTag|False<br>``|Specifies the broker who brokered the order|
|allow_crossing<br>`ac` |boolean|False<br>`false`|Specifies if post only order is allowed to cross the orderbook|
??? info "[TriggerOrderMetadata](/../../schemas/trigger_order_metadata)"
Contains metadata related to trigger orders, such as Take Profit (TP) or Stop Loss (SL).<br><br>Trigger orders are used to automatically execute an order when a predefined price condition is met, allowing traders to implement risk management strategies.<br><br><br>

Expand Down
1 change: 0 additions & 1 deletion artifacts/apidocs/schemas/api_open_orders_response.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,6 @@
|create_time<br>`ct` |string|False<br>`0`|[Filled by GRVT Backend] Time at which the order was received by GRVT in unix nanoseconds|
|trigger<br>`t` |TriggerOrderMetadata|False<br>``|Trigger fields are used to support any type of trigger order such as TP/SL|
|broker<br>`b` |BrokerTag|False<br>``|Specifies the broker who brokered the order|
|allow_crossing<br>`ac` |boolean|False<br>`false`|Specifies if post only order is allowed to cross the orderbook|
??? info "[TriggerOrderMetadata](/../../schemas/trigger_order_metadata)"
Contains metadata related to trigger orders, such as Take Profit (TP) or Stop Loss (SL).<br><br>Trigger orders are used to automatically execute an order when a predefined price condition is met, allowing traders to implement risk management strategies.<br><br><br>

Expand Down
1 change: 0 additions & 1 deletion artifacts/apidocs/schemas/api_order_history_response.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,6 @@
|create_time<br>`ct` |string|False<br>`0`|[Filled by GRVT Backend] Time at which the order was received by GRVT in unix nanoseconds|
|trigger<br>`t` |TriggerOrderMetadata|False<br>``|Trigger fields are used to support any type of trigger order such as TP/SL|
|broker<br>`b` |BrokerTag|False<br>``|Specifies the broker who brokered the order|
|allow_crossing<br>`ac` |boolean|False<br>`false`|Specifies if post only order is allowed to cross the orderbook|
??? info "[TriggerOrderMetadata](/../../schemas/trigger_order_metadata)"
Contains metadata related to trigger orders, such as Take Profit (TP) or Stop Loss (SL).<br><br>Trigger orders are used to automatically execute an order when a predefined price condition is met, allowing traders to implement risk management strategies.<br><br><br>

Expand Down
2 changes: 1 addition & 1 deletion artifacts/apidocs/schemas/api_positions_response.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,4 +21,4 @@
|est_liquidation_price<br>`el` |string|True|The estimated liquidation price|
|leverage<br>`l` |string|True|The current leverage value for this position|
|cumulative_fee<br>`cf` |string|True|The cumulative fee paid on the position, expressed in quote asset decimal units|
|cumulative_realized_funding_payment<br>`cr` |string|True|The cumulative realized funding payment of the position, expressed in quote asset decimal units|
|cumulative_realized_funding_payment<br>`cr` |string|True|The cumulative realized funding payment of the position, expressed in quote asset decimal units. Positive if paid, negative if received|
2 changes: 1 addition & 1 deletion artifacts/apidocs/schemas/api_sub_account_history_response.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,4 +52,4 @@
|est_liquidation_price<br>`el` |string|True|The estimated liquidation price|
|leverage<br>`l` |string|True|The current leverage value for this position|
|cumulative_fee<br>`cf` |string|True|The cumulative fee paid on the position, expressed in quote asset decimal units|
|cumulative_realized_funding_payment<br>`cr` |string|True|The cumulative realized funding payment of the position, expressed in quote asset decimal units|
|cumulative_realized_funding_payment<br>`cr` |string|True|The cumulative realized funding payment of the position, expressed in quote asset decimal units. Positive if paid, negative if received|
2 changes: 1 addition & 1 deletion artifacts/apidocs/schemas/api_sub_account_summary_response.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,4 +53,4 @@
|est_liquidation_price<br>`el` |string|True|The estimated liquidation price|
|leverage<br>`l` |string|True|The current leverage value for this position|
|cumulative_fee<br>`cf` |string|True|The cumulative fee paid on the position, expressed in quote asset decimal units|
|cumulative_realized_funding_payment<br>`cr` |string|True|The cumulative realized funding payment of the position, expressed in quote asset decimal units|
|cumulative_realized_funding_payment<br>`cr` |string|True|The cumulative realized funding payment of the position, expressed in quote asset decimal units. Positive if paid, negative if received|
9 changes: 9 additions & 0 deletions artifacts/apidocs/schemas/funding_rate_aggregation_type.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
!!! info "[FundingRateAggregationType](/../../schemas/funding_rate_aggregation_type)"
Specifies different methods of aggregating historical funding rates<br>

|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.|
1 change: 0 additions & 1 deletion artifacts/apidocs/schemas/order.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,6 @@
|create_time<br>`ct` |string|False<br>`0`|[Filled by GRVT Backend] Time at which the order was received by GRVT in unix nanoseconds|
|trigger<br>`t` |TriggerOrderMetadata|False<br>``|Trigger fields are used to support any type of trigger order such as TP/SL|
|broker<br>`b` |BrokerTag|False<br>``|Specifies the broker who brokered the order|
|allow_crossing<br>`ac` |boolean|False<br>`false`|Specifies if post only order is allowed to cross the orderbook|
??? info "[TriggerOrderMetadata](/../../schemas/trigger_order_metadata)"
Contains metadata related to trigger orders, such as Take Profit (TP) or Stop Loss (SL).<br><br>Trigger orders are used to automatically execute an order when a predefined price condition is met, allowing traders to implement risk management strategies.<br><br><br>

Expand Down
1 change: 0 additions & 1 deletion artifacts/apidocs/schemas/order_metadata.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,6 @@
|create_time<br>`ct` |string|False<br>`0`|[Filled by GRVT Backend] Time at which the order was received by GRVT in unix nanoseconds|
|trigger<br>`t` |TriggerOrderMetadata|False<br>``|Trigger fields are used to support any type of trigger order such as TP/SL|
|broker<br>`b` |BrokerTag|False<br>``|Specifies the broker who brokered the order|
|allow_crossing<br>`ac` |boolean|False<br>`false`|Specifies if post only order is allowed to cross the orderbook|
??? info "[TriggerOrderMetadata](/../../schemas/trigger_order_metadata)"
Contains metadata related to trigger orders, such as Take Profit (TP) or Stop Loss (SL).<br><br>Trigger orders are used to automatically execute an order when a predefined price condition is met, allowing traders to implement risk management strategies.<br><br><br>

Expand Down
Loading