How to test an x402 endpoint with curl

Every command below runs against this store’s own paywall, so you can try them right now and compare with your endpoint. Set the URL once:

URL=https://x402-seller-kit.soloearn.workers.dev/download

1. The status is 402

curl -s -o /dev/null -w '%{http_code}\n' "$URL"      # 402

A 200 means the file is unprotected. A 401 or 403 means something else is in front of it, such as an auth layer or a firewall rule.

2. The PAYMENT-REQUIRED header is there and decodes

The x402 v2 HTTP transport spec puts the payment terms, base64-encoded, in this header. Clients read the header, not the body.

curl -s -D - -o /dev/null "$URL" | grep -i '^payment-required:' \
  | cut -d' ' -f2 | tr -d '\r' | base64 -d | jq .

You should see x402Version, resource and an accepts array. If base64 -d fails, check for URL-safe characters or a missing btoa on the server.

3. Browsers can read it

curl -s -D - -o /dev/null "$URL" | grep -i '^access-control-expose-headers'
# access-control-expose-headers: PAYMENT-REQUIRED

Without this, a browser-based x402 client on another origin gets the 402 but can’t see the terms. Expose PAYMENT-RESPONSE as well on the paid response.

4. The amount is in the right units

curl -s "$URL" | jq -r '.accepts[0].amount'          # 29000000

Amounts are strings in the token’s smallest unit. USDC has 6 decimals, so 29000000 is 29 USDC. A common mistake is writing "29", which asks for 0.000029 USDC.

5. Network, asset and payTo are what you meant

curl -s "$URL" | jq '.accepts[0] | {network, asset, payTo, maxTimeoutSeconds}'

• Networks use CAIP-2 IDs: Base mainnet is eip155:8453, Base Sepolia is eip155:84532.
• Native USDC on Base mainnet is 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913. A testnet token address on mainnet, or the reverse, means nobody can pay.
• Paste payTo into a block explorer and confirm it’s an address you control.

6. HEAD returns 402 as well

curl -s -I "$URL" | head -1                         # HTTP/2 402

Some link checkers and directory crawlers send HEAD first. On this store, an early version answered HEAD with 404 while GET returned 402, and we only noticed it in our request logs. Route both methods to the same handler.

7. Discovery metadata is present

curl -s "$URL" | jq '{desc: .resource.description, mime: .resource.mimeType, bazaar: (.extensions.bazaar != null)}'

A clear description and MIME type, plus Bazaar discovery metadata in extensions, help directories and agents list and price your endpoint. Keep the description specific: what the buyer gets, in one line.

A one-shot check script

#!/usr/bin/env bash
# usage: ./x402-check.sh https://your.host/paid-path
URL=$1
H=$(curl -s -D - -o /dev/null "$URL")
echo "$H" | head -1 | grep -q ' 402' && echo "ok   402 on GET" || echo "FAIL GET is not 402"
curl -s -I "$URL" | head -1 | grep -q ' 402' && echo "ok   402 on HEAD" || echo "FAIL HEAD is not 402"
T=$(echo "$H" | grep -i '^payment-required:' | cut -d' ' -f2 | tr -d '\r' | base64 -d 2>/dev/null)
[ -n "$T" ] && echo "ok   PAYMENT-REQUIRED decodes" || echo "FAIL no PAYMENT-REQUIRED header"
echo "$H" | grep -qi '^access-control-expose-headers:.*payment-required' && echo "ok   header exposed to browsers" || echo "WARN header not in Access-Control-Expose-Headers"
echo "$T" | jq -r '.accepts[] | "info \(.network) \(.asset) amount=\(.amount) payTo=\(.payTo)"'

This covers what a client and a directory see before payment. To test the paid path, use an x402 client library with a test wallet, ideally on Base Sepolia first.

FAQ

Source for header names: the x402 v2 HTTP transport spec in the coinbase/x402 repository. Building the endpoint from scratch? Read how to sell a digital file for USDC with x402 on Cloudflare Workers.