Reference

API reference

Every endpoint, in one place, checked against what the build actually serves.

Two surfaces

Partner paths 26Sandbox-gated 7Public /api/*Version v1

Surface	Auth	What it is for
`/api/v1/*`	Operator key + scope	The partner contract. Opaque contract ids, exact money, keyset cursors, no venue named anywhere.
`/api/*`	None	The public catalogue and the public demo. It powers a page anyone can open; it is not a contract.

They are different routes with different rules rather than one route with a flag. Adding auth to the public surface would break the demo; leaving it off the partner surface would make an operator's orders placeable by anyone who learns a player id.

http

Authorization: Bearer pk_test_...      # or sk_live_... in production
X-Parity-User: your-own-player-id    # on every quote and order
Content-Type: application/json

A machine-readable OpenAPI 3.1 document covering every path on this page is at /openapi.json.

Catalogue

GET/api/v1/eventsAPI key

The partner catalogue, keyset-paged. Scope markets:read. category, sort, dir, search, tradable, closesAfter, closesBefore, limit (1-100, default 25), cursor. An unrecognised filter value is a 400, not a silently unfiltered catalogue.

GET/api/v1/events/{id}API key

One event with every outcome. {id} is an event id or its slug. Scope markets:read.

GET/api/v1/categoriesAPI key

The values ?category= accepts, with live event counts. Scope markets:read.

GET/api/v1/images/{id}No auth

Event artwork from Parity's own origin. {id} is the event id. Unauthenticated, because it is a URL a browser loads from an <img> tag.

GET/api/v1/stream/pricesNo auth

Live prices for an embedded surface, as Server-Sent Events. ?contracts= is a comma-separated list of opaque ctr_… ids. No API key ever, because a browser cannot hold one. Every frame is normalised, names no venue and is not user-specific. An embed session token in Authorization: Embed <token> is optional and decides one thing: whose offering policy filters the feed before delivery. A token that is presented and refused closes the connection rather than downgrading it to anonymous. One connection per page; Parity multiplexes the venue side, so a thousand viewers of one contract cost one upstream subscription. Never render a price without reading tradeable.

Embed

POST/api/v1/embed-sessionsAPI key

Trade an API key for a short-lived token a browser may hold, scoped to one operator and one customer. Requires markets:read, quotes:write and orders:write together, because a session can browse, quote and order, so the key that mints one must be able to do all three itself. Body: externalUserId (required), returnOrigin, ttlSeconds (60-3600, default 900), locale, region, theme. The token is returned once. Send it as Authorization: Embed <token>; a token in a query string is refused outright. Full walkthrough on Parity Embed.

Trading

POST/api/v1/quotesAPI key

Price a trade and hold that price. Scope quotes:write. Exactly one of stake (sizes a BUY) or contracts (sizes a SELL). Requires X-Parity-User.

POST/api/v1/ordersAPI key

Spend a quote. Scope orders:write. Idempotent on clientOrderId: 201 on creation, 200 with idempotentReplay: true on a replay. Requires X-Parity-User.

GET/api/v1/ordersAPI key

Order history, newest first. Scope orders:read. externalUserId, clientOrderId (with externalUserId), status, since, until, limit (1-200, default 50), cursor. Returns orders, count, nextCursor and hasMore, and does not carry settlementState: use it to find the orderId, then read that order. ?status= is not validated, so an unknown value returns an empty page rather than a 400.

GET/api/v1/orders/{id}API key

One order, with settlementState and transmissionState. Scope orders:read. ?fills=true includes the individual executions, and that exact spelling is what is matched: ?fills=1 and ?fills=TRUE do not enable it. This is the only route that returns settlementState. The list route below does not, so a recovery polls this one.

POST/api/v1/orders/{id}/confirm-reserveAPI key

Confirm your customer's funds are held. Scope orders:write. Idempotent: the same call twice yields one executable order and a 200, never a conflict. Until it is made, a recorded order is reserve_pending and cannot execute.

POST/api/v1/orders/{id}/cancelAPI key

Withdraw an order that has not reached a venue, and receive the release instruction. Scope orders:write. Issued exactly once: a second call replays the same cancellationId and the same releaseAmount. Refused with 409 for any order whose transmissionState is not not_transmitted.

Positions

GET/api/v1/positionsAPI key

What your players hold. Scope positions:read. externalUserId, status, limit (1-200, default 50), cursor.

GET/api/v1/positions/{id}API key

One position by positionId. Scope positions:read.

Settlement and reconciliation

GET/api/v1/settlementsAPI key

The settlement register, keyset-paged on a monotonic sequence. Scope settlements:read. externalUserId, outcome, settledFrom, settledTo, limit (1-500, default 100), cursor.

GET/api/v1/settlements/positionsAPI key

The older position-settlement feed, cursored on settledAt. Superseded by /api/v1/settlements, which its own response says in supersededBy: this one pages with no tiebreaker, and settlements written in one transaction share a timestamp exactly.

GET/api/v1/reconciliationAPI key

The verdict: do Parity's records, the cash ledger and the venue agree? Scope ledger:read. Optional from.

GET/api/v1/reconciliation/feedAPI key

Every money fact recorded for you, totally ordered and resumable. Scope ledger:read. cursor, type (repeatable), externalUserId, limit (1-500, default 100).

Customers

PUT/api/v1/users/{id}/jurisdictionAPI key

State where one of your customers is. Scope orders:write. Body: country (ISO 3166-1 alpha-2, required) and optionally subdivision (the part of an ISO 3166-2 code after the hyphen, or null for country level). You ran the KYC and hold the licence, so the assertion is yours; Parity does not authenticate your end users and does not geolocate them. It changes nothing until jurisdiction enforcement is switched on for your account, so you can populate assertions first and enforce after. A country that is not two letters is 400 invalid_jurisdiction.

GET/api/v1/users/{id}/limitsAPI key

One customer's wager limits, and what actually applies. Scope orders:write. Returns three objects: account (what you set on this customer), operator(the ceiling over every account you hold) and effective (what the quote and order seams will enforce, with the rung that decided each figure named). Read effective. The account rung can only ever TIGHTEN the operator rung, never loosen it, so an account ceiling set above the operator ceiling has no effect at all, and a caller reading only its own write would believe it had raised a limit it had not raised.

PUT/api/v1/users/{id}/limitsAPI key

Set them, for a limit that arrives from YOUR system: a cool-off, a self-exclusion, a player-set deposit limit, or a ceiling your risk team applies. Scope orders:write. Body: maxWagerMinor caps ONE wager; periodStakeMinor with periodHours caps total stake across a rolling window. The pair travels together, because a stake ceiling with no window is not a rule anybody can enforce and a window with no ceiling bounds nothing, so the half-written form is 400 invalid_request. Amounts are exact integers of minor units. Send null at a field to withdraw the opinion at this rung. The reply is the same shape as the GET.

DELETE/api/v1/users/{id}/limitsAPI key

Clear the ACCOUNT rung only. Any operator-wide ceiling above it still stands, which is why the reply still carries effective: a 200 here does not mean the customer is now unlimited. Scope orders:write.

GET/api/v1/users/{id}/jurisdictionAPI key

What you asserted, alongside the country we OBSERVED from the player's own address, which is evidence and never access, plus whether the two disagree. Scope markets:read.

These two work in live mode

They are the only /api/v1/users/{id}/* paths that do. The balance and movement reads below are gated to sandbox tenants; a jurisdiction assertion is production machinery and is how enforcement is fed.

Sandbox only

Every path in this section answers 403 sandbox_only in live mode

They model a per-user balance held by Parity, which exists so an integration can be learned against simulated money. A live operator owns its customers' cash ledger, so there is nothing here for it to read. The live contract is operatorMoney, operatorExitMoney and settlementCredit.

GET/api/v1/users/{id}/balanceAPI key

A player's derived balance. Scope ledger:read. Optional currency.

GET/api/v1/users/{id}/ledgerAPI key

The movements behind that balance, newest first. Scope ledger:read. limit (1-200, default 50), cursor.

GET/api/v1/funding/supported-assetsAPI key

Fundable asset and chain pairs, read live on every call. Scope funding:write. symbol, symbols, chainId.

POST/api/v1/funding/deposit-addressAPI key

Issue a deposit address for one player. Scope funding:write. 201 on success.

GET/api/v1/funding/deposits/{id}API key

Deposit status, timeline and history. Scope funding:write. ?sync=false skips the bridge poll.

POST/api/v1/sandbox/scenariosAPI key

Arm the next order to behave a particular way, a partial fill for instance. Scope orders:write; GET lists what is armed under orders:read. It drives the real order code rather than a simulation of it. A scenario fires once and expires after an hour. See Sandbox.

POST/api/v1/sandbox/resolutionsAPI key

Settle one position on demand: WIN, LOSS or VOID, relative to the position's own side. Scope settlements:read. It names a position, never a market, because resolving a market would settle every other operator's positions on it. Asking twice is idempotent; asking for a different resolution is 409 resolution_conflict.

Public: no credentials

These power the public site and the public demo. They are useful to read and they are not the partner contract: they carry no operator scoping, and the ones that take no key carry no commitment about their shape either. They name contracts by the same opaque ctr_… id /api/v1 uses, and they never name a liquidity pool.

GET/api/eventsNo auth

The public event feed. Offset-paged.

GET/api/events/{key}API key

One event with price history. range is 1d, 1w, 1m or all. Needs a key with markets:read: it is addressed by an internal grouping key and has no first-party reader, so it is not a public surface any more. Use GET /api/v1/events/{id}.

GET/api/marketsNo auth

The public contract catalogue.

GET/api/markets/{id}No auth

One contract, its history and related contracts.

GET/api/markets/quotes?ids=…No auth

Up to 100 contracts by id in one request.

GET/api/healthNo auth

Database, ingest and price-coverage status. 503 only when the database is down.

POST/api/demo/quotesNo auth

The demo's quote path. Same pricing code, no credentials.

POST/api/demo/ordersNo auth

The demo's order path. Same execution code, under a well-known demo operator.

Do not integrate against /api/demo/* or /api/*

The demo exists so the public page exercises the production path rather than a parallel implementation of it. It is unauthenticated, its identity model is not yours, and it is not a contract. The public catalogue is likewise a website feed: partners read /api/v1/events.

Conventions that hold everywhere

Auth. Authorization: Bearer <key> on every /api/v1/* request except /api/v1/images/{id} and /api/v1/stream/prices. Scope is checked before the rate limit is consumed, so a scope mistake never arrives disguised as a 429 on the retry.
Identity. X-Parity-User carries your id for the player. Parity never authenticates end users and stores only that opaque value. A write path creates a user on first use; a read never does.
Idempotency. clientOrderId on orders, enforced by a unique index on (operator, user, clientOrderId) rather than by a check in a handler. Retrying is the correct response to a timeout.
Money. Exact decimal strings inside operatorMoney, operatorExitMoney and a settlement. Numbers elsewhere are for display. Contract prices are 0-1, and sub-cent prices are real.
Cursors. Keyset, not offset. Loop on nextCursor; a last page legitimately has none. Every paged feed refuses a malformed cursor with 400 invalid_cursor rather than restarting at page one. A cursor that decodes cleanly and names a row that has since gone is a different case, and three feeds still answer it with page one. See Errors.
Errors. A JSON body with a machine-readable error. Branch on the code, never on the message.
Rate limits. Two per-minute counters: one per key, one per operator across every key it holds. RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset report the key and are on most responses rather than all of them. POST /api/v1/quotes and POST /api/v1/orders answer without them. See Rate limits.
Timestamps. ISO-8601, UTC, always as strings.
Sourcing. A contract is a ctr_… id, and no response on this surface names a venue. The last exception was the deprecated GET /api/v1/settlements/positions, which published a venueListingIdcarrying the source's name and its own id for the contract. It now publishes contractId like everything else. Webhook payloads are narrowed the same way.

Scopes

Scope	Reaches
`markets:read`	events, events/{id}, categories, GET users/{id}/jurisdiction
`quotes:write`	quotes
`orders:write`	POST orders, POST orders/{id}/confirm-reserve, POST orders/{id}/cancel, PUT users/{id}/jurisdiction, and the sandbox scenario control
`orders:read`	GET orders, orders/{id}, and the sandbox scenario list
`positions:read`	positions, positions/{id}
`settlements:read`	settlements, settlements/positions, and the sandbox resolution control
`ledger:read`	reconciliation, reconciliation/feed, and the sandbox balance and ledger
`funding:write`	all three funding routes, including the two reads