Quickstart: charge for an endpoint

This guide takes you from an unprotected HTTP route to an x402-gated endpoint with one successful payment.

Selling products to people and agents? The Business Checkouts API creates one checkout with a hosted payment URL for people and an x402_url for agents. Use it to support both payment flows without running your own x402 server or facilitator. See Accept agentic payments with x402.Charging for an MCP tool instead? Follow Charge over MCP. This quickstart covers HTTP routes.

Using a coding agent? Install the matching skill and your agent runs this guide in your own project:

npx skills add coinbase/cdp-sdk --skill build-x402-server

Prerequisites

A CDP API key and wallet secret. The API key authenticates your server to the CDP Facilitator; the wallet secret lets the SDK provision the wallet that receives payments.
Node.js 22 or later.

Set your credentials in the environment before running anything:

export CDP_API_KEY_ID="your-api-key-id"
export CDP_API_KEY_SECRET="your-api-key-secret"
export CDP_WALLET_SECRET="your-wallet-secret"

1. Install the SDKs

The CDP SDK handles the receiving wallet and the facilitator. The x402 packages handle the protocol and the framework middleware.

TypeScript
Python

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

This guide uses Express. For Hono and Next.js, see Runnable examples.

Python 3.10 or later is required.

pip install "cdp-sdk" "x402[evm,svm,fastapi]" uvicorn

This guide uses FastAPI. For Flask, see Runnable examples.

2. Price a route

The following servers charge $0.01 for GET /report and receive payments in your CDP wallet.

TypeScript
Python

createX402Server does the whole setup in one call: it provisions the receiver wallet, connects to the CDP Facilitator, registers the payment schemes and extensions, and returns a compliant x402 server object that any x402 framework adapter accepts.

// server.ts
import { createX402Server } from "@coinbase/cdp-sdk/x402";
import { paymentMiddlewareFromHTTPServer } from "@x402/express";
import express from "express";

const app = express();

const server = await createX402Server({
  environment: "development", // uses testnets and test funds
  routes: {
    "GET /report": {
      price: "$0.01",
      description: "Generate a concise research report",
    },
  },
});

app.use(paymentMiddlewareFromHTTPServer(server));

app.get("/report", (_req, res) => res.json({ report: "..." }));

app.listen(8402, () =>
  console.log(`Receiving payments at ${server.payToEvmAddress}`),
);

Every route you add to routes is protected; everything else stays free.

Python has no createX402Server, so you assemble the same pieces yourself: a CDP wallet to receive payments, and the x402 Foundation middleware pointed at the CDP Facilitator with create_facilitator_config.

# server.py
import asyncio

from cdp import CdpClient
from cdp.x402 import create_facilitator_config
from fastapi import FastAPI
from x402.http import HTTPFacilitatorClient, PaymentOption
from x402.http.middleware.fastapi import PaymentMiddlewareASGI
from x402.http.types import RouteConfig
from x402.mechanisms.evm.exact import ExactEvmServerScheme
from x402.server import x402ResourceServer

NETWORK = "eip155:84532"  # Base Sepolia


async def resolve_pay_to() -> str:
    """Provision the CDP wallet that receives payments."""
    async with CdpClient() as cdp:
        account = await cdp.evm.get_or_create_account(name="x402-receiver-wallet-1")
        return account.address


PAY_TO = asyncio.run(resolve_pay_to())

# create_facilitator_config() reads your CDP API key and authenticates verify
# and settle against the CDP Facilitator.
server = x402ResourceServer(HTTPFacilitatorClient(create_facilitator_config()))
server.register(NETWORK, ExactEvmServerScheme())

routes = {
    "GET /report": RouteConfig(
        accepts=[
            PaymentOption(
                scheme="exact", pay_to=PAY_TO, price="$0.01", network=NETWORK
            )
        ],
        mime_type="application/json",
        description="AI-generated report",
    ),
}

app = FastAPI()
app.add_middleware(PaymentMiddlewareASGI, routes=routes, server=server)


@app.get("/report")
async def get_report() -> dict:
    return {"report": "..."}


if __name__ == "__main__":
    import uvicorn

    print(f"Receiving payments at {PAY_TO}")
    uvicorn.run(app, port=8402)

Every route you list in routes is protected; everything else stays free.

3. Start the server and confirm x402 is set up

In a new terminal, start the server:

TypeScript
Python

npx tsx server.ts

python server.py

From a second terminal, request the route without paying:

curl -i http://localhost:8402/report

HTTP/1.1 402 Payment Required
Content-Type: application/json; charset=utf-8
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQYXltZW50IHJlcXVpcmVkIiwi...

{}

The 402 Payment Required response confirms that the route is protected.

4. Test the payment

Choose either testing path:

Ask your agent to use the Pay for Service skill with http://localhost:8402/report.
Build a basic client with the buyer quickstart, then point its request at http://localhost:8402/report.

Both paths fund a buyer wallet and make the paid request. A successful call returns HTTP 200.

5. Move to production

After the test payment succeeds, switch the route to a mainnet before accepting real payments:

TypeScript
Python

- environment: "development",
+ environment: "production",

Routes without an explicit networks list switch from Base Sepolia and Solana Devnet to Base and Solana mainnets.

- NETWORK = "eip155:84532"  # Base Sepolia
+ NETWORK = "eip155:8453"   # Base

Confirm that each payTo address can receive funds on its mainnet. Dollar prices such as "$0.01" automatically use the network’s default USDC asset. If you specify a token address and amount directly, replace any testnet asset address with its mainnet equivalent and verify its decimals. See Production configuration for custom networks, assets, receiving wallets, and payment schemes.

Runnable examples

Complete versions of the server cover more frameworks:

TypeScript
Python

GET STARTED

WALLETS

PAYMENTS

STABLECOINS

TRADING

ONCHAIN TOOLS

CUSTOMERS

WEBHOOKS

CONSUMER APIS

BUSINESS APIS

INSTITUTIONAL APIS

Prerequisites

1. Install the SDKs

2. Price a route

3. Start the server and confirm x402 is set up

4. Test the payment

5. Move to production

Runnable examples

What to read next

​Prerequisites

​1. Install the SDKs

​2. Price a route

​3. Start the server and confirm x402 is set up

​4. Test the payment

​5. Move to production

​Runnable examples

​What to read next

Prerequisites

1. Install the SDKs

2. Price a route

3. Start the server and confirm x402 is set up

4. Test the payment

5. Move to production

Runnable examples

What to read next