Skip to main content

Custody

The Trading Balance​

Before you can trade, provide liquidity, or place triggers, you deposit tokens into a trading balance on the market canister for that pair. Once deposited, every operation draws from this balance atomically — no per-trade approvals, no multi-step flows.

This is the design principle that powers the entire protocol. Batch cancel-and-replace, instant order matching, atomic LP — all of it works because the tokens are already in the canister's custody. One deposit unlocks unlimited atomic operations until you withdraw.

Deposits​

PartyDEX never asks you to send tokens to a raw address. Deposits use the ICRC-2 approve-and-pull pattern:

  1. You approve — grant the spot canister permission to pull a specific amount from your wallet
  2. You call deposit — the canister pulls tokens from your wallet into its custody
  3. Your trading balance is credited — tokens are ready for trading, liquidity, or immediate withdrawal

If anything goes wrong — insufficient allowance, not enough funds — the deposit is rejected and nothing moves.

Withdrawals​

  1. Call withdraw with the token and amount
  2. The canister transfers tokens directly to your wallet

If the outbound transfer fails for any reason, your trading balance is restored. Tokens are never lost — they either reach your wallet or stay in your trading balance.

The Balance Sheet: On-Chain Proof​

Each market canister enforces a fundamental accounting rule:

Assets = Liabilities + Equity

Assets are the canister's tracked token holdings, updated on every deposit and withdrawal. Liabilities are everything owed to users: trading balances, tokens locked in orders, tokens in liquidity positions. Equity is protocol fees earned.

If this equation doesn't balance, the canister reports a drift — a red flag visible to anyone. You can verify this yourself at any time by calling get_balance_sheet on any spot canister.

This is not a promise. It is an on-chain invariant you can check whenever you want.

Pass-Through Trading​

For backend services, payment processors, or other canisters that need to move tokens through a trade without maintaining a persistent balance — pass_through_trade provides a wallet-to-wallet shortcut. The canister pulls your input, executes the trade, and sends the output directly to a recipient wallet.

The tradeoff: pass-through trades require an ICRC-2 transfer in and an ICRC-1 transfer out instead of drawing from a pre-funded balance, so they carry more latency and don't support the atomic batch operations available to trading balance users.

If the outbound transfer fails, tokens are credited to a trading balance that you can withdraw later. Nothing is ever lost.

For exact function signatures and parameter details, see the Spot API reference.