Withdraw Collateral

Withdraw collateral from your Synthetix trading account back to your wallet, subject to approval, margin requirements and risk checks.

Endpoint

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

Request

Request Format

{
  "params": {
    "action": "withdrawCollateral",
		"subAccountId": "1867542890123456789",
    "symbol": "USDT",
    "amount": "1000.0",
    "destination": "0x742d35Cc6634C0532925a3b8D371d1c62a39b6e2"
  },
  "nonce": 1704067200000,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  },
  "expiresAfter": 1704067300
}

Request Parameters

Parameter	Type	Required	Description
`params`	object	Yes	Action object containing withdrawal details
`params.action`	string	Yes	Must be `"withdrawCollateral"`
`params.subAccountId`	string	Yes	Subaccount identifier
`params.symbol`	string	Yes	Collateral asset symbol to withdraw (e.g., "USDT", "ETH")
`params.amount`	string	Yes	Amount to withdraw as decimal string (e.g., "1000.0")
`params.destination`	string	Yes	Destination wallet address (0x-prefixed Ethereum address)
`nonce`	integer	Yes	Positive integer, incrementing nonce
`signature`	object	Yes	EIP-712 signature object
`expiresAfter`	integer	No	Expiration timestamp in seconds (optional)

Response

Success Response

{
  "status": "ok",
  "response": {
    "requestId": "withdraw-req-123",
    "symbol": "USDT",
    "amount": "1000.0",
    "destination": "0x742d35Cc6634C0532925a3b8D371d1c62a39b6e2"
  },
  "request_id": "5ccf215d37e3ae6d"
}

Error Response

{
  "status": "error",
  "error": {
    "message": "Insufficient withdrawable balance",
    "code": "VALIDATION_ERROR"
  },
  "request_id": "5ccf215d37e3ae6d",
  "timestamp": "2025-01-01T00:00:00Z"
}

Validation Rules

nonce must be a positive integer, incrementing and unique per request
symbol must be a valid collateral symbol (e.g., "USDT", "ETH")
amount must be a positive number as string
destination must be a valid Ethereum address (0x-prefixed)
Account must have sufficient withdrawable balance of the specified asset
Withdrawal must not violate margin requirements
Must be signed by account owner (no delegate support)
SubAccount is determined from authenticated context (not provided in request)

EIP-712 Signature Structure

The withdrawal request fields are signed using EIP-712:

WithdrawCollateral Type Definition

const WithdrawCollateralTypes = {
  WithdrawCollateral: [
    { name: "subAccountId", type: "uint256" },
    { name: "symbol", type: "string" },
    { name: "amount", type: "string" },
    { name: "destination", type: "address" },
    { name: "nonce", type: "uint256" },
    { name: "expiresAfter", type: "uint256" }
  ]
}

Example Typed Data for WithdrawCollateral

{
  "types": {
    "EIP712Domain": [
      { "name": "name", "type": "string" },
      { "name": "version", "type": "string" },
      { "name": "chainId", "type": "uint256" },
      { "name": "verifyingContract", "type": "address" }
    ],
    "WithdrawCollateral": [
      { "name": "subAccountId", "type": "uint256" },
      { "name": "symbol", "type": "string" },
      { "name": "amount", "type": "string" },
      { "name": "destination", "type": "address" },
      { "name": "nonce", "type": "uint256" },
      { "name": "expiresAfter", "type": "uint256" }
    ]
  },
  "primaryType": "WithdrawCollateral",
  "domain": {
    "name": "Synthetix",
    "version": "1",
    "chainId": 1,
    "verifyingContract": "0x0000000000000000000000000000000000000000"
  },
  "message": {
    "subAccountId": "1867542890123456789",
    "symbol": "USDT",
    "amount": "1000.0",
    "destination": "0x742d35Cc6634C0532925a3b8D371d1c62a39b6e2",
    "nonce": 1704067200000,
    "expiresAfter": 1704067300
  }
}

Important Notes:

The amount field is a string type and should match the decimal representation from the request (e.g., "1000.0")
The expiresAfter field should match the request value, or be set to 0 when not provided (representing no expiration)
The nonce field is included in the EIP-712 message and matches the top-level request field
All withdrawal operations must be signed by the master account owner
For testnet, use chainId: 11155111 (Ethereum Sepolia). See Environments for complete configuration details

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 any positive integer as nonce
Each nonce must be greater than the previous one (incrementing)
Date.now() is a convenient option, not a requirement
If nonce conflicts occur, increment by 1 and retry

:::note SubAccountAction Exception SubAccountAction endpoints (getPositions, getOpenOrders, getOrdersHistory, getTrades, getFundingPayments, getSubAccount, getSubAccounts, getDelegatedSigners, getBalanceUpdates) do not require a nonce. Only the signature and optional expiresAfter parameters are needed. :::

Error Handling

Common error scenarios:

Error Code	Description	Retryable
`UNAUTHORIZED`	EIP-712 signature validation failed	No
`VALIDATION_ERROR`	Request validation failed	No
`MISSING_REQUIRED_FIELD`	Required field is missing	No
`INVALID_FORMAT`	Field format is invalid	No
`INVALID_VALUE`	Invalid parameter value	No
`RATE_LIMIT_EXCEEDED`	Too many requests in time window	Yes
`INSUFFICIENT_MARGIN`	Not enough margin for trade	No
`ORDER_NOT_FOUND`	Order does not exist	No
`OPERATION_TIMEOUT`	Operation timed out	Yes

Error	Description
Insufficient withdrawable balance	Account lacks required funds for specified asset
Margin requirement violation	Withdrawal would violate margin rules
Invalid asset symbol	Asset type not supported as collateral
Account health check failed	Withdrawal would make account unhealthy
Delegate signature not allowed	Must be signed by account owner
Minimum withdrawal amount	Amount below minimum threshold

Deposits - How to deposit collateral into your account
Get Balance Updates - View deposit and withdrawal history
Get Subaccount - Check current balances and margin status