Skip to main content
POST
/
v1
/
setLeverage
Set leverage for a market
curl --request POST \
  --url https://api.testnet.arcus.xyz/v1/setLeverage \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --header 'X-Signature: <api-key>' \
  --header 'X-Timestamp: <api-key>' \
  --data '
{
  "address": "<string>",
  "marketId": 32767,
  "leverage": 500,
  "accountIndex": 4
}
'
{
  "requestId": "<string>",
  "address": "<string>",
  "accountIndex": 4,
  "marketId": 32767,
  "leverage": 2
}
Set per-(account, market) leverage. Requires address query parameter or JSON address field (must match X-API-Key’s master if both are present). leverage is an integer in [1, market max].

​
Response behavior

Asynchronous. The endpoint returns 200 OK (engine confirmed the change), 422 Unprocessable Entity (engine rejected — see rejectReason), or 202 Accepted (request forwarded but the firehose ack didn’t arrive within the timeout; the engine may still apply the change — observe the next accounts / positions WebSocket frame to confirm). Lowering leverage on an account with open positions can fail with UNDERCOLLATERALIZED if the higher initial margin requirement would push equity below required margin; the engine rolls back atomically on this path. Maintenance margin and liquidation price are unaffected by leverage changes — they depend on the market’s maintenanceMarginFraction, not the per-account leverage cap.

Authorizations

​
X-API-Key
string
header
required

Hex-encoded Ed25519 public key (64 chars). The public key IS the API key — register it via POST /createApiKey. Required on every authenticated request, both read-only and signed.

​
X-Timestamp
string
header
required

Unix time in nanoseconds as a decimal string (e.g. "1713825891591000000"). Millisecond or second epochs are rejected with 401 Unauthorized. Must be within ±30,000 ms (MaxTimestampDriftMs, the drift window stays configured in milliseconds) of server wall-clock, or the request is rejected with 401 Unauthorized. Required on all mutating / credential-creating endpoints. This same value must appear as the ct field in the ordersign typed canonical payload (single-order endpoints) or in each element's ct field (batch endpoints).

​
X-Signature
string
header
required

Lowercase hex-encoded Ed25519 signature (128 chars).

Single-order endpoints (placeOrder, cancelOrder, modifyOrder, and other non-batch mutating routes) sign over the ordersign typed canonical payload — a compact, key-sorted JSON object built from parsed request fields using engine-native integer values:

placeOrder:   {"ad":"0x…","ai":N,[,"c":"…"],"ct":N,"g":N,"m":N,"op":1,"p":N,"q":N,"r":0|1,"s":N,"t":N,"v":1}
cancelOrder:  {"ad":"0x…","ai":N,[,"c":"…"],"ct":N,[,"id":"…"],"m":N,"op":2,"v":1}
modifyOrder:  {"ad":"0x…","ai":N,[,"c":"…"],"ct":N,[,"id":"…"],"m":N,"op":3,"p":N,"q":N,"v":1}

ct must equal the X-Timestamp header value. Keys in brackets are conditional (omitted when empty). op values: 1=place, 2=cancel, 3=modify. See the ordersign package for field definitions and reference signing code.

Other signed routes (e.g. createApiKey, tokens, userPreferences) still use the legacy scheme: signing_message = X-Timestamp + ACTION + canonicalJSON(body), where ACTION is the camelCase final path segment.

Batch endpoints (batchPlaceOrders, batchCancelOrders) do NOT use this header. They authenticate with per-element typed ordersign signatures embedded in the request body (see the global auth description and the per-field signature descriptions on OrderRequest / CancelOrderRequest).

Read endpoints are authenticated by ?address= (and optionally X-API-Key) only — no signature is required. canonicalJSON(body) is the JSON body with object keys sorted lexicographically at every level and no whitespace; the server canonicalizes the received body before verifying, so only the bytes signed over must be canonical. Required on all mutating / credential-creating endpoints.

Query Parameters

​
address
string
required

Master Ethereum address for this API key (must match address from POST /createApiKey for the same key). Required on REST for account-scoped reads and for place/cancel. Invalid hex → 400; mismatch with key → 403.

20-byte EVM address as hex: optional 0x or 0X prefix and exactly 40 hexadecimal digits. API responses normalize to lowercase a–f after 0x.

Pattern: ^(0x|0X)?[0-9a-fA-F]{40}$

Body

application/json
​
address
string
required

Master EVM address for this account. May also be supplied via the ?address= query parameter; if both are present they must match. When X-API-Key is enforced the body / query address must match the key's master, otherwise the request is rejected with HTTP 403.

Pattern: ^(0x|0X)?[0-9a-fA-F]{40}$
​
marketId
integer
required

Perpetual market identifier (uint16). Map to display name via GET /markets. Used for orders, positions, funding, and market metadata.

Required range: 0 <= x <= 65535
​
leverage
integer
required

Leverage to set for this (account, market), e.g. 5 for 5x. Must be in [1, market max]. Values exceeding the market's max leverage (1 / InitialMarginFraction) are rejected with HTTP 400.

Required range: 1 <= x <= 1000
​
accountIndex
integer

Account index (account index, 0–9). Identifies the account for orders, positions, fills, and API keys.

Required range: 0 <= x <= 9

Response

Engine confirmed the leverage change (status: APPLIED). leverage reflects the applied value.

​
requestId
string
required

Server-generated UUID identifying this request in subsequent firehose / WebSocket events.

​
address
string
required

20-byte EVM address as hex: optional 0x or 0X prefix and exactly 40 hexadecimal digits. API responses normalize to lowercase a–f after 0x.

Pattern: ^(0x|0X)?[0-9a-fA-F]{40}$
​
accountIndex
integer
required

Account index (account index, 0–9). Identifies the account for orders, positions, fills, and API keys.

Required range: 0 <= x <= 9
​
marketId
integer
required

Perpetual market identifier (uint16). Map to display name via GET /markets. Used for orders, positions, funding, and market metadata.

Required range: 0 <= x <= 65535
​
leverage
integer
required

Effective leverage now in force for this (account, market). On APPLIED this is the requested value. On REJECTED this is the prior override if one exists, otherwise the market default (1 / InitialMarginFraction). On ACK this echoes the requested value without confirmation.

Required range: x >= 1
​
status
enum<string>
required

Engine-lifecycle marker for the setLeverage response body. Distinct from the HTTP status code, which is a transport-level signal.

  • ACK (HTTP 202): Kafka accepted the request; the engine has not yet confirmed. Not a failure — subscribe to the accountAttributes WebSocket channel for the engine-confirmed value.
  • APPLIED (HTTP 200): engine accepted the change. leverage reflects the applied value.
  • REJECTED (HTTP 422): engine rejected the change; see rejectReason. leverage is the effective leverage now in force — the prior override if one exists, otherwise the market default.
Available options:
ACK,
APPLIED,
REJECTED
​
rejectReason
enum<string>

Engine-side rejection reason, present on HTTP 422 responses:

  • UNDERCOLLATERALIZED: lowering leverage would push existing open positions below required margin. The override was rolled back and the response leverage field carries the unchanged prior value.
  • INVALID_LEVERAGE: the requested leverage is not in [1, market max] (market max = 1 / InitialMarginFraction).
  • UNKNOWN_MARKET: marketId is not configured.
Available options:
UNDERCOLLATERALIZED,
INVALID_LEVERAGE,
UNKNOWN_MARKET