Breaking Changes

AuthState is an object

// Before
passage.auth.getState() === "logged-in";

// After
passage.auth.getState().type === "logged-in";

OAuthAccessToken requires signInMethod

// Before
return { value: data.value, expiresAt: new Date(data.expiresAt) };

// After
return {
  value: data.value,
  expiresAt: new Date(data.expiresAt),
  signInMethod: data.signInMethod,
};

ClientCredentialsOAuth is no longer an OAuthAccessToken

Added

Wallet sign-in

• walletSignIn on PassageProvider takes { challenge, complete, signOut, connection }: three calls to your backend, and your app’s WalletConnection (connecting, disconnected, or connected with an address and chain).
• useWalletSignIn() returns { state, signIn }. signIn(wallet) resolves to a WalletSignInResult: signed-in, canceled, or failed with the step that failed (challenge, signature, or complete). A call while one is pending starts nothing and resolves with the pending one’s result.
• passage.auth.signInWithWallet({ wallet }) is the same sign-in without the hook. Both throw WalletSignInConfigRequiredError without the walletSignIn prop.
• usePassage().authState is passage.auth.getState() as React state, so a component re-renders on a sign-in or sign-out.

What a wallet session can call

Checkout on a wallet session

Other additions

• signInMethodFor(requirements) from /universal returns "coinlist" for any requirement and "wallet" for none, so a server can choose the page’s sign-in button before any user is known.
• useOfferRequirements({ offerId, data?, enabled? }) reads an offer’s requirements without statuses, so a wallet session can read them too.
• useCheckoutSessionViewModel (@alpha) gives a checkout with its own UI the same session handling as CheckoutContainer.
• OndoSwapRefusal and a build-refused arm on OndoSwapPreparationError, for an order CoinList refuses because its requirements are not met. An exhaustive switch on the error gets a compile error until it handles the new arm.
• SignInMethod, SessionWallet, SiweMessage, WalletSignInChallenge, WalletSignInChallengeParams, and WalletSignInGrant are new types from /universal.

Changed

• Ondo and Centrifuge checkouts show a skeleton until PassageProvider is ready.
• An Ondo requirements_not_met now says “Complete the requirements for this offer before placing an order.” instead of asking the user to try again.
• A wallet that rejects with a plain 4001 now reads as canceled rather than failed.

Breaking Changes

optionId is required on every checkout

// Before
<CheckoutContainer
  key={`${offer.id}:${chain}:${side}`}
  offer={offer}
  chain={chain}
  side={side}
  wallets={wallets}
/>

// After
const optionId = selectedOption?.id ?? offer.options[0]?.id; // your choice, not the SDK's
{optionId && (
  <CheckoutContainer
    key={`${offer.id}:${chain}:${side}:${optionId}`}
    offer={offer}
    chain={chain}
    side={side}
    optionId={optionId}
    wallets={wallets}
  />
)}

ClaimContainer takes offers

One claim viewmodel

// Before
const { state, onEvent } = useCentrifugeVaultClaimViewModel({ offer, wallets, onClaimed });
onEvent({ type: "ON_CLAIM", legId });

// After
const { state, onEvent } = useClaimViewModel({
  offers: offer,
  wallets,
  config: { "centrifuge::vault": { onClaimed } },
});
onEvent({ type: "ON_CFG_CLAIM", legId });

useCentrifugeClaimPositions reads several offers

Added

Several offers in one claim card

• The card has one header, one empty state, and one wallet footer. The footer shows only when a vault offer is on the card.
• It loads until every offer has answered. If any offer fails, it shows one error, and Retry refetches every offer. An error shows even while another offer is still loading.
• Rows come in this order: claimable vault positions, pending vault positions, then token-sale participations, newest first.
• With one offer and no orders, the card shows that provider’s copy. With two or more, it shows “No orders yet.” A card of vault offers only renders nothing when it has no rows and externalAdapter is null.
• An empty list renders nothing.
• Each provider reads all of its offers on one poll. A claim collects one row, on that row’s offer.

CentrifugeVaultOfferDetail.underlyingFund

Changed

• useCoinListTokenSaleParticipations takes offers?: OfferId | readonly OfferId[] as its first argument (was offerId?: OfferId). Existing calls still compile. A list is read offer by offer on one poll, and the hook settles once every offer has answered. Any failure fails the whole read. A new array with the same ids does not refetch. See Invest flow.
• CentrifugeVaultClaimed gains offerId, so onClaimed tells you which offer was claimed.
• CentrifugeVaultLegId now includes the vault address, so two vaults on one chain no longer share an id. Treat it as opaque.

Added

WalletSelection.status

import type { WalletSelection } from "@passage-cl/react/universal";

const wallets: WalletSelection = {
  status: embeddedWalletsListed ? "ready" : "loading",
  embedded,
  external,
  externalAdapter,
};

• While 'loading', before a first answer, the card shows its loading state. It sends no request and starts no poll.
• It shows “No orders found for this asset.” only once every wallet it asked about has answered.
• When a wallet is added, the card shows loading in that same render instead of the earlier empty answer. Rows it already shows stay visible while the new wallet is read.
• Going from 'ready' back to 'loading' keeps the orders and the connect footer the card last showed until 'ready' returns.

Changed

• The Ondo quote line (“Quote expires in N seconds” and “Refresh quote”) is hidden while the place-order button is loading, on both buy and sell, and comes back once it stops. OndoQuoteStatusUi gains { type: 'placing' }, which useOndoReviewExecution returns exactly while an order is being placed. An exhaustive switch over OndoQuoteStatusUi needs a case for it. See Ondo swap.
• Terms links in the review step now point at CoinList: https://coinlist.co/terms/centrifuge for Centrifuge (was https://centrifuge.io/terms) and https://coinlist.co/terms/ondo for Ondo (was https://docs.ondo.finance/legal/terms-of-service).

