Deposits and withdrawals

For the custody and money-movement model, read Wallets and funds. This guide covers the requests and states needed to implement it.

All paths below begin /v1/accounts/{externalUserId}. Require a ready account and the required features enabled. Do not accept a browser-selected external ID without checking your own session.

For cash balances and the order ticket's available-to-trade amount, see Cash balance and buying power, including SDK/HTTP examples, response fields and unavailable-value handling.

Deposit overview

Before you start: a ready account with funding enabled. Examples use the configured server client; substitute the external ID authorized by your backend. HTTP tabs omit signing headers.

const result = await crisp.getFunding('example:user-123', { details: 'full' });

Use GET /wallet/funding?details=summary for a balance-only display, details=trading for balance plus available buying power, and details=full (the compatible default) for deposit/withdrawal UI. Summary/trading omit Bridge instructions, avoiding unnecessary Bridge calls. availableToTrade: null means unavailable or not loaded, never zero.

GET /wallet/funding returns balance, deposit instructions/supported assets and withdrawal-source availability. GET /wallet/deposit-instructions returns current Bridge addresses and supported assets separately. Render only assets supported on the selected network; never reuse an address from another user or network.

Balance uses exact baseUnit and six-decimal formatted pUSD values. A partial RPC outage can return 200 with balance: null, balanceStatus: "temporarily_unavailable" and withdrawals disabled. Keep usable deposit instructions visible, show balance unavailable, and offer retry—not zero.

Quote and originate the source transfer

const result = await crisp.quoteDeposit('example:user-123', {
  fromAmountBaseUnit: '25000000',
  fromChainId: '1',
  fromTokenAddress: '0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
});

Choose a currently supported asset. The amount is source-token base units, not universally six decimals. CRISP fixes the quote recipient to the managed account. The quote itself does not move money. The user signs the source-chain transaction in their connected wallet or transfers to the appropriate returned instructions. Show token, network, amount, recipient and quote fees before signing. Revalidate wallet/account changes; never silently send from a different connected wallet.

GET /wallet/transfers?limit=50&cursor=… reports Bridge status for that account, not arbitrary addresses. Empty history is valid; distinguish pending bridge delivery from credited trading cash. Refresh funding after confirmed delivery.

Deposit done when: final delivery is reflected in funding/buying power. The SDK does not send or sign the user's external-wallet transfer. Next: place an order.

Withdrawal intent

Requires explicit withdrawal enablement; it is not a default permission. Your authenticated user must approve the exact recipient. Provisioned contact wallet data does not authorize a withdrawal.

Quote via POST /wallet/withdrawal-quote, then submit the same destination fields to POST /withdrawals with an Idempotency-Key:

const result = await crisp.createWithdrawal(
  'example:user-123',
  {
    amountBaseUnit: '25000000',
    recipientAddress: '0x1111111111111111111111111111111111111111',
    toChainId: '1',
    toTokenAddress: '0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  },
  'withdrawal-intent-unique-001',
);

This placeholder recipient must be replaced by the user's approved destination. Amount is source Polygon pUSD, six decimals. CRISP creates the Bridge destination and signs from the managed wallet. A balance/quote is not a reservation; unsettled fee obligations or changed funds can block a request.

Poll crisp.getWithdrawal(externalUserId, withdrawalId) (HTTP: GET /v1/accounts/{externalUserId}/withdrawals/{withdrawalId}). List via listWithdrawals. Do not use waitForOperation for withdrawals.

Exact contracts: getFunding, quoteDeposit, createWithdrawal, getWithdrawal.