settlekit-express-paid-api
A runnable Express (TypeScript) example that sells API calls in USDC via
the x402 "HTTP 402 pay-per-call" protocol, using
@settlekit/x402.
GET /health— FREE liveness probe.GET /research— PAID. Gated behind a verified x402 payment of 0.005 USDC on thearcnetwork.
An unpaid request to /research returns HTTP 402 with machine-readable
payment requirements. The client pays USDC on-chain, then retries the request
with an X-Payment header carrying the proof. The server confirms the
settlement with the SettleKit API before serving the paid result.
How it works
@settlekit/x402 exposes withSettleKitPayment(config)(handler), where
handler is a web Fetch handler (Request -> Response). Express, however,
uses the classic (req, res) idiom. This example bridges the two with a small,
fully-implemented adapter (src/express-adapter.ts) that:
- Builds a web
Requestfrom the Expressreq— method, absolute URL, all headers (includingAuthorizationandX-Payment), and the request body. - Runs the wrapped Fetch handler.
- Copies the returned
Response(status, headers, body) back ontores.
GET /research ──▶ expressFromFetch( withSettleKitPayment({...})( researchHandler ) )
│ │ │
Express req x402 gate: paid result
⇄ web Request 402 challenge or (Request→Response)
⇄ web Response verify X-Payment
Payment verification lives in src/verify.ts: a real, fetch-based
PaymentVerifier that POSTs the proof + challenge requirements to a configurable
SettleKit verify endpoint. It never blanket-accepts — when no verify URL is
configured it honestly rejects every proof.
Files
| File | Purpose |
|---|---|
src/server.ts |
Express app: free /health, paid /research. |
src/express-adapter.ts |
Express (req,res) ⇄ web Request/Response adapter. |
src/verify.ts |
fetch-based SettleKit PaymentVerifier (honest rejection by default). |
src/x402.ts |
Re-exports the @settlekit/x402 API (see note below). |
Prerequisites
1. Build @settlekit/x402 first
This example imports the package by a relative path to its compiled output
(../../packages/x402/dist/index.js). The examples/ directory is not part of
the pnpm workspace, so a workspace:* dependency would not resolve here.
Build the package from the monorepo root:
pnpm --filter @settlekit/x402 build
Alternative — import
@settlekit/x402by name. If you add this example to the workspace (or install the published package), editsrc/x402.tsand change the import specifiers from"../../../packages/x402/dist/index.js"to"@settlekit/x402". Nothing else changes — every other file imports x402 throughsrc/x402.ts.
2. Install this example's dependencies
# from examples/express-paid-api
pnpm install # or: npm install
Configuration
Set via environment variables:
| Variable | Required | Default | Description |
|---|---|---|---|
PAY_TO |
yes | — | USDC destination address advertised in the 402 challenge. |
PORT |
no | 3000 |
Port to listen on. |
SETTLEKIT_API_URL |
no | — | SettleKit API base, e.g. http://localhost:8787. When set, the verifier POSTs to ${SETTLEKIT_API_URL}/v1/paid/research/verify. |
SETTLEKIT_API_KEY |
no | — | Bearer key sent as Authorization: Bearer <key> to the verify endpoint. |
Without
SETTLEKIT_API_URL(or an explicitverifyUrl), the verifier rejects every payment by design — it will not grant free access.
Run
export PAY_TO=0xYourUsdcDestinationAddress
export SETTLEKIT_API_URL=http://localhost:8787
export SETTLEKIT_API_KEY=sk_test_your_key
pnpm dev # tsx watch src/server.ts
# or
pnpm build && pnpm start
settlekit-express-paid-api listening on http://localhost:3000
FREE GET /health
PAID GET /research (0.005 USDC via x402, payTo=0xYour...)
Try it
Free route
curl -s http://localhost:3000/health
# {"data":{"status":"ok","service":"settlekit-express-paid-api","time":"..."}}
Paid route — step 1: get the 402 challenge
curl -i http://localhost:3000/research
HTTP/1.1 402 Payment Required
Content-Type: application/json; charset=utf-8
X-Payment-Required: {"scheme":"x402","amount":"0.005","asset":"USDC","network":"arc",...}
Accept-Payment: {"scheme":"x402",...}
{
"error": "payment_required",
"accepts": [
{
"scheme": "x402",
"amount": "0.005",
"asset": "USDC",
"network": "arc",
"payTo": "0xYour...",
"productId": "prod_research",
"resource": "http://localhost:3000/research",
"nonce": "…"
}
]
}
Paid route — step 2: pay USDC, then retry with X-PAYMENT
Pay 0.005 USDC on arc to payTo, echoing the challenge nonce. Build the
proof and base64-encode it:
// PaymentProof
{
"txHash": "0xabc123…",
"from": "0xYourWallet…",
"amount": "0.005",
"network": "arc",
"nonce": "<nonce from the 402 challenge>"
}
PROOF='{"txHash":"0xabc123","from":"0xYourWallet","amount":"0.005","network":"arc","nonce":"<nonce>"}'
HEADER=$(printf '%s' "$PROOF" | base64)
curl -s http://localhost:3000/research -H "X-PAYMENT: $HEADER"
On a verified payment you get the paid result:
{
"data": {
"productId": "prod_research",
"report": {
"title": "Market research: USDC pay-per-call APIs",
"summary": "This premium report was unlocked by a verified x402 USDC payment.",
"generatedAt": "…",
"findings": ["…"]
}
}
}
If verification fails (or is unconfigured), you get another 402 with a
reason explaining why — never a silent free pass.
Manifest — package.json
{
"name": "settlekit-express-paid-api",
"version": "0.1.0",
"private": true,
"type": "module",
"scripts": {
"build": "tsc",
"dev": "tsx watch src/server.ts",
"start": "node dist/server.js"
},
"dependencies": {
"express": "^4.19.2"
},
"devDependencies": {
"@types/express": "^4.17.21",
"@types/node": "^20.14.0",
"tsx": "^4.16.2",
"typescript": "^5.5.4"
}
}
@settlekit/x402 is consumed by relative path (see Prerequisites), so it is
not listed as an npm dependency here.