Positions API Overview - Polymarket US Documentation

Endpoints

Method	Endpoint	Description
`GET`	`/v1/positions`	Get current positions
`POST`	`/v1/positions/balance`	Get single account balance
`POST`	`/v1/positions/balances`	Get multiple account balances
`GET`	`/v1/positions/ledger`	Query historical position changes. See Position Ledger.
`GET`	`/v1/positions/ledger/download`	Download position ledger as CSV. See Position Ledger.

Position Data

Each position includes:

Field	Description
`symbol`	Trading instrument
`account`	Trading account
`netPosition`	Current net position quantity
`qtyBought`	Total quantity bought
`qtySold`	Total quantity sold
`cost`	Total cost basis (scaled integer)
`realized`	Realized profit/loss (scaled integer)
`bodPosition`	Beginning-of-day position
`updateTime`	Last update timestamp

Balance Data

Account balances include:

Field	Description
`balance`	Current cash balance
`buyingPower`	Available buying power for trading
`capitalRequirement`	Required capital to maintain positions
`excessCapital`	Capital above requirements
`marginRequirement`	Margin required for open positions
`unsettledFunds`	Funds pending settlement
`openOrders`	Value reserved for open orders
`updateTime`	Last update timestamp

Historical Position Queries

Query positions as they existed at a specific point in time. Useful for regulatory reporting, reconciliation, or end-of-day snapshots.

Parameters

Parameter	Type	Description
`as_of_time`	RFC3339 timestamp	Exact point-in-time (e.g., `2026-01-02T17:00:00Z`)
`as_of_date`	Date object	End-of-trading-day snapshot (year, month, day)

Mutually Exclusive: Use as_of_time OR as_of_date, not both. The as_of_time parameter already contains date information.

Examples

Query by timestamp (exact point in time):

GET /v1/positions?name=firms/ISV-Alice/accounts/trading&as_of_time=2026-01-02T17:00:00Z

Query by trade date (end of trading day):

GET /v1/positions?name=firms/ISV-Alice/accounts/trading&as_of_date.year=2026&as_of_date.month=1&as_of_date.day=2

Use Cases

End-of-Day Reports: Query positions at market close for daily P&L calculations
Regulatory Snapshots: Capture position state at specific regulatory timestamps
Reconciliation: Compare historical positions against external records
Audit Trail: Review position history for compliance or dispute resolution

Usage Notes

Position Updates After TradesPosition data is updated after each trade execution. For real-time trade notifications that affect positions, use the gRPC Order Stream.

Positions are aggregated by symbol and account
Balances reflect current available and reserved amounts
Use the Order Stream for real-time execution updates that affect positions
Historical queries return the position state as of the specified time

Position Ledger

The position ledger records every change to a position as a single entry, with both the delta (quantityChange, costChange, realizedChange) and the cumulative state immediately after the change (netPosition, cost, realized). Use it for reconciliation, point-in-time replay, and end-of-day reporting.

Ledger Endpoints

Method	Endpoint	gRPC	Required Scope	Description
`GET`	`/v1/positions/ledger`	`PositionAPI.GetPositionLedger`	`read:positions`	Paginated query of position ledger entries
`GET`	`/v1/positions/ledger/download`	`PositionAPI.DownloadPositionLedger`	`read:positions`	Streamed CSV download of position ledger entries

Both endpoints are scoped under read:positions (the same scope used for GetAccountBalance, ListAccountBalances, and the position queries on this section). Calls without read:positions fail with 403 Forbidden (REST) / PERMISSION_DENIED (gRPC).

Historical Floor

Setting	Value
Earliest queryable date	`2026-05-01T00:00:00Z`

The ledger has a hard historical floor of May 1, 2026 (UTC). Enforcement is defense-in-depth:

start_time is clamped upstream to the floor when the caller asks for earlier data.
Entries with update_time before the floor are post-filtered from responses.

Pre-floor entries are not retrievable through this endpoint.

Delta Computation

Each ledger entry is computed from the exchange’s before/after position snapshots:

quantityChange = after.netPosition - before.netPosition
costChange     = after.cost        - before.cost
realizedChange = after.realized    - before.realized

The cumulative fields (netPosition, cost, realized) on each entry are the state immediately after the change. To reconstruct point-in-time position state, replay entries in update_time order.

Cross-Firm Access

The account in account=firms/{firm}/accounts/{id} must belong to the caller’s firm (extracted from the JWT firm_id claim). Cross-firm access is blocked at the gateway:

Condition	Error Code
Account belongs to a different firm	`PermissionDenied`
JWT missing or `firm_id` absent	`Unauthenticated`
ISV credentials not configured at gateway	`FailedPrecondition`
Upstream exchange service unavailable	`Unavailable`

Get Position Ledger

GET /v1/positions/ledger?account=firms/ISV-Alice/accounts/alice-trading&start_time=2026-05-01T00:00:00Z&page_size=100

Query Parameters

