Enable a key
Proposes enabling a disabled key (accounts:propose) — a change on the account’s slot (0.65.0): the answer is the account row, KEY_CHANGE pending (at an accounts count of 0, concluded at once), the key ENABLE in keys[]; a second user’s POST /accounts/{id}/approve concludes it, /withdraw returns it. Another change pending on the account is 409 PROPOSAL_PENDING.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
The record’s id — a positive 32-bit integer the platform minted.
The key’s id beneath the account — keyId on the account row’s keys[], credentialId on its own row; a key of another account is 404.
Headers
Required on every write: a URL-safe string of 1 to 64 characters from [A-Za-z0-9._~-] (a UUID fits), scoped to you. It names one operation on one record, ever: a retry replays the stored outcome (Idempotent-Replay: true) or attaches to the live one, and reuse on another record refuses 409 IDEMPOTENCY_KEY_REUSED. Missing or malformed, 400.
Required on every entity write: the ETag the read minted, quoted or bare — the version this write was computed against — or * to write unconditionally on purpose, except on a notification endpoint’s approval, which refuses * 400 INVALID_IF_MATCH. Absent is 428 PRECONDITION_REQUIRED; a weak validator 400 INVALID_IF_MATCH; a stale value 412 VERSION_CONFLICT (CONFIG_SEQ_CONFLICT on an algo’s config write) with currentVersion and a fresh ETag: re-read, reapply, retry. A * write overwrites every field from your copy, a colleague’s amend since your read included.
Your own id for the request: 8 to 128 of [A-Za-z0-9._-]. It becomes the request’s id and is echoed on the response. A value off that grammar is replaced with a fresh id, never refused.
Query parameters
A position you hold — an X-Immix-Global-Sequence you read, or a 202’s commandGlobalSequence: this member answers only once it has folded the platform’s stream through it, waiting up to its deadline, then 503 PROJECTION_BEHIND with Retry-After. Within that stream a read is never older than what you have seen; drop your positions after an announced stream cut. A retry stating its 202’s position attaches to or replays that operation while the journal holds its key, never publishing twice. Stated once: one to nineteen digits, at most 9223372036854775807; else 400 MALFORMED_REQUEST.
Request
A note for the approvers of this proposal; empty-not-null. At most 256 bytes; longer refuses INVALID_FIELD. Optional in this body: absent reads as "".
Response
The account as the platform now holds it after the write — the account’s own, or (0.65.0) one of its keys’ — the same row the read serves, with the answering change’s position, the account’s ETag (what a key’s write never takes in If-Match: that is keys[].version), on a key write Location (the key’s own route) and, on a replayed key, Idempotent-Replay.
Who approved the row’s last proposal and when, in approval order — grown by each approval and kept on the concluded row as its record until the next proposal or a withdrawal clears it; empty until the first approval. The proposal concludes at the approval that meets the organisation’s count for the family as it stands then; pendingTransition says whether one is pending. a repeating group served as an array of objects, in the group’s own order; empty = no entries, never null
Derived from the keys beneath the account (keys[]) as enforcement reads them: trade is the account’s own key where it trades, transfer its transfers key — a pending key changes nothing here until it is approved. It is derived, not decided: it changes with the keys’ records and their health without the row’s version moving, and it reads the same on both views.
What the row’s last proposal proposed, kept once it concluded: the pending transition the conclusion cleared, as the register wrote it (KEY_CHANGE, since v21, a key’s change — the key’s own concludedTransition says which); NONE while it pends, or where none was. NONE is the unset sentinel: outputs only — as input the field is required, and explicit NONE refuses 400. A consumer READING this field treats an unknown name as NONE, never as an error; as input an unknown name refuses 400 — the parse is strict
The account’s reading through the key that reads it (its own key while ACTIVE, else its transfers key standing in): CONNECTING until the first answer, then the probe’s or the connector’s word — CONNECTED, DEGRADED or DOWN with its reason (IP_NOT_WHITELISTED, AUTH_FAILED, ACCOUNT_EXISTS when another live account of the organisation already holds that venue account, ACCOUNT_DISABLED, …). A DOWN reading stays on the row for the member to read, and the periodic re-probe recovers it once the venue answers. Null once the account is DELETED.
The account’s name, as a person states it. At most 64 bytes; longer refuses INVALID_FIELD.
The position as a decimal string — the last change this member had applied, orders, balance readings and algo instances included.
The account’s live keys, ascending by keyId, never a deleted one; GET /accounts/{id}/keys/{keyId} serves the whole row. On the latest view each key’s latest image: a change pending on the account’s slot (pendingTransition KEY_CHANGE, 0.65.0) shows as the key’s own transition and image — a rotation’s incoming fingerprint and observed, an amend’s name, flags and rotateByNs (0.70.0), an enable, a delete, a new key. On ?view=approved each key as enforcement reads it; the two agree while nothing pends. Readings move without the row’s version; a key change moves it.
Why the last proposal was withdrawn, as the withdrawer stated it; empty-not-null.
The owning org — stamped by the owner from the maker’s org, never client-supplied.
Whose value the account holds; HOUSE unless stated otherwise. UNKNOWN is the unset sentinel: outputs only — as input the field is required, and explicit UNKNOWN refuses 400. A consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict
On a sub-account, the organisation’s account for the parent the key probe stated (parentExternalRef), else null — derived at the read, never recorded.
The venue’s identifier for the account this one is a sub-account of, as the key probe stated it; empty for a main account, or until a probe answers. The organisation’s row for it, where one exists, is served beside it as parentAccountId. At most 256 bytes; longer refuses INVALID_FIELD.
ACTIVATE (the connection), AMEND (a re-statement — the proposed axes ride this record while the last approved record keeps enforcing), ENABLE, DELETE, KEY_CHANGE (since v21 a change to one of the account’s keys — added, amended, rotated, enabled or deleted; the key’s own pendingTransition says which); NONE otherwise. NONE is the unset sentinel: outputs only — as input the field is required, and explicit NONE refuses 400. A consumer READING this field treats an unknown name as NONE, never as an error; as input an unknown name refuses 400 — the parse is strict
What the account is for; TREASURY unless stated otherwise. UNKNOWN is the unset sentinel: outputs only — as input the field is required, and explicit UNKNOWN refuses 400. A consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict
When the account was last read: the latest account report on the key that reads it (the account’s own key while ACTIVE, else its transfers key standing in) — its health.account.reportedAtNs while CONNECTED, or DEGRADED for a reason other than RATE_LIMITED and VENUE_UNAVAILABLE, and only after the status’s first report (transitionAtNs); null otherwise — DOWN, those two, unreported — and once DELETED. The one clock to age for an account: a time that stops is a connector stopped silently; null: the report shows no clean read, health.account saying why.
The maker’s note on the pending proposal, for its approvers; empty-not-null. At most 256 bytes; longer refuses INVALID_FIELD.
UNKNOWN is the unset sentinel: outputs only — as input the field is required, and explicit UNKNOWN refuses 400. A consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict
The order-entry connector’s reading on the account’s trading key; null when no key trades the account.
The venue’s own identifier for this account (an OKX uid, a Bybit UID), filled by the first key probe that answers; empty until then. Unique among the organisation’s live accounts at the venue. At most 256 bytes; longer refuses INVALID_FIELD.
Platform time the row’s last proposal concluded; 0 while it is pending, or when the row never carried one. A write the organisation’s count let through at once concludes in the maker’s own fact: equal to proposedAtNs. int64 as a decimal JSON string
Who concluded the row’s last proposal: the approver whose approval met the organisation’s count, or the maker when the count was 0 and the write concluded at once; null while it is pending, or when the row never carried one. an actor: an object {kind, id}; null where none is stated
The venue the account is at — the exchange its keys are keys of.
When an API key made the row’s last proposal, the member the key’s secret had last been answered to as it proposed — its last rotator then, else its issuer — kept on the concluded row with proposedBy; null when a member made the proposal, or the row never carried one. The proposal counts as this member’s and the key’s issuer’s, whoever rotates the key afterwards: neither may approve it (SELF_APPROVAL). an actor: an object {kind, id}; null where none is stated
Platform time of that withdrawal; 0 when none was. The three fields and lastWithdrawalReason stand until the next proposal replaces them. int64 as a decimal JSON string
Who made the last proposal that was withdrawn; null when none was. an actor: an object {kind, id}; null where none is stated
Who withdrew it — the proposer, or a checker returning it; null when none was. an actor: an object {kind, id}; null where none is stated
Single assignment in the POC; 0 = unassigned.
Platform time the row’s last proposal was made, kept on the concluded row; 0 when the row never carried one. int64 as a decimal JSON string
Who made the row’s last proposal — kept on the concluded row as its record; null when the row never carried one. pendingTransition says whether that proposal is still pending. an actor: an object {kind, id}; null where none is stated