Skip to main content
GET
List positions for a user or market

Query Parameters

user
string | null

The wallet to anchor on. At least one of user/condition is required.

condition
string | null

Condition id(s), comma-separated (at most 20 distinct values). With user, narrows that user's positions (all ids honoured). Without user, anchors on the market's holders; exactly one id is accepted there, and a multi-id list is rejected rather than silently truncated.

limit
integer<int32> | null

First-page size. Ignored when cursor is supplied (the cursor's size wins).

Required range: 0 <= x <= 1000
cursor
string | null

Opaque pagination cursor from a prior response's next_cursor. It carries the page position, page size, and the status/sort/direction it was minted under.

status
string | null

One of OPEN, REDEEMABLE, REDEEMABLE_LOST, MERGEABLE, or CLOSED; defaults to OPEN. REDEEMABLE_LOST requires user, supports all six sorts, and defaults to CURRENT_VALUE; it preserves row status REDEEMABLE. MERGEABLE is OPEN narrowed to live complementary pairs (conditions where the wallet holds >= 2 servable-live tokens) and defaults to TOKENS; it is user-scoped, so a market-anchored request renders as OPEN.

OPEN is the superset; it includes settled-but-unredeemed winners, which REDEEMABLE narrows to. CLOSED is exited positions.

event_id
string | null

Event id(s), comma-separated (at most 20 distinct values). User-anchored only.

title
string | null

Case-insensitive market-title substring filter, honoured on every anchor and status. SQL LIKE wildcards (%, _) keep their usual meaning; empty or whitespace-only is treated as absent; at most 200 characters. NOT carried by the cursor: re-send it on every page of a walk (like condition and the start/end window), or the cohort silently widens.

filter_type
string | null

CASH or TOKENS; defaults to TOKENS (the /v2/trades-homogenized filter pair, replacing the former size_threshold).

filter_amount
number<double> | null

The filter floor. TOKENS: minimum CURRENT holding in shares (defaults to the 0.1 dust floor; applies to OPEN/REDEEMABLE; a user's CLOSED set is not narrowed by it, and on a market anchor it moves the OPEN/CLOSED boundary). CASH: minimum mark-to-market current_value in USDC, on top of the token dust floor. Invalid values fall back to the default.

include_archived
boolean | null

Also include positions on archived markets; defaults to false. OPEN/REDEEMABLE/REDEEMABLE_LOST/MERGEABLE only; combining it with status=CLOSED is rejected. Inactive markets remain excluded either way.

sort_by
string | null

One of CURRENT_VALUE, PRICE, TOKENS, UNREALIZED_PNL, REALIZED_PNL, TOTAL_PNL, or TIMESTAMP (the row's last_event_at). PRICE ranks by the response's effective current_price on every supported anchor and status. On REDEEMABLE, the existing winners-first partition remains ahead of the requested price order. The default follows the status: CURRENT_VALUE for OPEN/REDEEMABLE, REALIZED_PNL for CLOSED.

start
integer<int64> | null

Inclusive lower bound on last_event_at, epoch seconds; omit or 0 for unbounded (the /v2/activity + /v2/trades vocabulary).

end
integer<int64> | null

Inclusive upper bound on last_event_at, epoch seconds; omit or 0 for unbounded.

A position with no native economics carries no last_event_at and is therefore excluded by any bound, in either direction; a window asks which positions moved inside it, and a row with no clock has no answer. Unbounded requests still serve those rows.

sort_direction
string | null

ASC or DESC; defaults to DESC.

Response

A page of positions

{ data, pagination } envelope for /v2/positions.

data
object[]
required

The page's rows.

pagination
object
required

Paging envelope: follow next_cursor until null.