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.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.
202 with ready: false, then 200 with ready: true.
decimals below is 6. BNB Chain tokens on this response are 18-decimal; read decimals.
evmAddress is the user’s deposit address on every supported EVM chain and Hyperliquid: for a Privy wallet-provider app it is the Privy embedded wallet AGG is authorized to sign (409 when the Privy wallet does not grant signing rights), and for other apps it is a managed wallet AGG creates. svmAddress receives on Solana.
Only send the tokens listed for each chain. Treat supportedChains as the source of truth; it can
change. Card deposits are Onramp.
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. Thedeposits.confirmed webhook fires for
each confirmed deposit.
availableRaw, totalRaw, reservedRaw, and balanceRaw are integer strings in token decimals (125000000 with decimals: 6 is 125 USDC). positions[].balance and costBasis are display USD, not availableRaw.
availableRaw is what can be spent now. reservedRaw is held for open limit orders and trades in
progress. 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.
What a buy can spend
availableRaw does not account for transfer minimums, so it can be more than a buy can spend.
A chain’s balance only funds a buy when it clears the minimum for the move it needs to reach the
venue’s chain:
A balance below its minimum is skipped entirely, never partly used. The destination minimums
listed under Withdrawal minimums do not apply to buys.
To set a Max button, add up the chain balances that clear these minimums. Fees come out of
maxSpend, so do not subtract them. A larger maxSpend returns insufficient_balance.
A buy bridges only what it needs, so a balance under the minimum can be left on the source chain.
If a buy fails after its bridge completes, the bridged funds stay in the user’s managed balance on
the venue’s chain. They are not moved back.
3. Withdraw
Withdrawals come from the managed balance, to any address on a supported destination chain. To withdraw from a user’s own linked wallet instead, see Self-custody withdrawals. Destination chains are Ethereum (1), Polygon (137), Arbitrum (42161), Base (8453), BNB Chain
(56), Solana (792703809), HyperCore (1337) and HyperEVM (999). HyperEVM takes USDC or
USDT (paid out as USD₮0).
Supported tokens are USDC, USDC.e, and USDT. Withdrawal amounts are 6-decimal integer strings, except BNB Chain, which is 18-decimal. Every other raw amount in the samples below is 6-decimal. 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:maxDeliverableRaw of 124880000 with decimals: 6 is 124.88 USDC. Not display units.
"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:amountRaw of 50000000 is 50 USDC at 6 decimals. On BNB Chain the same whole token is an 18-decimal integer string.
receiveAmountRaw, feeRaw, pricingStatus (quoted or unviable),
unviableReason, and quoteExpiresAt. The preview creates nothing.
Submit
amountRaw of 50000000 is 50 USDC at 6 decimals (18-decimal on BNB Chain). The response has a withdrawalId and status: "pending".
Withdraw funds.
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. Send one on every exact-amount withdrawal:
it is what makes a timeout safe to resolve. A requestId is remembered permanently, so use a new
one for each new attempt, including after a failed withdrawal. See
Errors.
When the amount cannot be delivered, POST /execution/withdraw returns 400 with the same reason
the preview gives as unviableReason, and records a failed withdrawal that moves no funds.
Poll to a final state
completedAmountRaw is an integer string in the destination token’s decimals (6, or 18 on BNB Chain).
legs[] and sources[] carry per-transfer status and txHash values.
completedAmountRaw is set only when at least one source delivered, so it is null on every
failed withdrawal, never "0". On a failed withdrawal every entry in sources[] is failed.
The amount of a failed withdrawal stays in the user’s balance.
Amounts and fees
amountRaw is the amount to deliver, not the amount to debit. How much leaves the balance depends
on the route:
On bridge and swap routes, every bridged or swapped part is always debited a fixed buffer on top:
2% plus a flat $0.10 per bridged part, or 2% plus a flat $0.04 per swapped part, plus a few units
of rounding. The buffer does not shrink when the real fee is lower. The whole debited amount goes
into the bridge, so whatever the fee does not use reaches the recipient. The user only loses the
real fee.
The user’s balance must cover the debit. A balance of $100 can deliver at most about $97.90 over a
bridge. Asking for more makes the preview
unviable with maxDeliverableRaw set; nothing is
debited. max: true does this calculation for you.
The real bridge fee is roughly a flat dollar amount, set mostly by the destination chain:
These are measured values, not guarantees. Because the fee is flat, it is a large share of a small
withdrawal and a tiny share of a large one, and so is the flat part of the buffer:
- A 1 USDC bridge to Polygon debits about 1.1224 and delivers about 1.07. The fee was less than
the buffer, so the recipient gets more than
amountRaw. - A 1 USDC bridge to Solana debits about 1.1224 and delivers about 0.89. The fee was more than
the buffer, so the recipient gets less than
amountRaw. - A 100 USDC bridge to Polygon debits about 102.14 and delivers about 102.09.
receiveAmountRaw in the preview is an estimate. The route is priced again when the withdrawal
runs, so the delivered amount can differ slightly.
There is no mode that debits exactly amountRaw and delivers amountRaw minus fees. max: true
withdraws the whole withdrawable balance and delivers that minus fees.
On the status response:
completedAmountRawis the amount delivered to the recipient, not the amount debited, so it can be aboveamountRaw. For bridged parts it is the bridge’s output at execution time, not an on-chain balance reading.sources[].amountRawis the amount debited from each source, in that source’sdecimals. Convert each to the same decimals, then add them up for the total debited.
Solana recipients need a USDC token account
A USDC withdrawal on Solana can only go to an address that already has a USDC token account. AGG does not create the recipient’s token account or pay its rent. If the account is missing, the preview returnspricingStatus: "unviable" and POST /execution/withdraw returns 400 with the
same reason, before anything is sent. To fix it, open the account from any Solana wallet, or send
it any amount of USDC, then try again.
Minimums
Every withdrawal must be at least 1 token. On top of that, each chain’s balance only counts toward a withdrawal when it clears a minimum for the kind of transfer it needs:
A balance below its minimum is left out of
max and of maxDeliverableRaw. A small leftover on
one chain, for example $0.25, cannot be withdrawn on its own until the user adds more to that
chain.
Unviable reasons
WhenpricingStatus is unviable, unviableReason explains why. Show it to the user, but do not
match on the text, since the wording can change. For logic, check pricingStatus and, when set,
maxDeliverableRaw.
Related
Managed balance refills
Keep a USDC minimum on a chosen chain.
Webhooks
wallets.ready and deposits.confirmed events.