Fixed

• coinlistBaseUrl with a trailing slash or a path. auth.startOAuth() and requirements.handle join coinlistBaseUrl to the page path with exactly one slash. Before, a trailing slash gave a // in the sign-in redirect, and requirements.handle dropped any path after the origin.

Breaking Changes

category is removed from offers

// Before
const label = offer.category;

// After
const label = offer.type;

WalletError gains disconnected

• an EIP-1193 error with code 4100 anywhere in the cause chain;
• wagmi’s ConnectorNotConnectedError;
• the new WalletDisconnectedError.

// After
case "disconnected":
  return "Your wallet disconnected - reconnect or choose another.";

Added

WalletDisconnectedError

import { WalletDisconnectedError } from "@passage-cl/react/universal";

throw new WalletDisconnectedError("The account changed.", { cause: error });

Centrifuge deposit fee

Changed

• Checkouts follow the wallet the host supplies now. The token sale, Ondo buy and sell, Superstate and Centrifuge checkouts hold the confirmed wallet by its address and look it up in the current wallets on every render, so each step sends through the wallet you supply now. When you stop supplying that address, the checkout reopens the wallet step with “Your wallet disconnected - reconnect or choose another.” A send already in flight settles first. A checkout that skipped its wallet step for a preselected wallet (every provider but Superstate, which keeps it) has no step to return to, so there the user sees the disconnected copy only if a send fails. The Centrifuge claim card looks up its wallet the same way.
• A Centrifuge deposit is built on the amount step. Confirming the amount approves the funding token and requests the deposit (POST /v1/centrifuge/vault/invest), so the review opens with the built request and its fee, and Place only sends it. An approval or request failure shows on the amount button. The review shows the API’s fee, 0.00 USDC included, and a total equal to the amount. A request that expires before Place is rebuilt once, and so is one the vault refuses as request-expired at Place. A failed rebuild shows an error with Retry. A redemption is unchanged.
• Centrifuge buy review types (@alpha): CentrifugeBuyCheckoutUiState.review is a CentrifugeBuyReviewUiState, which adds { type: 'loading' } and { type: 'error'; reason: CentrifugeBuyReviewErrorReason } ('build-failed' | 'expired') to CentrifugeReviewUiState. CentrifugeBuyCheckoutUiEvent takes CentrifugeBuyReviewUiEvent, which adds { type: 'ON_RETRY' }.

Fixed

• The Centrifuge deposit’s confirmation dialog shows the token’s icon. Before, it showed none.

Breaking Changes

Ondo orders require offerOptionId

// Before
await passage.ondo.prepareBuy({ wallet, symbol, chain, swapContracts, tokenAddress, amount });

// After
await passage.ondo.prepareBuy({ wallet, symbol, chain, swapContracts, tokenAddress, amount, offerOptionId: option.id });

Centrifuge claims are built by the API

// Before
await passage.centrifuge.claim({ wallet, vault, direction: "deposit" });

// After
await passage.centrifuge.claim({ wallet, symbol: AssetSymbol(offer.asset.code), vault, direction: "deposit" });

Added

optionId for Ondo and Centrifuge checkouts

• With no optionId, the checkout uses the offer’s only option.
• An offer with several options and no optionId, an id the offer does not show, or an offer with no options replaces the checkout with “Option not available” (unknown-option). No request is sent.
• Superstate and a Centrifuge redemption ignore it. The token sale still buys its first option when none is named.
• The checkout reads optionId once, at mount. To switch options, remount it with a key.

Centrifuge claim transactions

Requirements checklist continueLabel

USDZ

Dark-theme token logos

Changed

• CheckoutBlockedReason is now 'unsupported-chain' | 'unknown-option' | TBlocked, so OndoCheckoutErrorReason and CentrifugeCheckoutErrorReason gain 'unknown-option'. The token sale already had it. An exhaustive switch over either reason needs a case for it.
• The Centrifuge claim dialog shows three steps: “Preparing your claim”, “Confirm in your wallet” and “Confirming on-chain”. Wallet failures use the same messages as the checkout. Retry is offered once when the vault refuses the claim, and never for a claim that may still confirm, for nothing to claim, or for a chain with no proxy.
• The Centrifuge claim card reads “No orders found for this asset.” and “Invested with an external wallet? Connect it to view your orders.” Claimable rows explain the ~ estimate in a tooltip.
• A blocked checkout logs checkout blocked once per reason: at error for a configuration problem (unsupported-chain, unknown-option, no-price, no-payable-asset), at warn for market state (not-tradable, not-orderable). Superstate’s load-failed screen logs no such line.
• At debug, every transaction logs when it is sent and how it ends, and a reverted transaction is replayed to log the contract’s revert reason. Below debug the replay makes no request. The debug line for an HttpError includes the response body and request id.

Fixed

• A transaction built by the API (Ondo swaps, Centrifuge requests, the Superstate allow-list) that reverts during gas estimation is now a contract_reverted WalletError with its reason. Before, it was unknown.
• A stale Centrifuge request now reports request-expired, as v0.14.0 described. Before, the check never matched and the checkout showed a generic error.
• Retrying a failed Centrifuge claim uses the wallet the host supplies now for that address. Before, it reused the adapter from the first attempt and failed again after the wallet changed account or chain. If the address is no longer connected, Retry closes the dialog.

Breaking Changes

