grist.tools
x402 · usdc on base · 50 endpoints

Deterministic x402 APIs for agents. Every endpoint does one thing, does it the same way every time, and costs a fraction of a cent.

try it free: dns-lookup, no payment, no key
curl -X POST 'https://grist.tools/v1/dns-lookup' -H 'content-type: application/json' -d '{"domain":"example.com","types":["a","mx"]}'
200 OK
{
  "domain": "example.com",
  "types_requested": [
    "a",
    "mx"
  ],
  "records": [
    {
      "type": "a",
      "values": [
        {
          "address": "93.184.215.14",
          "ttl": 3600
        }
      ],
      "truncated": false,
      "resolution_error": null
    },
    {
      "type": "mx",
      "values": [
        {
          "exchange": "mail.example.com",
          "priority": 10
        }
      ],
      "truncated": false,
      "resolution_error": null
    }
  ],
  "queried_at": "2026-08-26T18:00:00.000Z"
}

01How a paid call works

1 the agent calls
POST /v1/archive-extract-file
content-type: application/json

{
  "url": "https://grist.tools/samples/archives/bundle.zip",
  "entry": "data/squares.csv"
}
GET /v1/archive-extract-file/schema - always free
2 it pays and repeats the call
402 Payment Required
payment-required: <this envelope, base64>
price
$0.003 USD Coin
network
Base
pay to
0x2C5d…F81C
deadline
111s
full envelope ↗

You need a wallet holding USDC on Base.

POST /v1/archive-extract-file
payment-signature: <signature>

200 OK
{
  "source_url": "https://grist.tools/samples/archives/bundle.zip",
  "kind": "zip",
  "entry_name": "data/squares.csv",
  "size": 31,
  "compression": "deflate",
  "crc32": "89761172",
  "sha256": "202663eb5661a93d557520ce47e40bb6ccdcd7fded543fca46592d2291e2c8cf",
  "content_base64": "bixzcXVhcmUKMSwxCjIsNAozLDkKNCwxNgo1LDI1Cg=="
}

The v1 header x-payment is still accepted.

You pay only for calls that succeed. Payment is verified before the work starts and settled after a 200. A rejected, failed or timed-out call costs nothing.

02Discovery

PathWhat it is
/openapi.jsonFull specification
/.well-known/x402Discovery manifest
/llms.txtFor crawlers
/index.jsonMachine catalogue
/v1/<name>/schemaAlways free

03Families

No.FamilyShelfEndpointsFrom
01Fetch & extractWeb7$0.002
02Feeds & site structureWeb5$0.002
03Domain, DNS & networkWeb5$0
04DocumentsDocuments14$0.005
05ImagesMedia8$0.003
06Audio & videoMedia7$0.003
07Archives & binaryMedia4$0.003

05Parts list

01 fetchFetch & extract

Web: Requires the network. · default $0.002 · ceiling 15 s
Endpoint
Description
Price
Timeout
html-clean-text
Fetches a web page and returns the article as clean text and markdown, with its declared metadata.
$0.002
12 s
http-headers
Returns the response headers, final status, redirect chain and a security-header grade for a URL, without downloading the body.
$0.002
8 s
link-extract
Fetches a web page and returns every link on it, resolved to absolute, each tagged with its rel, a nofollow flag and whether it stays on the same site.
$0.002
8 s
page-metadata
Fetches a page and returns its <head> metadata -- title, description, canonical, language, hreflang, favicon, Open Graph and Twitter cards -- with every URL resolved to absolute.
$0.002
8 s
structured-data-extract
Fetches a web page and returns its embedded machine-readable data -- JSON-LD, OpenGraph, microdata and meta tags -- plus a normalised merge across all four.
$0.002
8 s
url-to-markdown
Fetches a web page and returns the article as clean markdown, with its title, byline and final URL.
$0.002
12 s
url-unshorten
Follows a shortened or tracking URL to its real destination and returns every hop it went through.
$0.002
10 s

02 feedsFeeds & site structure

