x402 Paid API Starter

Turn a JSON endpoint into a 402-style paid API surface in minutes, then swap the demo gate for real x402 facilitator verification.

This starter is for developers building paid APIs for AI agents, dashboards, bounty feeds, data products, and small utility services. It ships with a zero-dependency Node.js server, a free preview endpoint, a paid endpoint, a .well-known/x402 discovery route, tests, and a static demo page.

Demo page: https://go165.github.io/x402-paid-api-starter/

Repository: https://github.com/go165/x402-paid-api-starter

Template: https://github.com/new?template_name=x402-paid-api-starter&template_owner=go165

Agent-readable summary: https://go165.github.io/x402-paid-api-starter/llms.txt

Static agent card: https://go165.github.io/x402-paid-api-starter/.well-known/agent.json

Why This Exists

x402 makes paid HTTP APIs possible without account setup, subscription screens, or long-lived API keys. The hard part for many builders is not the protocol idea; it is getting a small resource server shape running quickly:

• a free preview route buyers and agents can inspect,
• a paid route that returns 402 Payment Required,
• a discovery document that explains accepted network/payment settings,
• local tests that do not require a wallet or funded account,
• a clear replacement point for production x402 verification.

This repo keeps that first step small and inspectable.

What You Get

• Zero runtime dependencies: uses only Node.js built-ins.
• GET /v1/preview: free sample response.
• GET /v1/paid/data: full response gated by a demo X-Payment header.
• GET /.well-known/x402: machine-readable payment discovery shape.
• GET /.well-known/x402.json: discovery alias for directories that expect a JSON well-known path.
• GET /.well-known/agent.json: machine-readable service card for agent directories and autonomous buyers.
• GET /openapi.json: OpenAPI 3.1 contract for agents, docs, and API marketplaces.
• Hosted llms.txt and static agent card for LLM and directory discovery.
• payment-required and payment-response headers encoded for agent compatibility tests.
• Environment-driven price, network, asset, and pay-to settings.
• Optional DATA_FEED_URL adapter for turning a live JSON feed into the paid response.
• Node test coverage for config, filtering, and payment gate behavior.
• Cloudflare Worker example with matching routes and tests.
• Express production example using official x402 middleware.
• Static GitHub Pages demo for sharing the flow.

The included payment gate is intentionally a demo. Replace isPaymentSatisfied() with the official x402 middleware or facilitator verification before charging real users or agents.

Quick Start

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

Or start it directly as a package once published or installed from GitHub:

npx x402-paid-api-starter

Run it in Docker:

docker build -t x402-paid-api-starter .
docker run --rm -p 8787:8787 x402-paid-api-starter

Open another terminal:

curl http://localhost:8787/health
curl http://localhost:8787/.well-known/x402
curl http://localhost:8787/.well-known/x402.json
curl http://localhost:8787/.well-known/agent.json
curl http://localhost:8787/openapi.json
curl 'http://localhost:8787/v1/preview?tag=x402'
curl -i 'http://localhost:8787/v1/paid/data?min_score=80'
curl -H 'X-Payment: demo-paid' 'http://localhost:8787/v1/paid/data?min_score=80'

Decode a payment-required header while testing buyer integrations:

npm run decode:payment-required -- '<payment-required-header>'

Run a local buyer smoke test against a running server:

npm run smoke:buyer -- http://localhost:8787
SMOKE_QUERY='min_score=50&tag=mergework' npm run smoke:buyer -- http://localhost:8787

Run the Bounty Radar feed smoke when DATA_FEED_URL is configured:

DATA_FEED_URL=https://go165.github.io/bounty-radar/feed/latest.json npm start
BOUNTY_RADAR_QUERY='min_score=30&opportunity=quick-win&max_effort_score=30' npm run smoke:bounty-radar -- http://localhost:8787

To keep that contract checked in CI, copy examples/github-action-smoke.yml to .github/workflows/x402-paid-api-smoke.yml in your API repo.

To keep the live Bounty Radar feed adapter checked in CI, copy examples/github-action-bounty-radar-smoke.yml to .github/workflows/bounty-radar-paid-alert-smoke.yml.

Expected unauthenticated paid response:

HTTP/1.1 402 Payment Required
payment-required: <base64url-json>
content-type: application/json; charset=utf-8

Expected authenticated demo response:

{
  "paid": true,
  "count": 2,
  "items": [
    {
      "id": "base-usdc-bounty-feed",
      "title": "Base/USDC bounty feed",
      "score": 91,
      "tags": ["base", "usdc", "bounty"],
      "sample": true
    }
  ]
}

Configuration

Copy .env.example and adjust values:

