Funds lifecycle

How collateral moves in and out — deposit, delegate, trade, withdraw.

Collateral flows through four stages:

deposit  →  delegate  →  trade  →  withdraw

init-deposit-ledger   ─┐
init-basket           ─┼─ one-time setup
deposit               ─┘   (bundles any missing setup + funds the ledger)
delegate-basket       ─── enable trading
   │
   ▼
trade (fast, gasless)
   │
   ▼
withdraw              ─── pull funds back out

Deposit

The one-shot deposit endpoint funds the deposit ledger and conditionally bundles whatever setup is missing (basket, deposit ledger, delegation, trade vault). Prefer it for onboarding. Use deposit-direct if you'd rather run each setup step yourself.

Deposit ledger — a per-owner PDA that tracks the balances available as collateral. Deposits credit it; opening positions and adding collateral draw it down.

Trade vault — a per-mint token account that deposits land in and withdrawals are paid from.

Delegate

delegate-basket is a one-time step that enables trading on your basket. A trade submitted before the basket is delegated is rejected.

Withdraw

The single-call withdraw endpoint builds one transaction that locks the amount and releases the funds. Two things to know:

1. Fee payer ≠ owner. The client supplies its own fee payer (which must differ from owner) and co-signs the transaction with both keys.

2. It's asynchronous. Funds release after the transaction lands; poll the returned escrow receipt until it closes.

Two response flags drive the flow:

• custodySettlementRequired: true → the trade vault can't cover the amount yet. Call custody-settlement first, then retry withdraw.

• isNativeSol: true → the released funds arrive as WSOL; unwrap the WSOL account back to native SOL.

If a withdrawal doesn't finalize on its own, withdrawal-settle resumes it.

Step-by-step: Withdraw funds.