@coinlist-co/react 0.6.0 → 0.10.0

package/dist/client/index.d.ts

@@ -1,7 +1,296 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { A as AuthorizationCode, C as CodeVerifier, a as Config, O as OAuthAccessToken, b as Offer, P as PaginationParams, c as PaginatedResponse, d as OfferId, e as OfferDetail, f as Participation, g as ParticipationsPaginationParams, h as ParticipationId, i as CreateParticipationParams, j as OfferOptionId, R as Requirement, k as RequirementStatusInfo, l as RequirementType, m as RequirementStatusValue } from '../requirement-Dk6nYN1c.js';
+import { Hex, Abi, Hash, TransactionReceipt } from 'viem';
+import { E as EvmWalletAddress, a as EthereumChain, C as CoinListSwapNamespace, O as OfferId, b as EvmContractAddress, c as CoinListErc20Namespace, B as Bps, d as BlockchainAmount, S as SwapNamespaceImpl, e as SharedNamespaceContext, f as CoinListTokenSaleNamespace, g as OfferOptionId, A as AssetId, P as Participation, T as TokenSaleNamespaceImpl, h as AuthorizationCode, i as CodeVerifier, j as Config, k as OAuthAccessToken, l as Offer, m as PaginationParams, n as PaginatedResponse, o as OfferDetail, p as CreateWalletOwnershipChallengeParams, W as WalletOwnershipChallenge, q as ConnectExternalWalletParams, r as OfferOptionAddress, s as OfferOptionAddressId, R as Requirement, t as RequirementStatusInfo, u as Pii, D as DocumentType, v as DocumentSubmission, K as KycLevelName, w as KycToken, x as WalletChallengeType, y as RequirementType, z as RequirementStatusValue, F as Erc20Asset, G as AssetDecimals, H as StablecoinSymbol } from '../requirement-CDi5NJI8.js';
+import { S as SwapQuote, N as NonEmptyArray } from '../collections-ZYLKp8JB.js';
+
+type WriteContractParams = {
+    abi: Abi;
+    address: `0x${string}`;
+    functionName: string;
+    args?: readonly unknown[];
+    value?: bigint;
+    chain: EthereumChain;
+};
+type BroadcastTxParams = {
+    to: `0x${string}`;
+    data: Hex;
+    chain: EthereumChain;
+};
+/**
+ * The signing-only wallet capability: address + `signMessage`. This is all the
+ * external-wallet ownership proof needs (see `useConnectWallet`), so hosts can
+ * satisfy that flow without implementing on-chain capabilities. The richer
+ * {@link EvmWallet} extends this for swap flows.
+ *
+ * SDK users implement this against their own wallet stack (e.g. viem, wagmi,
+ * Privy). `signMessage` throws on failure and the SDK classifies it.
+ */
+interface EvmSigner {
+    readonly address: EvmWalletAddress;
+    signMessage(message: string): Promise<Hex>;
+}
+/**
+ * The full on-chain wallet the SDK needs to run the swap flows: an
+ * {@link EvmSigner} plus contract writes, raw-tx broadcast, and confirmation.
+ * SDK users implement this against their own wallet stack (e.g. viem, wagmi,
+ * Privy).
+ *
+ * Methods throw on failure. The SDK catches and classifies the thrown error
+ * (viem's `UserRejectedRequestError`, `InsufficientFundsError`, timeouts, …)
+ * into a typed {@link WalletError}, so implementers can simply let their wallet
+ * library's errors propagate.
+ */
+interface EvmWallet extends EvmSigner {
+    writeContract(params: WriteContractParams): Promise<Hash>;
+    broadcastRawTx(params: BroadcastTxParams): Promise<Hash>;
+    awaitTx(hash: Hash, chain: EthereumChain): Promise<TransactionReceipt>;
+}
+
+/**
+ * A classified wallet/transaction failure. The SDK derives this from whatever
+ * the {@link EvmWallet} throws, so consumers get a stable, typed error
+ * shape regardless of the underlying wallet library.
+ */
+type WalletError = {
+    type: 'user_rejected';
+} | {
+    type: 'insufficient_funds';
+} | {
+    type: 'contract_reverted';
+    reason: string;
+} | {
+    type: 'timeout';
+    hash: Hash;
+} | {
+    type: 'unknown';
+    cause: unknown;
+};
+/**
+ * Classifies an error thrown by an {@link EvmWallet} into a typed
+ * {@link WalletError}. Pass the transaction `hash` when awaiting a receipt so a
+ * timeout can be reported against it.
+ */
+declare function classifyWalletError(error: unknown, ctx?: {
+    hash?: Hash;
+}): WalletError;
+
+/** A step-tagged reason {@link submitErc20Approval} failed. */
+type Erc20ApprovalError = {
+    step: 'approval';
+    cause: WalletError;
+} | {
+    step: 'approval-reverted';
+};
+
+/**
+ * Progress phases emitted by {@link executeSwap}, in the order they occur. An
+ * allowance that already covers the swap skips the approval phases.
+ */
+type SwapExecutionPhase = 'checking-status' | 'checking-allowance' | 'resetting-allowance' | 'confirming-allowance-reset' | 'approving' | 'confirming-approval' | 'swapping' | 'confirming-swap';
+/** A step-tagged reason {@link executeSwap} failed. */
+type SwapExecutionError = {
+    step: 'status-check';
+} | {
+    step: 'swap-stopped';
+} | {
+    step: 'allowance-check';
+} | Erc20ApprovalError | {
+    step: 'swap';
+    cause: WalletError;
+} | {
+    step: 'swap-reverted';
+};
+type SwapExecutionResult = {
+    type: 'success';
+    swapTxHash: Hash;
+    inputAmount: BlockchainAmount;
+    fee: BlockchainAmount;
+    outputAmount: BlockchainAmount;
+    pricePerShare: BlockchainAmount | null;
+    recipientAddress: EvmWalletAddress;
+} | {
+    type: 'error';
+    error: SwapExecutionError;
+};
+type ExecuteSwapParams = {
+    swap: CoinListSwapNamespace;
+    erc20: CoinListErc20Namespace;
+    wallet: EvmWallet;
+    contractAddress: EvmContractAddress;
+    chain: EthereumChain;
+    inputTokenAddress: EvmContractAddress;
+    quote: SwapQuote;
+    slippageBps: Bps;
+    onProgress?: (phase: SwapExecutionPhase) => void;
+};
+/**
+ * Executes an on-chain swap end-to-end: verifies the contract is not paused,
+ * ensures a sufficient ERC-20 allowance (resetting a stale non-zero allowance
+ * first for USDT-style tokens), submits the swap, waits for it to mine, and
+ * decodes the confirmed output from the `Swapped` event (falling back to the
+ * quote's estimate).
+ *
+ * The wallet is only asked to sign after all read-only checks pass, so a user
+ * never signs a transaction the swap would revert. Progress is reported via
+ * `onProgress` for consumers rendering loading states.
+ */
+declare function executeSwap(params: ExecuteSwapParams): Promise<SwapExecutionResult>;
+/** Progress phases emitted by {@link authorizeWallet}, in order. */
+type WalletAuthorizationPhase = 'checking-authorization' | 'requesting-challenge' | 'signing-message' | 'submitting-signature' | 'broadcasting-transaction' | 'awaiting-confirmation' | 'verifying-authorization';
+/** A step-tagged reason {@link authorizeWallet} failed. */
+type WalletAuthorizationError = {
+    step: 'authorization-check';
+} | {
+    step: 'challenge-request';
+} | {
+    step: 'signing';
+    cause: WalletError;
+} | {
+    step: 'allow-wallet';
+} | {
+    step: 'broadcast';
+    cause: WalletError;
+} | {
+    step: 'not-authorized';
+};
+type WalletAuthorizationResult = {
+    type: 'success';
+} | {
+    type: 'error';
+    error: WalletAuthorizationError;
+};
+type AuthorizeWalletParams = {
+    swap: CoinListSwapNamespace;
+    wallet: EvmWallet;
+    offerId: OfferId;
+    contractAddress: EvmContractAddress;
+    chain: EthereumChain;
+    onProgress?: (phase: WalletAuthorizationPhase) => void;
+};
+/**
+ * Proves ownership of a wallet and allow-lists it for an offer's swap: checks
+ * whether it is already authorized, otherwise signs a challenge, submits it,
+ * broadcasts any returned allow-list transaction, and re-verifies on-chain.
+ *
+ * Wallet selection/connection is the app's responsibility — this operates on an
+ * already-connected {@link EvmWallet}. Progress is reported via
+ * `onProgress`.
+ */
+declare function authorizeWallet(params: AuthorizeWalletParams): Promise<WalletAuthorizationResult>;
+
+/**
+ * The client-side swap namespace: everything the shared
+ * {@link CoinListSwapNamespace} reads/writes over the API, plus the on-chain
+ * flows that drive a wallet (`executeSwap`, `authorizeWallet`). The flows take
+ * the wallet and addresses per call; the namespace itself supplies the API
+ * reads they depend on.
+ */
+interface CoinListClientSwapNamespace extends CoinListSwapNamespace {
+    /**
+     * Runs an on-chain swap end-to-end against the given wallet: status check,
+     * ERC-20 allowance/approval, swap submission, and receipt confirmation.
+     */
+    executeSwap(params: Omit<ExecuteSwapParams, 'swap' | 'erc20'>): Promise<SwapExecutionResult>;
+    /**
+     * Proves ownership of a wallet and allow-lists it for an offer's swap,
+     * broadcasting any required allow-list transaction.
+     */
+    authorizeWallet(params: Omit<AuthorizeWalletParams, 'swap'>): Promise<WalletAuthorizationResult>;
+}
+declare class ClientSwapNamespaceImpl extends SwapNamespaceImpl implements CoinListClientSwapNamespace {
+    private readonly erc20;
+    constructor(ctx: SharedNamespaceContext, erc20: CoinListErc20Namespace);
+    executeSwap(params: Omit<ExecuteSwapParams, 'swap' | 'erc20'>): Promise<SwapExecutionResult>;
+    authorizeWallet(params: Omit<AuthorizeWalletParams, 'swap'>): Promise<WalletAuthorizationResult>;
+}
+
+/**
+ * Progress phases emitted by {@link executeTokenSale}, in the order they occur.
+ * The `resetting-allowance`/`confirming-allowance-reset` phases only occur when
+ * the wallet holds a non-zero allowance that must be reset to 0 first
+ * (USDT-style tokens reject non-zero -> non-zero `approve()`).
+ */
+type TokenSaleExecutionPhase = 'checking-allowance' | 'resetting-allowance' | 'confirming-allowance-reset' | 'approving' | 'confirming-approval' | 'recording-participation';
+/**
+ * A step-tagged reason {@link executeTokenSale} failed.
+ *
+ * The reset-to-zero step (`allowance-reset` / `allowance-reset-reverted`) is
+ * reported distinctly from the main approval (`approval` /
+ * `approval-reverted`, reused from {@link Erc20ApprovalError}) so consumers can
+ * tell which of the two wallet prompts the user rejected or which approval
+ * reverted on-chain.
+ */
+type TokenSaleExecutionError = {
+    step: 'allowance-check';
+} | {
+    step: 'allowance-reset';
+    cause: WalletError;
+} | {
+    step: 'allowance-reset-reverted';
+} | Erc20ApprovalError | {
+    step: 'participation';
+    approvalTxHash: Hash;
+};
+type TokenSaleExecutionResult = {
+    type: 'success';
+    participation: Participation;
+    approvalTxHash: Hash;
+} | {
+    type: 'error';
+    error: TokenSaleExecutionError;
+};
+type ExecuteTokenSaleParams = {
+    erc20: CoinListErc20Namespace;
+    tokenSale: CoinListTokenSaleNamespace;
+    wallet: EvmWallet;
+    offerId: OfferId;
+    offerOptionId: OfferOptionId;
+    assetId: AssetId;
+    /** ERC-20 the user pays with (e.g. USDC/USDT). */
+    paymentTokenAddress: EvmContractAddress;
+    /** Contract that pulls the payment — the `approve()` spender. */
+    fundingContractAddress: EvmContractAddress;
+    chain: EthereumChain;
+    amount: BlockchainAmount;
+    onProgress?: (phase: TokenSaleExecutionPhase) => void;
+};
+/**
+ * Executes a token sale end-to-end: submits an ERC-20 `approve()` for the sale
+ * amount to the funding contract (resetting a stale non-zero allowance to 0
+ * first for USDT-style tokens), waits for it to mine, and records the
+ * participation with CoinList. An approval is submitted even when the existing
+ * allowance already covers the amount — the backend requires a fresh approval
+ * transaction hash for every participation and verifies it on-chain before
+ * confirming.
+ *
+ * Wallet selection/connection and chain switching are the app's responsibility —
+ * this operates on an already-connected {@link EvmWallet}. Progress is reported
+ * via `onProgress` for consumers rendering loading states.
+ */
+declare function executeTokenSale(params: ExecuteTokenSaleParams): Promise<TokenSaleExecutionResult>;
+
+/**
+ * The client-side token-sale namespace: everything the shared
+ * {@link CoinListTokenSaleNamespace} reads/writes over the API, plus the
+ * on-chain flow that drives a wallet (`executeTokenSale`). The flow takes the
+ * wallet and addresses per call; the namespace supplies the participation
+ * writes and (via the ERC-20 namespace) the allowance read it depends on.
+ */
+interface CoinListClientTokenSaleNamespace extends CoinListTokenSaleNamespace {
+    /**
+     * Runs a token sale end-to-end against the given wallet: ERC-20
+     * allowance/approval (resetting a stale non-zero allowance first for
+     * USDT-style tokens), approval confirmation, and participation recording.
+     */
+    executeTokenSale(params: Omit<ExecuteTokenSaleParams, 'erc20' | 'tokenSale'>): Promise<TokenSaleExecutionResult>;
+}
+declare class ClientTokenSaleNamespaceImpl extends TokenSaleNamespaceImpl implements CoinListClientTokenSaleNamespace {
+    private readonly erc20;
+    constructor(ctx: SharedNamespaceContext, erc20: CoinListErc20Namespace);
+    executeTokenSale(params: Omit<ExecuteTokenSaleParams, 'erc20' | 'tokenSale'>): Promise<TokenSaleExecutionResult>;
+}
 
 type AuthState = 'unknown' | 'logged-in' | 'logged-out';
 /** Discriminated error reasons from {@link CoinListClient.completeOAuth}. */
