@coinlist-co/react 0.9.0 → 0.10.0

package/dist/client/index.d.cts

@@ -2,8 +2,8 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { Hex, Abi, Hash, TransactionReceipt } from 'viem';
-import { E as EvmWalletAddress, a as EthereumChain, C as CoinListSwapNamespace, O as OfferId, b as EvmContractAddress, B as Bps, c as BlockchainAmount, S as SwapNamespaceImpl, A as AuthorizationCode, d as CodeVerifier, e as Config, f as OAuthAccessToken, g as Offer, P as PaginationParams, h as PaginatedResponse, i as OfferDetail, j as Participation, k as ParticipationsPaginationParams, l as ParticipationId, m as CreateParticipationParams, n as CreateWalletOwnershipChallengeParams, W as WalletOwnershipChallenge, o as ConnectExternalWalletParams, p as OfferOptionAddress, q as OfferOptionId, r as OfferOptionAddressId, R as Requirement, s as RequirementStatusInfo, t as Pii, D as DocumentType, u as DocumentSubmission, K as KycLevelName, v as KycToken, w as WalletChallengeType, x as RequirementType, y as RequirementStatusValue, z as Erc20Asset, F as AssetDecimals, G as StablecoinSymbol } from '../requirement-C2w45Q11.cjs';
-import { S as SwapQuote, N as NonEmptyArray } from '../collections-B84Vw55t.cjs';
+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.cjs';
+import { S as SwapQuote, N as NonEmptyArray } from '../collections-CJ24dOda.cjs';
 
 type WriteContractParams = {
     abi: Abi;
@@ -76,6 +76,14 @@ 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.
@@ -88,12 +96,7 @@ type SwapExecutionError = {
     step: 'swap-stopped';
 } | {
     step: 'allowance-check';
-} | {
-    step: 'approval';
-    cause: WalletError;
-} | {
-    step: 'approval-reverted';
-} | {
+} | Erc20ApprovalError | {
     step: 'swap';
     cause: WalletError;
 } | {
@@ -113,6 +116,7 @@ type SwapExecutionResult = {
 };
 type ExecuteSwapParams = {
     swap: CoinListSwapNamespace;
+    erc20: CoinListErc20Namespace;
     wallet: EvmWallet;
     contractAddress: EvmContractAddress;
     chain: EthereumChain;
@@ -188,7 +192,7 @@ 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'>): Promise<SwapExecutionResult>;
+    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.
@@ -196,10 +200,98 @@ interface CoinListClientSwapNamespace extends CoinListSwapNamespace {
     authorizeWallet(params: Omit<AuthorizeWalletParams, 'swap'>): Promise<WalletAuthorizationResult>;
 }
 declare class ClientSwapNamespaceImpl extends SwapNamespaceImpl implements CoinListClientSwapNamespace {
-    executeSwap(params: Omit<ExecuteSwapParams, 'swap'>): Promise<SwapExecutionResult>;
+    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}. */
 type OauthClientErrorReason = 'user_canceled' | 'missing_state' | 'invalid_state' | 'missing_code' | 'missing_code_verifier';
@@ -297,38 +389,6 @@ interface CoinListClient {
      * {@link NotAuthenticatedError}.
      */
     fetchOfferDetails(id: OfferId): Promise<OfferDetail>;
-    /**
-     * Fetches all participations by iterating through every paginated response.
-     *
-     * 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[]>;
-    /**
-     * Fetches a single page of participations, optionally filtered by offer.
-     *
-     * 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>>;
-    /**
-     * Fetches a participation by id.
-     *
-     * 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>;
-    /**
-     * Creates a participation.
-     *
-     * 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>;
     /**
      * Creates a single-use wallet-ownership challenge for the given wallet and
      * chain. The user signs the returned {@link WalletOwnershipChallenge.message}
@@ -430,8 +490,30 @@ interface CoinListClient {
      */
     contactSupport(): void;
     /**
-     * On-chain swap operations: quoting a swap, reading swap-contract state and
-     * token allowances, and proving/allow-listing wallet ownership — e.g.
+     * 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}
@@ -520,11 +602,11 @@ interface CoinListSignInCardProps {
 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;
@@ -1438,4 +1520,4 @@ interface UseTaxDocumentResult {
  */
 declare function useTaxDocument({ isOpen, }: UseTaxDocumentOptions): UseTaxDocumentResult;
 
-export { type AuthState, type AuthorizeWalletParams, type BroadcastTxParams, ChecklistStatus, type ClientConfig, ClientSwapNamespaceImpl, type CoinListClient, CoinListClientInitializationError, type CoinListClientSwapNamespace, 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, 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 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, useCoinList, useCompleteOAuth, useConnectWallet, useKycToken, useOfferDetails, useOffers, useOptionAddresses, useParticipations, useRequirements, useSwapOutputToken, useSwapQuote, useSwapTokenBalances, useTaxDocument };
+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 };

package/dist/client/index.d.ts

@@ -2,8 +2,8 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { Hex, Abi, Hash, TransactionReceipt } from 'viem';
-import { E as EvmWalletAddress, a as EthereumChain, C as CoinListSwapNamespace, O as OfferId, b as EvmContractAddress, B as Bps, c as BlockchainAmount, S as SwapNamespaceImpl, A as AuthorizationCode, d as CodeVerifier, e as Config, f as OAuthAccessToken, g as Offer, P as PaginationParams, h as PaginatedResponse, i as OfferDetail, j as Participation, k as ParticipationsPaginationParams, l as ParticipationId, m as CreateParticipationParams, n as CreateWalletOwnershipChallengeParams, W as WalletOwnershipChallenge, o as ConnectExternalWalletParams, p as OfferOptionAddress, q as OfferOptionId, r as OfferOptionAddressId, R as Requirement, s as RequirementStatusInfo, t as Pii, D as DocumentType, u as DocumentSubmission, K as KycLevelName, v as KycToken, w as WalletChallengeType, x as RequirementType, y as RequirementStatusValue, z as Erc20Asset, F as AssetDecimals, G as StablecoinSymbol } from '../requirement-C2w45Q11.js';
-import { S as SwapQuote, N as NonEmptyArray } from '../collections-BQbFJS3g.js';
+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;
@@ -76,6 +76,14 @@ 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.
@@ -88,12 +96,7 @@ type SwapExecutionError = {
     step: 'swap-stopped';
 } | {
     step: 'allowance-check';
-} | {
-    step: 'approval';
-    cause: WalletError;
-} | {
-    step: 'approval-reverted';
-} | {
+} | Erc20ApprovalError | {
     step: 'swap';
     cause: WalletError;
 } | {
@@ -113,6 +116,7 @@ type SwapExecutionResult = {
 };
 type ExecuteSwapParams = {
     swap: CoinListSwapNamespace;
+    erc20: CoinListErc20Namespace;
     wallet: EvmWallet;
     contractAddress: EvmContractAddress;
     chain: EthereumChain;
@@ -188,7 +192,7 @@ 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'>): Promise<SwapExecutionResult>;
+    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.
@@ -196,10 +200,98 @@ interface CoinListClientSwapNamespace extends CoinListSwapNamespace {
     authorizeWallet(params: Omit<AuthorizeWalletParams, 'swap'>): Promise<WalletAuthorizationResult>;
 }
 declare class ClientSwapNamespaceImpl extends SwapNamespaceImpl implements CoinListClientSwapNamespace {
-    executeSwap(params: Omit<ExecuteSwapParams, 'swap'>): Promise<SwapExecutionResult>;
+    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}. */
 type OauthClientErrorReason = 'user_canceled' | 'missing_state' | 'invalid_state' | 'missing_code' | 'missing_code_verifier';
@@ -297,38 +389,6 @@ interface CoinListClient {
      * {@link NotAuthenticatedError}.
      */
     fetchOfferDetails(id: OfferId): Promise<OfferDetail>;
-    /**
-     * Fetches all participations by iterating through every paginated response.
-     *
-     * 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[]>;
-    /**
-     * Fetches a single page of participations, optionally filtered by offer.
-     *
-     * 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>>;
-    /**
-     * Fetches a participation by id.
-     *
-     * 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>;
-    /**
-     * Creates a participation.
-     *
-     * 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>;
     /**
      * Creates a single-use wallet-ownership challenge for the given wallet and
      * chain. The user signs the returned {@link WalletOwnershipChallenge.message}
@@ -430,8 +490,30 @@ interface CoinListClient {
      */
     contactSupport(): void;
     /**
-     * On-chain swap operations: quoting a swap, reading swap-contract state and
-     * token allowances, and proving/allow-listing wallet ownership — e.g.
+     * 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}
@@ -520,11 +602,11 @@ interface CoinListSignInCardProps {
 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;
@@ -1438,4 +1520,4 @@ interface UseTaxDocumentResult {
  */
 declare function useTaxDocument({ isOpen, }: UseTaxDocumentOptions): UseTaxDocumentResult;
 
-export { type AuthState, type AuthorizeWalletParams, type BroadcastTxParams, ChecklistStatus, type ClientConfig, ClientSwapNamespaceImpl, type CoinListClient, CoinListClientInitializationError, type CoinListClientSwapNamespace, 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, 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 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, useCoinList, useCompleteOAuth, useConnectWallet, useKycToken, useOfferDetails, useOffers, useOptionAddresses, useParticipations, useRequirements, useSwapOutputToken, useSwapQuote, useSwapTokenBalances, useTaxDocument };
+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 };