Building the Checkout flow

CheckoutContainer is the plug-and-play checkout: hand it an offer and it renders whichever provider that offer belongs to. Superstate swap, Ondo buy, CoinList token sale - you write one integration, not three. This is the highest rung of the SDK (L3, components) and the one to start from. Reach for a provider-specific container or the hooks below it only when you need markup the SDK does not give you.

Prefer CheckoutContainer over OndoBuyCheckoutContainer or SuperstateSwapCheckoutContainer even when you know the offer type. The provider containers exist, but routing on offer.type yourself means a new provider is your problem; letting CheckoutContainer do it means a new provider is a version bump.

Prerequisites

A completed OAuth session with a working CoinListProvider
An OfferDetail from Display offer details
A CheckoutWalletSelection built from your wallet stack

Render it

"use client";

import {
  CheckoutContainer,
  defaultCheckoutConfig,
  type CheckoutWalletSelection,
} from "@coinlist-co/react";
import { AssetSymbol, type OfferDetail } from "@coinlist-co/react/shared";

// Per-integration, not per-offer: build it once and reuse it for every offer.
const checkoutConfig = defaultCheckoutConfig({
  "ondo::swap": {
    symbol: (offer) => AssetSymbol(offer.asset.code),
  },
  "coinlist::token_sale": {
    render: (offer) => <MyTokenSalePage offer={offer} />,
  },
});

export function Checkout({
  offer,
  wallets,
}: {
  offer: OfferDetail;
  wallets: CheckoutWalletSelection;
}) {
  return (
    <CheckoutContainer
      key={`${offer.id}:ethereum_mainnet`}
      offer={offer}
      chain="ethereum_mainnet"
      wallets={wallets}
      config={checkoutConfig}
    />
  );
}

That is the whole integration. The container is self-scoped: it renders fully styled with no style provider in the tree.

Props

Prop	Type	Description
`offer`	`OfferDetail`	The offer being bought. Its `type` decides which provider renders. Fixed for the lifetime of the mount.
`chain`	`EthereumChain`	Where the order executes: balance reads, the approval, and the broadcast all go here. Fixed for the lifetime of the mount.
`wallets`	`CheckoutWalletSelection`	The wallets the buyer can spend from, plus connect and disconnect lambdas. See Wallets.
`config`	`CheckoutConfig`	What each offer type needs beyond the offer itself. See below.
`enabled`	`boolean`	Default `true`. `false` turns off every request and timer in every provider, for a checkout that is mounted but not on screen yet.
`className`	`string`	Applied to the rendered provider view.

One mount, one offer, one chain

To render a different offer or chain, remount rather than reassign. Give the container a key that changes with them, as the example above does. offer and chain 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 offer it was made against: a Superstate wallet authorization is allowlisted per offer, and an ERC-20 approval is granted per chain. Changing either prop in place would carry a completed step from one offer onto another. Worse, a swap could land mid-execution, between an approval and the broadcast it was granted for. React discards the old flow’s state along with its component instance, which is the only reset that cannot strand an in-flight transaction.

CheckoutConfig

CheckoutConfig is keyed by OfferType, and every key is required. That is not an oversight. A host that renders CheckoutContainer is saying it will handle whatever offer it is given, so when a new offer type ships, every host breaks at compile time rather than rendering a blank screen their users find first. A new offer type arriving in a catalogue is something you have to decide about. 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.

Key	Field	What you supply
`ondo::swap`	`symbol: (offer) => AssetSymbol`	Required. Ondo’s API symbol for the offer’s asset, e.g. `AAPLon`.
	`onOrderConfirmed?: (order) => void`	Optional. Fired once an Ondo swap has mined. The confirmation dialog shows either way.
`superstate::swap`	`onOrderConfirmed?: (order) => void`	Optional. Superstate needs nothing required today: the swap contract is looked up from the chain, and the funding assets and issuer are the provider’s own constants.
`coinlist::token_sale`	`render: (offer) => ReactNode`	Required. The SDK ships no token-sale UI yet, so this branch is yours. An L3 token-sale component is planned.

