Skip to main content
CheckoutContainer is the plug-and-play checkout: hand it an offer and it renders whichever provider that offer belongs to. Superstate swap, Ondo buy, Ondo sell, CoinList token sale, Centrifuge deposit, Centrifuge redemption - you write one integration, not six. This is the highest rung of the SDK (L3, components) and the one to start from. Reach for the hooks below it only when you need markup the SDK does not give you.
CheckoutContainer is the only checkout component the SDK exports. The per-provider containers it mounts are internal, so routing on offer.type is never your problem: when a new provider ships, CheckoutContainer renders it.

Prerequisites

Render it

That is the whole integration. Only offer, chain, optionId and wallets are required: <CheckoutContainer offer={offer} chain={chain} optionId={optionId} wallets={wallets} /> renders every provider on its defaults. optionId is required for every offer type, even one with a single option. The container is self-scoped: it renders fully styled with no style provider in the tree. In the dark theme it shows each token’s dark logo when the token registry has one.

Props

One mount, one offer, one chain

To render a different offer, chain, side, option or preselected wallet, remount rather than reassign. Give the container a key that changes with them, as the example above does. Add wallets.preselected?.address to the key if your preselection can change on one page. offer, chain, side, optionId and wallets.preselected are read as fixed for the lifetime of the mount. Each provider’s viewmodel owns a step machine - which wallet was authorized, how much is being spent - and that progress is bound to the order it was made against: a Superstate wallet authorization is allowlisted per offer, and an ERC-20 approval is granted per chain, for one specific token. Changing any of them in place would carry a completed step onto an order it was never made for. Worse, a swap could land mid-execution, between an approval and the broadcast it was granted for. So the flow reads side, optionId, and wallets.preselected once and ignores later values. offer and chain are not latched, so changing either in place is unsupported. The session gate above the flow reads optionId on every render, so change the option through key on a wallet session too. The rest of wallets stays live. A newly connected external wallet appears as a row without a remount, and a wallet you stop supplying sends the checkout back to its wallet step (see When the wallet disconnects). React discards the old flow’s state along with its component instance, which is the only reset that cannot strand an in-flight transaction.

side: buy or sell

side is a prop rather than something the offer says, because no offer can answer it: offer.type is ondo::swap in both directions, and the direction is a property of your page rather than of the catalog. It is a prop rather than a config entry because it is per-render, while the config is per-integration, so one config object serves a buy page and a sell page. A Centrifuge redemption is a request, not a sale. The user enters how many of the vault’s shares to redeem, bounded only by what the wallet holds: the offer’s dollar minimum applies to deposits only. The review approves the vault for that many shares, unless the allowance already covers them, and broadcasts the request. Placing it pays nothing yet. The fund fulfills the request later, and the user then claims the payout in a second transaction, for example with ClaimContainer. A vault pays in the same coin a deposit spends: USDZ, a test stablecoin, on ethereum_sepolia, and USDC on every other chain. A deposit works the same way in the other direction: the user claims the shares once the fund fulfills it. See Centrifuge Vaults.
side is read once, at mount. The flow below it holds an approval granted for whichever coin that side spends, so a re-render with a new side is ignored by design. A buy/sell toggle on one page works only if side is in the container’s key. A forgotten side on a sell page renders the buy checkout.
Unmounting a checkout does not cancel an order already in flight. A Superstate swap, an Ondo swap or a token-sale order still goes through, and your onOrderConfirmed or onOrderPlaced callback still fires for it. A Centrifuge checkout unmounted while its approval mines (a deposit approves when the user confirms the amount, a redemption when they place it) broadcasts no request: the approval stays on-chain, no order is placed, and onOrderPlaced does not fire. Gate a toggle where it can reach an executing flow, for example by disabling it once the user is past the amount step.

optionId: which option is bought

