Configure Your x402 Client

Configure x402 payments for your application after completing the buyer quickstart. Connect an existing client, choose payment schemes, enforce spend limits, and respond to payment lifecycle events.

Use CDP with an existing x402 client

TypeScript
Python

Already have an x402Client built on @x402/core with your own key? Add a CDP-managed signer without migrating to CdpX402Client:

import { CdpClient } from "@coinbase/cdp-sdk";
import { fromCdpEvmAccount } from "@coinbase/cdp-sdk/x402";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";

const cdp = new CdpClient();
const account = await cdp.evm.getOrCreateAccount({ name: "my-x402-signer" });

const client = new x402Client();
registerExactEvmScheme(client, { signer: fromCdpEvmAccount(account) });

fromCdpEvmAccount has counterparts for other account types: fromCdpSmartWallet for a Smart Contract Wallet, and cdpSolanaAccountToSvmSigner for Solana. See x402DevMigration.ts for a runnable example.

Payment schemes

A scheme is the payment behavior a server asks for, such as charging a fixed amount. The server advertises what it accepts, and your client picks a matching registered scheme.

TypeScript
Python

CdpX402Client registers exact and upto for you. batch-settlement is opt-in through its networkSchemes option. The upto scheme uses Permit2, but the CDP Facilitator sponsors that approval, so the buyer does not need to pay a network fee.For exact signatures and configuration, see the CDP SDK x402 reference.

Python clients register schemes explicitly. See the Python buyer setup for the recommended exact scheme configuration.

Set spend limits

Spend controls enforce a client-side budget on top of what the server charges.

TypeScript
Python

const USDC_BASE_TESTNET = "0x036cbd53842c5426634e7929541ec2318f3dcf7e";

const client = new CdpX402Client({
  environment: "development",
  spendControls: {
    maxAmountPerPayment: { atomic: 10_000n, asset: USDC_BASE_TESTNET },
    maxCumulativeSpend: { atomic: 50_000n, asset: USDC_BASE_TESTNET },
    maxCumulativeSpendWindow: "24h",
    allowedNetworks: ["eip155:84532"],
  },
});

Spend is reserved before paying, then confirmed or rolled back once settlement is known. An ambiguous outcome remains reserved so the guardrail fails toward under-spending rather than over-spending. Blocked payments throw SpendControlError with a machine-readable code.See the full runnable version in payForApiWithSpendControls.ts.

Add onchain attribution

Builder Codes attribute the clients and intermediaries that create x402 payments. The CDP Facilitator records these codes in ERC-8021 Schema 2 calldata when it settles an EVM payment.

TypeScript
Python

Pass your Builder Code to CdpX402Client:

const client = new CdpX402Client({
  builderCode: "my_client",
});

Composite applications can pass an array to attribute multiple clients or middleware layers.

from x402.extensions.builder_code import BuilderCodeClientExtension

client.register_extension(BuilderCodeClientExtension("my_client"))

Each code must contain 1–32 lowercase letters, numbers, or underscores. Omit the option or extension to leave client attribution unset. See the builder-code specification for the attribution fields and protocol flow.

Lifecycle hooks

TypeScript
Python

x402HTTPClient provides onPaymentRequired. Its underlying x402Client provides onBeforePaymentCreation, onAfterPaymentCreation, onPaymentCreationFailure, and onPaymentResponse. CdpX402Client inherits these hooks.

client.onPaymentResponse(async ({ settleResponse }) => {
  if (settleResponse?.success) {
    console.info("Payment settled", {
      network: settleResponse.network,
      transaction: settleResponse.transaction,
    });
  }
});

x402HTTPClient provides on_payment_required. Its underlying x402Client provides on_before_payment_creation, on_after_payment_creation, on_payment_creation_failure, and on_payment_response.

def log_payment(context) -> None:
    if context.settle_response and context.settle_response.success:
        print(
            "Payment settled",
            {
                "network": context.settle_response.network,
                "transaction": context.settle_response.transaction,
            },
        )


payment_client.on_payment_response(log_payment)

GET STARTED

WALLETS

PAYMENTS

STABLECOINS

TRADING

ONCHAIN TOOLS

CUSTOMERS

WEBHOOKS

CONSUMER APIS

BUSINESS APIS

INSTITUTIONAL APIS

Use CDP with an existing x402 client

Payment schemes

Set spend limits

Add onchain attribution

Lifecycle hooks

What to read next

​Use CDP with an existing x402 client

​Payment schemes

​Set spend limits

​Add onchain attribution

​Lifecycle hooks

​What to read next

Use CDP with an existing x402 client

Payment schemes

Set spend limits

Add onchain attribution

Lifecycle hooks

What to read next