Update Leverage

Change your leverage setting for a specific symbol/market

Endpoint

POST https://papi.synthetix.io/v1/trade

Request

Request Format

{
  "params": {
    "action": "updateLeverage",
    "symbol": "BTC-USDT",
    "leverage": "20"
  },
  "nonce": 1704067200000,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  },
  "expiresAfter": 1704067300000
}

Request Parameters

Response

Success Response

{
  "status": "ok",
  "response": {
    "symbol": "BTC-USDT",
    "previousLeverage": "10",
    "newLeverage": "20"
  },
  "request_id": "5ccf215d37e3ae6d",
  "timestamp": "2025-01-01T00:00:00Z"
}

Error Response

{
  "status": "error",
  "error": {
    "message": "Leverage exceeds maximum allowed",
    "code": "VALIDATION_ERROR"
  },
  "request_id": "5ccf215d37e3ae6d",
  "timestamp": "2025-01-01T00:00:00Z"
}

Code Examples

Degen Leverage Setting

{
  "params": {
    "action": "updateLeverage",
    "symbol": "BTC-USDT",
    "leverage": "100"
  },
  "nonce": 1704067200000,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  }
}

Conservative Leverage Setting

{
  "params": {
    "action": "updateLeverage",
    "symbol": "SOL-USDT",
    "leverage": "5"
  },
  "nonce": 1704067200000,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  }
}

Important Behavior

How Leverage Settings Work

When you update leverage for a market:

• The new leverage setting applies to all current and future positions in that market

Key Points

• Each symbol can have different leverage settings
• Leverage persists across sessions (survives reconnections)
• Higher leverage = higher liquidation risk
• Lower leverage = more margin required

Market-Specific Limits

Different markets may have different maximum leverage limits:

• Major pairs (BTC-USDT, ETH-USDT): Up to 50x
• Other pairs: May have lower limits

Validation Rules

• nonce must be a timestamp in milliseconds and must be increasing
• leverage must be a positive integer
• leverage must not exceed market maximum
• symbol must be a valid market symbol
• Must be signed by account owner or authorized delegate

Signing

All trading methods are signed using EIP-712. Each successful trading request will contain:

• A piece of structured data that includes the sender address
• A signature of the hash of that structured data, signed by the sender

For detailed information on EIP-712 signing, see EIP-712 Signing.

Nonce Management

The nonce system prevents replay attacks and ensures order uniqueness:

• Use current timestamp in milliseconds as nonce
• Each nonce must be greater than the previous one
• Recommended: Use Date.now() or equivalent
• If nonce conflicts occur, increment by 1 and retry

Error Handling

Common error scenarios: