Skip to main content
GET
Use this to build a positions board, or send wallet to read one wallet’s complete open positions instead of the whole feed. Rows come from 0xinsider’s copy of Polymarket’s wallet positions, ordered by current_value_usd, largest first. For the individual fills that built one row, use Position timeline, and for the $50,000 change-detection feed, use Large positions.

​
Parameters

Every filter is applied before the page is built, so paging deep into the feed costs the same as page 1. With wallet, a page holds that wallet’s own positions, and rows from several wallets are interleaved by current_value_usd.

​
Key response fields

​
Example

One wallet’s complete open positions, then three wallets in one request:
For a repeatable multi-page read, add consistency=snapshot to a wallet request. Follow next_cursor with the same filters until has_more is false. If the cursor expires or another first page replaces it, request page 1 again. If the result exceeds 500 positions or 2 MB, narrow the filters or use live.

​
What it does not return

  • A position on a market with more than two outcomes. This route covers two-outcome markets only.
  • A position 0xinsider has not valued yet. Its current_value_usd would be null, so the row is left out.
  • A position worth under $100, unless you send min_size=0 or wallet, which sets the floor to 0.
  • A closed position. A holding that reaches 0 shares is dropped, so a wallet read covers open positions only.
  • The fills that built the position. Those are on Position timeline.

​
Caching

Send the ETag from a response back in an If-None-Match header. If the page has not changed, you get 304 Not Modified with an empty body. data_quality is part of the representation, so its stored clocks change the ETag; meta.cached and meta.cache_age_s describe the transport cache.

Authorizations

​
Authorization
string
header
required

Legacy default or named integration API key, or OAuth 2.1 access token, in the Authorization header as Bearer oxi_sk_live_... or Bearer oxi_at_.... Default keys retain full access; integration keys are limited to their approved read, webhooks, export and usage scopes and expire within 90 days. All credentials share the owner's account limits. Data calls require an active Pro subscription and return live data. A 401 carries WWW-Authenticate: Bearer resource_metadata="https://api.0xinsider.com/.well-known/oauth-protected-resource" (RFC 6750 section 3, RFC 9728).

Headers

​
X-Query-Validation
enum<string>

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.

Available options:
strict
​
If-None-Match
string

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

Query Parameters

​
limit
integer
default:20

Maximum number of current positions to return. Out-of-range values are clamped to 1..100.

Required range: 1 <= x <= 100
​
cursor
string

Pagination cursor from previous response's next_cursor.

​
consistency
enum<string>
default:live

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.

Available options:
live,
snapshot
​
min_size
number
default:100

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.

​
category
string

Exact match against provider-backed market_canonical.category.

​
condition_id
string

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 [].

​
wallet
string[]

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.

Maximum array length: 25
​
wallet[]
string[]

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

Maximum array length: 25
​
min_grade
enum<string>

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

Available options:
S,
A,
B,
C,
D,
F
​
side
enum<string>

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

Available options:
yes,
no

Response

Page of positions

​
object
string
required
Allowed value: "list"
​
data
object[]
required
​
data_quality
object
required

Writer-backed age and coverage for this page; it is part of the representation and the ETag, while transport cache facts remain in meta.

​
has_more
boolean
required
​
meta
object
required
​
next_cursor
string
​
total
integer

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

​
snapshot
object

Present only with consistency=snapshot. Dates the frozen response rows, not the provider's underlying observations.