Concepts
This page is the map; the REST API guide and the references are the territory. Each section links to the rules it summarises.
Organisations and principals
Everything you do, you do as a user of one organisation, and both come from your token and the
platform’s records. No request names an organisation or a user: every read is scoped to your
organisation by construction, and every write is stamped with the user who made it. Another
organisation’s record answers 404, exactly as if it did not exist.
Principals
Admission and capabilities
A verified token is not yet a member. Your first request registers you, and an administrator of
your organisation admits you by granting capabilities: scope strings of the form
resource:verb, each standing alone. There are no roles — presets only expand to a set of
capabilities when they are granted. A write your capabilities do not cover is refused.
Authentication and admission
Maker-checker
Most records live under dual control. Creating or amending a credential, an account or a policy lands as a proposal, and a second user holding that resource’s approve capability concludes it — the proposer cannot approve their own. Reads can show you either side: the proposed content under review, or what the platform enforces now. Maker-checker
Reads: positions and versions
Every read tells you where in the platform’s history it was served from — the
X-Immix-Global-Sequence header — and an entity read tells you the row’s version in its ETag.
A reader at a position has seen every change at or before it. Reads
Writes: idempotency and preconditions
Every write carries an Idempotency-Key, so a retry never acts twice: it replays the answer the
first attempt got. Entity writes carry the ETag you read as If-Match, so two editors working
from stale copies cannot silently overwrite each other. A write the platform has accepted but not
yet answered returns 202, and you poll its operation for the outcome.
Writes
Money and ids
Money is a decimal string, in and out, at the precision the platform holds it — parse it with a decimal type and never through a float. Large ids, versions and timestamps are decimal strings too, because they exceed what a JSON number holds exactly. Money · Ids, sentinels, enums and sets
Evolution
The API grows by addition. Enumerations only ever gain values: read an unknown value as the field’s unset value, never as an error. Each API carries its own semantic version, and its changelog records every change. Versioning · Changelog
Market data
One WebSocket connection carries every topic you subscribe to. A topic streams raw — every
update — or conflated at a fixed tier. Latest-image topics (top of book, mark, funding, open
interest, ticker) push their current image when you subscribe, once the gateway holds one. Books
follow a sync contract: a book is syncing until the gateway holds it synced, and a stale marker
means the book must not be trusted until the restatement that follows. A heartbeat carries the
stream’s freshness, and a session that falls behind is disconnected rather than throttled —
reconnect and subscribe again.
Market Data WebSocket reference