List positions for a user or market
A keyset page of positions in the standard
{ data, pagination } envelope. One route serves a user’s open book, their
closed book (status=CLOSED), and a market’s holders (market anchor).
At least one of user/condition is required. Supplying both anchors on the
user and applies condition as a narrowing filter.
status defaults to OPEN, which is the superset: a
settled-but-unredeemed winner still holds its tokens, so it is an open
position whose condition resolved. REDEEMABLE narrows to that subset, and
each row echoes its own status.
Resume contract: a next_cursor binds the status/sortBy/sortDirection
the walk started with. To follow it, send cursor together with the same
user or condition anchor used on the first page; a bare ?cursor= request
returns 400. The token is the authority on the spine and the total order,
and the handler adopts all three from it. Restating them is allowed and
must agree;
explicitly contradicting one is a 400, because replaying an anchor under
a different spine or order would silently walk a different result set.
Omitting them is not a contradiction; a defaulted status is the absence of
a choice, not a request for OPEN.
A malformed condition id is a 400 naming the value; a
well-formed one that matches nothing serves an empty data array, which
is the meaningful zero-state; absence means the market is not servable,
and only that.
Query Parameters
The wallet to anchor on. At least one of user/condition is required.
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.
First-page size. Ignored when cursor is supplied (the cursor's size wins).
0 <= x <= 1000Opaque 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.
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(s), comma-separated (at most 20 distinct values). User-anchored only.
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.
CASH or TOKENS; defaults to TOKENS (the /v2/trades-homogenized
filter pair, replacing the former size_threshold).
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.
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.
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.
Inclusive lower bound on last_event_at, epoch seconds; omit or 0 for
unbounded (the /v2/activity + /v2/trades vocabulary).
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.
ASC or DESC; defaults to DESC.