@dexterai/x402 3.8.0 → 3.9.0

package/dist/{types-DDBPREEu.d.ts → types-D9VMq7In.d.ts}

@@ -1,6 +1,6 @@
 import { RequestHandler } from 'express';
 import { ChannelStorage } from '@x402/evm/batch-settlement/server';
-import { b as CloseReceipt } from './types-DllrEG_Z.js';
+import { b as CloseReceipt } from './types-CTl7yVq6.js';
 
 /**
  * Result of closing one channel from the seller side. Either a settlement

package/dist/{types-htvWHuW3.d.cts → types-RxdlGPaG.d.cts}

@@ -302,6 +302,25 @@ declare class EvmAdapter implements ChainAdapter {
     private getChainId;
     getBalance(accept: PaymentAccept, wallet: unknown, rpcUrl?: string): Promise<number>;
     private encodeBalanceOf;
+    /**
+     * Confirm an EVM payment settled on-chain, after a post-payment timeout.
+     *
+     * EIP-3009 (`exact`): calls the token contract's
+     * `authorizationState(authorizer, nonce)` view — `true` means our exact
+     * signed authorization was consumed, i.e. the transfer settled. The nonce
+     * is the 32-byte value the SDK itself generated, so this is a definitive,
+     * surgical yes/no.
+     *
+     * Permit2: calls `Permit2.nonceBitmap(owner, wordPos)` and tests the bit
+     * for our nonce. A set bit means the Permit2 transfer was executed.
+     *
+     * For any other scheme (e.g. exact-approval) there is no clean
+     * nonce-consumed check — this throws, which the strategy reads as
+     * "unknown" and maps to `payment_unconfirmed`.
+     */
+    confirmSettlement(probe: SettlementProbe, rpcUrl: string): Promise<SettlementConfirmation>;
+    /** Raw `eth_call` returning the result hex word. Throws on RPC error. */
+    private ethCall;
     buildTransaction(accept: PaymentAccept, wallet: unknown, rpcUrl?: string): Promise<SignedTransaction>;
     /**
      * Build a payment transaction for chains that use the approval-based scheme.
@@ -392,6 +411,26 @@ declare class SolanaAdapter implements ChainAdapter {
     isConnected(wallet: unknown): boolean;
     getBalance(accept: PaymentAccept, wallet: unknown, rpcUrl?: string): Promise<number>;
     buildTransaction(accept: PaymentAccept, wallet: unknown, rpcUrl?: string): Promise<SignedTransaction>;
+    /**
+     * Confirm a Solana payment settled on-chain, after a post-payment timeout.
+     *
+     * Solana has no EIP-3009-style "was this nonce consumed" view. Instead we
+     * scan recent signatures on the merchant's destination ATA and look for a
+     * transfer of exactly the expected amount. The window is naturally bounded:
+     * the payment transaction is only valid for ~150 slots (~60s) after the
+     * blockhash it was built against, so a settling transfer — if it happened —
+     * is among the most recent signatures on that account. We cap the scan at
+     * the 25 most recent signatures.
+     *
+     * This is strong but not surgical: it matches on (destination ATA, amount),
+     * not a unique nonce. A same-amount transfer to the same merchant inside
+     * the window from an unrelated payer could in principle match. In practice
+     * the blockhash window makes that vanishingly unlikely, and a false
+     * positive here only means we tell the caller "paid" when they were not —
+     * which is the safe direction (it discourages a retry; the caller verifies
+     * against their own wallet). A false negative maps to `payment_unconfirmed`.
+     */
+    confirmSettlement(probe: SettlementProbe, rpcUrl: string): Promise<SettlementConfirmation>;
 }
 /**
  * Create a Solana adapter instance
@@ -408,6 +447,50 @@ interface GenericWallet {
     /** Whether the wallet is connected and ready */
     connected: boolean;
 }