Variable	Default	Purpose
PORT	8787	Local server port.
BASE_URL	http://localhost:8787	Public URL used in discovery and payment resources.
PAY_TO	zero address	Receiver wallet address for production settings.
NETWORK	eip155:84532	CAIP-2 network id. Use eip155:8453 for Base mainnet.
ASSET	USDC	Display asset for the payment requirement.
PRICE_USD	0.001	Price displayed in the requirement.
PAYMENT_TOKEN	demo-paid	Local-only demo header value.
BYPASS_PAYMENT	false	Set to true for local integration tests only.
DATA_FEED_URL	empty	Optional JSON feed with an items array. Use the Bounty Radar feed for a live paid alert API.
DATA_FEED_TTL_SECONDS	60	In-memory feed cache TTL.

Bounty Radar Feed Mode

Use the companion Bounty Radar feed as a real dataset for the paid route:

DATA_FEED_URL=https://go165.github.io/bounty-radar/feed/latest.json npm start
curl 'http://localhost:8787/v1/preview?opportunity=quick-win&max_effort_score=30'
curl -H 'X-Payment: demo-paid' 'http://localhost:8787/v1/paid/data?min_score=50&repo=ramimbo/mergework'

The adapter accepts any JSON document shaped like { "items": [...] }. Bounty Radar fields such as score, opportunity_class, effort_score, effort_signals, decision_notes, preset, repo, signals, labels, addresses, and url are normalized into paid API rows so teams can sell alert feeds, webhook inputs, or agent-readable bounty intelligence.

Feed mode supports the same agent-friendly filters on preview and paid routes:

Query	Purpose
min_score=50	Require a minimum payout-signal score.
opportunity=quick-win	Keep one Bounty Radar opportunity class.
max_effort_score=30	Prefer low-effort rows for fast agent execution.
tag=x402	Require a normalized tag from preset, signal, or label text.
repo=owner/name	Limit alerts to one GitHub repository.

The dedicated smoke command verifies the full buyer-visible flow against that feed mode: free preview, unpaid 402 challenge with payment-required, and paid demo response after X-Payment: demo-paid.

npm run smoke:bounty-radar -- http://localhost:8787

Production Integration Path

The production replacement point is deliberately small:

export function isPaymentSatisfied(request, config) {
  if (config.bypassPayment) return true;
  return request.headers['x-payment'] === config.paymentToken;
}

For a real paid service, replace that demo check with official x402 server verification, for example @x402/express plus a facilitator client. Keep the surrounding route shape: free preview, paid endpoint, discovery, and tests.

A production-oriented Express example is available in examples/express-x402. It uses @x402/express, @x402/core, and @x402/evm instead of the demo X-Payment header:

cd examples/express-x402
cp .env.example .env
npm install
npm start

Recommended production checklist:

• Use a facilitator that supports your target network and asset.
• Use Base Sepolia first, then Base mainnet after end-to-end settlement tests pass.
• Keep a free preview response so agents can discover value before payment.
• Log verification failures without storing payment secrets.
• Return clear 402 responses and avoid claiming payment success before settlement is verified.

Cloudflare Worker

The same API shape is available in examples/cloudflare-worker:

cp examples/cloudflare-worker/wrangler.toml.example examples/cloudflare-worker/wrangler.toml
cd examples/cloudflare-worker
npx wrangler deploy

The Worker example is designed for edge-hosted paid feeds and agent tools. It intentionally keeps the demo payment header separate from production settlement so teams can swap in real x402 verification without changing the route contract.

Opportunity Assessment

• TAM / audience: API builders, AI agent developers, data-feed operators, and open-source maintainers experimenting with paid endpoints and autonomous buyers.
• Differentiation: a minimal resource-server scaffold focused on the first runnable paid API shape, not a full marketplace, wallet app, or vendor-specific gateway.
• Star-worthy hook: developers can clone it, run it without keys, see the 402 flow, and replace one function when ready for real x402 verification.
• Monetization path: paid hosted feeds, usage-priced APIs, bounty alert feeds, webhook products, and x402-paid MCP/agent tools.
• 7-day demo feasibility: day-one local starter is complete; a hosted demo page is static, and production x402 middleware wiring can be added as the next focused example.

Use Cases

• Paid bounty alert feeds for coding agents.
• Base/USDC market, liquidation, or funding-rate signals.
• Paid GitHub repository intelligence endpoints.
• Lightweight paid MCP tool backends.
• Private data previews where the first row is free and the full response is paid.

Legal and Ethical Publishing Checklist

• Do not buy stars, trade stars, use fake accounts, or spam communities.
• Be explicit that this repo's default payment gate is a demo for local development.
• Share only in relevant x402, Base, API, and agent-builder communities where project links are welcome.
• Do not imply that demo headers are real onchain settlement.
• Include real examples, tests, and screenshots when submitting to awesome lists or newsletters.

Launch Plan

See docs/launch-plan.md for a non-spam publishing checklist and community-specific post drafts.

License

MIT