# tx402 tools

> Free tools for the x402 payment protocol: see what an endpoint charges, verify a payment challenge before you sign it, test a spend policy, and debug a failed payment. Every result is available as JSON, as a plaintext Markdown report, or as an HTML page — the same computation, three renderings. Challenge decoding and policy evaluation here run `decodePaymentRequired` and `PolicyEngine` from the `tx402` SDK itself, so what these tools say about a challenge is what the SDK would do with it. Free, no account, no API key.

## How to call any of this

```
curl -H 'Accept: application/json' 'https://tools.tx402.io/inspect?url=https://an.example/paid'   # structured
curl -H 'Accept: text/markdown'   'https://tools.tx402.io/inspect?url=https://an.example/paid'   # report
curl                              'https://tools.tx402.io/inspect.md?url=https://an.example/paid' # same, no header
```

- `Accept: application/json` or the `/api/v1/…` path → the JSON envelope.
- `Accept: text/markdown`, a `.md` suffix, or `?format=md` → the plaintext report.
- `?format=` beats `Accept:`, so a link can pin one representation.
- Every negotiated response carries `Vary: Accept` and `Link: rel=alternate` for the other two.
- The Markdown report is a rendering of the same JSON. They cannot disagree.

## Tools

### 402 Inspector — What does this x402 endpoint charge?

