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 catalogue. 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 catalogue: 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 behaviour 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

// Before
import type { Props } from '@coinlist-co/react';

// After
import type { OffersGridProps } from '@coinlist-co/react';

Added

Server (@coinlist-co/react/server)

• CoinListServer now exposes the full data-fetching surface previously only available on CoinListClient: fetchAllOffers(), fetchOffersPage(), fetchOfferDetails(), fetchAllParticipations(), fetchParticipationsPage(), fetchParticipation(), createParticipation(), fetchOfferRequirements(), and fetchRequirementStatuses(). Use these in Next.js Route Handlers and Server Components without shipping any client bundle.
• @coinlist-co/react/server now re-exports all shared types — Offer, OfferDetail, Participation, Requirement, RequirementStatusInfo, pagination helpers, NotAuthenticatedError, and related types — so you no longer need to import them from the client entry.

Client (@coinlist-co/react, @coinlist-co/react/client)

• useParticipations(offerId?) hook — loads all participations for the authenticated user with a LOADING / CONTENT / ERROR state machine, optionally filtered by offer. New exported types: UseParticipationsResult, LoadParticipationsState, LoadParticipationsReason.
• handleRequirement(requirement) on CoinListClient — opens the corresponding CoinList page for completing a requirement in a new tab (/verify-identity, /wallet, etc.). No-op for jurisdiction requirements.
• contactSupport() on CoinListClient — opens the CoinList support ticket page in a new tab.

Changed

Components

• RequirementsChecklist: onRequirementAction and onContactSupport props have been renamed to onRequirementActionOverride and onContactSupportOverride. Both now default to CoinListClient#handleRequirement and CoinListClient#contactSupport respectively, so most integrations can omit them entirely. Pass null to disable the corresponding button/link.
• RequirementItem: onAction and onContactSupport now accept null (in addition to undefined) to suppress rendering of action buttons.

Removed

Client (@coinlist-co/react, @coinlist-co/react/client)

• sandbox option removed from ClientConfig. Sandbox offers are no longer toggled via the SDK config.
• StaticRequirementsChecklistProps type removed. Use RequirementsChecklist with the connected API or BaseRequirementsChecklist for fully custom rendering.

Added

Client (@coinlist-co/react, @coinlist-co/react/client)

• fetchOfferRequirements(offerId) on CoinListClient — returns requirements grouped by option ID (Record<OfferOptionId, Requirement[]>).
• fetchRequirementStatuses(offerId) on CoinListClient — returns the authenticated user’s status for each requirement.
• useCoinListRequirements(offerId) hook for loading requirements and statuses with a LOADING / CONTENT / ERROR state machine.
• sandbox option on ClientConfig — when true, passes sandbox=true to offers API calls so sandbox offers are included.
• New exported types: Requirement, RequirementId, RequirementType, RequirementStatusValue, RequirementStatusInfo, ParticipationsPaginationParams.
• New exported enums/constants: RequirementVariant, RequirementStatus, ChecklistStatus.
• New hook types: UseCoinListRequirementsResult, LoadRequirementsState, LoadRequirementsReason.
• fetchAllParticipations(offerId?) and fetchParticipationsPage(params) now accept an optional offerId to fetch participations for a specific offer. fetchParticipationsPage takes the new ParticipationsPaginationParams type (superset of PaginationParams) which carries the offerId field.

Fixed

Components

• Fixed missing dark mode CSS variables in Next.js projects — prebuilt styles now include the full set of design-system tokens so components render correctly under dark class or prefers-color-scheme: dark.

Added

Client (@coinlist-co/react, @coinlist-co/react/client)

• fetchAllParticipations() on CoinListClient for fetching all participations across pages.
• fetchParticipationsPage() on CoinListClient for paginated participation fetching.
• fetchParticipation() on CoinListClient for fetching a single participation by id.
• createParticipation() on CoinListClient for creating a new participation.
• New exported types: Participation, ParticipationId, ParticipationStatus, CreateParticipationParams, Blockchain, WalletAddress.

Added

Client (@coinlist-co/react, @coinlist-co/react/client)

• Added support for passing className and containerClassName to <OffersGrid />, <OfferCard />, and <CoinListSignInCard />.

Fixed

Client (@coinlist-co/react, @coinlist-co/react/client)

• Re-export offer, offer detail, and pagination types from the package root and client core entry so you can type against Offer, OfferDetail, pagination params, and related helpers without reaching into internal modules.
• Export BaseCoinListSignInCard and BaseCoinListSignInCardProps from @coinlist-co/react/client for custom sign-in layouts built on the same primitives as CoinListSignInCard.

Added

Client (@coinlist-co/react/client)

• fetchAllOffers(), fetchOffersPage(), and fetchOfferDetails() on CoinListClient for fetching offers data.
• <OffersGrid /> — batteries-included component that loads offers and displays them in a responsive grid, with <OfferCard /> for each tile.
• useCoinListOffers() hook for loading offers when you want full control over layout instead of the grid.
• useCoinListOfferDetails() hook for a single offer’s details.
• useCompleteCoinListOAuth() hook to run the OAuth redirect callback once on mount.
• Optional authorizationPageUrl on client config so you can point startOAuth() at a non-production authorization page.

Added

Client (@coinlist-co/react/client)

• CoinListProvider and useCoinList() hook for React context-based SDK initialization.
• createCoinListClient(config) factory for manual or non-React usage.
• OAuth 2.0 with PKCE via startOAuth() and completeOAuth().
• getAuthState() and logout().

Server (@coinlist-co/react/server)

• createCoinListServer(config) factory for BFF / Next.js API routes.
• completeOAuth(), accessToken() (auto-refreshing), and logout().

Components

• CoinListSignInCard and CoinListSignInButton for OAuth sign-in flows.
• RequirementsChecklist / RequirementItem — eligibility checklist with accordion UI.
• PoweredByCoinList attribution badge.
• Prebuilt CSS — no tailwindcss peer dependency required.

Infrastructure

• Subpath exports: @coinlist-co/react, @coinlist-co/react/client, @coinlist-co/react/server.
• Requires React 18+.