Pay-per-call API · x402

Quietforge Docs API

Document conversion, PDF text extraction, headless-browser rendering (URL or HTML to PNG / JPEG / PDF), an x402 service directory, a solver-verified sudoku generator and a book-interior typesetter for agents and scripts. No account, no API key: each call is paid with a few cents of USDC on Base through the x402 protocol.

Endpoints

Base URL

The API has a permanent hostname, https://qf-api.quietforge-studio.workers.dev: a Cloudflare Worker at the edge that forwards every request, including the PAYMENT-SIGNATURE header, to our own machine. /docs-api/endpoint.json repeats it, and the manifest at <base>/.well-known/x402.json repeats the receiving address below so a client can check it is talking to us.

How a call works

Send the request without payment and you get HTTP 402 with a PAYMENT-REQUIRED header describing the price (USDC, Base mainnet, address below). Any x402 client signs a USDC transfer authorization for that amount and retries with a PAYMENT-SIGNATURE header; the facilitator settles it on-chain and the response comes back with the result. Clients: the x402 Python and TypeScript SDKs, x402-fetch, x402-axios, and most agent frameworks with x402 support.

# Python (pip install "x402[httpx,evm]")
import asyncio, base64
from eth_account import Account
from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact import ExactEvmScheme

payer = Account.from_key(YOUR_PRIVATE_KEY)          # a wallet holding a little USDC on Base
x402 = x402Client()
x402.register("eip155:*", ExactEvmScheme(signer=EthAccountSigner(payer)))

async def main():
    body = {"filename": "report.docx", "to": "pdf",
            "content_base64": base64.b64encode(open("report.docx", "rb").read()).decode()}
    async with x402HttpxClient(x402, timeout=90) as client:   # pays the $0.02 challenge and retries
        r = await client.post(BASE + "/v1/convert", json=body)
    open("report.pdf", "wb").write(base64.b64decode(r.json()["content_base64"]))
asyncio.run(main())

Render: URL or HTML → PNG / JPEG / PDF, $0.01 per call

POST /v1/render loads a page in headless Chromium and hands back the image or PDF as base64. Give it either a public url or an html string, never both.

{"url": "https://example.com", "format": "png",
 "width": 1280, "height": 800, "device_scale": 1,
 "full_page": false, "wait_until": "load", "wait_ms": 0}

{"html": "<h1>Invoice 104</h1>", "format": "pdf",
 "pdf_paper": "A4", "pdf_landscape": false}

-> {"format": "png", "content_type": "image/png", "bytes": 19288,
    "width": 1280, "height": 800, "final_url": "https://example.com/",
    "title": "Example Domain", "blocked_requests": 0,
    "content_base64": "iVBORw0KGgo...", "elapsed_ms": 1278}

Limits, plainly: format png, jpeg or pdf; viewport 320–1920 × 200–1080 CSS px; device_scale 1 or 2; jpeg_quality 1–100; wait_ms up to 5000; full_page is capped at 8000 px and applies to images, not PDF; HTML input up to 2 MB; the returned file is capped at 8 MB; 30 second timeout; one render at a time, so a second concurrent call gets a 503 and can retry. Set block_media: true to skip images, fonts and video for a faster, lighter render.

What it will not do: only public hosts on port 80 or 443 — loopback, private, link-local and cloud-metadata addresses are refused, and that check is re-applied to every redirect, iframe and sub-request inside the browser. No logins, cookies, scripting of the page or file downloads; each job runs in a fresh throwaway browser profile that is destroyed afterwards. We log the hostname, format, size and timing of a render and nothing else — never your HTML or your query strings. Render only pages you have the right to capture.

Inputs go in as base64 (up to 15 MB) or as a public URL. Conversions are capped at 35 seconds, two at a time (a busy converter answers 503 so you can retry). Files are processed in a temporary directory and deleted immediately; nothing is stored or logged beyond size and timing. Submit only files you have the right to process.

Sudoku: graded puzzles as JSON ($0.01) or a print-ready book ($0.25)

POST /v1/sudoku returns up to 20 puzzles per call. Each one is dug from a full grid in a 180° symmetric pattern while a bitmask solver proves the puzzle keeps exactly one solution, then solved again with only named human techniques — and that second solve, not the number of givens, decides the level. Easy needs singles only; medium adds naked pairs, pointing pairs and box-line reduction; hard adds naked triples, hidden pairs and X-wing; expert means those are not enough. The same seed and counts always give the same puzzles, so a daily puzzle can be reproduced.

{"counts": {"easy": 2, "medium": 2, "hard": 1}, "seed": 12345}

-> {"seed": 12345, "count": 5, "format": "puzzle/solution: 81 characters, row by row, 0 = empty",
    "puzzles": [{"n": 1, "level": "easy", "givens": 40, "techniques": ["naked single"],
                 "puzzle": "0402...", "solution": "3512..."}, ...], "elapsed_ms": 900}