+/**
+ * Everything an adapter needs to ask the chain "did this exact payment
+ * settle?" after the fact — without trusting the facilitator or the merchant.
+ *
+ * `buildTransaction` populates this on the {@link SignedTransaction} it
+ * returns. If a post-payment timeout fires, the strategy hands it back to
+ * {@link ChainAdapter.confirmSettlement}. A scheme that has no clean on-chain
+ * "was this consumed" check (e.g. EVM exact-approval) leaves it `undefined`,
+ * and the strategy falls back to reporting `payment_unconfirmed`.
+ */
+type SettlementProbe = {
+    /** EVM EIP-3009 `transferWithAuthorization` — the default `exact` scheme. */
+    kind: 'eip3009';
+    /** The authorizer (payer) address — `authorization.from`. */
+    from: string;
+    /** The 32-byte authorization nonce the SDK generated. The unique key. */
+    nonce: string;
+    /** The token contract (USDC) — also the EIP-3009 contract exposing `authorizationState`. */
+    asset: string;
+    /** EVM chain id, decimal. */
+    chainId: number;
+} | {
+    /** EVM Permit2 `permitWitnessTransferFrom`. */
+    kind: 'permit2';
+    /** The payer address — Permit2 nonces are namespaced per owner. */
+    from: string;
+    /** The Permit2 nonce (256-bit, decimal string). */
+    nonce: string;
+    /** EVM chain id, decimal. */
+    chainId: number;
+} | {
+    /** Solana SPL transfer. No nonce-consumed view — confirmed by a windowed scan. */
+    kind: 'solana';
+    /** The buyer's source associated-token-account. */
+    sourceAta: string;
+    /** The merchant's destination associated-token-account — the address we scan. */
+    destinationAta: string;
+    /** The token mint. */
+    asset: string;
+    /** Atomic amount, as a string. */
+    amount: string;
+    /** The transaction's recent blockhash — bounds how far back the scan need look. */
+    blockhash: string;
+};
 /**
  * Result of building and signing a transaction.
  *
@@ -423,6 +506,21 @@ interface SignedTransaction {
     signature?: string;
     /** Protocol extensions (e.g., erc20ApprovalGasSponsoring) to attach to the payment payload */
     extensions?: Record<string, unknown>;
+    /**
+     * Data needed to confirm settlement on-chain after a post-payment timeout.
+     * `undefined` for schemes with no clean on-chain confirmation check.
+     * See {@link SettlementProbe} and {@link ChainAdapter.confirmSettlement}.
+     */
+    settlementProbe?: SettlementProbe;
+}
+/**
+ * Outcome of an on-chain settlement check.
+ */
+interface SettlementConfirmation {
+    /** True if the payment is confirmed settled on-chain. */
+    settled: boolean;
+    /** The settling transaction hash, when the check can recover it. */
+    txSignature?: string;
 }
 /**
  * Chain adapter interface - each chain implements this
@@ -476,6 +574,29 @@ interface ChainAdapter {
      * @param network - CAIP-2 network identifier
      */
     getDefaultRpcUrl(network: string): string;
