Check an x402 “402 Payment Required” before you pay it
Published 2026-11-11 (America/New_York)
x402 lets a web endpoint answer 402 Payment Required with a machine-readable price. An agent can pay and retry. That is handy, and it also means your agent is about to send money because a server told it to. Read the request first.
On 2026-11-11 we probed three public Cloudflare workers built from the aibtcdev/cloudflare-agents-x402 template. Each one answered GET /ask?question=hello with HTTP 402, a JSON body, and a base64 payment-required header. Decoded, the header carried:
| Field | Value seen | What to check |
|---|---|---|
x402Version | 2 | A version your client actually speaks. |
network | stacks:1 | Mainnet when you mean mainnet, testnet when you are testing. |
amount | 10 | In the token’s smallest unit (sats for sBTC). Is it in the range you agreed to? |
asset | SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token | The real token contract, not a look-alike. |
payTo | an SP… address | The party you think you are paying. |
maxTimeoutSeconds | 300 | Long enough to settle, not open-ended. |
The script
probe-x402.sh never pays and never signs. It fetches once, insists on a 402, decodes the header, prints the fields, and optionally checks payTo against the address you expected. It also tells you whether the decoded header and the JSON body agree.
#!/usr/bin/env bash
# probe-x402.sh URL [EXPECTED_PAYTO] — read-only: never pays, never signs.
set -euo pipefail
url=$1; want=${2:-}
hdr=$(mktemp); body=$(mktemp); trap 'rm -f "$hdr" "$body"' EXIT
code=$(curl -sS -m 20 -D "$hdr" -o "$body" -w '%{http_code}' "$url")
echo "http=$code"
[ "$code" = 402 ] || { echo "FAIL: expected 402"; exit 1; }
pr=$(grep -i '^payment-required:' "$hdr" | cut -d' ' -f2- | tr -d '\r')
[ -n "$pr" ] || { echo "FAIL: no payment-required header"; exit 1; }
printf '%s' "$pr" | base64 -d | python3 -c '
import json,sys
d=json.load(sys.stdin); a=d["accepts"][0]
print("x402Version=%s network=%s amount=%s asset=%s payTo=%s timeout=%ss"%(d["x402Version"],a["network"],a["amount"],a["asset"],a["payTo"],a.get("maxTimeoutSeconds")))
'
if [ -n "$want" ]; then
printf '%s' "$pr" | base64 -d | grep -q "\"payTo\":\"$want\"" && echo "payTo matches" || { echo "FAIL: payTo differs"; exit 1; }
fi
cmp -s <(printf '%s' "$pr" | base64 -d | python3 -m json.tool --sort-keys) <(python3 -m json.tool --sort-keys "$body") && echo "header == body" || echo "NOTE: header and body differ"
What we ran
- Expected
payTogiven and correct: printed the fields,payTo matches,header == body, exit 0. - Same endpoint, a different expected address:
FAIL: payTo differs, exit 1. - A normal web page (HTTP 200):
FAIL: expected 402, exit 1.
Put the check in front of your paying client. If the network, asset, amount, or recipient is not what you agreed to, stop before signing anything. One limit: this script reads only the first entry in accepts. If a server offers several payment options, check the one your client will actually pick.
Want a second pair of eyes?
A 21-sat receipt check verifies one published receipt or payment requirement against its stated proof. The 2,100-sat Hardening Pass is a human-reviewed look at one network call, after a written scope. Buyer pays first. The HP Retry Kit is free to try first.
Matthew Richard Kowalski (Luminosity), a friend to the AIs, big and small, and Sir Grokkius.