Propose retiring a risk limit
Proposes the account row’s retirement (risk:propose); the account falls back to the default row. In force at once when the default is no looser on any threshold, else it collects approvals. The default row never retires (409). Answers the row.
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.
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; US-ASCII, at most 256 bytes.
Response
The risk limit as the platform now holds it after the write — the same row the read serves, with the answering change’s position, the row’s ETag and, on a replayed key, Idempotent-Replay.
The row’s version as a decimal string, bumped by every change, the ETag an entity write’s If-Match takes.
The account the row governs (GET /accounts); 0 is the organisation-wide default row, which governs every account without a row of its own and every threshold such a row leaves unstated.
PENDING_APPROVAL: a first proposal not yet approved, or withdrawn — it governs nothing. ACTIVE: in force. RETIRED: retired, the default governs again. The value set is append-only: read an unknown value as UNKNOWN.
money (an exact decimal string at the scale the row holds it, trailing zeros included): Gross leverage over derivatives and their resting orders past which the account is held to reducing its risk, as a ratio to the margin equity ("3" is 3x). "0" is no cap; null is not stated, which on an account’s row means the organisation-wide default’s value applies.
money (an exact decimal string at the scale the row holds it, trailing zeros included): Gross leverage over derivatives and their resting orders past which the account is blocked. "0" is no cap; null is not stated, which on an account’s row means the organisation-wide default’s value applies.
money (an exact decimal string at the scale the row holds it, trailing zeros included): Net leverage over derivatives and their resting orders past which the account is held to reducing its risk. "0" is no cap; null is not stated, which on an account’s row means the organisation-wide default’s value applies.
money (an exact decimal string at the scale the row holds it, trailing zeros included): Net leverage over derivatives and their resting orders past which the account is blocked. "0" is no cap; null is not stated, which on an account’s row means the organisation-wide default’s value applies.
money (an exact decimal string at the scale the row holds it, trailing zeros included): Gross leverage with the coins held and every resting order past which the account is held to reducing its risk. "0" is no cap; null is not stated, which on an account’s row means the organisation-wide default’s value applies.
money (an exact decimal string at the scale the row holds it, trailing zeros included): Gross leverage with the coins held and every resting order past which the account is blocked. "0" is no cap; null is not stated, which on an account’s row means the organisation-wide default’s value applies.
money (an exact decimal string at the scale the row holds it, trailing zeros included): The margin equity in USD (marginEquityUsd on the risk record: the equity of the account’s margin wallets — at Binance the spot and USD-M wallets together — not the account’s whole NLV) at or under which the account is blocked. "0" is no cap; null is not stated, which on an account’s row means the organisation-wide default’s value applies.
The maker of the row’s last proposal — an actor, kept on the record once it concludes or is withdrawn; null when the row has had none (the organisation-wide default the platform creates). Always a member’s: only members write risk. pendingTransition alone says whether a proposal is pending.
What the pending proposal proposes: ACTIVATE a first row, AMEND new thresholds on an active row, RETIRE its retirement; NONE when nothing is pending. On view=latest the thresholds are the proposed ones while it is pending; view=approved shows those in force.
When the row’s last proposal was made, epoch nanoseconds as a decimal string; null when none was.
When the row’s last proposal concluded, epoch nanoseconds as a decimal string — equal to proposedAtNs on one that only tightened and so concluded as it was submitted; null while it is pending, after a withdrawal, and on a row that has had none.
Who concluded it — the approver whose approval met the organisation’s risk rule in force, or the maker where nothing needed approving; null when concludedAtNs is.
What the row’s last proposal proposed, kept once it concluded — ACTIVATE, AMEND or RETIRE, however the row’s status has moved on since; NONE while it is pending, after a withdrawal, and on a row that has had none. The value set is append-only: treat an unknown name as unknown, never as an error.
Who approved the row’s last proposal and when, in approval order; empty until the first approval and after a withdrawal. It concludes when they number the organisation’s risk rule in force at that approval (GET /approval-rules?family=RISK).
The maker’s note on the last proposal; empty when none.
Who made the last withdrawn proposal; null when none was.
Who withdrew it — its maker, or an approver returning it; null when none was.
When it was withdrawn, epoch nanoseconds as a decimal string; null when none was.
Why it was withdrawn, as the withdrawer stated it; empty when none.
Who wrote this version, never null: a member, or the platform itself — MACHINE with id 0 — on the default row every organisation is given, every threshold "0".
The position as a decimal string — the last change this member had applied, orders, balance readings and algo instances included.