API overview

API overview

Boon’s API is split along a product boundary, not a tier boundary.

• Free public reads back the hosted human UX — the board, profile pages, receipt verification, and policy. They are an implementation detail of the Boon web app, not a general-purpose public data API.
• x402-paid graph reads are the agent / app / indexer surface for structured gratitude-graph extraction. Anything chronological, per-handle, or graph-shaped is monetized by default.

Treat the free surface as “what the product UI needs to render itself” and the paid surface as “what an external system needs to build on Boon.” If you find yourself wanting a chronological feed, a per-handle boon list, or artifact-filtered edges, you are on the paid side of the boundary.

Base URLs

Surface	URL
App	https://boonprotocol.com
API	https://api.boonprotocol.com

Data units

USDC amounts are returned as decimal strings in base units, with 6 decimals. 2000000 means 2 USDC.

Points are scaled integers. The public policy endpoint reports pointScale: "1000". See x402 protocol → Boon Points model for the full scoring shape.

Public data surfaces

These endpoints back the hosted UX. They are stable but intentionally aggregate-only — there is no public chronological feed and no per-handle list on the free side.

Health

GET /health

Returns service readiness:

{ "ok": true, "service": "boon-worker", "version": "0.1.0" }

Points by handle

GET /api/v1/handles/:handle/points

Aggregate Boon Points for a canonical handle. Notable fields: points, decayedPoints, receivedPoints, sentPoints, sentPointsSource, boonsSent, boonsReceived, linkedWallet, policyVersion.

Profile by handle

GET /api/v1/handles/:handle/profile

The points envelope plus aggregate profile totals: totalReceived, pushedAmount, escrowedAmount, claimedAmount, totalSent, firstTipAt, lastTipAt. There is no per-boon list in this response — that is the paid surface.

Receipt by transaction hash

GET /api/v1/receipts/:txHash

One indexed boon receipt. This is how a sender or recipient verifies a known boon without a browsable public feed.

Board

GET /api/v1/board?limit=25

Top recipients, tippers, and aggregate stats for ranking. GET /api/leaderboard is retained as a compatibility alias.

Points policy

GET /api/v1/points/policy

The versioned scoring rules — same policyVersion value referenced from points and profile responses.

Sender disclosure

GET    /api/v1/boons/:txHash/disclosure
POST   /api/v1/boons/:txHash/disclosure
DELETE /api/v1/boons/:txHash/disclosure

GET is public and reads optional sender disclosure metadata for a known receipt. POST and DELETE require a sender EIP-712 signature and are verified against the indexed tipper for that receipt — see Authentication → Sender disclosure signatures.

Retired feed

GET /api/feed

The public feed is deliberately retired and returns gone/not-found with a replacement hint. Use aggregate endpoints for public reads, or the x402-paid per-handle list for chronological detail.

Paid graph surface

The paid surface is the agent / indexer product:

• per-handle boon list
• handle-centered gratitude graph
• repo / artifact-filtered graph
• batch graph queries
• suggested boon score

Unpaid requests return 402 Payment Required with a PAYMENT-REQUIRED challenge. See x402 paid endpoints for shapes and pricing, and x402 protocol for the header flow, networks, facilitators, security rules, points model, and deployment gates.

Privacy boundary

Boon’s free surfaces show aggregate reputation and receipt-level verification. Detailed graph, list, and edge data is intentionally behind x402 so that agents and apps pay for structured reads instead of getting a public feed by default. Do not add free endpoints that expose chronological who-paid-who data.