x402 Graph

x402 Graph

Hosted API boundary: These pages document the public hosted API at api.boonprotocol.com, consumed by the open-source clients in this repository. The onchain Boon protocol itself requires no x402: the contract, EIP-712 vouchers, canonical handle rules, and USDC settlement are separate.

These endpoints require x402 or MPP payment. The Boon SPA uses separate compact website display routes, not an Origin bypass around the paid API. Recipient/tipper private reads are free after EIP-712 auth; third-party private-tip reveals are x402-paid. See x402 protocol for the full header flow, networks, facilitators, security rules, and deployment gates.

For the task-oriented path from endpoint discovery through review and optional routed recognition, start with Use the x402 route graph.

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

Resource discovery for agent ecosystems starts at GET /api/v1/acp/resources. That catalog separates free aggregate resources from these x402-paid graph resources so ACP/A2A clients can offer “Send a Boon?” recognition prompts without treating Boon as the job escrow layer.

For x402 endpoint discovery, start with the one-cent GET /api/v1/x402/graph?sort=reviewed&context=with&limit=20 relationship graph. Use the one-cent route directory when you only need compact candidates. Every official GET /api/v1/x402/* read has the same launch price. The gratitude graph below is for a known handle or repository.

Free planning and existence probes

Preview the declared Boon API cost of a multi-step workflow before requesting a paid resource:

POST /api/v1/workflows/cost-preview
Content-Type: application/json

{
  "requests": [
    { "method": "GET", "path": "/api/v1/x402/graph" },
    { "method": "GET", "path": "/api/v1/x402/routes/{routeId}" },
    { "method": "GET", "path": "/api/v1/x402/routes/{routeId}/reviews" }
  ]
}

This route is free and non-executing. It totals configured Boon API charges only. It does not include third-party endpoint charges, gratuity, BOON burns, gas, retries, pagination, or unlisted conditional branches.

Use GET /api/v1/handles/:handle/has-boons for a free lightweight aggregate probe across github:name, x:name, and agent:N. It returns only Boon existence booleans and received/sent counts. The existing free profile route also accepts all three canonical handle schemes.

Launch pricing

Key	Route	Price
boons	GET /api/v1/handles/:handle/boons	$0.01
graph	GET /api/v1/graphs/gratitude?…	$0.01
queriesBase	POST /api/v1/graphs/queries	$0.01
score	POST /api/v1/score	$0.01
x402Read	GET /api/v1/x402/*	$0.01
privateTipUnlock	GET /tips/:tipId without recipient/tipper auth	$1 USDC

Batch graph queries currently use a flat $0.01 launch price for the route, regardless of the number of requested handles within the public limit. Paid reads use a flat one-cent price so the CDP facilitator’s per-transaction fee outside the monthly free tier does not push any 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.01.

Gratitude graph

GET /api/v1/graphs/gratitude?subject=handle:github:alice&limit=100
GET /api/v1/graphs/gratitude?subject=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.01.

x402 endpoint graph

GET /api/v1/x402/graph?sort=reviewed&context=with&limit=20&eventLimit=200
GET /api/v1/x402/graph?q=Locus&sort=reviewed&context=with&limit=20&eventLimit=200

Returns bounded endpoint and wallet nodes plus routed recognition, signed review, and signed participant-description edges. Monetary fields are factual receipts. Direct related-party flags only compare wallet addresses and do not prove operator independence. Launch price: $0.01.

x402 route and review endpoints

The relationship graph is the agent starting point. The compact directory and route-scoped reads let a client inspect one endpoint without confusing endpoint discovery with the separate handle or repository gratitude graph.

Purpose	Endpoint	Price
Endpoint and wallet relationship graph	GET /api/v1/x402/graph	$0.01
Compact described-route directory	GET /api/v1/x402/routes	$0.01
One route with exact signed payloads	GET /api/v1/x402/routes/:routeId	$0.01
Routed recognition receipts	GET /api/v1/x402/routes/:routeId/recognitions	$0.01
All signed review evidence lanes	GET /api/v1/x402/routes/:routeId/reviews	$0.01
Routes reviewed by one wallet	GET /api/v1/x402/reviews?reviewer=0x...	$0.01
Self-reported review publication	POST /api/v1/x402/reviews/self-reported	$0.05
Receipt-verified review publication	POST /api/v1/x402/reviews/receipt-verified	$0.01
Boon-backed review publication	POST /api/v1/x402/reviews	no added API charge

Every review is a wallet-signed, subjective statement with no stars or numeric score and a 1000 UTF-8 byte limit. The API keeps three evidence lanes separate:

• Self-reported V3 proves only control of the signing wallet. It does not claim purchase or use, costs $0.05 to publish, and does not affect reviewed ordering.
• Receipt-verified V2 binds the review to the payer on an official signed x402 offer and receipt. It costs $0.01 to publish and does not affect reviewed ordering.
• Boon-backed V1 binds the review to the tipper from a cited routed Boon. That event already sent nonzero USDC and burned 100,000 $BOON, so review publication adds no API charge and this is the only lane used in reviewed ordering.

reviewSummary reports each lane separately. sort=reviewed orders routes by Boon-backed review count, distinct Boon-backed reviewers, USDC recognition, then recency. Self-reported and receipt-verified activity remains visible but does not change that order.

The human route page at https://boonprotocol.com/x402/routes/<routeId> provides a compact free display and a connected-wallet review composer. Programmatic reads return exact signed payloads through the paid API. See the route graph guide for the corresponding CLI flows and evidence boundaries.

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. Launch pricing is the flat queriesBase $0.01 route price.

Private-tip unlock

POST /tips/:tipId/auth-challenge
GET  /tips/:tipId

The original tipper and authorized recipient can read the private note/amount for free by signing the challenge from POST /tips/:tipId/auth-challenge and sending the auth headers on GET /tips/:tipId.

A third party that does not have recipient/tipper auth can call GET /tips/:tipId and satisfy the x402 challenge. The price is the immutable UNLOCK_PRICE_USDC() set on Boon (launched value: $1 USDC). Payment settles directly to the original tipper for that private tip (not to the Boon Safe).

Suggested boon score

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

{
  "recipient": "github:alice",
  "note": "Used the $0.10 x402 property endpoint for a useful decision check.",
  "serviceCostUsdc": "0.10"
}

Returns a deterministic conservative suggestion plus a component breakdown. Boon Points remain the baseline. Concrete artifact references and explicit service-cost context can adjust the score and suggested amount. A structured serviceCostUsdc value takes precedence over note parsing. The cited service cost is recognition context, not a fee, invoice, or repayment. Launch price: $0.01.

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 recipients

Graph/scoring paid-route revenue settles to the Boon team Safe:

0x9eD16E6E1c0eA4f3739d1cF23041ed7aA782c08F

Private-tip unlock revenue settles dynamically to the original tipper for that tip. The x402 challenge for /tips/:tipId should be read per response; do not assume the Safe is the recipient for private-tip unlocks.

A 402 challenge response alone is not proof that end-to-end paid settlement has been validated. See x402 protocol → Verifying a paid integration.