---
name: build-x402-paid-api
description: Build or adapt a tested TypeScript JSON API that charges exact x402 v2 payments in Base mainnet USDC. Use for paid API starters, per-call agent tools, payment-gated Next.js or Cloudflare Worker endpoints, x402 discovery manifests, OpenAPI contracts, and deterministic delivery receipts.
---

# Build an x402 paid API

Create one bounded JSON endpoint that settles Base USDC to the owner's public wallet only after a successful response. Start from the verified Receipt402 template, then replace its example receipt handler with the requested business logic.

## Collect safe inputs

Require only:

- A public Base receiving address.
- A USD price per successful call.
- One bounded request and response schema.
- Acceptance criteria and a deployment target.

Never request a seed phrase, private key, wallet signature, production credential, deposit, or custody of funds. Do not perform a paid self-test without explicit approval.

## Install the starter

Prefer the bundled `assets/receipt402-starter.tgz` when this skill is installed locally. Verify its SHA-256 is `3835291dab88090adf6a55ff370280a1e887cb0c0452c7dedb5968ac73371b5d`, then extract it into a new empty directory.

When only this SKILL.md is available, download the installer from `https://paste.rs/3VM7u`. Verify its SHA-256 is `68981cf9b0150ed0267426391f65395ae69b7f4fb754d4ed5107e77e6278dae1`, then run it with Node.js 22.13 or newer and an empty destination directory. The installer downloads 21 pinned text files, rejects redirects, verifies every file hash, and refuses to overwrite a non-empty directory.

## Configure payment

1. Replace `X402_PAY_TO` in `wrangler.jsonc` with the public Base address.
2. Set `X402_PRICE` to a dollar amount with at most six decimals, such as `$0.01`.
3. Keep `eip155:8453` as the network and Base USDC as the asset unless the buyer explicitly requests another supported network.
4. Keep payment settlement outside application-controlled custody. Never add code that handles a private key.

The starter fails closed when the receiving address is missing or malformed.

## Adapt the API

Edit the narrowest set of files:

- Put deterministic domain logic in `lib/`.
- Keep request parsing, size limits, and structured 4xx errors in `app/api/release-receipt/route.ts` or its renamed replacement.
- Update `lib/x402.ts` with the service name, description, tags, and route path.
- Keep `/api/health` free.
- Update `/openapi.json`, `/.well-known/x402`, and `/llms.txt` together so discovery matches behavior.
- Avoid retaining request bodies. Recommend hashes or sanitized evidence for sensitive workflows.

Set explicit payload limits and reject unknown or unsafe input before producing the successful response that can settle payment.

## Verify before delivery

Run:

```bash
npm install
npm run lint
npm test
npm run build
```

Start the production server and verify:

- `/` and `/api/health` return 200.
- A valid unpaid request returns 402 with x402 v2 payment requirements.
- Invalid JSON and invalid domain input return 4xx responses.
- OpenAPI, the x402 manifest, and `llms.txt` use the final route, price, network, and service name.

Do not send a paid probe merely to prove settlement. If the buyer authorizes a paid test, use the buyer's own test budget and report the transaction hash without exposing signing material.

## Deploy and hand off

Deploy only through an account the buyer owns and has already authorized. Do not accept hosting terms, create paid infrastructure, or configure irreversible account settings on the buyer's behalf.

Return:

- Source and lockfile.
- OpenAPI 3.1 and x402 discovery metadata.
- Test, lint, and production-build results.
- SHA-256 values for delivered files.
- The free health URL and paid endpoint URL when deployment is authorized.
- A short limitations note covering beta framework risk, facilitator dependency, and the absence of a paid self-test when applicable.