An offer lists one or more options in offer.options, and each option has its own requirements and minimum purchase. optionId names the option the user buys. Pass the option whose requirements you showed the user. optionId is required for every offer type, even an offer with one option, and even for the providers that ignore it. The SDK never picks an option for you: a default would break silently the day the offer gains a second option. If your page selects an option automatically, pick it yourself, for example offer.options[0], and pass its id.
Breaking in v0.16.0. optionId used to be optional: Ondo and a Centrifuge deposit took the offer’s only option, and a token sale bought its first one. Code that leaves it out no longer compiles. Pass the option the user picked.
When optionId names no option the offer shows, the checkout is blocked with unknown-option, so an offer with no options always blocks. A Superstate swap and a Centrifuge redemption never block on it. The checkout then shows a “not available” screen in place of its steps and sends no request, so the user never pays gas for an approval on an order that cannot go through. If you set a logger, the SDK logs checkout blocked at error level, with the reason, the offer’s id and type, and the chain. Like side, optionId is read once, at mount. If the user can switch options on one page, put optionId in the container’s key, as in ${offer.id}:${chain}:${side}:${optionId}.

Wallets and the wallet step

wallets is a CheckoutWalletSelection: embedded, external, an externalAdapter with connect and disconnect, and preselected. Set externalAdapter to null for a host with embedded wallets only. The external-wallet row is then hidden, unless external holds a connected wallet: that wallet still shows, with no way to disconnect it. Every checkout runs the same three steps - wallet, amount, review - and every provider honors wallets.preselected: On a wallet session, the session gate replaces preselected for Ondo and Centrifuge with the session’s wallet.

When the wallet disconnects

The checkout holds the wallet the user confirmed by its address, not by the EvmWallet object. On every render it looks that address up again in the current wallets (case-insensitively, as WalletSelection.find does). So when your wallet stack hands over a fresh EvmWallet for the same address, for example after a chain switch, the checkout sends through the new one on its next request. You do not remount. When you stop supplying a wallet at that address, because it disconnected or the external wallet moved to another account, the checkout reacts in one of two ways: A send that fails because the wallet is gone classifies as the disconnected WalletError, and every checkout shows the disconnected message for it rather than “try again”. Your EvmWallet reports a disconnect by throwing WalletDisconnectedError, or by letting an EIP-1193 4100 or wagmi’s ConnectorNotConnectedError propagate. On a wallet session, the session gate acts first. When wallets.external stops being the session’s wallet, the gate replaces an Ondo or Centrifuge checkout with the “Connect your wallet” card. With walletSignIn set, the wallet change also ends the session, and the checkout then renders as for no session.

The session gate

Ondo and Centrifuge checkouts wait for the session before they open. CheckoutContainer shows a skeleton until PassageProvider is ready, for every integration, whether or not you use wallet sign-in. A wallet session belongs to a user who signed in with their wallet (PassageProvider’s walletSignIn prop) and has no CoinList login. Once the session is known, the first row that matches decides what renders:
  • The cards have no button. Your page renders the way to sign in or connect.
  • Any requirement asks for a CoinList login, not only coinlist_account. The gate reads the option’s requirements with the skeleton up. If the read fails, or enabled is false, the gate skips this check, and CoinList refuses an order the session cannot place. The wallet row still applies. A Centrifuge redemption passes no option, so it runs no check.
  • A new wallet session remounts the checkout, and its progress goes with it. You do not add the session to key. Signing in with CoinList does not remount it.
  • enabled={false} reads nothing and signs nobody out, and it keeps an opened checkout as it was.
Superstate and the token sale do not go through the gate. A wallet session cannot allowlist a wallet for Superstate or record a token-sale participation, because both need a CoinList login. A token sale asks for its approval first, so that transaction still goes out.

CheckoutConfig

CheckoutConfig is keyed by OfferType, and every key is optional, as is the config prop itself. A provider you say nothing about runs on its defaults. Nothing in the config is per-offer. It is per-integration, so you build one object and pass the same one for every offer you render. Anything the SDK can derive from the offer, it derives: Ondo’s API symbol comes from offer.asset.code, and a token sale’s funding contract, coins and price come off the offer. Use the callbacks to navigate, refresh a portfolio or log. The SDK already shows the confirmation.