@@ -101,37 +390,43 @@ interface CoinListClient {
      */
     fetchOfferDetails(id: OfferId): Promise<OfferDetail>;
     /**
-     * Fetches all participations by iterating through every paginated response.
+     * Creates a single-use wallet-ownership challenge for the given wallet and
+     * chain. The user signs the returned {@link WalletOwnershipChallenge.message}
+     * with their wallet, then passes the signature to
+     * {@link connectExternalWallet}.
      *
      * This method must be called only when the user's {@link AuthState} is
      * `'logged-in'`. If the user is not authenticated, it throws
      * {@link NotAuthenticatedError}.
      */
-    fetchParticipations(offerId?: OfferId): Promise<Participation[]>;
+    createWalletOwnershipChallenge(params: CreateWalletOwnershipChallengeParams): Promise<WalletOwnershipChallenge>;
     /**
-     * Fetches a single page of participations, optionally filtered by offer.
+     * Connects a proven external wallet to an offer option, using a signature of
+     * a challenge from {@link createWalletOwnershipChallenge}.
      *
      * This method must be called only when the user's {@link AuthState} is
      * `'logged-in'`. If the user is not authenticated, it throws
      * {@link NotAuthenticatedError}.
      */
-    fetchParticipationsPage(params: ParticipationsPaginationParams): Promise<PaginatedResponse<Participation>>;
+    connectExternalWallet(offerId: OfferId, params: ConnectExternalWalletParams): Promise<OfferOptionAddress>;
     /**
-     * Fetches a participation by id.
+     * Lists the user's proven wallet bindings for a single offer option (the
+     * bound address for `external_wallet`, or all whitelisted wallets for
+     * `whitelisted_wallet`).
      *
      * This method must be called only when the user's {@link AuthState} is
      * `'logged-in'`. If the user is not authenticated, it throws
      * {@link NotAuthenticatedError}.
      */
-    fetchParticipation(id: ParticipationId): Promise<Participation>;
+    listOptionAddresses(offerId: OfferId, offerOptionId: OfferOptionId): Promise<OfferOptionAddress[]>;
     /**
-     * Creates a participation.
+     * Removes one of the user's wallet bindings and returns the removed binding.
      *
      * This method must be called only when the user's {@link AuthState} is
      * `'logged-in'`. If the user is not authenticated, it throws
      * {@link NotAuthenticatedError}.
      */
-    createParticipation(params: CreateParticipationParams): Promise<Participation>;
+    removeOptionAddress(offerId: OfferId, addressId: OfferOptionAddressId): Promise<OfferOptionAddress>;
     /**
      * Fetches the requirements for all options of a given offer, grouped by option ID.
      *
@@ -148,15 +443,85 @@ interface CoinListClient {
      * {@link NotAuthenticatedError}.
      */
     fetchRequirementStatuses(offerId: OfferId): Promise<RequirementStatusInfo[]>;
+    /**
+     * Fetches the current user's PII, used to pre-fill tax forms such as the
+     * W-8BEN. Fields the entity hasn't provided are `null`.
+     *
+     * This method must be called only when the user's {@link AuthState} is
+     * `'logged-in'`. If the user is not authenticated, it throws
+     * {@link NotAuthenticatedError}.
+     */
+    fetchPii(): Promise<Pii>;
+    /**
+     * Starts (or resumes) a document signing submission for the given type
+     * (currently only `tax_certification`, e.g. W-8BEN/W-8BEN-E). `fields` are
+     * signing-form values keyed by the document's DocuSeal field names,
+     * forwarded verbatim to Passport to pre-fill the document.
+     *
+     * This method must be called only when the user's {@link AuthState} is
+     * `'logged-in'`. If the user is not authenticated, it throws
+     * {@link NotAuthenticatedError}.
+     */
+    submitDocument(documentType: DocumentType, fields: Record<string, string>): Promise<DocumentSubmission>;
+    /**
+     * Creates a short-lived Sumsub WebSDK access token for the current user so an
+     * identity verification (KYC) flow can be started, e.g. by the
+     * `IdentityVerification` component. `levelName` selects the Sumsub
+     * verification level; defaults to the backend's standard level. `reset`
+     * resets the Sumsub applicant first, so an already-approved level can be
+     * executed again (e.g. to update stale PII) — pass the `kycReset` value
+     * from the requirement status, and never on mid-flow token refreshes.
+     *
+     * This method must be called only when the user's {@link AuthState} is
+     * `'logged-in'`. If the user is not authenticated, it throws
+     * {@link NotAuthenticatedError}.
+     */
+    createKycToken(levelName?: KycLevelName, reset?: boolean): Promise<KycToken>;
     /**
      * Opens the CoinList page for completing a given requirement in a new tab.
-     * For `jurisdiction` requirements there is no CTA, so this is a no-op.
+     * For `jurisdiction` and `document` requirements there is no CTA, so this
+     * is a no-op — `document` requires the caller to use {@link fetchPii} and
+     * {@link submitDocument} directly (e.g. via a custom
+     * `onRequirementActionOverride`).
      */
     handleRequirement(requirement: Requirement): void;
     /**
      * Opens the CoinList support ticket page in a new tab.
      */
     contactSupport(): void;
+    /**
+     * Generic ERC-20 reads (token allowance and balance) shared across the
+     * on-chain flows — e.g. `coinlist.erc20.getTokenBalance({ ... })`.
+     *
+     * These reads must be called only when the user's {@link AuthState} is
+     * `'logged-in'`; if the user is not authenticated, they throw
+     * {@link NotAuthenticatedError}.
+     */
+    readonly erc20: CoinListErc20Namespace;
+    /**
+     * Token-sale operations: listing/reading/recording participations, plus the
+     * on-chain `executeTokenSale` flow that submits the ERC-20 approval and
+     * records the participation over a caller-supplied {@link EvmWallet} —
+     * e.g. `coinlist.tokenSale.executeTokenSale({ ... })`.
+     *
+     * The API-backed reads/writes must be called only when the user's
+     * {@link AuthState} is `'logged-in'`; if the user is not authenticated, they
+     * throw {@link NotAuthenticatedError}. `executeTokenSale` additionally drives
+     * a caller-supplied wallet and returns a step-tagged result rather than
+     * throwing.
+     */
+    readonly tokenSale: CoinListClientTokenSaleNamespace;
+    /**
+     * On-chain swap operations: quoting a swap, reading swap-contract state, and
+     * proving/allow-listing wallet ownership — e.g.
+     * `coinlist.swap.getOutputToken({ contractAddress, chain })`.
+     *
+     * The API-backed reads must be called only when the user's {@link AuthState}
+     * is `'logged-in'`; if the user is not authenticated, they throw
+     * {@link NotAuthenticatedError}. The on-chain flows (`executeSwap`,
+     * `authorizeWallet`) additionally drive a caller-supplied wallet.
+     */
+    readonly swap: CoinListClientSwapNamespace;
 }
 declare function createCoinListClient(config: ClientConfig): CoinListClient;
 