+    /**
+     * Ask the chain whether a specific payment settled.
+     *
+     * Called after a post-payment timeout: the SDK sent the payment
+     * authorization, the merchant never responded, and we need to know whether
+     * the money actually moved before deciding what to tell the caller. This
+     * consults the chain directly via `rpcUrl` — it does not trust the
+     * facilitator or the merchant.
+     *
+     * Optional: an adapter that cannot confirm a given scheme may omit this
+     * method (or return `{ settled: false }` is wrong — see below). When the
+     * method is absent, or the {@link SettlementProbe} was `undefined`, the
+     * strategy falls back to reporting `payment_unconfirmed`.
+     *
+     * @param probe - The {@link SettlementProbe} captured at build time.
+     * @param rpcUrl - The RPC endpoint to query.
+     * @returns settled true/false, plus the tx hash when recoverable. An
+     *   implementation that genuinely cannot tell should THROW rather than
+     *   return `{ settled: false }` — a thrown error is treated as "unknown"
+     *   (→ `payment_unconfirmed`), whereas `{ settled: false }` is treated as
+     *   a definitive "the money did not move."
+     */
+    confirmSettlement?(probe: SettlementProbe, rpcUrl: string): Promise<SettlementConfirmation>;
 }
 /**
  * Configuration for creating a chain adapter
@@ -514,4 +635,4 @@ interface BalanceInfo {
     asset: string;
 }
 
-export { type AccessPassClientConfig as A, type BalanceInfo as B, type ChainAdapter as C, type EvmWallet as E, type GenericWallet as G, type PaymentAccept as P, type SolanaWallet as S, type VerifyResponse as V, type WalletSet as W, X402Error as X, createEvmAdapter as a, type AccessPassTier as b, createSolanaAdapter as c, type AccessPassInfo as d, type SettleResponse as e, type PayToProvider as f, type PaymentRequired as g, type PayToContext as h, type PayToProviderDefaults as i, type AccessPassClaims as j, SolanaAdapter as k, EvmAdapter as l, type AdapterConfig as m, type SignedTransaction as n, isSolanaWallet as o, isEvmWallet as p };
+export { type AccessPassClientConfig as A, type BalanceInfo as B, type ChainAdapter as C, type EvmWallet as E, type GenericWallet as G, type PaymentAccept as P, type SettlementProbe as S, type VerifyResponse as V, type WalletSet as W, X402Error as X, type SolanaWallet as a, createEvmAdapter as b, createSolanaAdapter as c, type AccessPassTier as d, type AccessPassInfo as e, type SettleResponse as f, type PayToProvider as g, type PaymentRequired as h, type PayToContext as i, type PayToProviderDefaults as j, type AccessPassClaims as k, SolanaAdapter as l, EvmAdapter as m, type AdapterConfig as n, type SignedTransaction as o, isSolanaWallet as p, isEvmWallet as q };

package/dist/{types-htvWHuW3.d.ts → types-RxdlGPaG.d.ts}

@@ -302,6 +302,25 @@ declare class EvmAdapter implements ChainAdapter {
     private getChainId;
     getBalance(accept: PaymentAccept, wallet: unknown, rpcUrl?: string): Promise<number>;
     private encodeBalanceOf;
+    /**
+     * Confirm an EVM payment settled on-chain, after a post-payment timeout.
+     *
+     * EIP-3009 (`exact`): calls the token contract's
+     * `authorizationState(authorizer, nonce)` view — `true` means our exact
+     * signed authorization was consumed, i.e. the transfer settled. The nonce
+     * is the 32-byte value the SDK itself generated, so this is a definitive,
+     * surgical yes/no.
+     *
+     * Permit2: calls `Permit2.nonceBitmap(owner, wordPos)` and tests the bit
+     * for our nonce. A set bit means the Permit2 transfer was executed.
+     *
+     * For any other scheme (e.g. exact-approval) there is no clean
+     * nonce-consumed check — this throws, which the strategy reads as
+     * "unknown" and maps to `payment_unconfirmed`.
+     */
+    confirmSettlement(probe: SettlementProbe, rpcUrl: string): Promise<SettlementConfirmation>;
+    /** Raw `eth_call` returning the result hex word. Throws on RPC error. */
+    private ethCall;
     buildTransaction(accept: PaymentAccept, wallet: unknown, rpcUrl?: string): Promise<SignedTransaction>;
     /**
      * Build a payment transaction for chains that use the approval-based scheme.
@@ -392,6 +411,26 @@ declare class SolanaAdapter implements ChainAdapter {
     isConnected(wallet: unknown): boolean;
     getBalance(accept: PaymentAccept, wallet: unknown, rpcUrl?: string): Promise<number>;
     buildTransaction(accept: PaymentAccept, wallet: unknown, rpcUrl?: string): Promise<SignedTransaction>;
+    /**
+     * Confirm a Solana payment settled on-chain, after a post-payment timeout.
+     *
+     * Solana has no EIP-3009-style "was this nonce consumed" view. Instead we
+     * scan recent signatures on the merchant's destination ATA and look for a
+     * transfer of exactly the expected amount. The window is naturally bounded:
+     * the payment transaction is only valid for ~150 slots (~60s) after the
+     * blockhash it was built against, so a settling transfer — if it happened —
+     * is among the most recent signatures on that account. We cap the scan at
+     * the 25 most recent signatures.
+     *
+     * This is strong but not surgical: it matches on (destination ATA, amount),
+     * not a unique nonce. A same-amount transfer to the same merchant inside
+     * the window from an unrelated payer could in principle match. In practice
+     * the blockhash window makes that vanishingly unlikely, and a false
+     * positive here only means we tell the caller "paid" when they were not —
+     * which is the safe direction (it discourages a retry; the caller verifies
+     * against their own wallet). A false negative maps to `payment_unconfirmed`.
+     */
+    confirmSettlement(probe: SettlementProbe, rpcUrl: string): Promise<SettlementConfirmation>;
 }
 /**
  * Create a Solana adapter instance
@@ -408,6 +447,50 @@ interface GenericWallet {
     /** Whether the wallet is connected and ready */
     connected: boolean;
 }
