x402 paid endpoints

x402 paid endpoints

These endpoints require x402 V2 payment from every caller. The Boon SPA stays free because it only calls the public data surfaces — not because of an Origin allowlist. See x402 protocol for the full header flow, networks, facilitators, security rules, and deployment gates.

Base URL: https://api.boonprotocol.com

Launch pricing

Key	Route	Price
boons	GET /api/v1/handles/:handle/boons	$0.002
graph	GET /api/v1/graphs/gratitude?…	$0.005
queriesBase	POST /api/v1/graphs/queries	$0.01 base
queriesPerHandle	Additional batch handle	$0.002
score	POST /api/v1/score	$0.005

The queriesBase + queriesPerHandle combination lets a batch request across multiple canonical handles scale its price with the number of handles. The base paid route is not priced below $0.002 so the CDP facilitator’s per-transaction fee outside the monthly free tier does not push the route into negative margin.

Per-handle boon list

GET /api/v1/handles/:handle/boons?limit=50

Returns chronological detailed tips for a canonical recipient handle. Launch price: $0.002.

Gratitude graph

GET /api/v1/graphs/gratitude?handle=github:alice&limit=100
GET /api/v1/graphs/gratitude?repo=owner/repo&limit=100

Returns graph nodes and edges. Repo filtering is based on deterministic note markers until a future indexed artifact field exists. Launch price: $0.005.

Batch graph queries

POST /api/v1/graphs/queries
Content-Type: application/json

{ "handles": ["github:alice", "x:bob"], "limit": 100 }

Returns graph edges across up to 25 canonical handles. Pricing is the queriesBase $0.01 plus queriesPerHandle $0.002 per handle in the batch.

Suggested boon score

POST /api/v1/score
Content-Type: application/json

{
  "recipient": "github:alice",
  "tipper": "0x...",
  "amount": "5",
  "note": "pr:owner/repo#42 — review"
}

Returns a conservative suggested amount and rationale based on Boon Points and artifact-linked note context. Launch price: $0.005.

Unpaid request behavior

An unpaid request returns:

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <challenge>

The paid client signs the challenge and retries with PAYMENT-SIGNATURE. On success, the server returns PAYMENT-RESPONSE plus the JSON body.

Payment recipient

Production paid-route revenue settles to the Boon team Safe:

0x9eD16E6E1c0eA4f3739d1cF23041ed7aA782c08F

The funded live settlement smoke (pnpm --filter boon-worker run smoke:x402-live) remains the launch gate for production confidence. A challenge response alone is not proof that end-to-end paid settlement has been validated — see x402 protocol → Verification and deployment gates.