curl --request POST \
--url https://api.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,
"isolated": true,
"accountIndex": 4
}
'import requests
url = "https://api.arcus.xyz/v1/setLeverage"
payload = {
"address": "<string>",
"marketId": 32767,
"leverage": 500,
"isolated": True,
"accountIndex": 4
}
headers = {
"X-API-Key": "<api-key>",
"X-Timestamp": "<api-key>",
"X-Signature": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-API-Key': '<api-key>',
'X-Timestamp': '<api-key>',
'X-Signature': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
address: '<string>',
marketId: 32767,
leverage: 500,
isolated: true,
accountIndex: 4
})
};
fetch('https://api.arcus.xyz/v1/setLeverage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.arcus.xyz/v1/setLeverage",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'address' => '<string>',
'marketId' => 32767,
'leverage' => 500,
'isolated' => true,
'accountIndex' => 4
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>",
"X-Signature: <api-key>",
"X-Timestamp: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.arcus.xyz/v1/setLeverage"
payload := strings.NewReader("{\n \"address\": \"<string>\",\n \"marketId\": 32767,\n \"leverage\": 500,\n \"isolated\": true,\n \"accountIndex\": 4\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("X-Timestamp", "<api-key>")
req.Header.Add("X-Signature", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.arcus.xyz/v1/setLeverage")
.header("X-API-Key", "<api-key>")
.header("X-Timestamp", "<api-key>")
.header("X-Signature", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"address\": \"<string>\",\n \"marketId\": 32767,\n \"leverage\": 500,\n \"isolated\": true,\n \"accountIndex\": 4\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.arcus.xyz/v1/setLeverage")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["X-Timestamp"] = '<api-key>'
request["X-Signature"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"address\": \"<string>\",\n \"marketId\": 32767,\n \"leverage\": 500,\n \"isolated\": true,\n \"accountIndex\": 4\n}"
response = http.request(request)
puts response.read_body{
"requestId": "<string>",
"address": "<string>",
"accountIndex": 4,
"marketId": 32767,
"leverage": 2,
"status": "ACK",
"marginMode": "CROSS",
"rejectReason": "UNDERCOLLATERALIZED"
}{
"requestId": "<string>",
"address": "<string>",
"accountIndex": 4,
"marketId": 32767,
"leverage": 2,
"status": "ACK",
"marginMode": "CROSS",
"rejectReason": "UNDERCOLLATERALIZED"
}{
"error": "Invalid request body",
"code": "GEO_RESTRICTED",
"errorSource": "Order",
"errorType": "Tick",
"rejectionReason": "POST_ONLY_WOULD_CROSS"
}{
"error": "Invalid request body",
"code": "GEO_RESTRICTED",
"errorSource": "Order",
"errorType": "Tick",
"rejectionReason": "POST_ONLY_WOULD_CROSS"
}{
"error": "Invalid request body",
"code": "GEO_RESTRICTED",
"errorSource": "Order",
"errorType": "Tick",
"rejectionReason": "POST_ONLY_WOULD_CROSS"
}{
"requestId": "<string>",
"address": "<string>",
"accountIndex": 4,
"marketId": 32767,
"leverage": 2,
"status": "ACK",
"marginMode": "CROSS",
"rejectReason": "UNDERCOLLATERALIZED"
}{
"error": "rate limited",
"reason": "account_empty",
"retryAfterMs": 850,
"clientId": "my-order-42"
}{
"error": "Invalid request body",
"code": "GEO_RESTRICTED",
"errorSource": "Order",
"errorType": "Tick",
"rejectionReason": "POST_ONLY_WOULD_CROSS"
}{
"error": "Invalid request body",
"code": "GEO_RESTRICTED",
"errorSource": "Order",
"errorType": "Tick",
"rejectionReason": "POST_ONLY_WOULD_CROSS"
}Set leverage for a market
Set per-(account, market) leverage.
curl --request POST \
--url https://api.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,
"isolated": true,
"accountIndex": 4
}
'import requests
url = "https://api.arcus.xyz/v1/setLeverage"
payload = {
"address": "<string>",
"marketId": 32767,
"leverage": 500,
"isolated": True,
"accountIndex": 4
}
headers = {
"X-API-Key": "<api-key>",
"X-Timestamp": "<api-key>",
"X-Signature": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-API-Key': '<api-key>',
'X-Timestamp': '<api-key>',
'X-Signature': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
address: '<string>',
marketId: 32767,
leverage: 500,
isolated: true,
accountIndex: 4
})
};
fetch('https://api.arcus.xyz/v1/setLeverage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.arcus.xyz/v1/setLeverage",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'address' => '<string>',
'marketId' => 32767,
'leverage' => 500,
'isolated' => true,
'accountIndex' => 4
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>",
"X-Signature: <api-key>",
"X-Timestamp: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.arcus.xyz/v1/setLeverage"
payload := strings.NewReader("{\n \"address\": \"<string>\",\n \"marketId\": 32767,\n \"leverage\": 500,\n \"isolated\": true,\n \"accountIndex\": 4\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("X-Timestamp", "<api-key>")
req.Header.Add("X-Signature", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.arcus.xyz/v1/setLeverage")
.header("X-API-Key", "<api-key>")
.header("X-Timestamp", "<api-key>")
.header("X-Signature", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"address\": \"<string>\",\n \"marketId\": 32767,\n \"leverage\": 500,\n \"isolated\": true,\n \"accountIndex\": 4\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.arcus.xyz/v1/setLeverage")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["X-Timestamp"] = '<api-key>'
request["X-Signature"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"address\": \"<string>\",\n \"marketId\": 32767,\n \"leverage\": 500,\n \"isolated\": true,\n \"accountIndex\": 4\n}"
response = http.request(request)
puts response.read_body{
"requestId": "<string>",
"address": "<string>",
"accountIndex": 4,
"marketId": 32767,
"leverage": 2,
"status": "ACK",
"marginMode": "CROSS",
"rejectReason": "UNDERCOLLATERALIZED"
}{
"requestId": "<string>",
"address": "<string>",
"accountIndex": 4,
"marketId": 32767,
"leverage": 2,
"status": "ACK",
"marginMode": "CROSS",
"rejectReason": "UNDERCOLLATERALIZED"
}{
"error": "Invalid request body",
"code": "GEO_RESTRICTED",
"errorSource": "Order",
"errorType": "Tick",
"rejectionReason": "POST_ONLY_WOULD_CROSS"
}{
"error": "Invalid request body",
"code": "GEO_RESTRICTED",
"errorSource": "Order",
"errorType": "Tick",
"rejectionReason": "POST_ONLY_WOULD_CROSS"
}{
"error": "Invalid request body",
"code": "GEO_RESTRICTED",
"errorSource": "Order",
"errorType": "Tick",
"rejectionReason": "POST_ONLY_WOULD_CROSS"
}{
"requestId": "<string>",
"address": "<string>",
"accountIndex": 4,
"marketId": 32767,
"leverage": 2,
"status": "ACK",
"marginMode": "CROSS",
"rejectReason": "UNDERCOLLATERALIZED"
}{
"error": "rate limited",
"reason": "account_empty",
"retryAfterMs": 850,
"clientId": "my-order-42"
}{
"error": "Invalid request body",
"code": "GEO_RESTRICTED",
"errorSource": "Order",
"errorType": "Tick",
"rejectionReason": "POST_ONLY_WOULD_CROSS"
}{
"error": "Invalid request body",
"code": "GEO_RESTRICTED",
"errorSource": "Order",
"errorType": "Tick",
"rejectionReason": "POST_ONLY_WOULD_CROSS"
}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 returns200 OK (engine confirmed the change), 422 Unprocessable Entity (engine rejected — see rejectReason), or 202 Accepted (request forwarded but the confirmation 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
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 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).
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,"g":N,[,"id":"…"],"m":N,"op":3,"p":N,"q":N,"r":0|1,"s":N,"t":N,"v":1} (exactly one of id / c)
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) still use the legacy scheme: signing_message = X-Timestamp + ACTION + canonicalJSON(body), where ACTION is the camelCase final path segment.
Batch endpoints (batchPlaceOrders, batchCancelOrders, batchModifyOrders) 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 / ModifyOrderRequest).
Read endpoints are authenticated by ?address= (and optionally X-API-Key) only — no signature is required, except for the signed affiliate reads (see the Referral tag), which require the full header triple; with no body their signing message is X-Timestamp + ACTION. 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
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.
^(0x|0X)?[0-9a-fA-F]{40}$Body
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.
^(0x|0X)?[0-9a-fA-F]{40}$Optional. When present, also sets the margin mode for this (account, market): true switches to isolated margin mode, false switches to cross margin mode. A cross → isolated switch is rejected with HAS_OPEN_POSITION if the account already has an open position in that market. The reverse (isolated → cross) and any no-op change are always accepted. Omit to leave the current margin mode unchanged.
Response
Engine confirmed the leverage change (status: APPLIED). leverage reflects the applied value.
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.
x >= 1Engine-lifecycle marker for the setLeverage response body. Distinct from the HTTP status code, which is a transport-level signal.
ACK(HTTP 202): the request was accepted; the engine has not yet confirmed. Not a failure — subscribe to theaccountAttributesWebSocket channel for the engine-confirmed value.APPLIED(HTTP 200): engine accepted the change.leveragereflects the applied value.REJECTED(HTTP 422): engine rejected the change; seerejectReason.leverageis the effective leverage now in force — the prior override if one exists, otherwise the market default.
ACK, APPLIED, REJECTED 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 responseleveragefield carries the unchanged prior value.INVALID_LEVERAGE: the requested leverage is not in[1, market max](market max = 1 / InitialMarginFraction).UNKNOWN_MARKET:marketIdis not configured.HAS_OPEN_POSITION:isolated: truewas requested but the account already has an open position in this market. Close the position first, then switch to isolated mode.
UNDERCOLLATERALIZED, INVALID_LEVERAGE, UNKNOWN_MARKET, HAS_OPEN_POSITION Was this page helpful?