@coinbase/cdp-sdk/_types/x402/client.d.ts

SDK for interacting with the Coinbase Developer Platform Wallet API

import { x402Client } from "@x402/core/client";
import type { SpendControls } from "./guardrails/types.js";
import type { PaymentPayload, PaymentRequired } from "@x402/core/types";
import type { Address } from "viem";
type SupportedNetwork = "base" | "base-sepolia" | "polygon" | "arbitrum" | "world" | "world-sepolia" | "solana" | "solana-devnet";
/**
 * Wallet configuration for the CDP x402 client.
 */
export type WalletConfig = {
    /** CDP Server Wallet (EOA). Default when `type` is omitted. */
    type: "eoa";
    /**
     * Named CDP account. Defaults to `"x402-client-wallet-1"`.
     */
    accountName?: string;
} | {
    /** CDP Smart Contract Wallet. */
    type: "smart";
    /**
     * Named CDP smart account. Defaults to `"x402-client-wallet-1"`.
     */
    accountName?: string;
    /**
     * Owner EOA account name. Required for `"smart"` type.
     */
    ownerAccountName: string;
};
export type SchemesConfig = {
    /** Registers the `exact` scheme: transfers a fixed amount. On by default. */
    exact?: boolean;
    /**
     * Registers the `upto` scheme: authorizes a maximum amount and lets the
     * resource server settle the actual amount used. On by default — except on
     * EVM for a `"smart"` {@link WalletConfig}, since `upto`'s Permit2 approval
     * transaction can't be sponsored for Smart Contract Wallets.
     */
    upto?: boolean;
    /**
     * Registers the `batch-settlement` scheme (EVM only): reuses an off-chain
     * voucher channel across multiple payments. Opt-in.
     */
    batchSettlement?: boolean;
    /**
     * Registers the `auth-capture` scheme (EVM only): the client signs a
     * payer-agnostic authorization that the resource server's captureAuthorizer
     * can later capture, void, or let expire. On by default — except on EVM
     * for a `"smart"` {@link WalletConfig}, since the ERC-1271/ERC-6492-wrapped
     * signature a Smart Contract Wallet produces isn't supported by the
     * `auth-capture` settlement path yet.
     */
    authCapture?: boolean;
};
export type NetworkConfig = {
    network: SupportedNetwork;
    rpcUrl?: string;
    scheme: SchemesConfig;
};
/**
 * Configuration for {@link CdpX402Client}.
 */
export interface CdpX402ClientConfig {
    /** CDP API key ID. Falls back to `CDP_API_KEY_ID` env var. */
    apiKeyId?: string;
    /** CDP API key secret. Falls back to `CDP_API_KEY_SECRET` env var. */
    apiKeySecret?: string;
    /** CDP wallet secret. Falls back to `CDP_WALLET_SECRET` env var. */
    walletSecret?: string;
    /**
     * Wallet configuration. Defaults to `{ type: "eoa" }`.
     */
    walletConfig?: WalletConfig;
    /**
     * Optional SDK-managed spend controls. Unset by default — unlike upstream
     * `x402Client` (which defaults to a $1 per-payment cap), `CdpX402Client`
     * applies no cap unless you set one here. The constructor emits a
     * `console.warn` when this is unset.
     */
    spendControls?: SpendControls;
    /**
     * Optional [builder code](https://github.com/x402-foundation/x402/blob/main/specs/extensions/builder_code.md)
     * for on-chain attribution (`s` / service codes). Pass an array to attribute
     * several participants, e.g. a client layered behind middleware.
     *
     * Every `CdpX402Client` always attaches its own `cdp_sdk_client` service
     * code to `s` alongside any codes configured here, regardless of whether
     * this option is set. Up to four codes may be configured, because the x402
     * extension allows five service codes total.
     *
     * Each code must match `^[a-z0-9_]{1,32}$`; invalid codes and an empty array
     * are rejected by the constructor. A `builder-code` extension registered
     * manually via `registerExtension` replaces the one built from this option.
     */
    builderCode?: string | string[];
    /**
     * Deployment environment. Controls which Base network is prescribed by default.
     *
     * - `"production"` (default) — Base mainnet.
     * - `"development"` — Base Sepolia.
     *
     * Falls back to the `CDP_X402_CLIENT_ENVIRONMENT` env var.
     */
    environment?: "production" | "development";
    /**
     * Optional SDK-managed additional network schemes configuration.
     *
     * The Base network matching `environment` is always prescribed as a
     * baseline, regardless of this option, since CDP hosts a default RPC for it:
     *
     * Defaults to [
     *    { network: "base", scheme: { exact: true, upto: true, authCapture: true } },
     * ]
     * (or `"base-sepolia"` instead of `"base"` when `environment` is `"development"`)
     *
     * Use `networkSchemes` to add other networks (e.g. `"solana"`, `"polygon"`,
     * or the Base network for the *other* environment), or to override the
     * scheme for the prescribed Base network (e.g. to disable a scheme). An
     * override for `"base"` or `"base-sepolia"` that omits `rpcUrl` still gets
     * the CDP-hosted default RPC injected for it.
     *
     * Solana has no CDP-hosted default RPC and no override is required for
     * `exact` or `upto` — both fall back to a public default RPC. `authCapture`
     * isn't supported for Solana (skipped with a warning), regardless of
     * `rpcUrl` — it's an EVM-only scheme upstream. It's also skipped (with a
     * warning) on EVM for a `"smart"` {@link WalletConfig}, since a Smart
     * Contract Wallet's ERC-1271/ERC-6492-wrapped signature isn't supported by
     * the `auth-capture` settlement path yet. `batchSettlement` is opt-in on
     * top of the default baseline (EVM-only as well).
     */
    networkSchemes?: NetworkConfig[];
}
/**
 * Wallet addresses provisioned by a {@link CdpX402Client}.
 */
