Skip to main content
GET
List positions

Authorizations

Authorization
string
header
required

Scoped API key (ttk_...), created in the Totalis app or by a wallet-session user through the API keys routes with a fresh wallet signature; those routes never accept a key. Each key acts for one account, yours or a maker's, and holds only scopes that account can use. Each operation lists the scopes it requires. Send no Origin.

Scopes

account:read
vault:read

Headers

Origin
string<uri>

Required for browser sessions; API keys do not require an Origin.

Query Parameters

limit
integer
default:50

Maximum items per page, 1 to 200, default 50. A page may hold fewer, even none, while has_more is true. Maximum items in one page. A page may hold fewer, even none, while has_more is true.

Required range: 1 <= x <= 200
cursor
string

Omit for the first page; then send the previous response's next_cursor unchanged. Opaque list cursor. Send a previous response's next_cursor back unchanged; never build or parse one.

Required string length: 1 - 2048
status
enum<string>

Return only positions with this lifecycle status.

Available options:
OPEN,
AWAITING_SETTLEMENT,
SETTLED_UNCLAIMED,
CLOSED
maker_result
enum<string>

Return only positions the maker closed with this result: WON, LOST or EVEN (see maker_result).

Available options:
WON,
LOST,
EVEN
outcome_id
string

Return only positions with a leg on this HIP-4 outcome, resolved or not.

Maximum string length: 10
Pattern: ^(0|[1-9][0-9]{0,8}|[1-3][0-9]{9}|4[01][0-9]{8}|42[0-8][0-9]{7}|429[0-3][0-9]{6}|4294[0-8][0-9]{5}|42949[0-5][0-9]{4}|429496[0-6][0-9]{3}|4294967[0-1][0-9]{2}|42949672[0-8][0-9]|429496729[0-5])$

Response

Your positions, reconciled against the vault contract. A key for your account lists the positions you hold; a key for a maker lists the positions the maker backs. The key's permissions are checked on every request. One freshness status covers the read; amounts are atomic USDC strings or null. No shared caching.

context
object
required

Freshness of this read: the oldest source observation and one status for every amount in the response.

items
object[]
required

Positions on this page, newest created_at first, then position_id descending.

next_cursor
string | null
required

Opaque cursor for the next page, bound to this response's snapshot; null on the last page. Send it back unchanged as cursor.

Required string length: 1 - 2048
has_more
boolean
required

True when another page exists; true exactly when next_cursor is non-null.

total_count
string
required

Exact number of positions in the whole filtered snapshot (not just this page), as a decimal string.

Pattern: ^(0|[1-9][0-9]{0,77})$