Coinwall

Self-hosted payment gateway for AI agents.
The payment layer for the agentic web — x402 protocol, USDC on Base, zero code changes.

中文

---

Preview

What is Coinwall?

Coinwall is a self-hosted payment gateway that uses the x402 HTTP protocol to let AI agents pay for APIs autonomously. Point it at your upstream service, set a price, and Coinwall handles the rest — issuing 402 Payment Required, verifying USDC authorizations, settling on-chain, and forwarding requests to your API. Agents encounter the 402, sign an ERC-3009 authorization offline, and retry — fully autonomous, no wallet pop-ups, no checkout page. Just HTTP with money built in.

Features

• AI-native — MCP server for Claude and Cursor, TypeScript SDK with budget controls, /x402 skill for one-command setup. Built for how AI actually works.
• Pay-per-call — Clients pay via standard HTTP headers. No sign-ups, no API keys, no checkout flows.
• Spending guardrails — Per-call, per-hour, and total budget limits baked into the SDK. Agents pay autonomously but never more than you allow.
• Any upstream — REST, GraphQL, webhooks — if it speaks HTTP, you can monetize it.
• 5 signing engines — API Key, Bearer, HMAC-SHA256, OAuth2, or custom JavaScript in a QuickJS WASM sandbox.
• Merchant dashboard — Real-time analytics, resource management, transaction history, and a live payment demo.
• Admin panel — Multi-tenant: merchants, networks, tokens, facilitator config, gateway resilience.
• Production ready — PostgreSQL + Redis, rate limiting, circuit breaker, async write queue.
• i18n — English + Chinese out of the box.

Quick Start

git clone https://github.com/anthropics/coinwall.git && cd coinwall
pnpm install
pnpm dev        # http://localhost:5173

First login: Visit /admin — the first wallet becomes the platform admin. Then /login to create a merchant.

How it Works

  Client ──── GET /x402/data ──────> Coinwall ──── GET /upstream ───> Your API
         <─── 402 Payment Required           <─── 200 + data ───────
         ──── GET + payment header ─>        ──── + signing headers ─>
         <─── 200 + response ───────         <─── response ──────────
                                        │
                                   x402 Facilitator
                                   (on-chain settlement)

One HTTP round-trip: 402 → pay → verified → forwarded → done.

Deploy

# Docker (PostgreSQL + Redis + Caddy HTTPS)
docker compose -f deploy/production/docker-compose.yml up -d

Railway deployment also available — see deploy/.

Documentation

• Architecture — Strategy pattern, request flow, signing engines, project structure
• Deploy Guide — Docker Compose (production), Railway
• Start the dev server and visit /docs for the full interactive documentation

Contributing

Contributions welcome. Please open an issue first.

pnpm test && pnpm test:e2e   # all tests must pass

License

MIT