Funding & withdrawals

You’ll need: a signed-in user (Authentication & sessions). Result: the user’s deposit addresses, a funded balance, and a withdrawal polled to completed, partial, or failed.

In a managed account, each user gets deposit addresses on the supported chains. The user deposits to any of them, without picking a venue first. AGG tracks the balance per chain and moves funds to the venue a trade routes to. Self-custody users fund from their own wallet instead; see Self-custody trading. All calls below are user-tier: send x-app-id and the user’s Authorization: Bearer token.

1. Get deposit addresses

GET /execution/deposit-addresses returns 202 with { "ready": false } while the addresses are being created. Poll until it returns 200.

curl https://api.agg.market/execution/deposit-addresses \
  -H "x-app-id: $AGG_APP_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

let deposit = await client.getDepositAddresses();
while (!deposit.ready) {
  await new Promise((r) => setTimeout(r, 2000));
  deposit = await client.getDepositAddresses();
}

{
  "ready": true,
  "evmAddress": "0x8e2d6a1c4f7b0e3d9a5c2f8b1e6d4a7c0f3b9e25",
  "svmAddress": "5Hq3sT8mZr2vKc9Lw4NpXy7BdJfGa6UeRk1oQi3VtC8n",
  "supportedChains": [
    { "chainId": 137, "name": "Polygon", "tokens": [{ "symbol": "USDC", "address": "0x3c49...3359", "decimals": 6 }] },
    { "chainId": 8453, "name": "Base", "tokens": [{ "symbol": "USDC", "address": "0x8335...2913", "decimals": 6 }] }
  ]
}

evmAddress receives on every EVM chain in supportedChains. svmAddress receives on Solana. Only send the tokens listed for each chain. Treat supportedChains as the source of truth; it can change. The wallets.ready webhook fires when a user’s addresses are created.

2. Deposit and wait for the balance

The user sends a supported token to the address. The deposit shows in the balance after on-chain confirmation. There is no confirm call on your side. The deposits.confirmed webhook fires for each confirmed deposit.

curl https://api.agg.market/execution/balances \
  -H "x-app-id: $AGG_APP_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

const balances = await client.getManagedBalances();

{
  "cash": [
    {
      "tokenSymbol": "USDC",
      "totalRaw": "125000000",
      "availableRaw": "125000000",
      "reservedRaw": "0",
      "decimals": 6,
      "chains": [{ "chainId": 137, "balanceRaw": "100000000", "decimals": 6 }]
    }
  ],
  "positions": [{ "venue": "polymarket", "balance": 16.2, "costBasis": 15.3 }]
}

availableRaw is what can be spent now. reservedRaw is held for open limit orders and trades in progress. Amounts are integer strings in the token’s decimals: 125000000 with 6 decimals is 125 USDC. Pass custody=self to read the user’s linked self-custody wallets instead. To keep a minimum USDC balance on one chain after trades, see Managed balance refills.

3. Withdraw

Withdrawals always come from the managed balance, to any address on a supported destination chain. Supported tokens are USDC, USDC.e, and USDT. Amounts are in the destination token’s atomic units (6 decimals, or 18 on BNB Chain). The minimum is one whole token. Fees come out of the amount.

Show the maximum

For a Max button, ask how much can actually arrive after fees:

curl -X POST https://api.agg.market/execution/withdrawable/quote \
  -H "x-app-id: $AGG_APP_ID" -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "tokenSymbol": "USDC", "destinationChainId": 8453 }'
# -> { "maxDeliverableRaw": "124880000", "rawBalanceRaw": "125000000", "decimals": 6, ... }

When the user picks Max, send "max": true on the withdrawal. The server caps the amount to what can be delivered.

Preview before submitting

Optional, but show it before the user confirms:

curl -X POST https://api.agg.market/execution/withdraw/preview \
  -H "x-app-id: $AGG_APP_ID" -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "amountRaw": "50000000",
    "tokenSymbol": "USDC",
    "destinationAddress": "0x2f9a4c7e1b3d6f8a0c5e9b2d4f7a1c3e6b8d0f52",
    "destinationChainId": 8453
  }'

The response has receiveAmountRaw, feeRaw, pricingStatus (quoted or unviable), unviableReason, and quoteExpiresAt. The preview creates nothing.

Submit

curl -X POST https://api.agg.market/execution/withdraw \
  -H "x-app-id: $AGG_APP_ID" -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "requestId": "8a3f5c2e-1b7d-4e9a-9c6f-2d4b8e1a7c30",
    "amountRaw": "50000000",
    "tokenSymbol": "USDC",
    "destinationAddress": "0x2f9a4c7e1b3d6f8a0c5e9b2d4f7a1c3e6b8d0f52",
    "destinationChainId": 8453
  }'

const withdrawal = await client.withdrawManaged({
  requestId: crypto.randomUUID(),
  amountRaw: "50000000",
  tokenSymbol: "USDC",
  destinationAddress: "0x2f9a4c7e1b3d6f8a0c5e9b2d4f7a1c3e6b8d0f52",
  destinationChainId: 8453,
});

The response has a withdrawalId and status: "pending". requestId is an optional UUID that makes an exact-amount withdrawal safe to retry: the same requestId and body return the original withdrawal instead of sending twice, and a changed body returns 409. Do not combine requestId with max.

Poll to a final state

curl https://api.agg.market/execution/withdrawals/$WITHDRAWAL_ID \
  -H "x-app-id: $AGG_APP_ID" -H "Authorization: Bearer $ACCESS_TOKEN"

const terminal = new Set(["completed", "partial", "failed"]);
let w = await client.getWithdrawalStatus(withdrawal.withdrawalId);
while (!terminal.has(w.status)) {
  await new Promise((r) => setTimeout(r, 3000));
  w = await client.getWithdrawalStatus(withdrawal.withdrawalId);
}

`status`	Terminal	Meaning
`pending`	No	Accepted, not started.
`bridging`	No	Moving funds across chains.
`transferring`	No	Same-chain transfer in progress.
`completed`	Yes	Delivered. `completedAmountRaw` is the amount delivered.
`partial`	Yes	Some sources delivered. See `completedAmountRaw` and `sources[]`.
`failed`	Yes	Nothing delivered. See `errorMessage`.

legs[] and sources[] carry per-transfer status and txHash values.

Managed balance refills

Keep a USDC minimum on a chosen chain.

Webhooks

wallets.ready and deposits.confirmed events.

Start here

Core concepts

SDK reference

Account & identity

Trading guides

Market data & discovery

Security & compliance

Real-time

Webhooks

UI Kit

Releases

1. Get deposit addresses

2. Deposit and wait for the balance

3. Withdraw

Show the maximum

Preview before submitting

Submit

Poll to a final state

Managed balance refills

Webhooks

​1. Get deposit addresses

​2. Deposit and wait for the balance

​3. Withdraw

​Show the maximum

​Preview before submitting

​Submit

​Poll to a final state

​Related

Managed balance refills

Webhooks

1. Get deposit addresses

2. Deposit and wait for the balance

3. Withdraw

Show the maximum

Preview before submitting

Submit

Poll to a final state

Related