Centrifuge claims are encoded by the SDK

// Before
const result = await passage.centrifuge.claim({ wallet, chain, symbol, direction: "deposit" });
if (result.type === "success") console.log(result.claimed);

// After
const result = await passage.centrifuge.claim({ wallet, vault, direction: "deposit" });
if (result.type === "success") console.log(result.settlement?.shares);

Centrifuge vault status reports each direction

// Before
const canBuy = status.orderability.type === "orderable";

// After
const canBuy = status.deposit === "active";
const canSell = status.redeem === "active";

Centrifuge checkout and claim types

onOrderPlaced: (order) => {
  if (order.side === "buy") track("deposit", order.txHash);
  else track("redemption", order.txHash);
},

Added

Centrifuge sell checkout

• The steps are wallet, amount and review. A preselected wallet skips the wallet step, as on the buy side.
• The amount is a number of the vault’s share tokens, bounded by the wallet’s balance. The offer’s dollar minimum applies to deposits only.
• Placing the order approves the vault proxy for the shares when the allowance is short, builds the request and broadcasts it. A redemption pays nothing yet: the fund fulfils it later, and the user claims the USDC in ClaimContainer.
• The checkout blocks with “Redeeming is paused right now” when the vault’s redeem direction is paused or stopped.
• config["centrifuge::vault"].onOrderPlaced fires after the redemption request mines, with order.side === "sell".
• To build your own UI, use useCentrifugeSellCheckoutViewModel (@alpha) with CentrifugeSellCheckoutUiState and CentrifugeSellCheckoutUiEvent.

Typed Centrifuge refusals

Claim estimates

coinlist_account requirement

Changed

• The Centrifuge buy checkout blocks only when the vault’s deposit direction is paused or stopped. Before, it also blocked on an unlinked, halted or unpermissioned vault, or a stale price.
• The Centrifuge claim card no longer polls the vault status. Each row leads with what the claim pays, in that token’s icon, and the claim dialog is titled with it (“Claiming ~964.12 deJTRSY”).
• The Centrifuge order-placed dialog shows the amount invested or redeemed, the receiving wallet, and a notice to claim once the order is processed.

Fixed

• Centrifuge claims work. Before, both claim directions failed with a 404.
• A Centrifuge request whose signature went stale, because it expired or a claim moved the wallet’s nonce, now reports request-expired, so placing it again builds a fresh one.

npm uninstall @coinlist-co/react
npm install @passage-cl/react

Breaking Changes

The package is now @passage-cl/react

Exported names are rebranded to Passage

@coinlist-co/react           -> @passage-cl/react
createCoinListClient         -> createPassageClient
createCoinListServer         -> createPassageServer
CoinListClientInitializationError -> PassageClientInitializationError
CoinListClient               -> PassageClient
CoinListServer               -> PassageServer
CoinListProvider             -> PassageProvider
UseCoinListResult            -> UsePassageResult
useCoinList                  -> usePassage
CoinListStyleScope           -> PassageStyleScope

// Before
import { CoinListProvider, useCoinList } from "@coinlist-co/react";
const { coinlist } = useCoinList();
await coinlist.offers.list();

// After
import { PassageProvider, usePassage } from "@passage-cl/react";
const { passage } = usePassage();
await passage.offers.list();

CSS class names and selectors are rebranded

