Making an x402 Payment

Use Pay to run an x402 V2 API and give Claude Code a payment-aware HTTP client. The API, payer wallet, and settlement all use the Solana sandbox, so this walkthrough does not require an account or real funds.

You need a terminal, Pay, and Claude Code installed.

1. Install Pay

On macOS, install the prebuilt binary:

brew install pay
pay --version

On other platforms, install the npm package:

npm install --global @solana/pay
pay --version

2. Start an x402 sandbox API

Create x402-demo.yaml:

name: x402-demo
subdomain: x402-demo
title: "x402 Demo"
description: "Minimal x402 V2 sandbox endpoint."
category: devtools
version: v1
routing:
  type: respond
operator:
  currencies:
    usd: ["USDC"]
  network: "localnet"
  fee_payer: true
endpoints:
  - method: GET
    path: "report"
    description: "Return a sandbox report."
    metering:
      schemes: [x402-exact]
      dimensions:
        - direction: usage
          unit: requests
          scale: 1
          tiers:
            - price_usd: 0.001

Start the API and leave it running:

pay --sandbox server start x402-demo.yaml --bind 127.0.0.1:1402

The x402-exact scheme makes this an x402-only endpoint. Sandbox mode creates and funds temporary operator and payer accounts automatically.

3. Launch the agent with Pay

In another terminal, start Claude Code in sandbox mode:

pay --sandbox claude

Pay attaches its local MCP tools to the agent session. The agent does not receive a private key.

4. Make one x402 request

Paste this prompt into the agent:

Use Pay to make exactly one sandbox x402 API request to
http://127.0.0.1:1402/report.

Before paying, show me the amount and ask for approval. Then return the API
result and payment receipt. Do not make any other paid requests.

The request follows one complete x402 V2 payment loop:

1. The API returns 402 Payment Required with a PAYMENT-REQUIRED challenge.
2. Pay validates the x402 requirements and displays the payment terms.
3. After approval, the sandbox wallet signs and Pay retries the request with PAYMENT-SIGNATURE.
4. The API returns the result with a PAYMENT-RESPONSE receipt.

No real funds move. Rejecting the approval stops the request.

Continue with x402 on Solana to build an x402 V2 client and resource server, or become an x402 facilitator.