> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.immix.xyz/guides/concepts/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.immix.xyz/_mcp/server.

# Concepts

This page is the map; the [REST API guide](/guides/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](/guides/rest-api-guide#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](/guides/rest-api-guide#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](/guides/rest-api-guide#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](/guides/rest-api-guide#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](/guides/rest-api-guide#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](/guides/rest-api-guide#money) ·
[Ids, sentinels, enums and sets](/guides/rest-api-guide#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](/guides/rest-api-guide#versioning) ·
[Changelog](/changelog/overview)

## 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](/api-reference/market-data/overview)

> The ideas the API is built on, each linked to its full rules