+/**
+ * Everything an adapter needs to ask the chain "did this exact payment
+ * settle?" after the fact — without trusting the facilitator or the merchant.
+ *
+ * `buildTransaction` populates this on the {@link SignedTransaction} it
+ * returns. If a post-payment timeout fires, the strategy hands it back to
+ * {@link ChainAdapter.confirmSettlement}. A scheme that has no clean on-chain
+ * "was this consumed" check (e.g. EVM exact-approval) leaves it `undefined`,
+ * and the strategy falls back to reporting `payment_unconfirmed`.
+ */
+type SettlementProbe = {
+    /** EVM EIP-3009 `transferWithAuthorization` — the default `exact` scheme. */
+    kind: 'eip3009';
+    /** The authorizer (payer) address — `authorization.from`. */
+    from: string;
+    /** The 32-byte authorization nonce the SDK generated. The unique key. */
+    nonce: string;
+    /** The token contract (USDC) — also the EIP-3009 contract exposing `authorizationState`. */
+    asset: string;
+    /** EVM chain id, decimal. */
+    chainId: number;
+} | {
+    /** EVM Permit2 `permitWitnessTransferFrom`. */
+    kind: 'permit2';
+    /** The payer address — Permit2 nonces are namespaced per owner. */
+    from: string;
+    /** The Permit2 nonce (256-bit, decimal string). */
+    nonce: string;
+    /** EVM chain id, decimal. */
+    chainId: number;
+} | {
+    /** Solana SPL transfer. No nonce-consumed view — confirmed by a windowed scan. */
+    kind: 'solana';
+    /** The buyer's source associated-token-account. */
+    sourceAta: string;
+    /** The merchant's destination associated-token-account — the address we scan. */
+    destinationAta: string;
+    /** The token mint. */
+    asset: string;
+    /** Atomic amount, as a string. */
+    amount: string;
+    /** The transaction's recent blockhash — bounds how far back the scan need look. */
+    blockhash: string;
+};
 /**
  * Result of building and signing a transaction.
  *
@@ -423,6 +506,21 @@ interface SignedTransaction {
     signature?: string;
     /** Protocol extensions (e.g., erc20ApprovalGasSponsoring) to attach to the payment payload */
     extensions?: Record<string, unknown>;
+    /**
+     * Data needed to confirm settlement on-chain after a post-payment timeout.
+     * `undefined` for schemes with no clean on-chain confirmation check.
+     * See {@link SettlementProbe} and {@link ChainAdapter.confirmSettlement}.
+     */
+    settlementProbe?: SettlementProbe;
+}
+/**
+ * Outcome of an on-chain settlement check.
+ */
+interface SettlementConfirmation {
+    /** True if the payment is confirmed settled on-chain. */
+    settled: boolean;
+    /** The settling transaction hash, when the check can recover it. */
+    txSignature?: string;
 }
 /**
  * Chain adapter interface - each chain implements this
@@ -476,6 +574,29 @@ interface ChainAdapter {
      * @param network - CAIP-2 network identifier
      */
     getDefaultRpcUrl(network: string): string;
