Update Leverage

The updateLeverage action sets your account’s leverage for a specific contract. The new leverage sets the initial margin (IM) requirement of positions opened after the change — higher leverage means a smaller margin requirement per unit of notional value. Lowering leverage triggers a validation check: the server verifies that your available margin still covers the IM of your existing position at the new, lower leverage. If it does not, the request is rejected (leverage downgrade IM insufficient) and your leverage remains unchanged. For accounts in PORTFOLIO margin mode the check uses the share group’s margin. Read the leverage currently in effect from positions[].leverage in userAccount.

Endpoint

POST https://upsidemax.xyz/exchange

Request

All requests must include an ECDSA signature and a millisecond-precision nonce.

{
  "action": {
    "type": "updateLeverage",
    "a": 1,
    "leverage": 20
  },
  "signature": { "r": "0x...", "s": "0x...", "v": 28 },
  "nonce": 1778858800000
}

Action fields

string

required

type (required) — Fixed value: "updateLeverage".

int32

required

a (required) — The contract ID to update leverage for.

int32

required

leverage (required) — The new leverage value. Must be a positive integer and must not exceed the tier0.maxLeverage configured for the contract. 0 returns 400 INVALID_PARAM.

Use the configs query (POST /info) to retrieve the tier0.maxLeverage for each contract before calling this action.

Response

Success

{
  "status": "ok",
  "response": {
    "type": "updateLeverage",
    "data": { "leverageBefore": 10, "leverageAfter": 20 }
  }
}

Rejection

{
  "status": "ok",
  "response": {
    "type": "updateLeverage",
    "data": {
      "leverageBefore": 0,
      "leverageAfter": 0,
      "errorCode": 3,
      "errorMessage": "leverage exceeds tier0.maxLeverage=<n>"
    }
  }
}

Rejections still return HTTP 200 with status: "ok". Check for the presence of errorCode in data to detect failures.

Response fields

int

The leverage setting for the contract before the update. Returns 0 on rejection — read the current value from userAccount instead.

int

The leverage setting for the contract after the update. Returns 0 on rejection.

number

Present only on rejection. Identifies the failure reason; a non-zero value means the request was rejected and nothing changed.

string

Present only on rejection. Human-readable description of the failure.

Errors

Rejections

`errorMessage`	Cause
`invalid leverage`	`leverage` was `0` or negative.
`leverage exceeds tier0.maxLeverage=<n>`	The requested leverage exceeds the maximum allowed for this contract, where `<n>` is the configured limit.
`leverage downgrade IM insufficient`	Decreasing leverage would raise the initial margin requirement of your existing position beyond your available margin. The change is rolled back.

HTTP errors

HTTP	`code`	Cause
400	`INVALID_PARAM`	A field failed validation — for example `leverage` of `0`. `errors[]` names the field, the `reason`, and the `expected` value. Nothing is executed.
400	`BAD_REQUEST`	Malformed body, or the signer has no registered account.
400	`SYNC_NOT_APPLICABLE`	The envelope carried `sync`. This action always answers synchronously.
400	`DUPLICATE_NONCE`	A request with the same `nonce` from this signer is still in flight.
401	`SIGNATURE_INVALID`	Signature recovery failed or did not match.
429	`RATE_LIMITED`	Too many requests.
503	`DOWNSTREAM_UNAVAILABLE` / `WARMING_UP`	Temporarily unavailable; retry later.
504	`DOWNSTREAM_TIMEOUT`	No result within the waiting window. The leverage may already have changed — check `userAccount` before retrying; see Timeouts and retries.

Overview

Account

Orders

Margin & Leverage

Conditional Orders

Collateral Transfers

API Wallet

Endpoint

Request

Action fields

Response

Success

Rejection

Response fields

Errors

Rejections

HTTP errors

​Endpoint

​Request

​Action fields

​Response

​Success

​Rejection

​Response fields

​Errors

​Rejections

​HTTP errors

Endpoint

Request

Action fields

Response

Success

Rejection

Response fields

Errors

Rejections

HTTP errors