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 legacy 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 legacy paid GET /api/v1/x402/* read has the same launch price. Free /api/v1/x402/discovery and /api/v1/x402/economics are documented below. 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.

Evidence-led discovery and reports

Discovery contract: Confirm routes in the deployed OpenAPI catalog. Start with free discovery. Paid reports remain optional.

Start new task discovery with the free, bounded endpoint:

GET /api/v1/x402/discovery?q=<task>&limit=10&reviewer=<optional-wallet>

It returns candidates, match reasons, dated evidence, review context, price status, coverage, and an invocation handoff. It does not call a candidate, authorize payment, publish, or assign a quality score. Ordering uses task relevance, selected-reviewer evidence, and recency. Recognition amount, burn amount, and token balance never rank a candidate.

The read-only /mcp surface exposes free discovery and economics reads plus a remote, non-publishing review draft. It does not expose payment, signing, arbitrary URL fetches, publication, or monitoring.

For automatically written drafts, use boon_prepare_review or the free POST /api/v1/x402/review-prepare route. It accepts only a public routeId, outcome (response_received or request_failed), and schemaCheck (passed, failed, or not_checked). Unknown fields are rejected. Fixed text reports a technical observation, not proof of use or quality. It does not publish. Do not supply private route identifiers or invent observations.

The older boon_draft_review tool accepts free text and sends it to Boon; it is not a sanitizer. Keep private tasks, names, locations, logs, and request or response content out of both tools. Publishing separately can expose the signing wallet and linked profile even when the text has no personal details. Automatic sending is not available through these remote tools. The CLI supports a separately approved, wallet-bound policy for fixed, free review notes after future boon x402 fetch calls. See the agent skill for its limits and off switch.

Optional bounded reports keep caller-supplied baselines and provenance visible:

Report	Endpoint	Price
Compare candidates	POST /api/v1/x402/reports/compare	$0.01
Compare with a caller snapshot	POST /api/v1/x402/reports/changes	$0.01
Export a bounded report	POST /api/v1/x402/reports/export	$0.01

The compare report accepts the bounded query shape:

{
  "q": "search",
  "limit": 10
}

This is a request-shape example only. Do not execute a paid example automatically or treat its placeholder values as approval.

For a changes report, first save the entire actual response from GET /api/v1/x402/discovery, including its generated timestamp, query, candidate list, and coverage. Later send that complete response as baseline, using the same query, limit, and reviewer, with a later request timestamp. Never fabricate a baseline from a summary or hand-written example. The baseline is caller-supplied context, not an independently authenticated historical record. Boon keeps no historical ledger for this comparison and does not monitor for changes.

Compare returns a comparison matrix, not a quality winner. Export includes a contentDigest checksum for integrity checks. The digest is not a signature, identity proof, or authenticity guarantee.

The existing x402 or MPP middleware handles these charges. Read the live challenge for exact price, network, asset, and recipient. changes requires a discovery snapshot supplied by the caller. Missing or partial data cannot prove that an endpoint failed, a reviewer stopped using it, or one candidate is better. POST /api/v1/x402/review-draft is free and does not publish.

GET /api/v1/x402/economics is free and reports runtime payment recipients and the disabled experimental token-credit and buyback status. Credits are not sold, buybacks do not execute, and this route does not alter existing fixed burns.

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	Legacy paid 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
Three route-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
Review an owned settlement-backed use fact	POST /api/v1/x402/profiles/:profileId/activity/:activityId/review	free
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. Boon keeps four 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.
• Verified-use-backed activity review binds a free review to an existing client_settlement fact owned by the signing wallet in an opted-in profile. It proves settlement-backed use plus a separate subjective opinion, not provider success or response quality, 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, receipt-verified, and verified-use-backed 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

Payment recipients are runtime configuration, not a fixed documentation promise. Read GET /api/v1/x402/economics for the current recipient summary, then verify the exact payTo, price, network, and asset in the live PAYMENT-REQUIRED challenge for the route you are about to call. Never sign a cached recipient. Private-tip unlock revenue can settle dynamically to the original tipper for that tip.

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