POST /account/margin
Add or remove isolated margin on an open position
Add or remove isolated margin on an open position.
operationId: addMargin · CCXT method: addMargin
Declared server:
https://api.testnet.nexus.xyz/v1. See Networks.
Authentication: agentAuth, hmacAuth.
HMAC API key authentication. Send three headers:
X-API-Key: your key ID (e.g.nx_a1b2c3...)X-Timestamp: current time in unix millisecondsX-Signature:hex(hmac_sha256(secret, timestamp + "\n" + METHOD + "\n" + path + "\n" + query + "\n" + sha256_hex(body)))
Timestamp must be within 30 seconds of server time.
The key is network-scoped; the signature is not. The canonical string above has no network component, so the same signed request is byte-identical on every host. What stops a testnet key from authenticating against mainnet is that the key does not exist in that host's key store — sign only for the host that minted the key, and never replay a signed payload against another network. Presented to the wrong host, a key is refused with the same opaque 401 as an unknown key and must not be retried there. See “API keys are bound to one network” in the API description.
Updated allocated margin and account collateral after the adjustment.
Allocated margin and free collateral after an isolated-margin adjustment. A 200 means the adjustment is recorded, with the collateral and the allocated margin moved together, and all three fields are always present. Position reads can show the previous allocated margin until the engine's copy catches up.
The market whose position was adjusted.
BTC-USDX-PERPArbitrary-precision decimal serialized as a string (lossless). Parse with a decimal type, never a float.
Arbitrary-precision decimal serialized as a string (lossless). Parse with a decimal type, never a float.
Invalid amount, position not in isolated mode (MarginModeNotIsolated), or removal breaches the withdrawal floor / exceeds collateral (InsufficientMargin / InsufficientBalance).
Authentication failed. All 401 responses return the same opaque body to prevent information leakage. A credential minted on a different network is one of the causes it hides — by design, so that a key id cannot be probed for existence on another network. Do not retry it against another host.
Refused by a jurisdiction control. Permanent for the caller's origin — do not retry. Branch on the code (identical to the x-nexus-block-reason header): US_RESTRICTED for the US write restriction, GEO_UNRESOLVED when the origin could not be resolved and the write failed closed, or RESTRICTED_JURISDICTION for the sanctions list. Reads are never refused by the write restriction. See “Jurisdiction restrictions” in the API description.
No open position for the account in this market (NoOpenPosition). Risk folds every published fill before it decides, so a position whose opening fill is still being made durable answers 503 (MarketUnavailable) instead. A market whose risk view is lagged answers this, because a retry there would not succeed until the venue restarts.
Rate limit exceeded. Retryable — honour retry-after and back off; this is what separates a 429 from the permanent 403 jurisdiction refusals. Branch on the body's code, which is always RATE_LIMIT_EXCEEDED, and on bucket to learn WHICH budget bottlenecked — the buckets are independent, so a caller at its read ceiling can still submit orders and should not back off the whole client. Do not parse message: it is a diagnostic whose wording is not stable. Requests are charged by weight, so exhausting a budget takes fewer heavy calls than x-ratelimit-limit suggests. See “Rate limits” in the API description.
Risk sees no position for the account in this market while a commit on the market is still being made durable, so a fill may be opening it (MarketUnavailable). Nothing changed; retry. The check is per market, so an account with no position can briefly get this too while another account's fill on the market commits.
POST /v1/account/margin HTTP/1.1
Host: api.testnet.nexus.xyz
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 62
{
"market_id": "BTC-USDX-PERP",
"amount": "100",
"direction": "add"
}{
"market_id": "BTC-USDX-PERP",
"allocated_margin": "350.00",
"collateral": "9900.00"
}Test it cannot sign this request. X-Signature is an HMAC computed per call: see Authentication, or use an SDK.
API version 0.9.122
Last updated