export interface CdpX402WalletAddresses {
    /** EVM address (EOA or Smart Contract Wallet) used for payment signing. */
    evmAddress: Address;
    /** Solana address used for payment signing. */
    svmAddress: string;
    /** Name of the owner EOA account backing a `"smart"` wallet, if configured. */
    ownerWallet?: string;
}
/**
 * A Coinbase CDP-powered x402 client that initializes lazily on first payment.
 *
 * Extends `x402Client` with automatic wallet provisioning and scheme registration.
 * Credentials fall back to environment variables; wallet configuration and
 * RPC URLs are supplied explicitly via config.
 *
 * The account name/address used for payments is resolved internally. Use
 * {@link CdpX402Client.getAddresses} to retrieve it — for example, to fund
 * the wallet before making a payment.
 *
 * @example
 * ```typescript
 * import { CdpX402Client } from "@coinbase/cdp-sdk/x402";
 * import { wrapFetchWithPayment } from "@x402/fetch";
 *
 * const client = new CdpX402Client();
 * const { evmAddress, svmAddress } = await client.getAddresses();
 * console.log("Fund this address before paying:", evmAddress, svmAddress);
 *
 * const fetchWithPayment = wrapFetchWithPayment(fetch, client);
 * const response = await fetchWithPayment("https://api.example.com/report");
 * ```
 *
 * @example
 * ```typescript
 * const USDC_BASE = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
 * const client = new CdpX402Client({
 *   spendControls: {
 *     maxAmountPerPayment: { atomic: 10_000n, asset: USDC_BASE },
 *     maxCumulativeSpend: { atomic: 50_000n, asset: USDC_BASE },
 *     maxCumulativeSpendWindow: "24h",
 *     allowedNetworks: ["eip155:8453"],
 *   },
 * });
 * ```
 *
 * @example
 * ```typescript
 * // Attribute payments to this client via the builder-code extension.
 * const client = new CdpX402Client({ builderCode: "my_client" });
 * ```
 */
export declare class CdpX402Client extends x402Client {
    private readonly _config;
    private readonly _serviceBuilderCodes;
    private _initPromise;
    private _addresses;
    /**
     * Creates a CdpX402Client that initializes lazily on first payment.
     *
     * @param config - Optional configuration. Credentials fall back to environment variables.
     * @throws If `config.builderCode` is empty, has more than four codes, or
     * contains a code that is not 1-32 lowercase alphanumeric / underscore characters.
     */
    constructor(config?: CdpX402ClientConfig);
    /**
     * The CDP account name that this client provisions (or has already
     * provisioned) for payment signing. Resolved synchronously from config
     * and defaults — does not perform any CDP account lookups.
     *
     * @returns The resolved account name, e.g. `"x402-client-wallet-1"`.
     */
    get accountName(): string;
    /**
     * Provisions the CDP wallet (if not already provisioned) and returns its
     * addresses. Call this eagerly — for example, to display or fund the
     * wallet — instead of waiting for the lazy initialization on first payment.
     *
     * @returns The EVM and Solana addresses backing this client's payments.
     */
    getAddresses(): Promise<CdpX402WalletAddresses>;
    /**
     * Creates the payment payload, initializing the CDP wallet lazily on first call.
     *
     * @param paymentRequired - The x402 payment requirements from the resource server.
     * @returns The signed payment payload.
     */
    createPaymentPayload(paymentRequired: PaymentRequired): Promise<PaymentPayload>;
    /**
     * Provisions CDP accounts and registers payment schemes.
     */
    private _initialize;
    /**
     * Returns a shared initialization promise, starting initialization if needed.
     *
     * @returns Promise that resolves when the client is ready to make payments.
     */
    private _ensureInitialized;
}
export {};
//# sourceMappingURL=client.d.ts.map