name: revertwtf-agent-api
description: Use revert.wtf safely from agents, tools, browsers, or integrations through bounded HTTP APIs, MCP tools, and lightweight package subpaths without downloading the full catalog into client bundles.
version: 0.1.0

revert.wtf Agent API Skill

Use this skill when an agent needs to explain an EVM/RPC/provider/wallet/AA/x402 error, resolve a selector, search the catalog, or integrate revert.wtf into a product.

Default Choice

• Prefer MCP when the agent runtime supports MCP.
• Prefer the website HTTP API when calling the hosted service from an agent or app backend.
• Prefer package subpaths for local code.
• Never import the full catalog-backed parser into browser/client bundles for one-off searches.

MCP Tools

Use bounded tools:

• explain_error for raw errors, traces, JSON strings, revert bytes, and x402 payloads.
• search_catalog for catalog discovery. It returns summaries with limit, offset, totalMatches, and hasMore.
• get_error only after search_catalog returns a specific id.
• lookup_selector for 4-byte selectors.
• decode_revert_data for raw revert bytes.
• explain_aa_error for AAxx and EntryPoint failures.
• search_blockscout_chains and get_blockscout_chain for Blockscout registry checks.

Do not request or construct an all-catalog dump. Page through summaries only when the user explicitly needs breadth.

Hosted HTTP API

POST JSON to the public web API from a server/agent context:

curl -s https://revert.wtf/api/explain \
  -H "content-type: application/json" \
  -d '{"raw":"{\"code\":-32000,\"message\":\"nonce too low\"}"}'

Useful endpoints:

• POST /api/explain with { "raw": "..." }
• POST /api/revert-decode with { "data": "0x...", "abiText": "[...]" }
• POST /api/aa-decode with { "raw": "AA23 reverted or OOG" }
• POST /api/selector with { "selector": "0x08c379a0" }
• POST /api/search with { "query": "AA23", "limit": 20, "offset": 0 }

Inputs are capped for parsing. Do not paste private keys, seed phrases, access tokens, unreleased exploit details, or personal data.

Use /api/search for discovery and /api/explain for a specific raw failure.
Search returns summaries; fetch or explain the selected item instead of asking
for broad payloads.

Package Imports

Use precise subpaths:

import { explain } from "@revertwtf/parser/explain"; // server/API path
import { decodeRevertData } from "@revertwtf/parser/decode";
import { describePanic } from "@revertwtf/catalog/panic";
import { listKnownAACodes } from "@revertwtf/aa/parse";
import { searchCatalog } from "@revertwtf/search"; // server-side SQLite FTS

Browser/client bundles should use small helpers or call an API route. Full-data surfaces such as @revertwtf/catalog, @revertwtf/parser/explain, and @revertwtf/aa/explain belong on a server/API boundary.

For browser apps, prefer the lightweight SDK:

import { createRevertClient } from "@revertwtf/client";

const revert = createRevertClient();
const result = await revert.searchCatalog({ query: "x402 payment required", limit: 5 });