Token sales

coinlist::token_sale offers mount the SDK’s own token-sale checkout: pick a wallet, enter an amount in USD paid in one of the stablecoins the sale accepts on chain, then review and place the order through passage.tokenSale.execute. The amount is checked against the option’s minimum, and the amount and review steps are blocked outside the sale window. optionId chooses which option is bought (see optionId). Some offers cannot take an order at all, and the checkout renders a “not available” screen in their place: Each of these reasons sends no request and, if you set a logger, logs checkout blocked at error level.

What happens underneath

CheckoutContainer switches on offer.type and mounts only the matching provider’s container, handing it the offer narrowed to its variant. Ondo and Centrifuge mount theirs once the session gate opens. Only that provider’s viewmodel runs, so the others fetch nothing and hold no timers. enabled is forwarded to the mounted container as-is: it pauses a checkout that is mounted but not on screen yet. The switch on offer.type is exhaustive, and its default branch assigns to const exhaustive: never, so a new offer type is a compile error inside the SDK until it has a branch.
Each product exposes a god viewmodel wrapping its entire flow, plus the data hooks it is built from. Call one behind your own markup when you want the SDK’s logic, state and error handling but not its UI.
Each takes offer, chain, wallets, enabled? and its provider’s callback (onOrderConfirmed or onOrderPlaced), plus a required optionId where the table says so, and returns { state, onEvent }. optionId works as it does on CheckoutContainer: the viewmodel never picks an option, and an id the offer does not show blocks the flow with unknown-option. state is a discriminated union you switch on exhaustively, with a flow-level error arm for an offer that has no checkout to render, such as one that cannot settle on the chain you passed or one with no option to order. In the content arm of every flow except Superstate, wallet is null exactly when preselected skipped the wallet step.CheckoutBlockedReason gained unknown-option in v0.15.0, so OndoCheckoutErrorReason and CentrifugeCheckoutErrorReason gained it too. An exhaustive switch on either needs a case for it.The step components and step viewmodels are not exported. A god viewmodel is the smallest unit of the SDK’s checkout logic you can call.If you call these directly you are routing on offer.type yourself. Narrow the offer and call each viewmodel inside its own component, so only the matching one is mounted. That routing is exactly what CheckoutContainer does for you.You also leave the session gate behind. To keep it for Ondo and Centrifuge, call useCheckoutSessionViewModel({ offer, optionId, chain, wallets }) (@alpha), leaving out optionId for a Centrifuge redemption. While your UI is paused, pass enabled: false, or it still reads requirements and signs out a session on another chain. Its state.type is loading, not-authenticated, wallet-missing, or open. Mount your viewmodel once it is open, pass it state.wallets, and put state.session in its key.
Per-provider detail: Superstate Swap, Ondo Swap, Centrifuge Vaults, CoinList Token Sale. The conventions the hooks share - enabled, data, and the shape of state - are in SDK structure.
Below the hooks are plain TypeScript namespaces on PassageClient, with no React and no state. Use them for a non-React app, a custom state layer, or a step the SDK’s flows do not cover.
These return step-tagged results rather than throwing, so you can map each failure to your own copy. The full parameters, progress phases and error steps live on each provider’s page.A wallet session can build Ondo and Centrifuge orders only for its own wallet and chain, and CoinList refuses any other. Allowlisting a wallet with superstate.authorizeWallet and recording a participation with tokenSale.execute need a CoinList login.

Next steps

Superstate Swap

Wallet allowlisting, live quotes, and what Superstate needs from you.

Ondo Swap

Both directions, what each one approves, and the two-call order.

CoinList Token Sale

The approval, the participation, and tracking participations.

Errors and edge cases

Every error shape the flows return, and how to handle it.