x402-books

x402-books

Agents buy clean, chaptered full-text public-domain books — OpenLibrary search, Gutenberg delivery, in-response. $0.001 to search, $0.01 for the whole book, in USDC on Base or Solana. The 200 body carries the entire text: licence boilerplate stripped, split into chapters, each chapter as markdown paragraphs with a word count.

Docs site: https://nirholas.github.io/x402-books/

Why x402 for this

The text is free; getting it in a usable shape is not. An agent that wants Frankenstein as clean chaptered markdown has to find the right edition, guess the right Gutenberg id, download a 450 KB fixed-width text file, strip a licence header, and write a chapter splitter — every time, for every book. This service does that work and charges a cent for it. x402 makes a one-cent product viable at all: no invoice, no seat, no minimum, no account for a buyer who may purchase exactly one book and never return. And because the artifact is the response body, there is nothing to fetch afterwards.

Quickstart

git clone https://github.com/nirholas/x402-books
cd x402-books
npm install
npm run dev            # http://localhost:4025 — no configuration needed

See the price with no wallet at all:

curl -s "http://localhost:4025/search?q=frankenstein&limit=2" | jq
# 402 + accepts: [ USDC on Base, USDC on Solana ]

Then buy it, from an agent (wallet funded with Base Sepolia USDC — https://faucet.circle.com):

PRIVATE_KEY=0xYourTestKey npm run client

API

Full reference: docs/api.md · openapi.json

How x402 works

Pay in USDC on Base or Solana — your client picks the rail.

1. 402 — the route, called without payment, replies HTTP 402 with an accepts array holding both rails: exact price ($0.001 → 1000 USDC base units), asset, and payTo.
2. Sign — on Base, the client signs an EIP-3009 USDC authorization (no gas from the payer). On Solana, it signs an SPL transferChecked whose fee payer is the facilitator's sponsor account (so the buyer needs USDC only, no SOL).
3. Settle — the server hands the payload to the facilitator (https://x402.org/facilitator), which verifies and settles on the chosen chain.
4. 200 — the same request returns the artifact in the body, with the settlement receipt in the X-PAYMENT-RESPONSE header.

Those are the suite's public receive addresses and the server's defaults. Set PAY_TO_ADDRESS / SOLANA_PAY_TO_ADDRESS to be paid yourself.

Walkthroughs: examples/curl.md · examples/agent-client.ts · docs/tutorial.md

Real backend / API keys

All variables: .env.example

For AI agents

• skill.md — agent-facing skill file: endpoints, prices, schemas, both payment rails. Point your agent at it.
• GET /.well-known/x402 — discovery manifest listing every resource with both networks. Indexable by x402scan.com, the x402 Bazaar, and agentic.market.
• MCP — examples/mcp-tool.md exposes these routes as Claude MCP tools, with per-wallet spend caps and a claude_desktop_config.json example.
• More: docs/agents.md

Docs

• Landing: https://nirholas.github.io/x402-books/
• Tutorial · API reference · For AI agents

Support

Questions, bugs, or a listing request: nichxbt@gmail.com · open an issue

License

Apache-2.0. Part of the x402 Suite.

Star History

Support the project

If x402-books saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.

Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit

Built for AI agents too

Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/x402-books and it has the context it needs.

More from the same author

• All repositories by nirholas: the full catalog, grouped by topic
• three.ws: the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments
• Questions or ideas: open an issue or start a discussion

Contributors