DEV Community: Solo Earn

How to test an x402 endpoint with curl

Solo Earn — Tue, 13 Oct 2026 16:14:00 +0000

Quick answer: request the paid URL with curl -i. You should get status 402 and a PAYMENT-REQUIRED header that base64-decodes to JSON with x402Version: 2 and an accepts list. Check that the amount is in the token’s smallest units, that the network and asset are the ones you mean, that CORS exposes the header, and that HEAD returns 402 too.

Every command below runs against this store’s own paywall, so you can try them right now and compare with your endpoint. Prefer a browser? The free x402 endpoint checker runs all of these checks (and a few more) in one go. 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

Which headers does x402 v2 use?

Three, all base64-encoded JSON: PAYMENT-REQUIRED (server to client, sent with the 402), PAYMENT-SIGNATURE (client to server, carrying the signed payment) and PAYMENT-RESPONSE (server to client, carrying the settlement result).

Is the JSON body required?

The x402 v2 HTTP transport spec says protocol information travels in the headers and that the response body is up to the server. Sending the same terms in the body as well makes the endpoint easier for people and simple crawlers to read.

Why does my browser client not see PAYMENT-REQUIRED?

Browsers hide non-standard response headers from cross-origin scripts unless the server lists them in Access-Control-Expose-Headers. Add PAYMENT-REQUIRED and PAYMENT-RESPONSE there.

Can curl test the paid path?

Not on its own. A real PAYMENT-SIGNATURE needs a wallet signature, so use an x402 client library with a funded test wallet, or a testnet network, for that part. curl is for checking everything a client and a directory see before payment.

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.

Originally published at x402-seller-kit.soloearn.workers.dev. Free tool: the x402 endpoint checker. If you'd rather not build it yourself, the x402 Seller Kit ($29) is a tested Cloudflare Worker template.

Why can’t my browser x402 client read the PAYMENT-REQUIRED header?

Solo Earn — Mon, 12 Oct 2026 22:14:33 +0000

Quick answer: browsers hide non-standard response headers from cross-origin scripts. Send Access-Control-Expose-Headers: PAYMENT-REQUIRED, PAYMENT-RESPONSE on your 402 and paid responses, and answer the OPTIONS preflight with Access-Control-Allow-Headers that includes PAYMENT-SIGNATURE.

What the spec puts in headers

In the x402 v2 HTTP transport, the server sends the payment terms base64-encoded in PAYMENT-REQUIRED with the 402. The client retries with PAYMENT-SIGNATURE, and the server confirms with PAYMENT-RESPONSE. PAYMENT-REQUIRED and PAYMENT-RESPONSE are response headers that aren’t CORS-safelisted, so a script on another origin sees the 402 status but gets null for them unless you list them in Access-Control-Expose-Headers. PAYMENT-SIGNATURE is a request header: it goes in Access-Control-Allow-Headers, not the expose list.

Minimal Worker headers

const CORS = {
  'Access-Control-Allow-Origin': '*',
  'Access-Control-Allow-Headers': 'PAYMENT-SIGNATURE, X-PAYMENT, Content-Type',
  'Access-Control-Expose-Headers': 'PAYMENT-REQUIRED, PAYMENT-RESPONSE',
};
// OPTIONS -> new Response(null, { status: 204, headers: CORS })
// add CORS to the 402 and to the paid 200

Test it with curl

# the 402 exposes the terms
curl -s -D - -o /dev/null "$URL" | grep -i '^access-control-expose-headers'
# the preflight allows the payment header
curl -s -D - -o /dev/null -X OPTIONS "$URL" \
  -H 'Origin: https://example.com' \
  -H 'Access-Control-Request-Method: GET' \
  -H 'Access-Control-Request-Headers: payment-signature' | grep -i '^access-control-allow-headers'

Or paste the URL into the free x402 endpoint checker, which warns when the 402 has no CORS headers or doesn’t expose PAYMENT-REQUIRED. It doesn’t send a preflight, so run the second curl command for that.

FAQ

Which headers does x402 v2 use over HTTP?

PAYMENT-REQUIRED (server to client, with the 402), PAYMENT-SIGNATURE (client to server) and PAYMENT-RESPONSE (server to client, with the settlement result). All three carry base64-encoded JSON.

What about X-PAYMENT?

X-PAYMENT is the older v1 request header. Some servers accept it alongside PAYMENT-SIGNATURE for older clients, so allow both in Access-Control-Allow-Headers if you support both.

Do server-side agents need CORS?

No. CORS only applies to scripts running in a browser. Server-side clients and agents read every header regardless.

Sources: the x402 v2 HTTP transport spec, Cloudflare Agents x402 docs and MDN on Access-Control-Expose-Headers. More checks: how to test an x402 endpoint with curl.