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 fund share).
• 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+.