@@ -174,21 +539,22 @@ type CoinListProviderProps = {
  * React context: no DOM, no <style>, no .clco-sdk-root. Safe to mount app-wide:
  * it has zero visual impact on the host's own pages.
  *
- * Use this when you need useCoinList() available app-wide. Wrap SDK visual components
- * in {@link CoinListStyleScope} separately. For dropping in a single widget, use the
- * all-in-one {@link CoinListProvider}.
+ * Use this when you need useCoinList() available app-wide. SDK visual components
+ * self-scope, so you do not need to wrap them in {@link CoinListStyleScope}.
+ * {@link CoinListProvider} is an identical alias with a friendlier name.
  */
 declare function CoinListContextProvider({ config, children, }: CoinListProviderProps): react_jsx_runtime.JSX.Element;
 /**
- * All-in-one provider: the React context plus the SDK styling wrapper. Convenience for
- * dropping in a single widget. Composes {@link CoinListContextProvider} and
- * {@link CoinListStyleScope}.
+ * The provider to mount once at your app root. Provides the CoinList client context
+ * to the whole tree with zero visual impact: it renders no DOM, no `<style>`, and no
+ * `.clco-sdk-root`, so it never styles the host's own pages. SDK visual components
+ * (CoinListSignInCard, OffersGrid, ...) style themselves, so you do not need to wrap
+ * them in {@link CoinListStyleScope}.
  *
- * Caution: this applies SDK styling (.clco-sdk-root) to everything below it. If you need
- * context app-wide without styling the host's pages, mount {@link CoinListContextProvider}
- * at the root and wrap only SDK visual components in {@link CoinListStyleScope}.
+ * Alias of {@link CoinListContextProvider}: identical behavior, friendlier name for
+ * the common "mount one provider" case.
  */
-declare function CoinListProvider({ config, children }: CoinListProviderProps): react_jsx_runtime.JSX.Element;
+declare const CoinListProvider: typeof CoinListContextProvider;
 
 type CoinListStyleScopeProps = {
     children: ReactNode;
@@ -198,9 +564,17 @@ type CoinListStyleScopeProps = {
  * with the self-contained, scoped <style> injection. Mount this around SDK visual
  * components only. Keep it off the host's own pages to avoid styling them.
  *
- * This component self-injects all SDK styles via an inline <style> tag so consumers
- * do not need to import any CSS files or configure their bundler. Styles are fully
- * scoped to .clco-sdk-root and do not leak to the host page.
+ * This component self-injects all SDK styles via a <style> tag so consumers do not
+ * need to import any CSS files or configure their bundler. Styles are fully scoped
+ * to .clco-sdk-root and do not leak to the host page. On React 19 the <style> is a
+ * hoistable resource (href + precedence), so it is lifted to <head> and deduplicated
+ * across every scope on the page; on React 18 the extra attributes are inert and it
+ * renders in place.
+ *
+ * The wrapper div uses `display: contents` so it generates no box of its own, so an
+ * SDK component wrapped by this stays the layout element in the host's flex/grid.
+ * Inheritance (font, color, custom-property tokens) and the scoped descendant reset
+ * (`.clco-sdk-root *`) still apply through it.
  */
 declare function CoinListStyleScope({ children }: CoinListStyleScopeProps): react_jsx_runtime.JSX.Element;
 
@@ -219,18 +593,20 @@ interface CoinListSignInCardProps {
 /**
  * Sign-in card that prompts the user to authenticate with CoinList.
  *
- * Use this component only inside a tree wrapped by {@link CoinListProvider}.
- * By default, clicking the sign-in button starts the CoinList OAuth flow via
- * {@link CoinListClient#startOAuth}; pass `onSignIn` to override.
+ * Use this component inside a tree wrapped by {@link CoinListProvider} (for the
+ * client context). By default, clicking the sign-in button starts the CoinList
+ * OAuth flow via {@link CoinListClient#startOAuth}; pass `onSignIn` to override.
+ *
+ * Self-scoped: renders fully styled on its own, no `CoinListStyleScope` needed.
  */
 declare function CoinListSignInCard({ state, onSignIn, onClose, className, }?: CoinListSignInCardProps): ReactNode;
 
 type OfferCardUi = {
-    tagline: string | null;
-    bannerUrl: string | null;
-    logoUrl: string | null;
+    tagline: string;
+    bannerUrl: string;
+    logoUrl: string;
     formattedStartsAt: string;
-    formattedEndsAt: string;
+    formattedEndsAt: string | null;
 };
 declare const OfferCardUi: {
     fromDomain: (offer: Offer) => OfferCardUi;
@@ -244,6 +620,10 @@ interface Props {
     /** Optional className applied to an outer wrapper element. */
     containerClassName?: string;
 }
+/**
+ * Offer card. Self-scoped: renders fully styled on its own, with no
+ * `CoinListStyleScope` needed. Also composed by {@link OffersGrid}.
+ */
 declare function OfferCard({ offer, onClick, className, containerClassName, }: Props): ReactNode;
 
 interface OffersGridProps {
@@ -276,8 +656,239 @@ interface OffersGridProps {
  * Uses `loading` / `error` slots when provided; otherwise renders standard
  * fallback loading and error states. Offer cards are interactive only when
  * `onOfferClick` is provided.
+ *
+ * Self-scoped: renders fully styled on its own, with no `CoinListStyleScope` needed.
+ */
+declare function OffersGrid(props?: OffersGridProps): ReactNode;
+
+/** Load state of a connected-wallet list. */
+type WalletsStatus = 'ready' | 'loading' | 'error';
+/** A single connected wallet, shaped for display in {@link ConnectedWalletList}. */
+type ConnectedWalletUi = {
+    /** Id of the connected wallet, used to remove it. */
+    id: string;
+    /** Full wallet address (for `title`/`aria`). */
+    address: string;
+    /** Shortened address for display (e.g. `0x1234…abcd`). */
+    shortAddress: string;
+};
+interface ConnectedWalletListProps {
+    wallets: ConnectedWalletUi[];
+    /**
+     * Removes a connected wallet by id. May return a promise; the row shows a
+     * removing state until it settles and surfaces an inline error on rejection.
+     * `null`/omitted hides the remove control (read-only list).
+     */
+    onRemove?: ((id: string) => void | Promise<void>) | null;
+    /** Opens the connect flow to add another wallet. Omit to hide the button. */
+    onAdd?: (() => void) | null;
+    /** Label for the add button. Defaults to "Add wallet". */
+    addLabel?: string;
+    /**
+     * Load state of the wallets. `'loading'`/`'error'` render a status message so
+     * a failed or in-flight fetch is not mistaken for a genuinely empty list.
+     * Defaults to `'ready'`.
+     */
+    status?: WalletsStatus;
+    className?: string;
+}
+/**
+ * Presentational list of a user's connected wallets for a whitelisted-wallet
+ * requirement: each row shows the address with an inline two-step remove
+ * confirmation, plus an optional "Add wallet" button. Self-contained — holds
+ * only per-row confirm/removing/error UI state; all data and side effects come
+ * from props.
+ */
+declare function ConnectedWalletList({ wallets, onRemove, onAdd, addLabel, status, className, }: ConnectedWalletListProps): ReactNode;
+
+/**
+ * The host-provided wallet the ownership flow signs with: the signing-only
+ * {@link EvmSigner} plus the {@link EthereumChain} the signature is proven on.
+ * `chain` rides on the wallet (not the offer) because the binding is
+ * chain-agnostic: it only records which EVM chain signed.
+ */
+type ConnectWallet = EvmSigner & {
+    readonly chain: EthereumChain;
+};
+/**
+ * Machine-readable classification of a connect-wallet failure, so consumers can
+ * branch on the cause (e.g. hide a retry affordance on a terminal failure)
+ * instead of pattern-matching a display string.
+ */
+type ConnectWalletErrorCode = 'not_authenticated' | 'user_rejected' | 'wallet_not_whitelisted' | 'max_wallets_reached' | 'unknown';
+/**
+ * A classified connect-wallet failure. `retryable` is false when re-signing the
+ * same wallet can never succeed (a terminal binding rejection, or no signed-in
+ * session). Display copy is the caller's concern, kept out of the core.
+ */
+type ConnectWalletFlowError = {
+    code: ConnectWalletErrorCode;
+    retryable: boolean;
+};
+/** Progress phases emitted by {@link connectExternalWalletFlow}, in order. */
+type ConnectWalletPhase = 'requesting-challenge' | 'signing-message' | 'submitting-signature';
+type ConnectWalletFlowResult = {
+    type: 'success';
+    binding: OfferOptionAddress;
+} | {
+    type: 'cancelled';
+} | {
+    type: 'error';
+    error: ConnectWalletFlowError;
+};
+/** The client surface the flow actually depends on, kept narrow on purpose. */
+type ConnectWalletClient = Pick<CoinListClient, 'createWalletOwnershipChallenge' | 'connectExternalWallet'>;
+type ConnectWalletFlowParams = {
+    coinlist: ConnectWalletClient;
+    /** Host-provided connected wallet the flow signs with. */
+    wallet: ConnectWallet;
+    offerId: OfferId;
+    offerOptionId: OfferOptionId;
+    /** Challenge framing; defaults to `'siwe'`. */
+    challengeType?: WalletChallengeType;
+    /** SIWE statement shown in the signing prompt. */
+    statement?: string;
+    /**
+     * Polled before each irreversible step (signing, binding). Return true to
+     * abandon a superseded attempt; the flow then resolves `{ type: 'cancelled' }`
+     * without prompting the wallet or binding. React hooks pass a generation
+     * check here; non-React callers can omit it.
+     */
+    isCancelled?: () => boolean;
+    /** Reports flow progress for consumers rendering loading states. */
+    onProgress?: (phase: ConnectWalletPhase) => void;
+};
+/**
+ * Drives the external-wallet ownership flow for one offer option:
+ * `createWalletOwnershipChallenge` -> host `wallet.signMessage` ->
+ * `connectExternalWallet`. Pure and signer-agnostic: signing is delegated to
+ * the host-provided {@link ConnectWallet}, and no React is involved so non-hook
+ * consumers can drive it directly (mirrors `authorizeWallet` in `swap-flows`).
+ * EVM / EOA + SIWE only for now.
+ */
+declare function connectExternalWalletFlow(params: ConnectWalletFlowParams): Promise<ConnectWalletFlowResult>;
+
+/**
+ * A display-ready connect-wallet error: the core flow's machine-readable code
+ * and `retryable` flag, plus copy for the UI.
+ */
+type ConnectWalletError = {
+    code: ConnectWalletErrorCode;
+    message: string;
+    retryable: boolean;
+};
+/**
+ * Signing-in-flight and the last sign error live inside the READY state (not a
+ * separate top-level state) so a failed attempt returns to READY and can be
+ * retried without re-opening the modal. Mirrors {@link SignState} in
+ * `useTaxDocument`.
+ */
+type ConnectWalletSignState = {
+    type: 'idle';
+    error: ConnectWalletError | null;
+} | {
+    type: 'signing';
+};
+type ConnectWalletState = {
+    type: 'NEEDS_WALLET';
+} | {
+    type: 'READY';
+    address: EvmWalletAddress;
+    sign: ConnectWalletSignState;
+} | {
+    type: 'CONNECTED';
+    binding: OfferOptionAddress;
+};
+interface UseConnectWalletOptions {
+    /** The hook resets state each time it opens. */
+    isOpen: boolean;
+    offerId: OfferId;
+    offerOptionId: OfferOptionId;
+    /** Host-provided connected wallet, or `null` while none is connected. */
+    wallet: ConnectWallet | null;
+    /** Challenge framing; defaults to `'siwe'`. */
+    challengeType?: WalletChallengeType;
+    /** SIWE statement shown in the signing prompt. */
+    statement?: string;
+}
+interface UseConnectWalletResult {
+    state: ConnectWalletState;
+    /** READY.sign: idle -> signing -> (CONNECTED | idle w/ error). No-op otherwise. */
+    onSign: () => void;
+}
+/**
+ * React wrapper over {@link connectExternalWalletFlow}. Owns the modal state
+ * machine, the display copy, and generation-token supersession (so a wallet
+ * switch, modal close, or unmount cancels an in-flight attempt). The flow logic
+ * itself lives in the framework-free core so non-React consumers can drive it.
+ */
+declare function useConnectWallet({ isOpen, offerId, offerOptionId, wallet, challengeType, statement, }: UseConnectWalletOptions): UseConnectWalletResult;
+
+interface ConnectWalletModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    offerId: OfferId;
+    optionId: OfferOptionId;
+    /** Host-provided connected wallet, or `null` while none is connected. */
+    wallet: ConnectWallet | null;
+    /** Called once the wallet is bound to the offer option, right before close. */
+    onConnected?: (binding: OfferOptionAddress) => void;
+    /**
+     * Called when the user asks to connect (or switch) a wallet: the "Connect
+     * wallet" button when none is connected, and "Use a different wallet" when one
+     * already is.
+     */
+    onRequestConnect?: () => void;
+    /** Challenge framing; defaults to `'siwe'`. */
+    challengeType?: WalletChallengeType;
+    /** SIWE statement shown in the signing prompt. */
+    statement?: string;
+    className?: string;
+}
+/**
+ * Batteries-included modal for the external-wallet ownership flow. Drives
+ * {@link useConnectWallet} (challenge -> host signs -> connect) for one offer
+ * option. Signing is delegated to the host-provided {@link ConnectWallet}: the SDK
+ * never bundles a wallet stack.
+ *
+ * No portal is used — rendering stays inside the normal DOM tree so it keeps
+ * this SDK's `.clco-sdk-root`-scoped theme tokens without needing its own
+ * {@link CoinListStyleScope}.
  */
-declare function OffersGrid({ data, maxColumns, className, containerClassName, loading, error, emptyState, onOfferClick, }?: OffersGridProps): ReactNode;
+declare function ConnectWalletModal({ isOpen, onClose, offerId, optionId, wallet, onConnected, onRequestConnect, challengeType, statement, className, }: ConnectWalletModalProps): react_jsx_runtime.JSX.Element | null;
+
+interface IdentityVerificationProps {
+    /**
+     * Sumsub verification level to start. Determines which screens the Sumsub
+     * WebSDK shows. Defaults to the backend's standard identity level.
+     */
+    levelName?: KycLevelName;
+    /**
+     * Reset the Sumsub applicant before starting the flow, so an
+     * already-approved level can be executed again (e.g. to update stale PII).
+     * Pass the `kycReset` value from the requirement status. Applies only to
+     * the initial token — mid-flow token refreshes never repeat the reset.
+     */
+    reset?: boolean;
+    /** BCP-47 language tag for the Sumsub UI, e.g. `'en'`. */
+    locale?: string;
+    /**
+     * Called when the user submits their data in the Sumsub flow. Verification
+     * continues asynchronously on the backend, so the requirement typically moves
+     * to a pending state first — refetch requirement statuses to observe it.
+     */
+    onSubmitted?: () => void;
+    /** Called when the Sumsub flow reports an error. */
+    onError?: (error: Error) => void;
+    className?: string;
+}
+/**
+ * Inline Sumsub identity verification flow. Fetches a Sumsub WebSDK access
+ * token via {@link useKycToken} and renders the Sumsub iframe. Used by
+ * `RequirementsChecklist` for `identity_verified` requirements, and can also
+ * be rendered standalone.
+ */
+declare function IdentityVerification({ levelName, reset, locale, onSubmitted, onError, className, }: IdentityVerificationProps): ReactNode;
 
 type RequirementVariant = 'verification' | 'wallet';
 declare const RequirementVariant: {
@@ -296,21 +907,40 @@ type RequirementItemUi = {
     status: RequirementStatus;
     label: string;
     description: string;
-    walletAddress?: string;
+    /**
+     * `true` for `whitelisted_wallet` (a multi-slot list the user can add to and
+     * remove from), `false` for the single-slot `external_wallet`.
+     */
+    multiWallet: boolean;
+    /** The user's connected wallets. Single-slot requirements have at most one. */
+    connectedWallets: ConnectedWalletUi[];
 };
 declare const RequirementItemUi: {
-    fromDomain(req: Requirement, statusInfo: RequirementStatusInfo | undefined, label: string, description: string, walletAddress?: string): RequirementItemUi;
+    fromDomain(req: Requirement, statusInfo: RequirementStatusInfo | undefined, label: string, description: string, addresses?: OfferOptionAddress[]): RequirementItemUi;
 };
 interface RequirementItemProps {
     ui: RequirementItemUi;
     expanded?: boolean;
     onToggle?: () => void;
-    walletAddress?: string;
     className?: string;
+    /** Connect / change / add-wallet action (opens the connect flow). */
     onAction?: (() => void) | null;
+    /** Removes a bound wallet by id (whitelisted-wallet requirements only). */
+    onRemoveWallet?: ((id: string) => void | Promise<void>) | null;
+    /**
+     * Load state of {@link RequirementItemUi.connectedWallets}. `'loading'` /
+     * `'error'` keep a fetch-in-flight or failed fetch from looking like an empty
+     * wallet list. Defaults to `'ready'`.
+     */
+    walletsStatus?: WalletsStatus;
     onContactSupport?: (() => void) | null;
 }
-declare function RequirementItem({ ui, expanded, onToggle, className, onAction, onContactSupport, }: RequirementItemProps): react_jsx_runtime.JSX.Element;
+/**
+ * A single requirement row (label, status, expandable action zone). Self-scoped:
+ * renders fully styled on its own, with no `CoinListStyleScope` needed. Also composed
+ * by {@link RequirementsChecklist}.
+ */
+declare function RequirementItem({ ui, expanded, onToggle, className, onAction, onRemoveWallet, walletsStatus, onContactSupport, }: RequirementItemProps): react_jsx_runtime.JSX.Element;
 
 type LoadRequirementsReason = 'not-authenticated' | 'generic-error';
 type LoadRequirementsState = {
@@ -351,7 +981,9 @@ interface UseRequirementsResult {
  * Returns `LOADING` while CoinList is initializing or while data is being fetched.
  * Returns `CONTENT` with requirements and statuses on success.
  * Returns `ERROR` with:
- * - `not-authenticated` when fetching fails with {@link NotAuthenticatedError}
+ * - `not-authenticated` immediately (no request is sent) when the client's
+ *   auth state is logged-out, or when fetching fails with
+ *   {@link NotAuthenticatedError}
  * - `generic-error` for any other failure
  */
 declare function useRequirements(offerId: OfferId, options?: UseRequirementsOptions): UseRequirementsResult;
@@ -365,8 +997,9 @@ interface RequirementsChecklistProps {
     /**
      * Called when the user clicks a requirement's action button (e.g. "Continue", "Connect wallet").
      * Defaults to {@link CoinListClient#handleRequirement}, which opens the corresponding CoinList
-     * page in a new tab. Pass your own handler to override this behavior, or pass `null` to disable
-     * the action button entirely.
+     * page in a new tab — except for `document` requirements, which default to opening a built-in
+     * {@link TaxDocumentModal} instead. Pass your own handler to override this behavior for all
+     * requirement types, or pass `null` to disable the action button entirely.
      */
     onRequirementActionOverride?: ((requirement: Requirement) => void) | null;
     /**
@@ -376,21 +1009,54 @@ interface RequirementsChecklistProps {
      * the contact support button entirely.
      */
     onContactSupportOverride?: ((requirement: Requirement) => void) | null;
+    /**
+     * Host-provided connected wallet used to satisfy `external_wallet` /
+     * `whitelisted_wallet` requirements in-app via {@link ConnectWalletModal}.
+     * Pass a connected {@link ConnectWallet}, or `null` while none is connected
+     * (then also pass {@link onRequestConnect} so the modal can prompt to
+     * connect). When this prop is omitted entirely — or is `null` without an
+     * {@link onRequestConnect} to act on — wallet requirements fall back to
+     * {@link CoinListClient#handleRequirement} (opening CoinList in a new tab).
+     */
+    wallet?: ConnectWallet | null;
+    /** Called when the user asks to connect a wallet and none is connected yet. */
+    onRequestConnect?: () => void;
     /** Override the default label for a requirement type. */
     getLabel?: (requirement: Requirement) => string;
     /** Override the default description for a requirement type. */
     getDescription?: (requirement: Requirement) => string | null;
     /** Optional loading slot. */
     loading?: ReactNode;
+    /**
+     * Rendered when the user is not authenticated. Defaults to
+     * {@link CoinListSignInCard}, which prompts the user to sign in and starts
+     * the CoinList OAuth flow. Pass `null` to render nothing.
+     */
+    unauthenticatedState?: ReactNode;
     /** Optional error slot. */
     error?: ReactNode;
     className?: string;
     /**
      * Requirements data pre-fetched on the server (e.g. via
      * `CoinListServer.fetchOfferRequirements()` + `fetchRequirementStatuses()`).
-     * When provided, the component uses this data as-is and skips the client-side fetch entirely.
+     * When provided, the component uses this data as-is and skips the client-side
+     * requirements fetch. Connected-wallet addresses for wallet requirements are
+     * not part of `RequirementsData` and are always fetched client-side.
      */
     data?: RequirementsData;
+    /**
+     * Options for the inline Sumsub verification flow shown for KYC-backed
+     * requirements (`identity_verified`, `kyc_approved`, `accreditation`) when
+     * `onRequirementActionOverride` is not provided. The flow starts whenever
+     * the requirement's status carries a `kycLevel` — the backend prescribes
+     * both the level and whether the applicant must be reset first.
+     */
+    identityVerificationOptions?: {
+        /** Override the backend-prescribed Sumsub verification level. */
+        levelName?: KycLevelName;
+        /** BCP-47 language tag for the Sumsub UI, e.g. `'en'`. */
+        locale?: string;
+    };
 }
 /**
  * Connected requirements checklist that fetches requirements and statuses
@@ -400,13 +1066,142 @@ interface RequirementsChecklistProps {
  * Pass `data` (pre-fetched server-side) to use that data as-is and skip
  * the initial client-side fetch.
  *
+ * When the user is not authenticated, renders a sign-in card instead of the
+ * checklist — without fetching. Pass `unauthenticatedState` to customize
+ * that state, or `null` to render nothing.
+ *
  * By default, clicking a requirement's action button opens the corresponding
  * CoinList page in a new tab via {@link CoinListClient#handleRequirement}. It is
  * recommended to omit `onRequirementActionOverride` and rely on this default.
  * Pass your own handler only if you need custom navigation behavior, or `null`
  * to disable the action button entirely.
+ *
+ * Self-scoped: renders fully styled on its own, with no `CoinListStyleScope` needed.
+ */
+declare function RequirementsChecklist(props: RequirementsChecklistProps): ReactNode;
+
+interface TaxDocumentModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    /** Called once the document is successfully signed, right before the modal closes. */
+    onSubmitted?: (submission: DocumentSubmission) => void;
+    className?: string;
+}
+/**
+ * Batteries-included modal for the tax document (W-8BEN / W-8BEN-E) signing
+ * flow. Fetches the current user's PII via {@link useTaxDocument}, lets
+ * individuals review/edit it before signing; company/trust entities see a
+ * plain sign screen with no fields.
+ *
+ * No portal is used — rendering stays inside the normal DOM tree so it keeps
+ * this SDK's `.clco-sdk-root`-scoped theme tokens without needing its own
+ * {@link CoinListStyleScope}.
+ */
+declare function TaxDocumentModal({ isOpen, onClose, onSubmitted, className, }: TaxDocumentModalProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * The state of the swap's output-token fetch.
+ *
+ * - `LOADING`: no result yet (initial, or provider still initializing).
+ * - `ERROR`: the fetch failed.
+ * - `CONTENT`: the output token was fetched successfully.
+ *
+ * A stale `CONTENT`/`ERROR` is preserved while a re-fetch (e.g. after a chain
+ * change) is in flight, rather than flipping back to `LOADING`.
+ */
+type SwapOutputTokenState = {
+    type: 'LOADING';
+} | {
+    type: 'ERROR';
+} | {
+    type: 'CONTENT';
+    outputToken: Erc20Asset;
+};
+interface UseSwapOutputTokenOptions {
+    /** The swap contract whose output token to read. */
+    contractAddress: EvmContractAddress;
+    chain: EthereumChain;
+    /** When false, the hook does not fetch. */
+    enabled: boolean;
+}
+interface UseSwapOutputTokenResult {
+    outputTokenState: SwapOutputTokenState;
+}
+/**
+ * Fetches the ERC-20 output token a swap contract pays out. Re-fetches when the
+ * contract or chain changes, and once when `enabled` flips to true.
+ *
+ * The fetch runs once (no polling); a failure resolves to `ERROR` and is not
+ * retried until a dependency changes.
+ */
+declare function useSwapOutputToken(options: UseSwapOutputTokenOptions): UseSwapOutputTokenResult;
+
+interface UseSwapQuoteOptions {
+    /** The swap contract to quote against. */
+    contractAddress: EvmContractAddress;
+    chain: EthereumChain;
+    /** The gross amount the user wants to swap, in the input token. */
+    inputAmount: BlockchainAmount;
+    inputTokenAddress: EvmContractAddress;
+    /**
+     * Decimals of the swap's output token. Quoting is skipped until this is
+     * known (e.g. while {@link useSwapOutputToken} is still loading).
+     */
+    outputTokenDecimals: AssetDecimals | null;
+    /** How often to refresh the quote. Defaults to {@link SWAP_POLL_INTERVAL_MS}. */
+    pollIntervalMs?: number;
+    /** When false, the hook neither fetches nor polls. */
+    enabled: boolean;
+}
+interface UseSwapQuoteResult {
+    /** The latest quote, or `null` until the first successful fetch. */
+    quote: SwapQuote | null;
+    /** True until the first quote arrives; false while the hook is disabled. */
+    isLoading: boolean;
+    /** True while a background poll refreshes an existing quote. */
+    isRefreshing: boolean;
+}
+/**
+ * Polls a read-only swap quote for `inputAmount` of `inputTokenAddress` against
+ * the given swap contract, refreshing every `pollIntervalMs`.
+ *
+ * A failed fetch is swallowed: the last quote stays visible and the next poll
+ * tick retries. Quoting is skipped while `outputTokenDecimals` is `null` or
+ * `enabled` is false, and until the CoinList provider finishes initializing.
  */
-declare function RequirementsChecklist({ offerId, optionId, title, description, onContinue, onRequirementActionOverride, onContactSupportOverride, getLabel, getDescription, loading, error, className, data, }: RequirementsChecklistProps): ReactNode;
+declare function useSwapQuote(options: UseSwapQuoteOptions): UseSwapQuoteResult;
+
+interface UseSwapTokenBalancesOptions {
+    address: EvmWalletAddress;
+    chain: EthereumChain;
+    /** The assets to read balances for. */
+    assets: NonEmptyArray<StablecoinSymbol>;
+    /** How often to refresh balances. Defaults to {@link SWAP_POLL_INTERVAL_MS}. */
+    pollIntervalMs?: number;
+    /** When false, the hook neither fetches nor polls. */
+    enabled: boolean;
+}
+interface UseSwapTokenBalancesResult {
+    /**
+     * Raw on-chain balances keyed by the requested assets. Each requested asset
+     * has an entry once a fetch settles (`bigint` on success, `null` on failure).
+     * Assets that were not requested are absent.
+     */
+    balances: Map<StablecoinSymbol, bigint | null>;
+    isLoading: boolean;
+}
+/**
+ * Polls the raw ERC-20 balances of `assets` for `address`, refreshing every
+ * `pollIntervalMs`. Each asset settles independently: a failed read maps to
+ * `null` while the others still resolve. A poll tick is skipped while the
+ * previous fetch is still in flight. `assets` is compared by contents, so
+ * passing an inline array does not restart the poll.
+ *
+ * `isLoading` is true only until the first poll settles; background polls do
+ * not toggle it. Disabled (or before the provider is ready) the hook does not
+ * fetch.
+ */
+declare function useSwapTokenBalances(options: UseSwapTokenBalancesOptions): UseSwapTokenBalancesResult;
 
 interface UseCoinListResult {
     /**
@@ -462,6 +1257,47 @@ interface UseCompleteOAuthOptions {
  */
 declare function useCompleteOAuth(options: UseCompleteOAuthOptions): void;
 
+type KycTokenErrorReason = 'not-authenticated' | 'generic-error';
+type KycTokenState = {
+    type: 'IDLE';
+} | {
+    type: 'LOADING';
+} | {
+    type: 'ERROR';
+    reason: KycTokenErrorReason;
+} | {
+    type: 'CONTENT';
+    token: string;
+};
+interface UseKycTokenResult {
+    kycTokenState: KycTokenState;
+    /**
+     * Fetches a fresh Sumsub WebSDK access token and transitions the state to
+     * `CONTENT` (or `ERROR`). Resolves with the token so it can also be used
+     * imperatively, e.g. as the Sumsub `expirationHandler`. Rejects on failure.
+     */
+    fetchToken: () => Promise<string>;
+}
+/**
+ * Creates Sumsub WebSDK access tokens for the current user via
+ * {@link CoinListClient#createKycToken}, exposed as a state machine.
+ *
+ * Starts in `IDLE`; call `fetchToken()` to request a token. Returns `LOADING`
+ * while the request is in flight, then `CONTENT` with the token on success, or
+ * `ERROR` with:
+ * - `not-authenticated` when fetching fails with {@link NotAuthenticatedError}
+ * - `generic-error` for any other failure
+ *
+ * `reset` (resetting the Sumsub applicant so an already-approved level can be
+ * redone) tracks the latest value of the `reset` argument up until a token is
+ * first issued; after that, mid-flow token refreshes must never repeat the
+ * reset, or the user's in-progress submission would be wiped, so further
+ * changes to `reset` are ignored. Failed attempts keep the reset pending, so
+ * retrying still requests it — the backend treats resetting an
+ * already-pristine applicant as a no-op.
+ */
+declare function useKycToken(levelName?: KycLevelName, reset?: boolean): UseKycTokenResult;
+
 type LoadOfferDetailsReason = 'not-authenticated' | 'generic-error';
 type LoadOfferDetailsState = {
     type: 'LOADING';
@@ -530,6 +1366,51 @@ interface UseOffersResult {
  */
 declare function useOffers(options?: UseOffersOptions): UseOffersResult;
 
+type LoadOptionAddressesReason = 'not-authenticated' | 'generic-error';
+type LoadOptionAddressesState = {
+    type: 'LOADING';
+} | {
+    type: 'ERROR';
+    reason: LoadOptionAddressesReason;
+} | {
+    type: 'CONTENT';
+    addresses: OfferOptionAddress[];
+};
+interface UseOptionAddressesOptions {
+    /**
+     * Bound wallets pre-fetched on the server (e.g. via
+     * `CoinListServer.listOptionAddresses()`). When provided, the hook uses this
+     * data as-is and skips the initial client-side fetch. Calling `refetch()`
+     * (or `disconnect()`) will still trigger a fresh fetch.
+     */
+    data?: OfferOptionAddress[];
+    /**
+     * When `false`, the hook stays in a benign empty `CONTENT` state and sends no
+     * request. Use it to avoid fetching bindings for options with no wallet
+     * requirement. Defaults to `true`.
+     */
+    enabled?: boolean;
+}
+interface UseOptionAddressesResult {
+    addressesState: LoadOptionAddressesState;
+    /** Triggers a re-fetch of the bound wallets. */
+    refetch: () => void;
+    /**
+     * Removes a bound wallet, then refetches the list. Rejects (without
+     * refetching) if the removal fails, so callers can surface the error.
+     */
+    disconnect: (addressId: OfferOptionAddressId) => Promise<void>;
+}
+/**
+ * Loads the user's proven wallet bindings for a single offer option, then
+ * exposes them via a state machine plus `refetch`/`disconnect` actions.
+ *
+ * Returns `LOADING` while CoinList is initializing or data is being fetched,
+ * `CONTENT` with the bindings on success, and `ERROR` with `not-authenticated`
+ * (logged-out, or a {@link NotAuthenticatedError}) or `generic-error` otherwise.
+ */
+declare function useOptionAddresses(offerId: OfferId, offerOptionId: OfferOptionId, options?: UseOptionAddressesOptions): UseOptionAddressesResult;
+
 type LoadParticipationsReason = 'not-authenticated' | 'generic-error';
 type LoadParticipationsState = {
     type: 'LOADING';
@@ -565,4 +1446,78 @@ interface UseParticipationsResult {
  */
 declare function useParticipations(offerId?: OfferId, options?: UseParticipationsOptions): UseParticipationsResult;
 
-export { type AuthState, ChecklistStatus, type ClientConfig, type CoinListClient, CoinListClientInitializationError, CoinListContext, CoinListContextProvider, type CoinListContextValue, CoinListProvider, type CoinListProviderProps, CoinListSignInCard, type CoinListSignInCardProps, CoinListStyleScope, type CoinListStyleScopeProps, type CompleteOAuthFailureReason, type LoadOfferDetailsReason, type LoadOfferDetailsState, type LoadOffersReason, type LoadOffersState, type LoadParticipationsReason, type LoadParticipationsState, type LoadRequirementsReason, type LoadRequirementsState, OAUTH_CODE_VERIFIER_KEY, OAUTH_STATE_KEY, type OauthClientErrorReason, type OauthClientResult, OfferCard, type Props as OfferCardProps, OfferCardUi, OffersGrid, type OffersGridProps, RequirementItem, type RequirementItemProps, RequirementItemUi, RequirementStatus, RequirementVariant, RequirementsChecklist, type RequirementsChecklistProps, type RequirementsData, type UseCoinListResult, type UseCompleteOAuthOptions, type UseOfferDetailsOptions, type UseOfferDetailsResult, type UseOffersOptions, type UseOffersResult, type UseParticipationsOptions, type UseParticipationsResult, type UseRequirementsOptions, type UseRequirementsResult, createCoinListClient, useCoinList, useCompleteOAuth, useOfferDetails, useOffers, useParticipations, useRequirements };
+type TaxDocumentFields = {
+    fullLegalName: string;
+    dob: string;
+    countryOfCitizenship: string;
+    taxId: string;
+    permanentAddress: string;
+};
+/**
+ * Structured address pieces sent split in the payload (`City` / `Country`).
+ * Kept separate from the single editable `permanentAddress` display string
+ * and never shown or edited in the form.
+ */
+type TaxDocumentAddressParts = {
+    city: string;
+    country: string;
+};
+/**
+ * Signing-in-flight and the last sign error live inside the REVIEW/SIGN_ONLY
+ * state (not a separate top-level state) so a failed sign never loses the
+ * user's fields.
+ */
+type SignState = {
+    type: 'idle';
+    error: string | null;
+} | {
+    type: 'signing';
+};
+type TaxDocumentState = {
+    type: 'LOADING';
+} | {
+    type: 'REVIEW';
+    fields: TaxDocumentFields;
+    addressParts: TaxDocumentAddressParts;
+    piiUnavailable: boolean;
+    sign: SignState;
+} | {
+    type: 'EDITING';
+    fields: TaxDocumentFields;
+    original: TaxDocumentFields;
+    addressParts: TaxDocumentAddressParts;
+    piiUnavailable: boolean;
+} | {
+    type: 'SIGN_ONLY';
+    sign: SignState;
+} | {
+    type: 'ERROR';
+    reason: 'not-authenticated' | 'generic-error';
+} | {
+    type: 'SUBMITTED';
+    submission: DocumentSubmission;
+};
+interface UseTaxDocumentOptions {
+    /** The hook only fetches PII while open; state resets each time it opens. */
+    isOpen: boolean;
+}
+interface UseTaxDocumentResult {
+    state: TaxDocumentState;
+    onEditField: (field: keyof TaxDocumentFields, value: string) => void;
+    onStartEdit: () => void;
+    onSaveEdit: () => void;
+    onCancelEdit: () => void;
+    onSign: () => void;
+}
+/**
+ * Loads the current user's PII and drives the tax document (W-8BEN /
+ * W-8BEN-E) signing flow.
+ *
+ * Always fetches PII once per open — it's the only way to learn the
+ * entity's `kind`. For company/trust entities the fetched values are
+ * discarded (only `kind` is used) and the form is skipped entirely
+ * (`SIGN_ONLY`); for individuals they seed the review screen (`REVIEW`).
+ */
+declare function useTaxDocument({ isOpen, }: UseTaxDocumentOptions): UseTaxDocumentResult;
+
+export { type AuthState, type AuthorizeWalletParams, type BroadcastTxParams, ChecklistStatus, type ClientConfig, ClientSwapNamespaceImpl, ClientTokenSaleNamespaceImpl, type CoinListClient, CoinListClientInitializationError, type CoinListClientSwapNamespace, type CoinListClientTokenSaleNamespace, CoinListContext, CoinListContextProvider, type CoinListContextValue, CoinListProvider, type CoinListProviderProps, CoinListSignInCard, type CoinListSignInCardProps, CoinListStyleScope, type CoinListStyleScopeProps, type CompleteOAuthFailureReason, type ConnectWallet, type ConnectWalletError, type ConnectWalletErrorCode, type ConnectWalletFlowError, type ConnectWalletFlowParams, type ConnectWalletFlowResult, ConnectWalletModal, type ConnectWalletModalProps, type ConnectWalletPhase, type ConnectWalletSignState, type ConnectWalletState, ConnectedWalletList, type ConnectedWalletListProps, type ConnectedWalletUi, type EvmSigner, type EvmWallet, type ExecuteSwapParams, type ExecuteTokenSaleParams, IdentityVerification, type IdentityVerificationProps, KycLevelName, KycToken, type KycTokenErrorReason, type KycTokenState, type LoadOfferDetailsReason, type LoadOfferDetailsState, type LoadOffersReason, type LoadOffersState, type LoadOptionAddressesReason, type LoadOptionAddressesState, type LoadParticipationsReason, type LoadParticipationsState, type LoadRequirementsReason, type LoadRequirementsState, OAUTH_CODE_VERIFIER_KEY, OAUTH_STATE_KEY, type OauthClientErrorReason, type OauthClientResult, OfferCard, type Props as OfferCardProps, OfferCardUi, OffersGrid, type OffersGridProps, RequirementItem, type RequirementItemProps, RequirementItemUi, RequirementStatus, RequirementVariant, RequirementsChecklist, type RequirementsChecklistProps, type RequirementsData, type SignState, type SwapExecutionError, type SwapExecutionPhase, type SwapExecutionResult, type SwapOutputTokenState, type TaxDocumentAddressParts, type TaxDocumentFields, TaxDocumentModal, type TaxDocumentModalProps, type TaxDocumentState, type TokenSaleExecutionError, type TokenSaleExecutionPhase, type TokenSaleExecutionResult, type UseCoinListResult, type UseCompleteOAuthOptions, type UseConnectWalletOptions, type UseConnectWalletResult, type UseKycTokenResult, type UseOfferDetailsOptions, type UseOfferDetailsResult, type UseOffersOptions, type UseOffersResult, type UseOptionAddressesOptions, type UseOptionAddressesResult, type UseParticipationsOptions, type UseParticipationsResult, type UseRequirementsOptions, type UseRequirementsResult, type UseSwapOutputTokenOptions, type UseSwapOutputTokenResult, type UseSwapQuoteOptions, type UseSwapQuoteResult, type UseSwapTokenBalancesOptions, type UseSwapTokenBalancesResult, type UseTaxDocumentOptions, type UseTaxDocumentResult, type WalletAuthorizationError, type WalletAuthorizationPhase, type WalletAuthorizationResult, type WalletError, type WalletsStatus, type WriteContractParams, authorizeWallet, classifyWalletError, connectExternalWalletFlow, createCoinListClient, executeSwap, executeTokenSale, useCoinList, useCompleteOAuth, useConnectWallet, useKycToken, useOfferDetails, useOffers, useOptionAddresses, useParticipations, useRequirements, useSwapOutputToken, useSwapQuote, useSwapTokenBalances, useTaxDocument };