Skip to main content

​
Endpoint

POST /exchange

​
Request Body

ParameterTypeDescription
action*objectSee below
action.type*stringMust be "withdraw"
action.notionalChain*stringNotional chain: "Mainnet" or "Testnet"
action.signatureChainId*stringEIP-712 chain ID (hex string), e.g., "0xa4b1"
action.destination*stringDestination wallet address (normalized to lowercase), e.g., "0x1234567890abcdef..."
action.token*stringAsset ID as 8-char hex string (no 0x prefix), e.g., "00012710" for USDC
action.amount*stringAmount to withdraw, e.g., "1000.0"
action.source*stringSource account: "balance" or "segregated"
action.time*numberUnix timestamp in milliseconds, e.g., 1701234567890
nonce*numberTimestamp in milliseconds for replay protection, e.g., 1701234567890
signature*objectSee below
signature.r*stringFirst 32 bytes of signature (hex string), e.g., "0x1234..."
signature.s*stringSecond 32 bytes of signature (hex string), e.g., "0x5678..."
signature.v*numberRecovery ID (27 or 28)

​
Response

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

​
Response Fields

FieldTypeDescription
successbooleantrue if withdrawal was committed to event store
transactionIdstringDeterministic transaction ID (derived from signature hash)
statusstringAlways "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, API returns status: "pending" immediately
  • Transaction ID is deterministically derived from signature hash
  • source field: "balance" or "segregated"
  • token field must be an 8-character hex AssetId (no 0x prefix)