Skip to main content
POST
cURL

Authorizations

X-Monaco-Signature
string
header
required

Ed25519 session-key request signing. Every authenticated request carries three headers: X-Monaco-PublicKey (64-char lowercase-hex session public key), X-Monaco-Timestamp (Unix milliseconds, within 30s of server time), and X-Monaco-Signature (hex ed25519 signature). The signature is over METHOD\npath?query\ntimestamp_ms\nSHA256_hex(body), where the body hash is the SHA-256 of the empty byte string when there is no body. Obtain the session keypair from POST /api/v1/auth/challenge followed by POST /api/v1/auth/verify.

Body

application/json
asset
string | null
amount
string | null
tradingPairId
string<uuid> | null

Trading pair UUID whose isolated risk bucket receives collateral. Required for isolated risk buckets; omitted for cross risk buckets.

strategyKey
string | null
marginMode
string | null

Risk bucket mode. Defaults to ISOLATED. Values: ISOLATED, CROSS. A CROSS transfer names no pairs: the cross bucket's scope is derived from trading — a pair joins when a cross order on it succeeds and leaves when its positions close — so funding the bucket has nothing to declare.

selectedTradingPairIds
string<uuid>[] | null
deprecated

Deprecated: accepted and ignored. Cross scope is derived from trading (a pair joins the cross bucket when a cross order on it succeeds; after its positions close it stays listed until a later successful cross order on another pair reconciles the bucket), so a cross transfer-in has nothing to declare and can no longer replace the scope. Rejected for ISOLATED, as before. Read the current scope from the cross bucket's row in the margin-accounts list or from this response's selectedTradingPairIds; the parent row carries no scope. Pairs declared before scope became derived stay recorded until they trade and their positions close.

Minimum string length: 1
applyToPositionMargin
boolean | null

What the transferred collateral becomes when the ISOLATED bucket holds an open position. The two intents want opposite fates for the same dollars, so the caller states theirs:

  • true (and UNSET — the default is the human "Adjust Margin" gesture): the amount is COMMITTED to the position's stored margin. Effective leverage drops and stays down, initial margin required rises by the amount, free collateral is unchanged — new orders cannot spend it.
  • false: plain allocation. Free collateral rises and the next order can spend it. Programmatic funding loops that top a bucket up to a free collateral target MUST pass false, or each top-up converts into requirement and the loop never converges.

Either way the liquidation cushion improves identically (the breach check is bucket-equity based). On a FLAT isolated bucket there is no position to commit to and both values are a plain allocation. Explicit true is rejected for CROSS buckets (cross has no per-position margin); unset/false is a plain allocation there.

The response reports what actually happened in position_margin_credited — a credit can degrade to a plain allocation when the persisted position row is stale (close/reopen race).

Response

OK

movementId
string | null
marginAccountId
string | null
asset
string | null
amount
string | null
status
string | null
newEquity
string | null
newTotalCollateralValue
string | null
newWithdrawableCollateral
string | null

The largest amount a further transfer-out will accept after this one. See MarginAccountSummary.withdrawable_collateral: this is an allocation-bounded figure, not clamped equity headroom.

strategyKey
string | null
riskBucketId
string | null

Present when collateral was allocated to a risk bucket.

marginMode
string | null

Present when collateral was allocated to a risk bucket. Values: ISOLATED, CROSS.

selectedTradingPairIds
string<uuid>[] | null

The cross bucket's recorded pair scope: what trading has recorded (a pair joins when a cross order on it fills and leaves when its positions close), plus any pair declared before scope became derived, until it trades and its positions close. Only on cross risk-bucket transfers, and omitted while empty — i.e. until a cross order on the bucket has filled.

Minimum string length: 1
positionMarginCredited
boolean | null

Whether the transfer was committed to a position's stored margin. Present only when a position-margin credit was in play: true — the credit landed; false — a credit was requested (or defaulted) but degraded to a plain allocation because the bucket's persisted position row was stale (close/reopen race) — re-issue the Adjust Margin once the new position row lands if the commitment still matters. Absent on plain allocations, parent deposits, and releases.