Skip to navigation

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

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

idintegerRequired

The record’s id — a positive 32-bit integer the platform minted.

Headers

Idempotency-KeystringRequired

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.

If-MatchstringRequired

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.

X-Request-IdstringOptional

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

minGlobalSequencestringOptionalformat: "^[0-9]{1,19}$"

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

This endpoint expects an object.
remarkstringOptional<=256 characters

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.

riskLimitIdinteger
The row's id.
versionstringformat: "^-?[0-9]+$"

The row’s version as a decimal string, bumped by every change, the ETag an entity write’s If-Match takes.

accountIdinteger>=0

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.

statusenum

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.

Allowed values:
grossLeverageNoSpotSoftstring or nullformat: "^-?[0-9]+(\.[0-9]+)?$"<=64 characters

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.

grossLeverageNoSpotHardstring or nullformat: "^-?[0-9]+(\.[0-9]+)?$"<=64 characters

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.

netLeverageNoSpotSoftstring or nullformat: "^-?[0-9]+(\.[0-9]+)?$"<=64 characters

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.

netLeverageNoSpotHardstring or nullformat: "^-?[0-9]+(\.[0-9]+)?$"<=64 characters

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.

grossLeverageWithSpotSoftstring or nullformat: "^-?[0-9]+(\.[0-9]+)?$"<=64 characters

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.

grossLeverageWithSpotHardstring or nullformat: "^-?[0-9]+(\.[0-9]+)?$"<=64 characters

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.

marginEquityFloorUsdstring or nullformat: "^-?[0-9]+(\.[0-9]+)?$"<=64 characters

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.

proposedByobject or null

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.

pendingTransitionenum

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.

Allowed values:
proposedAtNsstring or nullformat: "^-?[0-9]+$"

When the row’s last proposal was made, epoch nanoseconds as a decimal string; null when none was.

concludedAtNsstring or nullformat: "^-?[0-9]+$"

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.

concludedByobject or null

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.

concludedTransitionenum

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.

Allowed values:
approvalslist of objects

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).

remarkstring

The maker’s note on the last proposal; empty when none.

lastWithdrawalProposedByobject or null

Who made the last withdrawn proposal; null when none was.

lastWithdrawalWithdrawnByobject or null

Who withdrew it — its maker, or an approver returning it; null when none was.

lastWithdrawalAtNsstring or nullformat: "^-?[0-9]+$"

When it was withdrawn, epoch nanoseconds as a decimal string; null when none was.

lastWithdrawalReasonstring

Why it was withdrawn, as the withdrawer stated it; empty when none.

updatedAtNsstringformat: "^-?[0-9]+$"
When this version was written, epoch nanoseconds as a decimal string.
updatedByobject

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".

globalSequencestringOptionalformat: "^[0-9]+$"

The position as a decimal string — the last change this member had applied, orders, balance readings and algo instances included.

Errors

400
Retire Limit Risk Request Bad Request Error
401
Retire Limit Risk Request Unauthorized Error
403
Retire Limit Risk Request Forbidden Error
404
Retire Limit Risk Request Not Found Error
409
Retire Limit Risk Request Conflict Error
412
Retire Limit Risk Request Precondition Failed Error
413
Retire Limit Risk Request Content Too Large Error
422
Retire Limit Risk Request Unprocessable Entity Error
428
Retire Limit Risk Request Precondition Error
429
Retire Limit Risk Request Too Many Requests Error
500
Retire Limit Risk Request Internal Server Error
503
Retire Limit Risk Request Service Unavailable Error