Skip to main content

​
Endpoint

POST /exchange

​
Request Body

ParameterTypeDescription
action*objectSee below
action.type*stringMust be "approveAgent"
action.hyperliquidChain*string"Mainnet" or "Testnet"
action.signatureChainId*stringEIP-712 chain ID (hex), e.g., "0xa4b1"
action.agentAddress*stringAgent’s wallet address (use zero address to revoke), e.g., "0x1234567890abcdef..."
action.agentNamestringOptional agent label, e.g., "My Trading Bot"
action.nonce*numberTimestamp in milliseconds (must match outer nonce)
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

{
  "status": "ok",
  "response": {
    "type": "approveAgent"
  }
}

​
Example Request

curl -X POST https://api.notional.xyz/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "action": {
      "type": "approveAgent",
      "hyperliquidChain": "Mainnet",
      "signatureChainId": "0xa4b1",
      "agentAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "agentName": "Momentum Trading Bot",
      "nonce": 1701234567890
    },
    "nonce": 1701234567890,
    "signature": {
      "r": "0x1234...",
      "s": "0x5678...",
      "v": 27
    }
  }'

​
Error Responses

{
  "error": "Invalid agent address format"
}

​
Notes

  • Use zero address (0x0000000000000000000000000000000000000000) to revoke agent
  • Agent can sign any exchange action on your behalf
  • Store agent private keys securely
  • action.nonce must equal the outer nonce