Positions

List current positions (positions-board feed)

Returns the current positions-board feed backed by the wallet_positions mirror. Ordered by current_value_usd DESC with deterministic (wallet, condition_id, outcome_index) tiebreakers. Pre-reconcile rows (current_value_usd IS NULL) are excluded. Cursor-paginated. Every filter pushes into SQL. Deep cursor pages cost the same as the first page: the value bounds and the cursor are index conditions, so a page never rescans the feed from the top. With wallet, the same feed is read for one wallet or a book of up to 25 wallets from each wallet's own ordered index range, so the pages are that wallet's complete reconciled binary open positions and the cost is the page, never the board. min_size then defaults to 0. What a wallet read does not return: positions with shares at 0 (closed), rows the reconciler has not valued yet (current_value_usd IS NULL), and non-binary outcomes; per-row last_reconciled_at and freshness say how old each valuation is. Each row also carries additive exact source atoms as decimal strings with unit, scale and basis metadata; parse those values with decimal-safe arithmetic and do not reconstruct them from the display-safe numeric fields. The response adds a top-level data_quality object beside data, with positions, trader, and market groups owned by wallet_positions.last_reconciled_at|updated_at, traders.last_synced, and market_canonical.last_refreshed_at. Its stored clocks are part of the ETag; meta continues to hold transport cache facts.

get/api/v1/positions

Query parameters

limitinteger

Maximum number of current positions to return.

cursorstring

Pagination cursor from previous response's next_cursor.

consistency'live' | 'snapshot'

live (default) reads the current value-ordered board. snapshot requires wallet and freezes up to 500 matching rows and 2 MB for up to five minutes. Keep consistency=snapshot and the same effective filters on every page; changing filters returns 400. A new first page from the same API key replaces its prior snapshot; replacement or expiry returns cursor_expired.

min_sizenumber

Minimum current position value in USD. Defaults to 100 when omitted, or to 0 when wallet is present; send 0 to include every reconciled position.

categorystring

Exact match against provider-backed market_canonical.category.

condition_idstring

Scope to one market. Accepts the raw provider condition_id or the mkt_-prefixed market id emitted by V1 responses. Combine with min_size=0 for every reconciled position in that market; an unknown id returns [].

walletstring[]

Scope to one wallet or a book of wallets (repeatable, up to 25 per request; comma-separated values inside one occurrence also work). Each value is a wallet address, a known username, or a trd_-prefixed trader id, resolved like /api/v1/trader/{address}. The response keeps the board's order and cursor, so pages of a book interleave wallets by current_value_usd. An address this API has never tracked returns its mirror rows or an empty list; a username or trader id that resolves to nothing is a 404 naming wallet; more than 25 values is a 400. min_size defaults to 0 when wallet is present.

wallet[]string[]

Backward-compatible bracket alias for wallet. Repeatable; same values and limits.

min_grade'S' | 'A' | 'B' | 'C' | 'D' | 'F'

Minimum trader grade allowlist. A matches S and A; B matches S, A, B; etc.

side'yes' | 'no'

Filter by the binary outcome side. yes maps to outcome_index=0, no to outcome_index=1.

Headers

X-Query-Validation'strict'

Opt into strict query-name validation. The default is compatible: unknown names are ignored and reported in X-Query-Ignored. With strict, an unknown name returns 400 bad_request with error.reason unknown_query_parameter before the handler runs, including when its percent escape is incomplete.

If-None-Matchstring

Conditional GET validator from a previous ETag. Matching values return 304 Not Modified with an empty body.

Response

Page of positions

object'list' required

has_moreboolean required

next_cursorstring

totalinteger

Total matching rows when the read model exposes a count; the key is absent when it does not.

Changes

Changed in 24 of the 89 revisions of this API.8250170

Sep 23, 202617a9c670dc862See the full diff
- ○
  added the new optional query request parameter consistency
  new-optional-request-parameter
- ○
  added the optional property to the response with the status
  response-optional-property-added
Sep 23, 20269d1ba37bd5e31See the full diff
- ○
  added the required property to the response with the status
  response-required-property-added
Sep 23, 2026ece7a25b7a4499See the full diff
- ●
  added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status
  response-property-enum-value-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
Sep 23, 2026cc7ab48fc9291See the full diff
- ○
  added the optional property // to the response with the status
  response-optional-property-added
Sep 23, 2026c6a3d3420dc51See the full diff
- ●
  removed the optional property // from the response with the status
  response-optional-property-removed
This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Sep 23, 20268fb2ad0990f41See the full diff
- ○
  added the optional property // to the response with the status
  response-optional-property-added
Sep 23, 20268462acf80f8c9See the full diff
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Sep 22, 2026e0f39b9ecc6f1See the full diff
- ○
  added the non-success response with the status
  response-non-success-status-added
Sep 22, 202619386d595e051See the full diff
- ○
  the response property // became required for the status
  response-property-became-required
Sep 22, 2026258f351891962See the full diff
- ○
  added the new optional query request parameter wallet
  new-optional-request-parameter
- ○
  added the new optional query request parameter wallet[]
  new-optional-request-parameter

Full history (24 revisions)