Api position history request
ApiPositionHistoryRequest
Query for position lifecycle records for a single sub account.
Returns both fully closed positions and positions that are still open but have been partially reduced (PARTIALLY_CLOSED).
Results are ordered as follows: partially closed positions (most recently opened first), then fully closed positions (most recently closed first).
Partially closed positions are included only when all of the following are true:
start_time is unset (partially closed positions have no close time)end_time is unset (partially closed positions have no close time)cursor is unset (they are only returned on the initial page)status is nil or includes PARTIALLY_CLOSED
Since these positions have no close time, query-row limits, as well as time-range and cursor-based pagination, do not apply to them.
Pagination works as follows:
- We perform a reverse chronological lookup by position-close time, 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 of the close-time range in unix nanoseconds. If nil, defaults to no lower bound. Only positions with close_time >= start_time are returned. Does not apply to partially closed positions (they have no close time and will be excluded when this field is set) |
end_time
et |
string |
False
now() |
End of the close-time range in unix nanoseconds. If nil, defaults to now. Only positions with close_time <= end_time are returned. Does not apply to partially closed positions (they have no close time and will be excluded when this field is set) |
kind
k |
[Kind] |
False
all |
The kind filter to apply. If nil, this defaults to all kinds. Otherwise, only positions 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 positions 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 positions matching the filter will be returned |
limit
l |
integer |
False
500 |
The limit to query for. Defaults to 500; Max 1000. Applies to fully closed positions only; limit excludes any matching partially-closed positions |
cursor
c |
string |
False
'' |
The cursor to indicate when to start the next page query from. Partially closed positions are only returned on the initial page (when cursor is unset) |
status
s |
[PositionCloseStatus] |
False
all |
The status filter to apply. If nil, this defaults to all statuses. Otherwise, only positions matching the filter will be returned |
is_long
il |
boolean |
False
false |
Set to true to filter for long positions. If both is_long and is_short are false (default), positions of both directions are returned |
is_short
is |
boolean |
False
false |
Set to true to filter for short positions. If both is_long and is_short are false (default), positions of both directions are returned |
margin_type
mt |
[PositionMarginType] |
False
all |
The margin type filter to apply. If nil, this defaults to all margin types. Otherwise, only positions matching the filter will be returned |
Kind
The list of asset kinds that are supported on the GRVT exchange
| Value |
Description |
PERPETUAL = 1 |
the perpetual asset kind |
FUTURE = 2 |
the future asset kind |
CALL = 3 |
the call option asset kind |
PUT = 4 |
the put option asset kind |
PositionCloseStatus
| Value |
Description |
CLOSED = 1 |
Position fully closed via reducing trade or flip |
LIQUIDATED = 2 |
Position closed via liquidation |
SETTLED = 3 |
Position closed via settlement |
PARTIALLY_CLOSED = 4 |
Position partially closed |
PositionMarginType
| 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 |