> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsidemax.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# updateLeverage: Set Per-Contract Leverage

> Adjust leverage for a specific contract. Reducing leverage triggers a margin check against existing positions to ensure requirements are met.

The `updateLeverage` action sets the leverage multiplier for a specific contract. Leverage controls the initial margin (IM) requirement for new and existing positions on that contract — higher leverage means a smaller margin requirement per unit of notional value.

Increasing leverage is always permitted. Decreasing leverage triggers a validation check: the exchange verifies that your existing position's margin can cover the higher IM implied by the lower leverage. If it cannot, the request is rejected and your leverage remains unchanged.

## Endpoint

```
POST https://dev.upsidemax.xyz/exchange
```

## Request

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

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

### Action fields

<ParamField body="type" type="string" required>
  Fixed value: `"updateLeverage"`.
</ParamField>

<ParamField body="a" type="int32" required>
  The contract ID to update leverage for.
</ParamField>

<ParamField body="leverage" type="int32" required>
  The new leverage value. Must be a positive integer and must not exceed the `tier0.maxLeverage` configured for the contract.
</ParamField>

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

## Response

### Success

```json theme={"system"}
{
  "status": "ok",
  "response": {
    "type": "updateLeverage",
    "data": { "leverageBefore": 10, "leverageAfter": 20 }
  }
}
```

### Rejection

```json theme={"system"}
{
  "status": "ok",
  "response": {
    "type": "updateLeverage",
    "data": {
      "leverageBefore": 0,
      "leverageAfter": 0,
      "errorCode": 3,
      "errorMessage": "leverage exceeds tier0.maxLeverage=50"
    }
  }
}
```

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

### Response fields

<ResponseField name="leverageBefore" type="int">
  The leverage setting for the contract before the update. Returns `0` on rejection.
</ResponseField>

<ResponseField name="leverageAfter" type="int">
  The leverage setting for the contract after the update. Returns `0` on rejection.
</ResponseField>

<ResponseField name="errorCode" type="int">
  Present only on rejection. Identifies the failure reason.
</ResponseField>

<ResponseField name="errorMessage" type="string">
  Present only on rejection. Human-readable description of the failure.
</ResponseField>

## Error reference

| `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 beyond your available margin for existing positions. |