Create a withdrawal

POST /v1/withdrawals

Build a redeem settlement for a vault position and return the unsigned payload to sign, along with a withdrawal quote id. Pass a share count as a base-10 integer string, pass "max", or omit shares entirely to redeem the full balance. Sign the authorization and executeDigest exactly as for a deposit, then submit the signatures with the quote id to the deposits endpoint to execute the withdrawal.

Authentication

Send your API key in the api-key header.

Request body (application/json)

{
  "userAddress": "0x7c3bd8a1f0a4d1a707f3b8f2eab6a95cbe8f1a3d",
  "chain": 84532,
  "vault": "0x9d4454b023096f34b160d6b654540c56a1f81688",
  "shares": "max"
}

Responses

Status	Description
200	The withdrawal plan and the settlement payload to sign.
400	Invalid request. Possible codes: USER_003 (invalid userAddress), VALIDATION_001 (malformed vault address or shares value), CHAIN_001 (unsupported chain), TRANSACTION_002 (no shares to redeem).
404	No configured venue matches this vault on this chain (RESOURCE_001).
500	Server-side failure. Possible codes: CHAIN_003 (share balance read failed over RPC), SYSTEM_002 (no settlement delegate configured for the chain), SYSTEM_001 (storage failure).

200 response

{
  "success": true,
  "data": {
    "quoteId": "6884f2a0a9b1d43e2c7a9f44",
    "kind": "withdraw",
    "shares": "24998100",
    "txPayload": {
      "authorization": {
        "chainId": 84532,
        "address": "0x5fbdb2315678afecb367f032d93f642f64180aa3",
        "nonce": 8
      },
      "executeDigest": "0x5d4c7b6a9f8e1d2c3b4a5f6e7d8c9b0a1f2e3f2a9c1d8e5b4a706f9d2c1b8a3e",
      "calls": [
        {
          "target": "0x9d4454b023096f34b160d6b654540c56a1f81688",
          "value": "0",
          "data": "0xba0876520000000000000000000000000000000000000000000000000000000001406a140000000000000000000000007c3bd8a1f0a4d1a707f3b8f2eab6a95cbe8f1a3d0000000000000000000000007c3bd8a1f0a4d1a707f3b8f2eab6a95cbe8f1a3d"
        }
      ],
      "executeNonce": "1"
    },
    "expiresAt": 1785283620
  },
  "timestamp": "2026-07-29T10:17:02.310Z"
}

400 response

{
  "success": false,
  "error": {
    "code": "TRANSACTION_002",
    "message": "no shares to redeem",
    "category": "TRANSACTION",
    "traceId": "a1b2c3d4e5f60718"
  },
  "timestamp": "2026-07-29T10:15:32.123Z"
}

404 response

{
  "success": false,
  "error": {
    "code": "RESOURCE_001",
    "message": "unknown vault",
    "category": "RESOURCE",
    "traceId": "a1b2c3d4e5f60718"
  },
  "timestamp": "2026-07-29T10:15:32.123Z"
}

500 response

{
  "success": false,
  "error": {
    "code": "CHAIN_003",
    "message": "Blockchain RPC error",
    "category": "CHAIN",
    "traceId": "a1b2c3d4e5f60718"
  },
  "timestamp": "2026-07-29T10:15:32.123Z"
}