Parameter	Type	Required	Description
`account`	string	Yes	Fully qualified account name. Example: `firms/ISV-Alice/accounts/alice-trading`.
`symbol`	string	No	Filter by instrument symbol.
`start_time`	RFC3339	No	Inclusive lower bound on `update_time`. Clamped to `2026-05-01T00:00:00Z`.
`end_time`	RFC3339	No	Inclusive upper bound on `update_time`.
`page_size`	integer	No	Maximum entries per page. Max 1000; values above 1000 return `InvalidArgument`.
`page_token`	string	No	Pagination token from a previous response’s `nextPageToken`.
`newest_first`	boolean	No	If `true`, descending `update_time` order. Default `false`.

Sample Response

{
  "entries": [
    {
      "id": "pl_01HXYZ...",
      "account": "firms/ISV-Alice/accounts/alice-trading",
      "symbol": "tec-nfl-sbw-2026-02-08-kc",
      "quantityChange": "50",
      "costChange": "26000",
      "realizedChange": "0",
      "netPosition": "150",
      "cost": "78000",
      "realized": "0",
      "updateTime": "2026-05-02T14:30:15.123Z",
      "updateBusinessDate": "2026-05-02",
      "description": "Trade fill"
    }
  ],
  "nextPageToken": "eyJvZmZzZXQiOjEwMH0=",
  "eof": false
}

PositionLedgerEntry Fields

Field	Type	Description
`id`	string	Unique entry identifier.
`account`	string	Account this entry belongs to.
`symbol`	string	Instrument symbol.
`quantityChange`	int64	Delta from previous position (`after.netPosition - before.netPosition`).
`costChange`	int64	Delta in cost basis.
`realizedChange`	int64	Delta in realized P&L.
`netPosition`	int64	Net position after this change.
`cost`	int64	Cost basis after this change.
`realized`	int64	Cumulative realized P&L after this change.
`updateTime`	RFC3339	Timestamp of the position change.
`updateBusinessDate`	string	Business date in `YYYY-MM-DD`.
`description`	string	Human-readable reason (e.g., trade fill, expiry, correction).

int64 fields are serialized as strings in JSON (e.g., "50" not 50) per the protobuf JSON mapping spec. Parse them as strings to avoid precision loss in languages with 53-bit integer limits.

Response Wrapper Fields

Field	Type	Description
`entries`	array	Position ledger entries for the requested account / time window.
`nextPageToken`	string	Pagination token to fetch the next page. Empty when there are no more results.
`eof`	boolean	`true` when this response contains the final page of results.

Download Position Ledger

GET /v1/positions/ledger/download?account=firms/ISV-Alice/accounts/alice-trading&start_time=2026-05-01T00:00:00Z

The download endpoint accepts the same query parameters as GET /v1/positions/ledger (account, symbol, start_time, end_time, page_size, page_token, newest_first). It streams raw CSV bytes from the upstream ledger as a passthrough; the gateway does not parse individual rows.

CSV passthrough caveat. Because the body is opaque to the gateway, ledger entries cannot be post-filtered row-by-row. The historical floor is still enforced upstream via start_time clamping, but no per-row filtering is performed on the CSV stream.

Empty result sets return a single empty chunk followed by EOF (HTTP 200 with an empty body). The gateway translates an upstream “stream returned a nil response” condition into an empty result.

Ledger Rate Limits (per firm)

Endpoint	Rate	Burst	Effective
`GET /v1/positions/ledger`	0.5 req/sec	5	~30 req/min
`GET /v1/positions/ledger/download`	0.0833 req/sec	1	~5 req/min

Exceeding these limits returns ResourceExhausted (429 Too Many Requests).

Ledger Error Codes

Error	Cause
`InvalidArgument`	Missing `account`.
`PermissionDenied`	Account belongs to a different firm.
`Unauthenticated`	Missing JWT or `firm_id` claim.
`FailedPrecondition`	ISV credentials not configured.
`Unavailable`	Upstream exchange service not connected.
`ResourceExhausted`	Per-firm rate limit exceeded.

Balance Ledger

Cash balance changes (deposits, withdrawals, fills, fees)

Balance Ledger Stream

Real-time balance ledger via gRPC

Order Stream

Real-time execution updates that affect positions

Authentication

Required scopes and OAuth flow

​Endpoints

​Position Data

​Balance Data

​Historical Position Queries

​Parameters

​Examples

​Use Cases

​Usage Notes

​Position Ledger

​Ledger Endpoints

​Historical Floor

​Delta Computation

​Cross-Firm Access

​Get Position Ledger

​Query Parameters

​Sample Response

​PositionLedgerEntry Fields

​Response Wrapper Fields

​Download Position Ledger

​Ledger Rate Limits (per firm)

​Ledger Error Codes

​See Also

Balance Ledger

Balance Ledger Stream

Order Stream

Authentication

Endpoints

Position Data

Balance Data

Historical Position Queries

Parameters

Examples

Use Cases

Usage Notes

Position Ledger

Ledger Endpoints

Historical Floor

Delta Computation

Cross-Firm Access

Get Position Ledger

Query Parameters

Sample Response

PositionLedgerEntry Fields

Response Wrapper Fields

Download Position Ledger

Ledger Rate Limits (per firm)

Ledger Error Codes

See Also