Web: Requires the network. · default $0.002 · ceiling 15 s
Endpoint
Description
Price
Timeout
feed-discover
Fetches a web page and returns the RSS, Atom and JSON feeds it declares in its <head>, as absolute URLs with their type and title.
$0.002
8 s
robots-check
Fetches robots.txt and answers whether a user agent may crawl a URL, showing the group, the winning rule and every rule that competed with it.
$0.002
8 s
rss-parse
Fetches an RSS, Atom or RSS 1.0 feed and returns its channel metadata and a normalised list of items -- id, title, link, summary, content, author, dates and categories -- with every date in ISO 8601 UTC.
$0.002
8 s
sitemap-parse
Parses a sitemap, a sitemap index or a bare origin into a flat, bounded list of URLs with lastmod, changefreq and priority.
$0.002
14 s
wellknown-fetch
Fetches and parses a domain's well-known files -- security.txt (RFC 9116), ads.txt and humans.txt -- returning typed fields, seller records and a cross-file summary in one call.
$0.002
12 s

03 domainDomain, DNS & network

Web: Requires the network. · default $0.002 · ceiling 15 s
Endpoint
Description
Price
Timeout
dns-lookupfree
DNS records for a domain (A, AAAA, MX, TXT, NS, CNAME, SOA, CAA) with their TTLs.
$0
5 s
email-validate
Validates an email address: syntax, MX records for its domain, and whether it is a disposable or role account.
$0.002
5 s
ip-info
Reverse DNS (PTR) and network ownership for an IP address or a domain.
$0.002
5 s
ssl-cert-info
Fetches the TLS certificate a host presents: issuer, subject, SAN list, validity window, days to expiry and the full chain.
$0.002
10 s
whois
Registration record for a domain over whois: registrar, creation/update/expiry dates, status codes and nameservers, with the raw response.
$0.002
12 s

04 documentsDocuments

Documents: Requires a heavy dependency. · default $0.005 · ceiling 60 s
Endpoint
Description
Price
Timeout
csv-to-json
Parses a CSV/TSV document into JSON rows, keyed by a header row or as arrays; the delimiter is auto-detected.
$0.005
30 s
docx-to-markdown
Converts a Word .docx to Markdown, surfacing anything that did not translate as warnings.
$0.005
40 s
epub-to-text
Extracts an EPUB’s reading-order text and Dublin Core metadata, chapter by chapter.
$0.005
45 s
html-to-pdf
Renders a web page or an inline HTML string to a PDF, returned base64-encoded with its page count.
$0.005
12 s
json-to-csv
Renders JSON objects as raw CSV with no spreadsheet formula protection; columns are inferred or given, nested values are JSON-encoded.
$0.005
30 s
markdown-to-pdf
Renders a Markdown document to a PDF, returned base64-encoded with its page count.
$0.005
12 s
ocr-image-to-text
Reads the text out of an image (scan, screenshot, photo) with Tesseract, returned with a mean confidence.
$0.005
45 s
pdf-merge
Concatenates 2–8 source PDFs, in order, into one PDF returned base64-encoded. Maximum output PDF size: 25 MiB before base64 encoding.
$0.005
45 s
pdf-metadata
Reads a PDF's page count, document-info fields, version and encryption flag without rendering it.
$0.005
25 s
pdf-split
Extracts a 1-indexed page selection (e.g. "1,3-4") from a PDF into one new PDF, returned base64-encoded. Maximum output PDF size: 25 MiB before base64 encoding.
$0.005
30 s
pdf-to-markdown
Converts a PDF to Markdown, inferring headings from font size (best-effort, not layout-perfect; no OCR).
$0.005
40 s
pdf-to-text
Extracts the text layer of a PDF, page by page, in reading order (no OCR).
$0.005
40 s
pptx-to-text
Extracts the slide text of a PowerPoint .pptx, slide by slide, in order (body text only, up to 1,000 slides).
$0.005
40 s
xlsx-to-json
Reads an Excel .xlsx into JSON rows, keyed by a header row or as arrays; dates become ISO strings. Archives are limited to 64 worksheets.
$0.005
40 s

05 imagesImages

