X402 Tools

x402 Tools

Read-only inspection of x402 endpoints. Two things it does:

1. Inspect a live endpoint — call it without paying, decode the payment challenge, and report the price in real money, the accepted networks and tokens, where the money goes, and how to call it.
2. Read an OpenAPI spec — find it, check it parses, lay out its contents, and show where it differs from the live endpoint.

It never pays, signs, or needs a wallet. It also never grades an endpoint: it reports what is there and leaves the conclusions to the reader.

When to use this

• Someone asks what an x402 or paid API costs, or which chains and tokens it takes
• A paid API call failed and the 402 response is opaque
• Someone wants to know how to call an endpoint before spending anything on it
• Someone is shipping an x402 API and wants to see what it actually emits
• Any request to read, find, or check an openapi.json

Do not use it to pay for anything — it has no wallet and cannot. If the user wants to actually call a paid endpoint, that is a different tool.

How to run it

node scripts/x402.mjs inspect <url> [--method POST] [--body '{}'] [--json]
node scripts/x402.mjs openapi <url> [--no-compare] [--spec-url <url>] [--json]
node scripts/x402.mjs decode <base64-value>

Requires only Node 18+. Nothing to install — the engine is bundled in lib/.

Run both, by default

When someone points at an endpoint — "what does X cost?", "inspect X", "/x402-tools for X" — run inspect and then openapi, and report both. The 402 challenge and the spec answer different questions: the challenge is what the endpoint charges right now, the spec is what it documents about itself — its full parameter list, response schema, error codes, and agent-readable x-* metadata. Someone deciding whether to call an API needs both, and openapi also produces the spec-vs-live comparison, which exists only if you run it.

node scripts/x402.mjs inspect https://api.syraa.fun/bitcoin --method POST --body '{}'
node scripts/x402.mjs openapi https://api.syraa.fun/bitcoin

openapi takes the same URL as inspect — it walks up to the origin itself to search.

Skip the openapi run only when the question is narrowly about payment ("is it Solana?", "just the price") or when the user asked for inspect alone. If no spec is found, say so in one line and move on — a missing spec is a fact worth reporting, not a failure to hide.

Inspecting an endpoint

node scripts/x402.mjs inspect https://hash-hmac.underscoredone.com/hash --method POST --body '{}'

Most x402 endpoints only answer POST. A GET often returns 404 or 405 with no challenge at all. If a GET shows no x402, retry with --method POST --body '{}' before concluding the endpoint is not x402.

Output covers: the price both as real money and as the raw atomic number, each accepted network and token, the pay-to address, the settlement timeout, an example request and response where the endpoint publishes one, and any base64 headers decoded.

Reading a spec

node scripts/x402.mjs openapi https://hash-hmac.underscoredone.com

Accepts an origin, an endpoint URL, or a direct link to a spec. Given an origin it tries /openapi.json, /.well-known/openapi.json, /openapi.yaml, /docs/openapi.json, /swagger.json, and then the x-openapi-url in the live challenge.

By default it also probes the live endpoint and prints a side-by-side table. Pass --no-compare to skip that.

Decoding a header by hand

node scripts/x402.mjs decode eyJ4NDAyVmVyc2lvbiI6Miw...

Reading the output

Price. x402 quotes prices in the token's smallest unit. 10000 of a 6-decimal token is 0.01, not ten thousand. The tool shows both; quote the human figure to the user.

Version. v2 puts the challenge in the payment-required response header as base64, with an empty body. v1 puts it in the 402 response body as plain JSON. The tool reads both and says which it found.

Differences between spec and live. Shown as two columns with no "correct" side. A spec being older than the endpoint it describes is ordinary. Report the difference; do not tell the user their API is broken.

Unknown tokens. If the tool does not recognise a token, it first looks for a decimals the endpoint declared in that option's extra block. If it finds one it converts the price and says the figure is the endpoint's own claim rather than one checked against the token contract — pass that caveat along. A decimals in extra is ignored for tokens the tool does know, so a challenge cannot talk it into a wrong price.

With no table entry and no declared decimals, it shows the raw number and says why. Do not guess on its behalf — a wrong price is worse than no price. It never queries a blockchain.

Notes. The Notes section is observations, not faults. Pass them along in the same neutral register.

How much to report

Default to everything the tool returned. Report every field, not a summary of the interesting ones. The person running this is usually inspecting an endpoint precisely because they don't yet know which field matters — dropping one to be concise forces another round trip. So unless asked otherwise, pass along:

• price as both the human figure and the raw atomic number, with the token's decimals
• every accepted network and token, not just the first or the cheapest
• the pay-to address in full, never truncated
• the x402 version found and where it was found (header vs body)
• the settlement timeout, resource, scheme, and MIME type
• any example request and response the endpoint publishes
• every decoded header, the full Notes section, and the HTTP status

And from openapi, in the same detail:

• the API title, version, OpenAPI version, and which URL the spec was found at — including which candidate paths were tried before one resolved
• the full description and the contact block
• every server URL
• every operation: method, path, summary, operationId, the request body schema with each field's type, whether it is required, and its description, plus every documented response code with its meaning
• any example request and response bodies the spec carries
• every x-* metadata key in full — x-402, x-pricing, x-ai-instructions, x-guidance, x-keywords, x-category, x-provider, x-openapi-url, x-payment-accepts and any others. These are written for agents specifically; x-ai-instructions in particular often carries the calling rules that nothing else states. Do not summarise them away.
• every row of the spec-vs-live comparison table, including the rows that agree, and the line saying what was probed and what it returned

If no spec is found, report which paths were tried and that none resolved.

When a spec covers many operations. Some specs are gateway-wide — api.syraa.fun documents 35 operations for one endpoint you asked about. There, give the operation the user actually pointed at in full detail as above, then list every other operation compactly as method, path and summary — one line each. List all of them; a compact line is not the same as omitting it, and the reader needs to know what else the API offers. The x-* metadata and the comparison table stay in full either way.

Narrow the output only when the prompt actually narrows it — "just the price", "which networks?", "is it Solana?", "one line". Then answer that and stop. A specific question is a request for a specific answer, not a cue to dump the rest alongside it.

Two things that are not reasons to trim: length, and your own sense that a field is uninteresting. If the full output is long, give it structure — group it under headings or a table — rather than cutting it.

When the tool errors or returns nothing, report the failure verbatim, including the exact message and status. Sandbox egress blocks, 404s on GET-only endpoints, and unrecognised tokens are all more useful quoted than paraphrased.

Safety

The tool refuses private, loopback, link-local, and internal addresses, and re-checks where a hostname actually resolves — including after every redirect. If a URL is refused, that is deliberate; do not try to work around it.

x402 Tools by _done — https://underscoredone.com/x402-tools