Accept Agentic Payments with x402

Checkouts created with the Coinbase Business Checkouts API return an x402_url — a payment endpoint an AI agent or x402 client can pay programmatically. Paying it authorizes a gasless USDC payment on Base (EIP-3009); Coinbase then captures and settles it server-side, with no hosted page, wallet pop-up, or human required. This guide walks through the end-to-end flow: create a checkout, pay its x402_url as an agent, and confirm the checkout completes.

Checkouts use an authorize-then-capture flow. Paying the x402_url authorizes (escrows) the funds; Coinbase captures and settles them server-side. Treat the checkout reaching COMPLETED as the source of truth for settlement — see Confirm settlement.

Prerequisites

A Coinbase Business account with a CDP API key. See Authentication.
On the paying (agent) side: a CDP account and API keys, and a wallet funded with USDC on Base. The examples below use CdpX402Client, which provisions and signs with a CDP-managed wallet, so no raw private keys are needed.
Node.js and npm.

1. Create a checkout

Create a checkout with the Create Checkout endpoint. Authenticate with a JWT Bearer token signed with your CDP API key secret; the rat#view scope is required (see Authentication).

curl -X POST https://business.coinbase.com/api/v1/checkouts \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"amount":"1.00","currency":"USDC","description":"x402 agentic payment"}'

The response includes both a hosted url (for humans) and an x402_url (for agents):

{
  "id": "68f7a946db0529ea9b6d3a12",
  "status": "ACTIVE",
  "amount": "1.00",
  "currency": "USDC",
  "network": "base",
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "url": "https://payments.coinbase.com/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "x402_url": "https://api.cdp.coinbase.com/platform/v2/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad/authorizations/x402"
}

2. Pay the `x402_url` as an agent

Point an x402 client at the x402_url. It is a POST endpoint: the first request returns 402 Payment Required with the payment requirements, and the client retries with the signed payment. With @x402/fetch, wrapFetchWithPayment handles that challenge-and-retry automatically.

Install the client packages

npm install @coinbase/cdp-sdk @x402/fetch @x402/core @x402/evm @x402/svm @x402/extensions dotenv

Pay the checkout

import "dotenv/config";
import { CdpX402Client } from "@coinbase/cdp-sdk/x402";
import { wrapFetchWithPayment, decodePaymentResponseHeader } from "@x402/fetch";

// Reads CDP_API_KEY_ID, CDP_API_KEY_SECRET, CDP_WALLET_SECRET from env.
// Defaults to Base mainnet.
const client = new CdpX402Client();

// Print the wallet address so you can fund it with USDC before paying.
const { evmAddress } = await client.getAddresses();
console.log("Fund this EVM address with USDC on Base:", evmAddress);

const fetchWithPayment = wrapFetchWithPayment(globalThis.fetch, client);

// Set X402_URL to the `x402_url` returned by Create Checkout (step 1).
const x402Url = process.env.X402_URL;
if (!x402Url) throw new Error("Set X402_URL to the x402_url returned by Create Checkout");

// The x402_url is a POST endpoint.
const response = await fetchWithPayment(x402Url, { method: "POST" });
console.log(response.status);

const paymentResponse = decodePaymentResponseHeader(
  response.headers.get("payment-response") ?? "",
);
console.log(paymentResponse);

CdpX402Client defaults to Base mainnet. To test on Base Sepolia, construct it with new CdpX402Client({ environment: "development" }) (or set CDP_X402_CLIENT_ENVIRONMENT=development; the explicit option takes precedence). Only fund the address with the amount you intend to pay.

A successful response means the payment was authorized, not yet settled. Coinbase captures it server-side, moving the checkout ACTIVE → PROCESSING → COMPLETED. Confirm the checkout reaches COMPLETED (next step) rather than treating the HTTP response alone as final. Prefer to pay as a human instead? Open the checkout’s hosted url in a browser, connect a wallet on Base, and approve the (gasless) USDC authorization.

3. Confirm settlement

After the agent authorizes, the checkout transitions ACTIVE → PROCESSING → COMPLETED as Coinbase captures the funds. Poll the Get Checkout endpoint until it reaches a terminal status:

curl https://business.coinbase.com/api/v1/checkouts/68f7a946db0529ea9b6d3a12 \
  -H "Authorization: Bearer $JWT"

On success, status is COMPLETED and transactionHash holds the on-chain settlement transaction. If the payment cannot be captured, the checkout ends FAILED and any authorization hold is released when the capture window expires. You can also subscribe to webhooks for real-time notifications instead of polling.

Refunds

A COMPLETED or PARTIALLY_REFUNDED checkout can be refunded (fully or partially, up to the remaining amount) with the Refund Checkout endpoint. Refunds are asynchronous — poll the checkout to watch refundedAmount and status (REFUNDED or PARTIALLY_REFUNDED).

GET STARTED

WALLETS

PAYMENTS

STABLECOINS

TRADING

ONCHAIN TOOLS

CUSTOMERS

WEBHOOKS

CONSUMER APIS

BUSINESS APIS

INSTITUTIONAL APIS

Prerequisites

1. Create a checkout

2. Pay the `x402_url` as an agent

3. Confirm settlement

Refunds

Next steps

​Prerequisites

​1. Create a checkout

​2. Pay the x402_url as an agent

​3. Confirm settlement

​Refunds

​Next steps

Prerequisites

1. Create a checkout

2. Pay the `x402_url` as an agent

3. Confirm settlement

Refunds

Next steps