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:

FieldValue seenWhat to check
x402Version2A version your client actually speaks.
networkstacks:1Mainnet when you mean mainnet, testnet when you are testing.
amount10In the token’s smallest unit (sats for sBTC). Is it in the range you agreed to?
assetSM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-tokenThe real token contract, not a look-alike.
payToan SP… addressThe party you think you are paying.
maxTimeoutSeconds300Long 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

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.