Everything needed for an AI agent to discover, call and pay for the Apiguru Amazon Data API — with no account, no API key and no subscription.
The existing backend is not modified by any of this. Not one line.
| Client | How |
|---|---|
| Claude Code | claude mcp add --transport http apiguru https://mcp.apiguru.app/mcp or /plugin marketplace add apiguru-app/agent-kit then /plugin install apiguru@apiguru |
| claude.ai, Claude Desktop, ChatGPT | add connector https://mcp.apiguru.app/account and sign in |
| Codex CLI | codex mcp add apiguru --url https://mcp.apiguru.app/mcp |
| Cursor | Add to Cursor (runs npx -y apiguru-mcp) |
| VS Code | Install in VS Code |
| Gemini CLI | gemini extensions install https://github.com/apiguru-app/agent-kit |
| Hermes, OpenClaw, any stdio client | npx -y apiguru-mcp (npm, Node only) or uvx apiguru-mcp (PyPI) |
| Skill only (any agent) | npx skills add apiguru-app/agent-kit or ClawHub apiguru-amazon-data |
The API is gated behind register → verify email → get key → top up. Every step assumes a human. Agents cannot do any of it, so agent traffic bounces off the front door.
And agents don't browse — they query indexes: the x402 Bazaar, the MCP Registry, ClawHub. Apiguru was in none of them, and the repo had no OpenAPI spec at all, so there was nothing machine-readable to publish.
agent ──► agent.apiguru.app/agent/v1/v2/product-details
│ ① free probes left for this IP? serve it (a 5xx hands the probe back)
│ ② payment header present? verify → serve → settle
│ ③ otherwise 402 + payment challenge
▼
a verified payment provisions a real `users` row for the payer wallet
and the request is forwarded with THAT account's API key
▼
apiguru_backend:8787 — existing @api_key_required + @billing_required
count usage, unchanged
▼
billable answer (2xx, or the 404 the backend bills)? settle on-chain,
write `agent_payments`. Anything else: `X-Payment-Status: not-settled`,
nothing charged.
Because the payer becomes an ordinary account, usage counters, per-second rate
limits, api_logs and the admin dashboard all work on agent traffic for free.
The payer's wallet address is the abuse-dedup identity, playing the role
canonical_email plays for human signups — and it is far harder to farm.
Settlement happens after the upstream call, in the x402 reference order. An
earlier version settled first, which charged agents real money for our own
503s and for their own 413s. The wallet's users.balance is never credited or
charged: the agent plan's internal rate is 0, so the backend can never block a
paid request on balance (its per-request counting — about 3 upstream requests
per ASIN on /stock — does not match the per-item quote).
agent-kit/
├─ spec/ SOURCE OF TRUTH
│ ├─ endpoints.json canonical: paths, schemas, prices, Bazaar copy
│ ├─ generate.py emits everything below from it
│ ├─ openapi.yaml/.json OpenAPI 3.1 (validated)
│ └─ llms.txt for agents crawling the site
├─ gateway/ keyless x402 paywall (Quart, port 8790)
├─ mcp/ MCP server, stdio + streamable HTTP (port 8791)
├─ npm/ `npx apiguru-mcp`: Node stdio bridge to the hosted server (no Python, no uv)
├─ skill/ SKILL.md in the Agent Skills open standard (canonical)
├─ plugin/ Claude Code plugin; plugin/apiguru/skills/ is a generated mirror of skill/
├─ .claude-plugin/ marketplace manifest
└─ deploy/ nginx, deploy script, distribution checklist
spec/endpoints.json is the only file describing the API. generate.py
writes the OpenAPI document, llms.txt, the MCP package's bundled copy, the
gateway's copy, and the skill's reference docs. They cannot drift.
python spec/generate.pyAdding an endpoint is one edit to endpoints.json plus that command.
| Component | What it gives you |
|---|---|
| Gateway | Keyless access + x402 payments + free probes + Bazaar metadata |
| MCP server | 11 tools for Claude Code, Codex CLI, OpenClaw, claude.ai, ChatGPT |
| Skill | One SKILL.md that runs in 20+ agents unmodified |
| Plugin | One-command install bundling the skill and MCP server (uvx apiguru-mcp) |
| npm bridge | npx -y apiguru-mcp for clients whose docs assume npx; Node 18+ is the only prerequisite |
| Spec | OpenAPI + llms.txt so crawling agents self-onboard |
# regenerate all derived artifacts
python spec/generate.py
# run the MCP server locally (no install; uvx fetches it from this repo)
uvx apiguru-mcp
uvx apiguru-mcp --http --port 8791
# deploy the gateway + MCP to server1
cp .env.agent.example .env.agent # fill in DATABASE_URL and X402_PAY_TO
./deploy/deploy.shpip install "x402[evm,extensions]" quart sqlalchemy aiosqlite httpx mcp
python tests/run_tests.pyNo network, no database, no wallet: pricing and item counting, spec drift (including the plugin's mirrored skill), MCP tool schemas and client-side validation, unforgeable client identity (including the hosted-MCP internal header), the free-probe budget and its refund on 5xx, 413 before challenge, 402 challenge structure, and the paid path end to end (verify → serve → settle, wallet provisioning, the revenue ledger, testnet tagging, and that an upstream failure leaves the payment unsettled).
deploy/deploy.sh runs the same suite on the server, in a throwaway
container, before it rebuilds anything.
| Gateway | https://agent.apiguru.app — Base mainnet, real USDC |
| MCP | https://mcp.apiguru.app/mcp — 11 tools |
| Receiving wallet | 0x766B4cc27333955BBb163a61e2B85aFa6e491422 |
| Facilitator | PayAI (no account, no company) |
| Free tier | 3 calls per client per 24h, then 402 |
Testnet settlement was proven end to end first — tx
0xa4812b6c…390a61.
Revert to testnet any time with ./deploy/go-mainnet.sh testnet.
Two things need you, not code:
- A receiving wallet.
X402_PAY_TOis just a self-custody wallet address — no company, no KYC, no account, about five minutes to create. You do not need Coinbase: the facilitator is swappable by config, and PayAI (https://facilitator.payai.network) runs on Base mainnet with no credentials at all. Coinbase CDP is worth it only for automatic x402 Bazaar listing. Seedeploy/PAYMENT-SETUP.md. - DNS. Done — both resolve and are grey-clouded (DNS only). Keep them
that way: Cloudflare's fixed 100s timeout is shorter than these Amazon
fetches, and it buffers SSE, which breaks MCP streamable HTTP. See
deploy/CLOUDFLARE.md.
Neither blocks the other four distribution channels — MCP Registry, ClawHub,
the plugin marketplace and llms.txt all ship without any payment rail. Run with
X402_ENABLED=false if you want to defer payments entirely.
Then work through deploy/DISTRIBUTION.md, which is ordered by leverage.
users.balance and subscription_plans.cost_per_request_cents are both in
dollars despite the column name (the Stripe webhook divides cents by 100
before adding to balance; the PAYG plan row is 0.0050 = $0.005/request).
A version of this kit read them as cents and credited $1.00 for a $0.01
payment. The full evidence is in gateway/money.py.
The gateway now stays out of users.balance altogether: the agent plan's
internal rate is 0, and revenue is recorded only in agent_payments, written
after on-chain settlement. Testnet settlements are tagged TESTNET in
detail and excluded from revenue by the admin dashboard.
The Stripe MPP rail emits correct WWW-Authenticate: Payment challenges and
parses credentials, but redemption is not implemented — Stripe's reference
flow uses a Node-first SDK with no verified Python equivalent. MPP_ENABLED
defaults to false and the gateway runs on x402 alone. See the note at the top
of gateway/mpp_rail.py.
This is a separate compose project that builds its own images. It never
touches the running apiguru containers. Do not run docker-compose down or
--force-recreate against the main stack on that host — the compose 1.29 +
Docker 27.x ContainerConfig bug leaves it unrecoverable.