# x402 Paid API Starter

> Zero-dependency Node.js starter for testing a paid HTTP API shape with x402-style discovery, a free preview route, a 402 paid route, OpenAPI output, and a replaceable production verifier.

Repository: https://github.com/go165/x402-paid-api-starter
Demo: https://go165.github.io/x402-paid-api-starter/
Agent card: https://go165.github.io/x402-paid-api-starter/.well-known/agent.json
Screenshot: https://raw.githubusercontent.com/go165/x402-paid-api-starter/main/docs/screenshot.png

## What this project is for

- API builders who want a runnable preview-plus-paid endpoint before wiring wallet settlement.
- AI agent developers testing buyer flows around HTTP 402 and x402 discovery.
- Data-feed operators turning JSON feeds into paid alert APIs.
- Builders looking for a small replacement point for real facilitator verification.

## Local run

```bash
git clone https://github.com/go165/x402-paid-api-starter.git
cd x402-paid-api-starter
cp .env.example .env
npm test
npm start
```

Useful local routes:

- `GET /health`
- `GET /.well-known/x402`
- `GET /.well-known/x402.json`
- `GET /.well-known/agent.json`
- `GET /openapi.json`
- `GET /v1/preview`
- `GET /v1/paid/data`

The default payment gate is a local demo header, not production settlement. Replace `isPaymentSatisfied()` with official x402 middleware or facilitator verification before charging real buyers.

## Feed mode

Set `DATA_FEED_URL` to a JSON document shaped like `{ "items": [...] }` to wrap a live feed. The companion Bounty Radar feed works out of the box:

```bash
DATA_FEED_URL=https://go165.github.io/bounty-radar/feed/latest.json npm start
npm run smoke:bounty-radar -- http://localhost:8787
```

## Key files

- `src/server.js`: zero-dependency HTTP server and route contract.
- `src/openapi.js`: OpenAPI 3.1 document builder.
- `examples/express-x402`: production-oriented Express example using official x402 packages.
- `examples/cloudflare-worker`: edge deployment shape.
- `scripts/buyer-smoke.js`: buyer-side smoke test for preview, 402, and paid response.
- `docs/launch-plan.md`: ethical distribution plan and post draft.