defaultCheckoutConfig({ ... }) fills in the entries that have a sensible default, so you only write the ones that do not. Today that is superstate::swap; it exists mostly so a provider that gains an optional setting can be defaulted there rather than appearing in every host’s config object.

Why `symbol` takes the offer

symbol is a function of the offer rather than a bare value because the symbol is per-asset while the config is per-integration: a host listing AAPLon and TSLAon side by side has one config and two answers. The SDK cannot answer it for you. Ondo’s symbol tracks the underlying ticker and changes on a rebrand, and it already disagrees with offer.asset.code on Sepolia, where a mock asset stands in. If your catalogue does agree, return AssetSymbol(offer.asset.code); if it does not, map the exceptions.

symbol must be total. React hooks cannot be called conditionally, so Ondo’s viewmodel runs for every offer, including Superstate and token-sale ones, where its result is handed to a disabled viewmodel and never read. Throwing on an offer you do not recognise would take down a checkout Ondo has no part in. Return anything.

What happens underneath

Every provider’s viewmodel is called on every render, because React hooks cannot be called conditionally. Only the one matching offer.type is enabled, so the other providers fetch nothing and run no timers. That is why every checkout viewmodel has an enabled flag. 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 as well as in your config.

Build your own UI with hooks (L2)

Each product exposes a god viewmodel wrapping its entire flow, plus the smaller 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.

import { useOndoBuyCheckoutViewModel } from "@coinlist-co/react";

const { state, onEvent } = useOndoBuyCheckoutViewModel({
  offer,
  ondoSymbol: AssetSymbol(offer.asset.code),
  chain: "ethereum_mainnet",
  wallets,
});

useSuperstateSwapCheckoutViewModel takes the same options minus ondoSymbol. Both return { state, onEvent }, where state is a discriminated union you switch on exhaustively.If you call these directly you are routing on offer.type yourself, and every hook must be called unconditionally - pass enabled: offer.type === "ondo::swap" to the ones that should be idle. That bookkeeping is exactly what CheckoutContainer does for you.Per-provider detail: Superstate Swap, Ondo Swap Buy, CoinList Token Sale. The conventions the hooks share - enabled, data, and the shape of state - are in SDK structure.

Drive it yourself with the client (L1)

Below the hooks are plain TypeScript namespaces on CoinListClient, 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.

const { coinlist } = useCoinList();

// Ondo: approve, then commit a firm quote, then broadcast it.
const prepared = await coinlist.ondo.prepareSwap({ /* ... */ });
const filled = await coinlist.ondo.executeSwap({ /* ... */ });

// Superstate: prove the wallet, then swap.
await coinlist.superstate.authorizeWallet({ /* ... */ });
await coinlist.superstate.execute({ /* ... */ });

// CoinList token sale: approve and record a participation.
await coinlist.tokenSale.execute({ /* ... */ });

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.

Next steps

Superstate Swap

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

Ondo Swap Buy

The symbol resolver, the committed quote, and the two-call order.

CoinList Token Sale

The render slot, the approval, and tracking participations.

Errors and edge cases

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

Get started

Offers and requirements

Flows

Reference

Building the Checkout flow

Prerequisites

Render it

Props

One mount, one offer, one chain

CheckoutConfig

Why `symbol` takes the offer

What happens underneath

Next steps

Superstate Swap

Ondo Swap Buy

CoinList Token Sale

Errors and edge cases

​Prerequisites

​Render it

​Props

​One mount, one offer, one chain

​CheckoutConfig

​Why symbol takes the offer

​What happens underneath

​Next steps

Superstate Swap

Ondo Swap Buy

CoinList Token Sale

Errors and edge cases

Prerequisites

Render it

Props

One mount, one offer, one chain

CheckoutConfig

Why `symbol` takes the offer

What happens underneath

Next steps