+    /**
+     * Ask the chain whether a specific payment settled.
+     *
+     * Called after a post-payment timeout: the SDK sent the payment
+     * authorization, the merchant never responded, and we need to know whether
+     * the money actually moved before deciding what to tell the caller. This
+     * consults the chain directly via `rpcUrl` — it does not trust the
+     * facilitator or the merchant.
+     *
+     * Optional: an adapter that cannot confirm a given scheme may omit this
+     * method (or return `{ settled: false }` is wrong — see below). When the
+     * method is absent, or the {@link SettlementProbe} was `undefined`, the
+     * strategy falls back to reporting `payment_unconfirmed`.
+     *
+     * @param probe - The {@link SettlementProbe} captured at build time.
+     * @param rpcUrl - The RPC endpoint to query.
+     * @returns settled true/false, plus the tx hash when recoverable. An
+     *   implementation that genuinely cannot tell should THROW rather than
+     *   return `{ settled: false }` — a thrown error is treated as "unknown"
+     *   (→ `payment_unconfirmed`), whereas `{ settled: false }` is treated as
+     *   a definitive "the money did not move."
+     */
+    confirmSettlement?(probe: SettlementProbe, rpcUrl: string): Promise<SettlementConfirmation>;
 }
 /**
  * Configuration for creating a chain adapter
@@ -514,4 +635,4 @@ interface BalanceInfo {
     asset: string;
 }
 
-export { type AccessPassClientConfig as A, type BalanceInfo as B, type ChainAdapter as C, type EvmWallet as E, type GenericWallet as G, type PaymentAccept as P, type SolanaWallet as S, type VerifyResponse as V, type WalletSet as W, X402Error as X, createEvmAdapter as a, type AccessPassTier as b, createSolanaAdapter as c, type AccessPassInfo as d, type SettleResponse as e, type PayToProvider as f, type PaymentRequired as g, type PayToContext as h, type PayToProviderDefaults as i, type AccessPassClaims as j, SolanaAdapter as k, EvmAdapter as l, type AdapterConfig as m, type SignedTransaction as n, isSolanaWallet as o, isEvmWallet as p };
+export { type AccessPassClientConfig as A, type BalanceInfo as B, type ChainAdapter as C, type EvmWallet as E, type GenericWallet as G, type PaymentAccept as P, type SettlementProbe as S, type VerifyResponse as V, type WalletSet as W, X402Error as X, type SolanaWallet as a, createEvmAdapter as b, createSolanaAdapter as c, type AccessPassTier as d, type AccessPassInfo as e, type SettleResponse as f, type PayToProvider as g, type PaymentRequired as h, type PayToContext as i, type PayToProviderDefaults as j, type AccessPassClaims as k, SolanaAdapter as l, EvmAdapter as m, type AdapterConfig as n, type SignedTransaction as o, isSolanaWallet as p, isEvmWallet as q };

package/dist/{sponsored-access-D96FgkQK.d.ts → x402-client-CHrU2Bs6.d.cts}

@@ -1,9 +1,83 @@
-import { C as ChainAdapter, W as WalletSet, A as AccessPassClientConfig, P as PaymentAccept } from './types-htvWHuW3.js';
 import { SponsoredRecommendation, SponsoredAccessSettlementInfo } from '@dexterai/x402-ads-types';
+import { C as ChainAdapter, W as WalletSet, A as AccessPassClientConfig, P as PaymentAccept, S as SettlementProbe } from './types-RxdlGPaG.cjs';
+
+/**
+ * Sponsored Access (Ads for Agents) — Client Helpers
+ *
+ * Extract sponsored recommendations from x402 payment receipts and
+ * fire impression beacons to confirm delivery to the ad network.
+ *
+ * Recommendations are injected by the facilitator after settlement
+ * via the `extensions["sponsored-access"]` field. Publishers who enable
+ * `sponsoredAccess: true` in their middleware also inject them into
+ * the JSON response body as `_x402_sponsored`.
+ *
+ * @example
+ * ```typescript
+ * import { wrapFetch, getSponsoredRecommendations, fireImpressionBeacon } from '@dexterai/x402/client';
+ *
+ * const x402Fetch = wrapFetch(fetch, { walletPrivateKey: key });
+ * const response = await x402Fetch('https://api.example.com/data');
+ *
+ * const recs = getSponsoredRecommendations(response);
+ * if (recs) {
+ *   console.log('Sponsored:', recs.map(r => `${r.sponsor}: ${r.description}`));
+ *   await fireImpressionBeacon(response); // Confirm delivery to ad network
+ * }
+ * ```
+ */
+
+/**
+ * Extract the full sponsored-access extension data from a payment receipt.
+ * Returns undefined if no sponsored-access extension is present.
+ */
+declare function getSponsoredAccessInfo(response: Response): SponsoredAccessSettlementInfo | undefined;
+/**
+ * Extract sponsored recommendations from an x402 payment response.
+ * Returns the recommendations array, or undefined if none present.
+ *
+ * @example
+ * ```typescript
+ * const recs = getSponsoredRecommendations(response);
+ * if (recs) {
+ *   for (const rec of recs) {
+ *     console.log(`${rec.sponsor}: ${rec.description} — ${rec.resourceUrl}`);
+ *   }
+ * }
+ * ```
+ */
+declare function getSponsoredRecommendations(response: Response): SponsoredRecommendation[] | undefined;
+/**
+ * Fire the impression beacon to confirm recommendation delivery to the ad network.
+ * This is a fire-and-forget GET request — failures are silently ignored.
+ *
+ * Call this after you've read the recommendations to help the ad network
+ * track delivery rates and verify impressions.
+ *
+ * @returns true if the beacon was fired (regardless of response), false if no beacon URL
+ *
+ * @example
+ * ```typescript
+ * const recs = getSponsoredRecommendations(response);
+ * if (recs) {
+ *   // Process recommendations...
+ *   await fireImpressionBeacon(response);
+ * }
+ * ```
+ */
+declare function fireImpressionBeacon(response: Response): Promise<boolean>;
 
 /**
  * x402 v2 Client
  *
+ * `createX402Client`, `X402Client`, and `X402ClientConfig` are
+ * @deprecated — slated for removal in `@dexterai/x402` 5.0 (~6 months out;
+ * longer cycle than the 4.0 batch because there are real consumers). Use
+ * `payAndFetch` from `@dexterai/x402/client` instead — it's the version-
+ * agnostic 2026+ client with a discriminated-union return type. The
+ * `getPaymentReceipt` helper and `PaymentReceipt` type in this file are NOT
+ * deprecated; they continue to support receipt-reading on any paid response.
+ *
  * Chain-agnostic client for x402 v2 payments.
  * Automatically detects 402 responses, finds a matching payment option,
  * builds the transaction with the appropriate chain adapter, and retries.
@@ -58,6 +132,9 @@ interface PaymentReceipt {
 declare function getPaymentReceipt(response: Response): PaymentReceipt | undefined;
 /**
  * Client configuration
+ *
+ * @deprecated Slated for removal in `@dexterai/x402` 5.0 alongside
+ * `createX402Client` and `X402Client`. Use `PayAndFetchOptions` instead.
  */
 interface X402ClientConfig {
     /**
@@ -121,6 +198,24 @@ interface X402ClientConfig {
      * ```
      */
     onPaymentRequired?: (requirements: PaymentAccept) => boolean | Promise<boolean>;
+    /**
+     * Called the instant the signed payment authorization is sent to the
+     * merchant — after `buildTransaction`, immediately before the paid retry
+     * fetch. This is the point past which a timeout can no longer be treated
+     * as "no money moved": the facilitator may settle at any time once the
+     * authorization is in its hands.
+     *
+     * The callback receives the `accept` it is paying against (network, asset,
+     * amount, payTo) and the `settlementProbe` the adapter produced (or
+     * `undefined` for schemes with no on-chain confirmation). `payAndFetch`
+     * uses this to mark a payment as dispatched — so a post-payment abort is
+     * not misreported as a plain timeout — and keeps the probe so it can
+     * confirm settlement on-chain if the merchant never responds.
+     *
+     * Fire-and-forget — the return value is ignored, and a throw is swallowed
+     * (the payment proceeds regardless). Do not do slow work here.
+     */
+    onPaymentDispatched?: (accept: PaymentAccept, settlementProbe?: SettlementProbe) => void;
     /**
      * Maximum retry attempts for transient failures (network errors, 502/503).
      * Does not cause double payments — EIP-3009 nonces prevent replay.
@@ -135,6 +230,9 @@ interface X402ClientConfig {
 }
 /**
  * x402 Client interface
+ *
+ * @deprecated Slated for removal in `@dexterai/x402` 5.0. Use `payAndFetch`
+ * directly instead of constructing a client object.
  */
 interface X402Client {
     /**
@@ -145,73 +243,26 @@ interface X402Client {
 }
 /**
  * Create an x402 v2 client
- */
-declare function createX402Client(config: X402ClientConfig): X402Client;
-
-/**
- * Sponsored Access (Ads for Agents) — Client Helpers
- *
- * Extract sponsored recommendations from x402 payment receipts and
- * fire impression beacons to confirm delivery to the ad network.
  *
- * Recommendations are injected by the facilitator after settlement
- * via the `extensions["sponsored-access"]` field. Publishers who enable
- * `sponsoredAccess: true` in their middleware also inject them into
- * the JSON response body as `_x402_sponsored`.
+ * @deprecated Slated for removal in `@dexterai/x402` 5.0 (~6 months out — long
+ * cycle because of real production consumers). Use `payAndFetch` from
+ * `@dexterai/x402/client` instead — it's version-agnostic across x402 v1 and
+ * v2 and returns a discriminated union for cleaner error handling.
  *
- * @example
+ * Migration:
  * ```typescript
- * import { wrapFetch, getSponsoredRecommendations, fireImpressionBeacon } from '@dexterai/x402/client';
- *
- * const x402Fetch = wrapFetch(fetch, { walletPrivateKey: key });
- * const response = await x402Fetch('https://api.example.com/data');
+ * // Before
+ * const client = createX402Client({ wallets });
+ * const res = await client.fetch(url);
  *
- * const recs = getSponsoredRecommendations(response);
- * if (recs) {
- *   console.log('Sponsored:', recs.map(r => `${r.sponsor}: ${r.description}`));
- *   await fireImpressionBeacon(response); // Confirm delivery to ad network
+ * // After
+ * import { payAndFetch } from '@dexterai/x402/client';
+ * const result = await payAndFetch(url, undefined, wallets);
+ * if (result.ok) {
+ *   const res = result.response;
  * }
  * ```
  */
+declare function createX402Client(config: X402ClientConfig): X402Client;
 
-/**
- * Extract the full sponsored-access extension data from a payment receipt.
- * Returns undefined if no sponsored-access extension is present.
- */
-declare function getSponsoredAccessInfo(response: Response): SponsoredAccessSettlementInfo | undefined;
-/**
- * Extract sponsored recommendations from an x402 payment response.
- * Returns the recommendations array, or undefined if none present.
- *
- * @example
- * ```typescript
- * const recs = getSponsoredRecommendations(response);
- * if (recs) {
- *   for (const rec of recs) {
- *     console.log(`${rec.sponsor}: ${rec.description} — ${rec.resourceUrl}`);
- *   }
- * }
- * ```
- */
-declare function getSponsoredRecommendations(response: Response): SponsoredRecommendation[] | undefined;
-/**
- * Fire the impression beacon to confirm recommendation delivery to the ad network.
- * This is a fire-and-forget GET request — failures are silently ignored.
- *
- * Call this after you've read the recommendations to help the ad network
- * track delivery rates and verify impressions.
- *
- * @returns true if the beacon was fired (regardless of response), false if no beacon URL
- *
- * @example
- * ```typescript
- * const recs = getSponsoredRecommendations(response);
- * if (recs) {
- *   // Process recommendations...
- *   await fireImpressionBeacon(response);
- * }
- * ```
- */
-declare function fireImpressionBeacon(response: Response): Promise<boolean>;
-
-export { type PaymentReceipt as P, type X402ClientConfig as X, type X402Client as a, getSponsoredRecommendations as b, createX402Client as c, getSponsoredAccessInfo as d, fireImpressionBeacon as f, getPaymentReceipt as g };
+export { type PaymentReceipt as P, type X402ClientConfig as X, getSponsoredAccessInfo as a, getPaymentReceipt as b, createX402Client as c, type X402Client as d, fireImpressionBeacon as f, getSponsoredRecommendations as g };