Media: Requires a heavy dependency. · default $0.003 · ceiling 94 s
Endpoint
Description
Price
Timeout
color-palette-extract
Extracts an image's dominant colours as a small palette (hex, RGB and coverage fraction).
$0.003
60 s
favicon-extract
Discovers a page's favicons and returns the best one decoded to a normalised PNG with its size.
$0.003
45 s
image-compress
Re-encodes an image in its own format at a lower quality to shrink the file, keeping its dimensions.
$0.003
60 s
image-convert
Transcodes an image to PNG, JPEG or WebP at a chosen quality, returned base64-encoded.
$0.003
60 s
image-metadata
Reads an image's EXIF/ICC/IPTC/XMP metadata and can return a copy with all metadata stripped.
$0.003
30 s
image-probe
Reports an image's format and pixel dimensions from its header, without decoding the pixels.
$0.003
20 s
image-resize
Resizes an image to a target width/height under a chosen fit, returned base64-encoded.
$0.003
60 s
svg-to-png
Rasterises an SVG to a PNG at a chosen resolution, returned base64-encoded.
$0.003
60 s

06 avAudio & video

Media: Requires a heavy dependency. · default $0.003 · ceiling 94 s
Endpoint
Description
Price
Timeout
audio-convert
Transcodes an audio file between WAV, MP3, FLAC, AAC and Opus, with an optional bit rate and sample rate.
$0.003
94 s
audio-extract
Extracts the audio track from a video (or any container) and returns it in a chosen audio format.
$0.003
94 s
media-probe
Reads a media file's container, duration, bit rate and per-stream codec/resolution without decoding it.
$0.003
30 s
subtitle-convert
Converts a subtitle track between SubRip (.srt) and WebVTT (.vtt), normalising the cues.
$0.003
15 s
subtitle-extract
Extracts a text subtitle track from a media container (MKV, MP4, WebM) as SubRip or WebVTT.
$0.003
60 s
video-thumbnail
Grabs a single frame from a video at a chosen timestamp as a PNG or JPEG, optionally scaled to a width.
$0.003
60 s
waveform-data
Reduces an audio file to a fixed number of normalised waveform peaks for drawing, without shipping samples.
$0.003
90 s

07 archivesArchives & binary

Media: Requires a heavy dependency. · default $0.003 · ceiling 94 s
Endpoint
Description
Price
Timeout
archive-extract-file
Extracts one named entry from a remote zip, tar or tar.gz and returns its bytes (base64) with a sha256.
$0.003
90 s
archive-inspect
Lists the entries of a remote zip, tar or tar.gz (paths, sizes, compression and CRC) without extracting any of them.
$0.003
60 s
file-type-detect
Detects a remote file's true type from its magic bytes, returning the canonical extension and media type.
$0.003
30 s
remote-file-hash
Computes the sha256, sha1 or md5 digest of a remote file, buffered in memory under a size cap, for checksum verification.
$0.003
60 s

06Questions

When is a call charged?
The signed payment is checked first and settlement waits for the endpoint to return 200. If the input is refused, the handler errors or the deadline passes, nothing is settled.
Which calls are free?
Free to call, with no payment header: dns-lookup. Every other endpoint is paid per call, at the price printed in its row above.
What is the payment made in?
USDC on Base. The caller signs a transfer authorization and nothing moves until settlement; the 402 envelope names the network id and the token contract.
What does the deadline in the 402 cover?
The whole call: payment verification, the endpoint's own run and the settlement after it. It ismax_timeout_seconds in the envelope, so size the validity of the signed authorization from it.
Can the work succeed and the payment still fail?
Yes, at settlement. If the facilitator refuses the transfer, the answer is a new 402 and the output is held back; a retry with a valid payment runs the call again. If settlement ends with no clear answer, the response is 500 internal and the transfer may still land: check the authorization nonce on chain before signing a new one.
What if the service is restarting?
A call that finishes too close to a redeploy is not settled. It gets 503 upstream_unavailable with retry-after 5, and the retry can spend the same authorization.
Do I need an account or an API key?
No. There is no sign-up and no key to manage. Each request carries its own x402 payment, signed by the caller.
Is the output deterministic?
Given the same input, an endpoint applies the same processing on every call. Endpoints that read a URL or a DNS record return what the network holds at the moment of the call.
Can I read an input schema before paying?
Yes. GET /v1/<name>/schema returns the JSON schema of an endpoint's input at no cost, and every docs page prints it too.
Where are the machine-readable files?
They are listed under Discovery above. An OpenAPI client can start from /openapi.json; an x402 client can start from /.well-known/x402.