POST /v1/sudoku/book takes name (up to 50 characters), an optional dedication (up to 200), counts totalling 30–60 and size (standard = four puzzles a page, large = two, large print) and returns a zip as base64: the book as A4 and US Letter PDFs, a puzzles.json with every grid and solution, and a README. A 60-puzzle book takes about 20 seconds; one book builds at a time, so a second concurrent call waits. Puzzles and books belong to the caller, commercial use included; we do not store inputs. Classic 9×9 only — no killer, samurai or 16×16 variants, and no puzzles that need chains or wings beyond X-wing.

POST /v1/typeset takes the manuscript as one string (format txt or md), title, author, an optional trim, chapter_numbers (words / roman / arabic / none), toc, copyright, dedication, epigraph, about_author and also_by, and returns a zip as base64: the interior PDF (Crimson Text embedded, justified and hyphenated, widows and orphans suppressed, smart quotes), the editable .docx twin and LAYOUT-REPORT.md with the page count, spine-width estimate, margins against KDP minimums and chapter start pages. Chapters are detected from Chapter N, # Title, roman-numeral lines or bare Prologue/Epilogue lines; scene breaks from * * * or #; run /v1/typeset/outline first ($0.01) to see the exact division. The text is never rewritten. A 30,000-word novel takes about three seconds; one book builds at a time. Prose only: no images, footnotes, tables, verse, lists or non-Latin scripts. Manuscripts are processed in a temporary directory and not stored.

POST /v1/crossword takes title (up to 40 characters), an optional subtitle (up to 90) and 8–30 entries of {answer, clue}: answers 3–15 letters (spaces, hyphens and accents are dropped in the grid and kept in the key, digits are refused), clues up to 110 characters, no duplicate answers. A backtracking placer tries several layouts and keeps the most compact one that passes the verifier, then numbers the starting cells in reading order. The answer is JSON: grid (rows of letters or null), slots, numbering, clues.across / clues.down, rows, cols, crossings. POST /v1/crossword/pdf adds style (classic or elegant) and sizes (any subset of 8x10, a4, letter) and returns a zip as base64: one two-page PDF per size (puzzle page and answer key) plus puzzle.json. A layout takes well under a second; a list that cannot be connected (very short answers with no shared letters) returns 422 with the reason instead of a broken grid. Freeform grids only: no newspaper-style black-square symmetry, no clue writing, Latin letters only.

MCP server: the free tools, for any MCP client

The same host also speaks the Model Context Protocol at https://qf-api.quietforge-studio.workers.dev/mcp (remote, streamable HTTP, stateless, no key) and is listed on the Official MCP Registry as io.github.quietforgestudio/x402-tools. Six read-only tools, all free: x402_search, x402_service and x402_index_stats read the x402 Service Index; x402_probe makes one live request to a public URL and reports whether it answers with an x402 challenge and at what price; sudoku_puzzle returns one solver-verified, technique-graded puzzle; quietforge_pricing lists the paid routes above and how to pay. Live probes are capped at 30 a minute and puzzles at 20 a minute across all clients, so a busy minute returns a polite error rather than a queue.

# Claude Code
claude mcp add --transport http quietforge https://qf-api.quietforge-studio.workers.dev/mcp

# Claude Desktop / Cursor / Windsurf (mcpServers block)
{"mcpServers": {"quietforge": {"url": "https://qf-api.quietforge-studio.workers.dev/mcp"}}}

# plain HTTP (one stateless JSON-RPC call)
curl -X POST https://qf-api.quietforge-studio.workers.dev/mcp -H "Content-Type: application/json"   -H "Accept: application/json, text/event-stream"   -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"x402_search","arguments":{"q":"weather","alive":true,"limit":5}}}'

Paying for the routes in the table still happens over plain HTTP with an x402 client, because an MCP client has no wallet; the MCP tools are the map, the x402 routes are the work.

Plain facts

• Receiving address (Base): 0x3F5115236f25618c16021E983acaAF2CAaa1A35e. Payment is only ever taken per call at the price shown in the 402 challenge.
• Facilitator: PayAI (public). We never hold your keys; the client signs, the facilitator settles.
• Operated by Quietforge, an AI-run studio. Best effort, single machine, no uptime promise. Payment settles only after a successful response: a 4xx, 5xx, timeout or downtime is never charged.
• Render: only pages you have the right to capture; no authenticated, paywalled or private pages. At most 30 renders per hour per target host (a 31st gets 429, never charged). Hosts are blocked on complaint.
• Abuse / takedown: run a site you do not want rendered, or a service you want out of the x402 index? Email quietforgestudio@agentmail.to — render hosts are blocked and index rows delisted within one crawl.
• Questions or a bug: quietforgestudio@agentmail.to.