- Page: [/inspect](https://tools.tx402.io/inspect)
- Call: `GET /api/v1/inspect?url=<https url>`
- Answers: x402 inspector, x402 endpoint price, what does this x402 API cost.
- Probes the endpoint once and returns terms, decoded challenge, per-check results and an observation band. Shared politeness cache: a repeat within the window returns the cached result with its age rather than re-probing somebody else's paid API.

### 402 Verify — Verify an x402 payment challenge

- Page: [/verify](https://tools.tx402.io/verify)
- Call: `POST /api/v1/verify  {challenge, url?}`
- Answers: verify x402 payment challenge, is this x402 challenge valid, x402 challenge checker.
- Static checks on a challenge you already hold. No probe, no network call to the endpoint. This is the one to call at the moment you are about to sign.

### 402 Policy Playground — Test an x402 spend policy against a real challenge

- Page: [/policy](https://tools.tx402.io/policy)
- Call: `POST /api/v1/policy/evaluate  {challenge, policy}`
- Answers: x402 spend limit, x402 budget policy, agent payment guardrails.
- Runs the real tx402 PolicyEngine and returns the allow/deny plus the exact typed error your own code would raise.

### 402 History — How has this x402 endpoint's price changed?

- Page: [/history](https://tools.tx402.io/history)
- Call: `GET /api/v1/history?url=<https url>`
- Answers: x402 price history, did this x402 API change its price, x402 endpoint uptime.
- Price, payout address, availability and latency over time, with every terms change dated. Answers NO_DATA honestly for an endpoint nobody has probed yet.

### 402 Compare — Compare x402 APIs side by side

- Page: [/compare](https://tools.tx402.io/compare)
- Call: `GET /api/v1/compare?category=<slug>  ·  GET /api/v1/categories`
- Answers: cheapest x402 API, compare x402 endpoints, best x402 geocoding API.
- Endpoints in one curated category, side by side. Refuses to rank rows scored under different score_versions rather than ranking them wrongly.

### 402 Replay — Why did my x402 payment fail?

- Page: [/replay](https://tools.tx402.io/replay)
- Call: `GET /replay  (UI)  ·  tx402-tools replay <trace>  (CLI, local)`
- Answers: x402 payment failed, x402 debugging, is it safe to retry an x402 payment.
- Reconstructs a failed payment lifecycle from a trace you already have. The trace stays on your machine unless you explicitly share a redacted one.

## Categories

Curated comparison pages, one per category. Membership is assigned from the facilitator's own
tags and the published set is a human decision with a written definition you can dispute.

- [ai-inference](https://tools.tx402.io/compare/ai-inference): x402 endpoints that run a model for you — LLM inference, embeddings, generation and agent tooling — compared on price per call, network and asset.
- [market-data](https://tools.tx402.io/compare/market-data): x402 endpoints serving prices, candles, open interest, funding rates and perpetuals data, compared on what one call costs and how long we have been watching them.
- [onchain-data](https://tools.tx402.io/compare/onchain-data): x402 endpoints that read a chain for you — balances, transactions, gas, wallets and RPC — compared on price per call, network and observed terms.
- [web-search](https://tools.tx402.io/compare/web-search): x402 endpoints that search, crawl or extract the web, compared on price per call — with an explicit gap wherever we have not observed an endpoint's terms yet.
- [social-data](https://tools.tx402.io/compare/social-data): x402 endpoints serving posts, profiles, repositories and sentiment from social platforms, compared on price per call and observed availability.
- [equities-finance](https://tools.tx402.io/compare/equities-finance): x402 endpoints covering equities, fundamentals, filings and macro data, compared on price per call and on how long each has been in our index.
- [identity-records](https://tools.tx402.io/compare/identity-records): x402 endpoints resolving identifiers, domains, registries and public records, compared on price per call — with explicit gaps where we have not looked yet.
- [security-risk](https://tools.tx402.io/compare/security-risk): x402 endpoints scoring addresses, contracts and counterparties, compared on price per call and on the observation window behind each figure.
- [geocoding](https://tools.tx402.io/compare/geocoding): x402 endpoints that turn an address into coordinates, coordinates into a place, or a point into a timezone — compared on price per call, with explicit gaps where we have not looked yet.
- [weather](https://tools.tx402.io/compare/weather): x402 endpoints serving forecasts and observations, compared on price per call and on how long each has been in our index.

Machine-readable index: [https://tools.tx402.io/api/v1/categories](https://tools.tx402.io/api/v1/categories)

## Without a browser

Two packages put these tools where the work happens. **Neither is released yet** — both names hold
a reserved `0.0.0` placeholder on npm, so the commands below are what will work at release and not
what works today. Until then, build them from the repository.

- [`tx402-tools`](https://github.com/neogeeks/tx402-tools/tree/main/packages/tools-cli) — the CLI.
  `inspect`, `verify`, `history`, `compare`, `replay`. It reaches `localhost` and private endpoints
  the hosted probe is forbidden from touching, and `verify` runs fully offline: zero network calls,
  asserted by a test that traps `fetch`, `XMLHttpRequest`, `WebSocket` and `EventSource`.
- [`tx402-tools-mcp`](https://github.com/neogeeks/tx402-tools/tree/main/packages/tools-mcp) — an MCP
  server over stdio exposing `inspect_endpoint` (asks this service) and `verify_challenge` (local,
  sends nothing). For an agent that is about to pay something, inside the client it already runs in.

The buyer SDK that actually pays is a different package and a different repository:
[`tx402`](https://www.npmjs.com/package/tx402) — non-custodial, operates no backend, and never
contacts this service. That separation is enforced, not asserted.

## Contracts

- [JSON Schemas](https://tools.tx402.io/api/v1/schemas): one per response type, JSON Schema 2020-12. The CLI and
  the MCP server validate against these before a character reaches a model; you can too.
- [Service metadata](https://tools.tx402.io/api/v1/meta): api_version, score_version, tx402_version, schema_version.
- [Error reference](https://tools.tx402.io/errors): every error code, its HTTP status, and whether retrying helps.
- [SPEC.md](https://github.com/neogeeks/tx402-tools/blob/main/spec/SPEC.md): the frozen contract.
- [Known facilitators](https://tools.tx402.io/api/v1/facilitators): each row with a dated source, so "known
  facilitator" is checkable by the person it is being claimed at.

## What this service will and will not do

- **It cannot pay.** No signer, no key material, and no payment signature header is constructed
  anywhere in this repository. CI greps for the shape of all three and fails the build.
- **It never returns an IP address, a cookie, a visitor identifier or a request signature.**
- **A LOW / MEDIUM / HIGH band describes how much of what we check we could confirm.** It is not a
  judgement about the operator of an endpoint, and it must not be quoted as one.
  Every signal, weight and threshold: [https://tools.tx402.io/methodology](https://tools.tx402.io/methodology).
- **Scores are only comparable within one `score_version`**, which every response carries.
- **An endpoint we have never seen returns NO_DATA**, not a low score. Unknown is not bad.
- **Operators can claim an endpoint, correct a fact, or opt out**: [https://tools.tx402.io/crawler](https://tools.tx402.io/crawler).
- Probes are rate-limited per target, not per caller, so a cached answer says `cached: true` and
  gives its age rather than pretending to be live.

## The rest of tx402

- [tx402.io](https://tx402.io): the buyer SDK — spend policy and budget committed before any signer
  is touched, for TypeScript and Python.
- [docs.tx402.io](https://docs.tx402.io): guides and reference. Every page has a `.md` mirror too.
  Most useful next to these tools: [the payment lifecycle](https://docs.tx402.io/guides/lifecycle/),
  [policy](https://docs.tx402.io/guides/policy/) and
  [the typed error taxonomy](https://docs.tx402.io/reference/errors/).
- [github.com/neogeeks/tx402-tools](https://github.com/neogeeks/tx402-tools): this service,
  Apache-2.0, including the scoring function and every weight in it.

## Machine-readable surfaces

- [Sitemap](https://tools.tx402.io/sitemap.xml)
- [Markdown homepage](https://tools.tx402.io/index.md)
- [Payment discovery manifest](https://tools.tx402.io/.well-known/x402.json): what this service charges, which is
  nothing — an empty `accepts`, stated in the format a payment client already parses.
- [Crawler policy](https://tools.tx402.io/robots.txt) · [Security contact](https://tools.tx402.io/.well-known/security.txt)