All endpoints live at https://agent402.tools (hosted instance) or your self-hosted root. Discovery endpoints are free and unpaywalled. Tool endpoints require payment (x402 or proof-of-work) unless FREE_MODE=true.

These are always free. No wallet, no PoW, no auth.

Resolve a natural-language task description to the best matching tool(s). Lexical ranking against the full catalog.

curl 'https://agent402.tools/api/find?q=convert%20pdf%20to%20text&k=3'

Returns an object, not a bare array:

{
  "query": "convert pdf to text",
  "count": 3,
  "results": [
    { "slug": "pdf-to-markdown", "name": "…", "route": "…", "price": "$0.010",
      "callExample": "…", "example": { }, "required": ["url"], "inputSchema": { },
      "category": "web", "description": "…", "score": 42,
      "computePayable": false, "docs": "https://agent402.tools/tools/pdf-to-markdown" }
  ],
  "packs": []
}

results holds the ranked tools; count is how many came back; packs holds any matching Skill Pack for the same query, so a task-shaped question can point at a whole workflow instead of one tool.

Cross-seller Smart Order Router. Finds the cheapest healthy tool for a task across Agent402 and every x402 seller crawled from the Coinbase CDP Bazaar.

curl -X POST https://agent402.tools/api/route \
  -H 'Content-Type: application/json' \
  -d '{"query":"screenshot webpage","top":3,"include":"external"}'

Full catalog: every tool with its price, category, input schema, and example input.

curl https://agent402.tools/api/pricing

Tools accept GET (query params) or POST (JSON body), depending on the tool. The catalog (/api/pricing, /openapi.json) specifies the method and schema for each.

Trust evidence for one x402 seller origin, so a buyer can vet a seller before routing money to it. Returns whether the origin is indexed, whether its manifest parses, how many tools it publishes, which chains it actually advertises, how many settled calls it has been observed receiving on-chain, and whether the Smart Order Router would spend buyer money there. The router's gate comes back field by field, so a refusal is explainable.

It never fetches the seller at call time: this is accumulated crawl and settlement evidence, not a liveness probe.

POST /api/sql-guard ($0.004) reviews one SQL statement an agent is about to run and returns a verdict (pass / warn / block) with the risks named; on pass it also returns an Ed25519 certificate binding that verdict to the SHA-256 of the exact statement. POST /api/sql-cert-verify ($0.001) is the gate your database layer calls before it obeys the agent, checking the signature, the version, the expiry, and that the statement hash matches. See Tool Catalog for the full behavior and the honest scope of the check.

Chat, embeddings, image generation, and text-to-speech are also served OpenAI-compatibly under /v1 - POST /v1/{nano,auto,pro,premium}/chat/completions, POST /v1/chat/completions, POST /v1/embeddings, POST /v1/images/generations, POST /v1/audio/speech, with GET /v1/models free. See LLM Gateway (OpenAI /v1) for tiers, the model-optional auto router, streaming, and caching. POST /api/route/execute runs the resolver's top pick in one paid call, and POST /api/my-usage returns the paying wallet's own purchase history.

curl 'https://agent402.tools/api/dns?name=example.com&type=A'

curl -X POST https://agent402.tools/api/hash \
  -H 'Content-Type: application/json' \
  -d '{"text":"hello world"}'

Successful responses return 200 with a JSON body. The shape varies by tool but is documented in each tool's inputSchema / example in the catalog.

1. Call a paid tool without payment.
2. Server responds 402 with a JSON body containing x402Version, accepts (array of payment options: price, network, asset, pay-to address).
3. Sign a USDC transferWithAuthorization from your wallet.
4. Retry the same request with the payment header (as specified by the x402 protocol).
5. The facilitator verifies and settles on-chain; the server returns the tool result.

# Step 1: see the quote
curl -i -X POST https://agent402.tools/api/hash \
  -H 'Content-Type: application/json' \
  -d '{"text":"hello"}'
# HTTP/2 402
# {"x402Version":2,"accepts":[{"price":"1000","network":"eip155:8453",...}]}

See Paying with x402 for full code examples in JavaScript and with Stripe's purl.

1. GET /api/pow/challenge?slug={tool} -- receive { challenge, difficulty, token, expiresAt }.
2. Find a nonce such that sha256(challenge + ":" + nonce) has at least difficulty leading zero bits.
3. Retry the tool request with header X-Pow-Solution: {token}:{nonce}.

# Get challenge
curl 'https://agent402.tools/api/pow/challenge?slug=hash'

# After solving, call the tool
curl -X POST https://agent402.tools/api/hash \
  -H 'Content-Type: application/json' \
  -H 'X-Pow-Solution: TOKEN:NONCE' \
  -d '{"text":"hello"}'

Challenges are single-use, short-lived, and scoped to exactly one slug. See Paying with Compute for a reference solver.

Send an Idempotency-Key header to enable idempotent requests. If the same key is seen again for the same method, path, and payment credential, the server replays the cached result without re-charging.

curl -X POST https://agent402.tools/api/hash \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: my-unique-key-123' \
  -H 'X-Pow-Solution: TOKEN:NONCE' \
  -d '{"text":"hello"}'

Cache key formula: sha256(METHOD + path + Idempotency-Key + gate-credential). Without the header, every request is treated as unique.

The cache is settlement-aware: a response body is captured when the handler produces it but is only committed to the cache once the final status is 200, i.e. after settlement succeeded. A 200 whose settlement then failed (and therefore became a 402) is never cached and never replayed. Streamed responses are never replayable.

All errors return a JSON body with an error string field.

{ "error": "description of what went wrong" }

Handlers throw errors with .statusCode set; the server maps these to the appropriate HTTP response.

Every code in the 4xx/5xx rows above cancels settlement, so none of them charge you. Only a 200 that then settles successfully is billed. See Architecture for the ordering.

• Tool Catalog -- what the 500+ tools are and how agents discover them
• Paying with x402 -- USDC payment flow with code examples
• Paying with Compute -- proof-of-work protocol and reference solver
• MCP Connector -- hosted connector and the agent402-mcp npm server
• Self-Hosting -- deploying on your own infrastructure