# Swift Bot Labs Toolbox

62 small, deterministic utility APIs behind one origin, paid per call with [x402](https://www.x402.org): DNS and e-mail security checks, web page to clean Markdown, EVM calldata and transaction decoding, x402 endpoint checks, IP/CIDR math, JSON and CSV, hashing, and unit, time zone and currency conversion.

No sign-up and no API key. Each call costs **$0.003 to $0.02 in USDC on Base**. Failed calls are not charged.

- Catalog: https://x402-toolbox.swiftbotlab.workers.dev/
- OpenAPI 3.1: https://x402-toolbox.swiftbotlab.workers.dev/openapi.json
- llms.txt: https://x402-toolbox.swiftbotlab.workers.dev/llms.txt
- MCP server (streamable HTTP): `https://x402-toolbox.swiftbotlab.workers.dev/mcp`

## How paying works

1. Call any tool. Without payment you get `402 Payment Required` and a `PAYMENT-REQUIRED` header (base64 JSON, x402 v2) with the price, the asset (USDC on Base, `eip155:8453`) and the pay-to address.
2. Your x402 client signs a USDC `transferWithAuthorization` (EIP-3009) for exactly that amount and retries with a `PAYMENT-SIGNATURE` header. The payer needs no ETH for gas.
3. The server verifies the payment, runs the tool and settles. The response is `{"ok": true, "tool": ..., "result": {...}, "payment": {...}}` with the settlement in `PAYMENT-RESPONSE`.

Input errors (HTTP 400), unreachable targets, upstream failures and timeouts return before settlement, so they cost nothing.

```bash
# see the price (free)
curl -i "https://x402-toolbox.swiftbotlab.workers.dev/v1/dns/mx?domain=example.com"
```

```js
// pay and call, with the official x402 client packages (Node)
import { wrapFetchWithPayment } from "@x402/fetch";   // plus an EVM signer from @x402/evm
const pay = wrapFetchWithPayment(fetch, client);
const res = await pay("https://x402-toolbox.swiftbotlab.workers.dev/v1/email/security?domain=example.com");
const { result, payment } = await res.json();
```

GET tools take query parameters (a JSON body on POST works too). POST tools take a JSON object body. `tools/pay.mjs` in this repo is a dependency-light reference payer (EIP-712 signing with `@noble/*`).

### MCP

`POST /mcp` speaks JSON-RPC over streamable HTTP (stateless, JSON responses). `initialize` and `tools/list` are free. `tools/call` follows the x402 MCP transport: without `params._meta["x402/payment"]` the result is `isError: true` with the `PaymentRequired` object in `structuredContent`; send the signed payment payload there and the settlement comes back in `result._meta["x402/payment-response"]`.

## Endpoints

`*` = required parameter. Full schemas and example results are in the [catalog](https://x402-toolbox.swiftbotlab.workers.dev/) and in `openapi.json`.

<!-- tools:start -->

### DNS & e-mail

| Endpoint | Price | What it does | Parameters |
|---|---|---|---|
| `GET /v1/dns/lookup` | $0.005 | DNS lookup for any record type over DNS-over-HTTPS | `name`*, `type` |
| `GET /v1/dns/mx` | $0.005 | Mail servers (MX) of a domain, sorted, with the mail provider | `domain`* |
| `GET /v1/dns/reverse` | $0.005 | Reverse DNS (PTR) for an IPv4 or IPv6 address, with forward confirmation | `ip`* |
| `GET /v1/dns/spf` | $0.008 | SPF record check: full include tree, DNS lookup count, problems | `domain`* |
| `GET /v1/dns/dmarc` | $0.005 | DMARC record check and parsed policy | `domain`* |
| `GET /v1/email/validate` | $0.005 | E-mail address check: syntax, MX, disposable, role, free provider, typos | `email`* |
| `GET /v1/email/security` | $0.02 | E-mail security audit of a domain: MX, SPF, DMARC, DKIM, MTA-STS, TLS-RPT, BIMI, grade | `domain`*, `dkimSelectors` |
| `GET /v1/domain/rdap` | $0.01 | Domain registration data (RDAP/WHOIS): registrar, created, expires, age, status | `domain`* |

### Web

| Endpoint | Price | What it does | Parameters |
|---|---|---|---|
| `GET /v1/web/extract` | $0.01 | Fetch a web page and return clean main text and Markdown plus title and metadata | `url`*, `format`, `mode`, `maxChars` |
| `GET /v1/web/metadata` | $0.008 | Page metadata for link previews and SEO: title, description, OpenGraph, Twitter card, JSON-LD, favicon | `url`* |
| `GET /v1/web/links` | $0.008 | All links on a page, absolute, de-duplicated, split into internal and external | `url`*, `filter`, `limit` |
| `GET /v1/web/headers` | $0.005 | HTTP status, response headers, redirect chain, timing and a security-header audit | `url`*, `method` |
| `GET /v1/web/robots` | $0.005 | Is a URL allowed for a crawler by robots.txt? Rules, crawl-delay and sitemaps | `url`*, `userAgent` |
| `GET /v1/web/sitemap` | $0.008 | Read a sitemap.xml (or a site's default sitemap): URLs with lastmod, child sitemaps | `url`*, `limit` |
| `POST /v1/html/extract` | $0.005 | Convert HTML you already have to clean text / Markdown and extract its metadata and links | `html`*, `baseUrl`, `format`, `mode`, `maxChars` |
| `GET /v1/url/parse` | $0.003 | Parse, normalize and clean a URL (components, query params, punycode, tracking params removed) | `url`* |

### EVM

| Endpoint | Price | What it does | Parameters |
|---|---|---|---|
| `GET /v1/evm/address` | $0.003 | Validate an EVM address and return its EIP-55 checksum form | `address`* |
| `GET /v1/evm/contract` | $0.005 | Is an address a contract or a wallet? Code size, EIP-1967 proxy implementation/admin/beacon, EIP-7702 delegation | `address`*, `chain` |
| `GET /v1/evm/selector` | $0.003 | Function selector and event topic for a Solidity signature | `signature`* |
| `GET /v1/evm/selector-lookup` | $0.005 | Reverse-lookup 4-byte function selectors and 32-byte event topics to signatures | `selectors`* |
| `POST /v1/evm/abi-encode` | $0.003 | ABI-encode values (or full calldata for a function signature) | `signature`, `types`, `values`* |
| `POST /v1/evm/abi-decode` | $0.003 | ABI-decode calldata, return data or log data with known types or a signature | `data`*, `signature`, `types` |
| `POST /v1/evm/calldata-decode` | $0.005 | Decode unknown transaction calldata: find the function signature and decode the arguments | `data`* |
| `GET /v1/evm/tx` | $0.01 | Explain an EVM transaction: status, fee, decoded method, ERC-20/721 transfers | `hash`*, `chain` |
| `GET /v1/evm/token` | $0.005 | ERC-20 token metadata: name, symbol, decimals, total supply (on-chain) | `address`*, `chain` |
| `GET /v1/evm/balance` | $0.005 | Native and ERC-20 balances of an address | `address`*, `chain`, `tokens` |
| `GET /v1/evm/gas` | $0.003 | Current gas price, base fee and priority fee on an EVM chain | `chain` |
| `GET /v1/evm/ens` | $0.005 | ENS: resolve a name to an address, or an address to its primary name (verified) | `name`, `address` |
| `GET /v1/evm/units` | $0.003 | Exact conversion between wei, gwei, ether or any token decimals | `value`*, `from`, `to` |
| `POST /v1/evm/verify-message` | $0.003 | Recover the signer of an EIP-191 personal_sign message and check it against an address | `message`*, `signature`*, `address`, `messageEncoding` |

### x402

| Endpoint | Price | What it does | Parameters |
|---|---|---|---|
| `GET /v1/x402/check` | $0.01 | Probe an x402 endpoint: alive? what does it charge, on which chain, to whom? Is its 402 valid? | `url`*, `method` |
| `GET /v1/x402/search` | $0.01 | Search the x402 Bazaar catalogs for paid APIs by keyword, with prices | `query`*, `network`, `maxPriceUsd`, `limit` |

### IP & CIDR

| Endpoint | Price | What it does | Parameters |
|---|---|---|---|
| `GET /v1/ip/info` | $0.003 | Parse and classify an IPv4/IPv6 address (private, loopback, CGNAT, documentation, ...) | `ip`* |
| `GET /v1/ip/cidr` | $0.003 | Subnet calculator for an IPv4/IPv6 CIDR block | `cidr`* |
| `POST /v1/ip/contains` | $0.003 | Which of these IPs fall inside which CIDR ranges (allowlist / blocklist check) | `cidrs`*, `ips`* |
| `GET /v1/ip/split` | $0.003 | Split a CIDR block into smaller subnets | `cidr`*, `newPrefix`*, `limit` |
| `POST /v1/ip/aggregate` | $0.003 | Merge / summarize a list of CIDRs into the smallest equivalent set | `cidrs`* |
| `GET /v1/ip/range` | $0.003 | Convert an IP range (start - end) to the minimal list of CIDR blocks | `start`*, `end`* |

### Data & text

| Endpoint | Price | What it does | Parameters |
|---|---|---|---|
| `POST /v1/json/validate` | $0.003 | Validate JSON data against a JSON Schema (draft 2020-12 / draft-07) | `schema`*, `data`*, `formats` |
| `POST /v1/json/format` | $0.003 | Parse, pretty-print, minify or canonicalize JSON (sorted keys); locate syntax errors | `json`*, `mode`, `indent`, `sortKeys` |
| `POST /v1/json/query` | $0.003 | Extract values from JSON with a JSON Pointer or a dotted path (a.b[0].c, items[*].id) | `json`*, `path`, `paths` |
| `POST /v1/json/diff` | $0.003 | Structural diff of two JSON documents as JSON-Patch-style operations | `a`*, `b`* |
| `POST /v1/csv/to-json` | $0.003 | CSV / TSV to JSON (RFC 4180 quoting, delimiter auto-detect, type inference) | `csv`*, `delimiter`, `header`, `inferTypes` |
| `POST /v1/json/to-csv` | $0.003 | JSON array of objects to CSV (nested objects flattened to dot.keys) | `json`*, `delimiter`, `flatten` |
| `POST /v1/text/stats` | $0.003 | Text statistics: words, sentences, reading time, readability, top keywords | `text`*, `top` |
| `POST /v1/text/diff` | $0.003 | Line diff of two texts as a unified diff with added/removed counts | `a`*, `b`*, `context` |
| `POST /v1/text/transform` | $0.003 | Slugify and case conversion (camel, snake, kebab, title, constant ...), trim, dedupe lines | `text`*, `op`* |

### Encode & hash

| Endpoint | Price | What it does | Parameters |
|---|---|---|---|
| `POST /v1/hash` | $0.003 | Hash text or bytes: SHA-1/2/3, Keccak-256, MD5, RIPEMD-160, BLAKE2/3 | `data`*, `inputEncoding`, `algorithm`, `outputEncoding` |
| `POST /v1/hmac` | $0.003 | HMAC (SHA-256/384/512/1, MD5), e.g. to check a webhook signature | `message`*, `key`*, `keyEncoding`, `algorithm`, `expected` |
| `POST /v1/encode` | $0.003 | Convert between UTF-8, hex, base64, base64url, base32, base58; URL and HTML escaping | `data`*, `from`, `to` |
| `GET /v1/uuid` | $0.003 | Generate UUIDs (v4 random, v7 time-ordered) or parse/validate one | `uuid`, `version`, `count` |
| `POST /v1/jwt/decode` | $0.003 | Decode a JWT and check its times; optionally verify an HS256/384/512 signature | `token`*, `secret`, `secretEncoding` |
| `GET /v1/random` | $0.003 | Cryptographically secure random bytes, tokens and passwords | `kind`, `length`, `encoding`, `symbols`, `count` |

### Convert

| Endpoint | Price | What it does | Parameters |
|---|---|---|---|
| `GET /v1/convert/units` | $0.003 | Convert between units: length, mass, volume, area, speed, time, data, pressure, energy, power, temperature, angle | `value`*, `from`*, `to`* |
| `GET /v1/time/convert` | $0.003 | Convert a time between time zones and formats (ISO, unix, RFC 2822), with DST-aware offsets | `time`, `from`, `to` |
| `GET /v1/time/diff` | $0.003 | Duration between two dates/times, calendar difference and business days | `start`*, `end`, `tz` |
| `GET /v1/cron/next` | $0.003 | Explain a cron expression and list its next run times in any time zone | `expression`*, `tz`, `count`, `from` |
| `GET /v1/color` | $0.003 | Colour conversion (hex, RGB, HSL) and WCAG contrast ratio between two colours | `color`*, `against` |
| `GET /v1/convert/currency` | $0.005 | Currency conversion with official ECB euro reference rates (30 fiat currencies) | `amount`, `from`*, `to`* |

### Validate & parse

| Endpoint | Price | What it does | Parameters |
|---|---|---|---|
| `GET /v1/semver` | $0.003 | Semantic versions: parse, compare, sort, and check against npm-style ranges | `versions`*, `range`, `compareTo` |
| `GET /v1/iban/validate` | $0.003 | Validate an IBAN: country length, mod-97 check digits, formatted output | `iban`* |
| `GET /v1/user-agent` | $0.003 | Parse a User-Agent: browser, engine, OS, device type, and known bots / AI crawlers | `ua`* |

<!-- tools:end -->

## Limits

- 120 price quotes and 60 paid calls per minute per IP.
- Request bodies up to 64 KB (1-2 MB for the hashing, text, JSON, CSV and HTML tools); query strings up to 16 KB.
- URL tools download at most 2 MB and give up after 12 seconds; each tool call has a 25 second ceiling.

## Security

- **Payment before work.** The payment is checked first (exact amount, pay-to, network, a validity window of at most 15 minutes, and a local check that the signature belongs to the payer), then the input is validated, then the USDC contract is asked whether the authorization is still unused, then the facilitator verifies it. Only then does the tool run, and the result is released only after settlement is confirmed. A used authorization is refused before any work.
- **No keys on the server.** The deployment only receives payments to a fixed address and holds no private key or secret.
- **SSRF protection.** User URLs must be `http`/`https` on ports 80, 443, 8080 or 8443, without credentials. Literal IPs and every DNS answer (A and AAAA) must be public unicast: private, loopback, link-local, CGNAT, multicast, documentation, NAT64, 6to4, Teredo and IPv4-mapped forms are refused. Redirects are followed by hand and every hop is checked again. Only GET and HEAD are sent, with no caller headers or cookies.
- **Fixed upstreams.** Everything else (DNS-over-HTTPS, public EVM RPCs, the signature database, ECB rates, IANA RDAP bootstrap, the facilitator and discovery catalogs) goes to a fixed allowlist of hosts, never following redirects.
- **Bounded work.** Every input has a size limit; the HTML parser is linear-time; the ABI decoder, CSV parser and diff are size-bounded; JSON Schema `pattern` runs on a linear-time matcher, so hostile regular expressions cannot stall the service; nothing user-supplied is ever evaluated as code.
- **Privacy.** Inputs are processed in memory and not stored. Logs hold the tool name, status, payer address and settlement hash only.

See [SECURITY.md](SECURITY.md) for the threat model and how to report a problem.

## Run it yourself

Cloudflare Workers, plain JavaScript, two pinned dependencies (`@noble/hashes`, `@noble/curves`).

```bash
npm ci --ignore-scripts
node test/run.mjs                    # offline suite (mocked network)
node test/live.mjs                   # live smoke test of the network tools (no payments)
npx wrangler dev                     # local
npx wrangler deploy --env test       # Base Sepolia twin (test USDC)
```

Set `PAY_TO` in `wrangler.toml` to your own receiving address before deploying.

## Contact

Bulk use, a tool you need, or a bug: [@SwiftBotLabsBot](https://t.me/SwiftBotLabsBot) on Telegram.

MIT License. Made by Swift Bot Labs.