/* Before */
.clco-sdk-root { --color-brand-primary: #0052ff; }

/* After */
.pcl-sdk-root { --color-brand-primary: #0052ff; }

ESM only, Node engines and bounded React peers

• The package ships ES modules only. The CommonJS builds, main, module and the require export conditions are removed. Bundlers and Next.js consume ESM natively. A plain-Node require() works only through Node’s built-in require(esm).
• engines.node is now ^20.19.0 || >=22.12.0.
• The react and react-dom peer ranges are now ^18.0.0 || ^19.0.0, instead of >=18.0.0. viem ^2 is unchanged.

Universal names are exported from /universal only

// Before
import { HttpError, type EvmWallet } from "@coinlist-co/react";

// After
import { HttpError, type EvmWallet } from "@passage-cl/react/universal";

The public API is Containers, viewmodels, data hooks and namespaces

CheckoutContainer takes side as a prop, and config is optional

// Before
const config = defaultCheckoutConfig({
  "ondo::swap": { symbol: (offer) => AssetSymbol(offer.asset.code), side: () => "sell" },
  "coinlist::token_sale": { render: (offer) => <MyTokenSalePage offer={offer} /> },
});
<CheckoutContainer offer={offer} chain={chain} wallets={wallets} config={config} />

// After
<CheckoutContainer
  key={`${offer.id}:${chain}:sell`}
  offer={offer}
  chain={chain}
  side="sell"
  wallets={wallets}
/>

CheckoutWalletSelection takes an externalAdapter

// Before
const wallets = { embedded, external, preselected: null, connectExternal: open, disconnectExternal: disconnect };

// After
const wallets = { embedded, external, preselected: null, externalAdapter: { connect: open, disconnect } };

Checkout viewmodel state

• OndoWalletSelectUiState and OndoWalletSelectUiEvent are replaced by CheckoutWalletSelectUiState and CheckoutWalletSelectUiEvent. The event has the same shape. The state’s externalWallet changes as described above.
• OndoBuyCheckoutUiState.wallet is now nullable. It is null when a preselected wallet skipped the wallet step.
• OndoBuyQuoteStatusUi and OndoSellQuoteStatusUi merge into OndoQuoteStatusUi, with the same shape.
• Superstate’s amount step uses the shared CheckoutAmountUiState and CheckoutAmountUiEvent. SuperstateAmountUiState and SuperstateAmountUiEvent are removed, confirmEnabled becomes confirmCta: CheckoutCtaUi, and the confirm event ON_PREVIEW_ORDER is renamed ON_CONFIRM_AMOUNT.
• The Superstate order dialog state drops issuer.

Data hooks return a state union

useParticipations is renamed useCoinListTokenSaleParticipations

• It polls passage.tokenSale.list(offerId) every 15 seconds while the page is visible, and reads again when the page becomes visible. pollInterval?: Seconds sets the interval.
• It returns refetch().
• A data seed skips only the first read. Before, a seed stopped all fetching.
• A switched-off hook with nothing in hand reports DISABLED instead of LOADING.
• A failed poll keeps the list it already has. A not-authenticated failure drops the list and reports ERROR.

Flow errors separate “not sent” from “sent but not confirmed”

passage.tokenSale.execute takes the offer

Token-sale and Superstate types

• The Blockchain and WalletAddress newtypes are removed. CreateParticipationParams takes chain: EthereumChain and walletAddress: EvmWalletAddress. Participation.chain is now Chain | null, and null stands for a chain the SDK does not model. Participation.walletAddress is EvmWalletAddress | null.
• AllowWalletResponse’s broadcast arm nests the transaction: { action: "broadcast_transaction"; tx: Tx } instead of { action; to; data }.
• CoinListSignInButtonProps is its own interface, and its props no longer accept null. Omit a prop instead.

Session handling (server)

• ServerConfig.accessTokenExpiryBufferSeconds is now a Seconds, not a number. Build it with Seconds.of(120) from @passage-cl/react/universal. The default is still 60 seconds.
• passage.auth.getAccessToken() on the server now throws the underlying error when the access token has expired and the refresh could not get an answer: a 5xx, a network failure or invalid_client. It used to return null and clear the session. It still returns null when there is no session or the session was rejected. Other methods that need a session throw the same error in that case.
• CompleteOAuthParams is removed. passage.auth.completeOAuth(grant) takes an AuthorizationGrant ({ code, codeVerifier }) from @passage-cl/react/universal, with the same fields.
• ServerAuthNamespaceImpl is no longer exported.

// Before
createPassageServer({ ...config, accessTokenExpiryBufferSeconds: 120 });

// After
import { Seconds } from "@passage-cl/react/universal";
createPassageServer({ ...config, accessTokenExpiryBufferSeconds: Seconds.of(120) });

Session handling (browser)

An empty base URL throws

Added

CoinList token-sale checkout in CheckoutContainer

• optionId?: OfferOptionId on CheckoutContainer picks the sale option. It defaults to the first option and is read once at mount.
• config["coinlist::token_sale"].onOrderPlaced is called after an order is placed.
• An option with no fixed price, such as an auction, renders “Not available yet” (no-price).
• useCoinListTokenSaleCheckoutViewModel and its UI types are public (@alpha). TokenSaleApproval is public and inside the compatibility contract.

Centrifuge vaults

• CheckoutContainer mounts a Centrifuge buy checkout, which places a deposit request, for side: "buy". It is USDC only and blocks with unsupported-chain or not-orderable while the vault is paused. side: "sell" renders an empty container until the redeem flow ships. config["centrifuge::vault"].onOrderPlaced fires after the request mines.
• passage.centrifuge exists on both PassageClient and PassageServer:

• Hooks: useCentrifugeVaultStatus, useCentrifugeVaultStatuses, useCentrifugeClaimPositions, useCentrifugeClaim, useCentrifugeBuyCheckoutViewModel and useCentrifugeVaultClaimViewModel.
• 'CENTRIFUGE' is a new LogScope. A logger that switches over LogScope needs the case.

ClaimContainer

{AsyncOfferDetail.is(offer) && <ClaimContainer key={offer.id} offer={offer} wallets={wallets} />}

• For a Centrifuge vault, it reads every wallet’s pending and claimable positions on-chain, and offers a Claim button on each claimable row. config["centrifuge::vault"].onClaimed fires after a claim.
• For a CoinList token sale, it lists your participations in that sale across your account and polls every 15 seconds, so an order placed on the same page appears by itself. There is nothing to claim: the sale delivers tokens and refunds by itself.
• It takes wallets: WalletSelection, an optional walletLabel resolver, config, enabled and className.
• To build your own claim UI, use useCentrifugeVaultClaimViewModel or useCoinListTokenSaleClaimViewModel (@alpha), with their UI state and event types.

Wallet preselection in every checkout

onSessionExpired

• In the browser, it fires after a 401 when your getAccessToken twice answers null or the very token the API just refused, one second apart, and the user had been logged in.
• On the server, it fires when the same refresh token is rejected twice, 5 to 60 seconds apart, or when an expired session has no refresh token. The SessionStore is cleared first.
• It never fires on logout, a 5xx or a network failure. It fires at most once per session within a 60-second window, counted per JavaScript module instance on the server (Next.js middleware and route handlers count separately), so make the handler idempotent. The SDK does not await it, and a rejection is logged and dropped.

Ondo market closed

Namespace methods

• passage.wallets.connect({ wallet, offerId, offerOptionId }) binds a host wallet to an offer option. It replaces connectExternalWalletFlow.
• passage.superstate.getQuote(params) returns a SwapQuote, on both the client and the server.

Other additions

• LoadErrorReason ("not-authenticated" | "generic-error") is the shared reason on the ERROR state of the ERC-20, Superstate quote, Ondo, participation and Centrifuge hooks. On these hooks an HTTP 401, including one from the JSON-RPC proxy, now reports not-authenticated instead of generic-error. useOffers, useOfferDetails and useRequirements keep their own reason types.
• EpochMillis, Millis and Seconds time types in /universal.
• WalletSelection, ExternalWalletAdapter and WalletLabelResolver in /universal.
• formatShareAmount(amount, locale), and a minFractionDigits option on formatAmount.
• CheckoutExternalWalletUi, CheckoutWalletSelectUiState, CheckoutAmountUiState, CheckoutBlockedReason, OndoQuoteStatusUi and the Load*State types named above.
• ./package.json is exported.
• The published API is recorded in API reports, and the typed surface outside @alpha is the compatibility contract.

Changed

• Single-flight session renewal. On the server, one refresh runs per refresh token per process, shared across PassageServer instances. A first invalid_grant no longer clears the session, and a 5xx or network failure never clears it. In the browser, concurrent requests share one getAccessToken call. A 401 now forces a refresh even when the token looks valid locally. /oauth/token is never retried automatically.
• A session with an invalid expiresAt now throws ValidationError instead of being served as fresh forever.
• Superstate checkout copy now matches the Ondo and Centrifuge wording. The amount button reads “Confirm amount”, approval and swap errors use the shared copy, and the review disclaimer names CoinList’s Terms of Service and Privacy Policy as well as Superstate’s Terms.
• Amount validation order is the same in every checkout: parse, zero, minimum, balance, cap. Ondo buy now reports the minimum before the balance.
• Amount fields show the token symbol after the number and accept only digits and one decimal point. The “Powered by CoinList” tag is removed from the sign-in card.
• formatAmount trims trailing zeros past the minimum after rounding, and Ondo share amounts show at most six decimals.
• The Superstate review keeps its in-flight state when the user leaves mid-swap, so a second swap cannot start while the first is still running.

Fixed

• passage.auth.logout() on the server clears the session whatever the revoke failure, including a network error, unless strict is set. With strict, it rethrows and keeps the session.
• In the browser, passage.auth.logout() wins over a getAccessToken answer already in flight, so a late answer can no longer sign the user back in.
• passage.ondo.executeSwap keeps the txHash when the receipt wait fails (see the new swap-unconfirmed arm).
• The Ondo transaction hooks no longer get stuck loading when the request changes during a build.
• A nullable field missing from a response now reads as null instead of undefined.
• A 401 renewed into a persistent 5xx makes 4 attempts instead of 6.
• instanceof HttpError holds whichever entry point the error came from.
• Long fund names wrap in the order-confirmation dialogs.

Breaking Changes

Offer and OfferDetail are unions on type

// Before
const subtitle = offer.tagline;
const spender = swapSpender(detail.swapContracts, chain);

// After
const subtitle = offer.type === "ondo::swap" ? null : offer.tagline;
const spender =
  detail.type === "ondo::swap" ? swapSpender(detail.swapContracts, chain) : null;

OffersGridContainer data is an object

// Before
<OffersGridContainer data={offers} />

// After
const server = coinListServerForRSC();
const [offers, tokens] = await Promise.all([server.offers.list(), server.tokens.list()]);
<OffersGridContainer data={{ offers, tokens }} />

On-chain reads return plain values

// Before
const { balance } = await coinlist.erc20.getBalance({ tokenAddress, owner, chain });
const { authorized } = await coinlist.superstate.getAuthorization(params);

// After
const balance = await coinlist.erc20.getBalance({ tokenAddress, owner, chain });
const authorized = await coinlist.superstate.getAuthorization(params);

Superstate SwapStatus is a union, and paused is not stopped

type SwapStatus =
  | { state: "active" }
  | { state: "paused"; pausedLevels: PauseFlags }
  | { state: "stopped" };

The requirements checklist no longer renders a sign-in card

// Before
<RequirementsChecklistContainer offerId={offer.id} optionId={option.id} {...copy} />

// After
const { isReady, coinlist } = useCoinList();
return isReady && coinlist.auth.getState() === "logged-in" ? (
  <RequirementsChecklistContainer offerId={offer.id} optionId={option.id} {...copy} />
) : (
  <CoinListSignInCardContainer />
);

ONDO_QUOTE_EXPIRY_THRESHOLD_MS is replaced

Added

Route on-chain reads to your own node

import { fallback, http } from "viem";

createCoinListClient({
  clientId,
  redirectUri,
  rpc: {
    ethereum_mainnet: "https://eth-mainnet.example.com/v2/KEY",
    ethereum_sepolia: fallback([http(primaryUrl), http(backupUrl)]),
    // base_* unset: proxied through CoinList
  },
});

• viemChain(chain) returns the viem Chain definition the SDK uses for an EthereumChain.
• isSwapAvailable, SWAP_LEVEL and PauseFlags, for the Superstate status above.
• Logging: a new RPC LogScope, and an rpc arm on LogCause with reason: RpcFailureReason (reverted, node-rejected, transport, malformed-response, unknown). Each reason names a remedy, not the viem error class. Nothing is read off the thrown error above debug.

Token-registry artwork on the offer cards

Security reference fields on OfferDetail

enabled on the remaining data hooks

• useOffers, useOfferDetails, useRequirements, useParticipations
• useOffersGridViewModel and OffersGridContainer
• useRequirementsChecklistViewModel and RequirementsChecklistContainer

Requirements checklist states

Changed

• CheckoutContainer mounts only the matching provider’s container. It used to call every provider’s viewmodel on every render and disable the ones that did not match. config["ondo::swap"].symbol and side now run only when an ondo::swap offer is showing, so they no longer have to handle Superstate and token-sale offers. enabled is forwarded to the mounted container as-is.
• Ondo quotes are offered for at most 15 seconds. The review step’s countdown runs to the earlier of Ondo’s deadline and 15 seconds after the quote was built, then asks for a fresh one.
• Requirements checklist design and copy. The footer shows an “N/M completed” counter, and Continue stays disabled until every requirement is met. The default labels are now Identity Verification (was KYC Verification) and Tax Documentation (was Document), with new descriptions for KYC, accreditation and tax documents. A tax document whose status is in_progress stays a required step until the user signs it. The loading, error and unsupported-jurisdiction states were redesigned.

Fixed

• Superstate’s confirmed output amount. The Swapped event ABI declared two non-indexed words where the contract emits three. As a result, decodeSwappedOutputAmount read the protocol fee as the amount received, and executeSwap reported that fee as the confirmed outputAmount. It now decodes the amount received.
• Amounts with a leading or trailing decimal point. parseBlockchainAmount now accepts .25 (read as 0.25) and 25. (read as 25). A bare . is still rejected.
• Checkout loading skeletons. The price skeletons in AssetSummaryRow and the Ondo and Superstate sidebars no longer stack flush against each other while loading.

Breaking Changes

@coinlist-co/react/shared is now @coinlist-co/react/universal

// Before
import { AssetSymbol, type OfferDetail } from "@coinlist-co/react/shared";
// After
import { AssetSymbol, type OfferDetail } from "@coinlist-co/react/universal";

Ondo forks into buy and sell

// Before
const prepared = await coinlist.ondo.prepareSwap({ wallet, symbol, chain, tokenAddress, amount });
// After
const prepared = await coinlist.ondo.prepareBuy({
  wallet, symbol, chain, tokenAddress, amount,
  swapContracts: offer.swapContracts,
});

The Ondo swap contract is read off the offer

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

// Before
const spender = ondoSwapContractAddress(chain);
// After
const spender = swapSpender(offer.swapContracts, chain); // EvmContractAddress | null

CheckoutConfig for Ondo requires side

const checkoutConfig = defaultCheckoutConfig({
  "ondo::swap": {
    symbol: (offer) => AssetSymbol(offer.asset.code),
    side: () => "buy",
  },
  "coinlist::token_sale": { render: (offer) => <MyTokenSalePage offer={offer} /> },
});

The Ondo checkout state is a union

type OndoBuyCheckoutUiState =
  | { type: "content"; wallet; amount; review; sidebar; orderConfirmed }
  | { type: "error"; reason: OndoCheckoutErrorReason };

OfferCard is now two components

// Before
<OfferCard offer={offer} onClick={...} />
// After
<OfferSaleCard offer={OfferSaleCardUi.fromOffer(offer)} onClick={...} />

CheckoutAssetUi.fromOffer takes token metadata

Added

The Ondo sell flow

CheckoutWalletSelection.preselected

Structured logging

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

<CoinListProvider
  config={{ clientId, redirectUri, logger: pinoClientLogger({ isDev: true, level: "debug" }) }}
>

• Logger (from @coinlist-co/react/universal) is the port: debug, info, warn, error, and level(). Implement it over your own sink in four methods.
• Two shipped implementations, one per environment: pinoClientLogger from @coinlist-co/react and pinoServerLogger from @coinlist-co/react/server.
• Every line is structured: a constant msg naming what happened, a scope (HTTP, OFFERS, ONDO, HOOKS, …), and a bag of fields carrying every value that varies. Field names follow OpenTelemetry where a stable key exists.
• Every event is a lambda, checked against level() before it runs, so an expensive debug line costs nothing at info and nothing at all with no logger supplied.

Base mainnet and Base Sepolia

Smaller additions

• coinlist.tokens.list(chain?) fetches the registry’s complete snapshot in a single request - every chain with no argument, one chain with it. Prefer it over get() in a loop when rendering a catalog. Unlike get, a missing snapshot throws rather than answering [].
• Offer.tokens and OfferDetail.tokens, the (chain, address) entries an offer’s assets live at, keyed by role.
• OffersAssetGrid, a responsive browse grid of OfferAssetCard leaves. Pure - no fetch, no provider - and distinct from OffersGridView, which lays out sale cards.
• useErc20Balance, the address-keyed counterpart to useErc20TokenBalances, for a token whose contract address arrives at runtime and has no registry symbol to look up.
• useCheckoutOfferTokenMetadata, which keys the registry lookup by the offer’s token entry for the checkout chain.
• OndoCheckoutError and OndoCheckoutErrorReason, the flow-level error surface both Ondo products share.
• Release candidates on npm. Every merge to main now publishes <next-patch>-rc.<short-sha> under the rc dist-tag, so a fix can be tried before it is tagged: npm install @coinlist-co/react@rc.

Changed

• Checkout asset logos resolve from the token registry first, taking the vector logo or the smallest raster variant covering the render width, and falling back to Offer.logoUrl and then a neutral placeholder. Every absence - loading, error, disabled, unlisted, no token entry - falls back rather than rendering a broken image.
• An Ondo checkout on a chain with no contract now fails at the flow level, before any step runs. It previously displayed a 0 balance for a token the flow would never spend and refused on Confirm, as though the amount were the problem.
• useTokenMetadata moved from the tokens feature to the shared hooks, now that checkout is its second consumer. The import path is unchanged: it is still exported from @coinlist-co/react.
• lucide-react is now ^1 (from ^0.577). It is a bundled dependency, not a peer, so no host action is needed.

Fixed

• An offer token on a chain the SDK does not model no longer blanks the offers list. One Base token took down the whole catalog: Offer.fromDto runs inside the paginated response’s map, so one unparseable item threw away the page. Unknown chains are now skipped, costing that token its logo.
• The Ondo amount step no longer strands the user when a quote expires while an error is showing. The refresh action is reachable from that state.
• The Ondo amount input reads USDC with a max affordance, matching the Superstate checkout.

Removed

• identity_verified, proof_of_address and source_of_funds are gone from RequirementType. They were left over from an abandoned modular-KYC effort and the backend no longer returns them, so a switch over requirement types needs three fewer arms.

Breaking Changes

Every remaining flat method moved into a namespace

// Before
const offers = await coinlist.fetchOffers();
const detail = await coinlist.fetchOfferDetails(offers[0].id);
const addresses = await coinlist.listOptionAddresses(offerId, offerOptionId);

// After
const offers = await coinlist.offers.list();
const detail = await coinlist.offers.get(offers[0].id);
const addresses = await coinlist.wallets.list({ offerId, offerOptionId });

// Before, on your backend
await coinListServer(response).completeOAuth(AuthorizationCode(code), CodeVerifier(codeVerifier));
const token = await coinListServer(response).accessToken();

// After
await coinListServer(response).auth.completeOAuth({
  code: AuthorizationCode(code),
  codeVerifier: CodeVerifier(codeVerifier),
});
const token = await coinListServer(response).auth.getAccessToken();

coinlist.swap is now coinlist.superstate

// Before
const result = await coinlist.swap.executeSwap({ wallet, contractAddress, chain, inputTokenAddress, quote, slippageBps });
// After
const result = await coinlist.superstate.execute({ wallet, contractAddress, chain, inputTokenAddress, quote, slippageBps });

Token-sale and ERC-20 methods dropped their stuttering prefixes

Offer.type values changed

switch (offer.type) {
  case 'coinlist::token_sale': return <TokenSale offer={offer} />;
  case 'superstate::swap':     return <Swap offer={offer} />;
  case 'ondo::swap':           return <OndoBuy offer={offer} />;
}

Components split into Container and View

// Before
import { OffersGrid } from "@coinlist-co/react";
<OffersGrid maxColumns={3} onOfferClick={onOfferClick} />

// After
import { OffersGridContainer } from "@coinlist-co/react";
<OffersGridContainer maxColumns={3} onOfferClick={onOfferClick} />

useSwapTokenBalances is now useErc20TokenBalances

Added

Ondo buy flow

• coinlist.ondo.prepareSwap({ wallet, symbol, chain, tokenAddress, amount, onProgress? }) submits the ERC-20 approval, then builds the transaction.
• coinlist.ondo.executeSwap({ wallet, transaction, chain, now?, onProgress? }) broadcasts it.

CheckoutContainer, a drop-in checkout for any offer type

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

const config = defaultCheckoutConfig({
  "ondo::swap": { symbol: (offer) => AssetSymbol(offer.asset.code) },
  "coinlist::token_sale": { render: (offer) => <MyTokenSalePage offer={offer} /> },
});

<CheckoutContainer offer={offer} chain="ethereum_sepolia" wallets={wallets} config={config} />

Superstate swap checkout UI

Token metadata from the CoinList registry

A global locale on CoinListProvider

<CoinListProvider config={config} locale="fr-FR">

HttpError and apiErrorCode

import { apiErrorCode, HttpError } from "@coinlist-co/react/shared";

try {
  await coinlist.tokenSale.createParticipation(params);
} catch (error) {
  if (error instanceof HttpError) {
    switch (apiErrorCode(error)) { /* ... */ }
  }
}

Smaller additions

• SolanaChain ('solana_mainnet' | 'solana_devnet') and Chain, the union of it with EthereumChain, both with validating constructors that throw ValidationError on an unknown value. Solana offers are not executable yet - this is the type surface an offer’s tokens are parsed against, ahead of the SolanaWallet seam.
• EvmSigner, the signing-only half of EvmWallet (address + signMessage). The external-wallet ownership proof needs nothing more, so a host can satisfy that flow without implementing on-chain capabilities.
• tokensBaseUrl on ClientConfig and ServerConfig, to point coinlist.tokens at a non-production registry.
• CoinListSignInButton, the button on its own for hosts that do not want the card.
• VerificationOverlay, and every requirements viewmodel and .types module.
• useOndoPrice, useOndoTradingStatus, useOndoSwapTransaction for composing your own Ondo viewmodel.
• Formatting and presentation helpers: useCountdown, and the asset-icon, date and duration formatters.

Changed

• Requirements, offers and wallets are the same namespace on both sides. coinlist.offers, coinlist.requirements and coinlist.wallets expose identical method names on CoinListClient and CoinListServer; the server adds an optional trailing clientCreds on the reads that can run without a user session, and the client adds requirements.handle.
• Ondo reads live under /v1/ondo/swap/* and take a required side. Ondo reports its limits per side, so a trading status fetched without one answers 422 rather than guessing buy.
• getQuote refuses a request sized by both tokenAmount and notionalValue, throwing ValidationError. TypeScript accepts an object carrying both, and the previous behavior silently dropped notionalValue.
• Participation, SwapQuote and the other provider types moved modules inside the package. They are still exported under the same names from @coinlist-co/react/shared, so only deep imports break - and deep imports were removed in v0.5.0.

Removed

• coinlist.swap.requestWalletOwnershipChallenge - use coinlist.wallets.createOwnershipChallenge, which is the same call and is shared by the checklist and the allow-list flow.

Fixed

Token-sale participations recorded the amount in the wrong units

Breaking Changes

Participation methods moved to the tokenSale namespace

// Before
const participations = await coinlist.fetchParticipations(offerId);
// After
const participations = await coinlist.tokenSale.fetchParticipations(offerId);

ERC-20 reads moved from swap to a new erc20 namespace

Offer.endsAt and OfferDetail.endsAt are now nullable

// Before — endsAt was always a Date
const label = offer.endsAt.toLocaleDateString();
// After — endsAt may be null
const label = offer.endsAt ? offer.endsAt.toLocaleDateString() : "No end date";

Added

Token-sale flow

const result = await coinlist.tokenSale.executeTokenSale({
  wallet,
  offerId,
  offerOptionId,
  assetId,
  paymentTokenAddress,    // ERC-20 the user pays with (e.g. USDC/USDT)
  fundingContractAddress, // the approve() spender
  chain,
  amount,                 // BlockchainAmount, base units
  onProgress,             // optional phase callback
});

erc20 namespace

Offer type

Changed

Stricter offer models

• Offer: tagline, bannerUrl, logoUrl.
• OfferDetail: tagline, bannerUrl, logoUrl, category.

Added

Swap namespace

• authorizeWallet({ wallet, offerId, contractAddress, chain, onProgress }) — proves wallet ownership and allow-lists it for a swap offer, with typed progress phases and a success / error result. Idempotent: returns success immediately if the wallet is already authorized.
• executeSwap({ wallet, contractAddress, chain, inputTokenAddress, quote, slippageBps, onProgress }) — runs the full on-chain swap: status check, ERC-20 approval (with USDT-style allowance reset), swap submission, and confirmation. The confirmed output is decoded from the Swapped event.

Swap hooks

• useSwapOutputToken — reads the swap contract’s output token (the tokenized equity).
• useSwapQuote — polls a live quote (15s default), skipping until the output-token decimals and a valid amount are known.
• useSwapTokenBalances — polls the user’s balance for one or more input assets.

Wallet abstraction

External wallet connect

• createWalletOwnershipChallenge(params) → POST /v1/wallet-ownership
• connectExternalWallet(offerId, params) → POST /v1/offers/{offer_id}/addresses
• listOptionAddresses(offerId, offerOptionId) → GET /v1/offers/{offer_id}/addresses
• removeOptionAddress(offerId, addressId) → DELETE /v1/offers/{offer_id}/addresses/{id}

Identity, KYC, and tax documents

• createKycToken(levelName?, reset?) → POST /v1/kyc-token (Sumsub)
• fetchPii() → GET /v1/pii, pre-fill data for tax forms
• submitDocument(documentType, fields) → POST /v1/documents/{document_type}/submission
• Components IdentityVerification and TaxDocumentModal; hooks useKycToken and useTaxDocument.
• handleRequirement now resolves the kyc_approved, identity_verified, proof_of_address, source_of_funds, accreditation, external_wallet, whitelisted_wallet, document, and jurisdiction requirement types.

App-level authentication

Shared (@coinlist-co/react/shared)

• BlockchainAmount (with add / sub), parseBlockchainAmount, formatAmount, computeSlip, and the Bps newtype.
• Constants and helpers: DEFAULT_SLIPPAGE_BPS, SLIPPAGE_OPTIONS_BPS, SWAP_POLL_INTERVAL_MS, SUPERSTATE_SWAP_CONTRACT_ADDRESS_SEPOLIA, TOKEN_REGISTRY, USDC_SYMBOL, txExplorerUrl.
• Swap, KYC, PII, document-submission, and wallet-ownership types.

Changed

CoinListProvider is safe to mount app-wide

Breaking Changes

approvalTransactionHash is required on createParticipation

await coinlist.createParticipation({
  offerId,
  offerOptionId,
  chain,
  walletAddress,
  amount,
  assetId,
  approvalTransactionHash, // ← now required
});

WalletAddress narrowed to `0x${string}`

Added

CSS isolation

coinlist.co support

Breaking Changes

SessionStore.setSession is now optional

// Before — no-op workaround (caused silent logout bug)
createCoinListServer({
  sessionStore: {
    getSession: () => getServerSession(),
    setSession: async () => {}, // ← remove this
  },
});

// After — read-only store (safe, explicit)
createCoinListServer({
  sessionStore: {
    getSession: () => getServerSession(),
  },
});

Added

WritableSessionStoreRequiredError

Fixed

No unnecessary network retries on expired tokens in read-only mode

Breaking Changes

Client methods renamed: fetchAll* → fetch*

fetchAllOffers(    →  fetchOffers(
fetchAllParticipations(  →  fetchParticipations(

Hooks renamed: useCoinList* → use*

// Before
import { useCoinListOffers, useCoinListRequirements } from '@coinlist-co/react';
const { offersState } = useCoinListOffers({ serverOffers: data });

// After
import { useOffers, useRequirements } from '@coinlist-co/react';
const { offersState } = useOffers({ data });

SSR prop renamed: serverOffers / serverData → data

LoadRequirementsState CONTENT shape: requirementsByOptionId → requirements

// Before
if (requirementsState.type === 'CONTENT') {
  const byOption = requirementsState.requirementsByOptionId;
}

// After
if (requirementsState.type === 'CONTENT') {
  const byOption = requirementsState.requirements;
}

Base* components removed

Import paths restructured — new @coinlist-co/react/shared entry point

// Before (sub-path imports — no longer valid)
import { CoinListClient } from '@coinlist-co/react/client';
import { useOffers } from '@coinlist-co/react/client/hooks';

// After
import { CoinListClient, useOffers } from '@coinlist-co/react';

OffersGridProps type renamed from Props