Withdraw

Endpoint

POST /exchange

Request Body

Parameter	Type	Description
`action`*	object	See below
`action.type`*	string	Must be `"withdraw"`
`action.notionalChain`*	string	Notional chain: `"Mainnet"` or `"Testnet"`
`action.signatureChainId`*	string	EIP-712 chain ID (hex string), e.g., `"0xa4b1"`
`action.destination`*	string	Destination wallet address (normalized to lowercase), e.g., `"0x1234567890abcdef..."`
`action.token`*	string	Asset ID as 8-char hex string (no 0x prefix), e.g., `"00012710"` for USDC
`action.amount`*	string	Amount to withdraw, e.g., `"1000.0"`
`action.source`*	string	Source account: `"balance"` or `"segregated"`
`action.time`*	number	Unix timestamp in milliseconds, e.g., `1701234567890`
`nonce`*	number	Timestamp in milliseconds for replay protection, e.g., `1701234567890`
`signature`*	object	See below
`signature.r`*	string	First 32 bytes of signature (hex string), e.g., `"0x1234..."`
`signature.s`*	string	Second 32 bytes of signature (hex string), e.g., `"0x5678..."`
`signature.v`*	number	Recovery ID (27 or 28)

Response

{
  "success": true,
  "transactionId": "0x1a2b3c4d5e6f7890...",
  "status": "pending"
}

Response Fields

Field	Type	Description
`success`	boolean	true if withdrawal was committed to event store
`transactionId`	string	Deterministic transaction ID (derived from signature hash)
`status`	string	Always `"pending"` - actual execution happens asynchronously

Example Request

curl -X POST https://api.notional.xyz/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "action": {
      "type": "withdraw",
      "notionalChain": "Mainnet",
      "signatureChainId": "0xa4b1",
      "destination": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "token": "00012710",
      "amount": "1000.0",
      "source": "balance",
      "time": 1701234567890
    },
    "nonce": 1701234567890,
    "signature": {
      "r": "0x1234...",
      "s": "0x5678...",
      "v": 27
    }
  }'

Error Responses

{
  "error": "Insufficient withdrawable balance"
}

Notes

Withdrawals execute asynchronously, so the API returns status: "pending" immediately. - Transaction ID is deterministically derived from the recovered withdrawal signature hash. - signatureChainId selects the EIP-712 domain used for signature recovery. - The signed withdrawal payload is notionalChain, destination, token, amount, source, and time. - API wallets (agents) cannot sign withdrawals; the signer must be the user account itself. - source must be "balance" or "segregated". - token must be an 8-character hex AssetId without a 0x prefix.
Amount precision is validated against Hyperliquid transfer precision rules. - First transfers to a new Hyperliquid destination account may require enough size to cover the exchange account activation fee plus the protocol minimum-after-fee threshold.

API OVERVIEW

READ ENDPOINTS

EXCHANGE ENDPOINTS

WEBSOCKET API

Endpoint

Request Body

Response

Response Fields

Example Request

Error Responses

Notes

​Endpoint

​Request Body

​Response

​Response Fields

​Example Request

​Error Responses

​Notes

Endpoint

Request Body

Response

Response Fields

Example Request

Error Responses

Notes