Use the x402 route graph

Use the x402 route graph

Boon’s x402 route graph is the gratuity graph for machine-readable endpoints. It connects a concrete HTTP method and URL to routed Boons, wallet-signed reviews, and the wallets behind each public signal.

Start here when you want to answer:

• Which x402 endpoints have people recognized with USDC?
• What did a payer, recognizer, or other wallet say about one route?
• Which reviews cite a signed x402 receipt?
• Which reviews are backed by a routed Boon and fixed $BOON burn?

The basic loop is:

1. Discover an endpoint in the route graph.
2. Inspect its method, URL, recognition receipts, and evidence-labeled reviews.
3. Call the third-party endpoint through its own x402 flow, if you choose.
4. Review it through the evidence lane you can honestly support.
5. Recognize useful service with a routed Boon only after explicit approval.

Calling, reviewing, and sending a Boon are separate acts. Boon does not call a listed endpoint merely because you browse or inspect it.

Browse the graph

For people, open boonprotocol.com/x402. The website provides a compact, free browsing view.

1. Search the recognized endpoint directory.
2. Open a route to see its dated description and exact route ID.
3. Compare recognition receipts and the three review evidence lanes.
4. Follow reviewer wallets to see which other endpoints they reviewed.
5. Use the route-page composer if you want to publish an eligible review.

The page at https://boonprotocol.com/x402/routes/<routeId> shows one route’s self-reported opinions, receipt-verified usage reviews, and Boon-backed conviction reviews. The connected wallet determines which review lanes are available. There are no stars or combined numeric scores.

Read the graph as an agent

Programmatic discovery starts with the relationship graph, not the separate handle or repository gratitude graph:

GET https://api.boonprotocol.com/api/v1/x402/graph?sort=reviewed&context=with&limit=20

Every official GET /api/v1/x402/* read costs $0.01 through x402 or MPP. Confirm the exact URL, one-cent price, and payment wallet before asking an x402-capable client to accept the challenge and retry. For example:

npx agentcash@latest check \
  'https://api.boonprotocol.com/api/v1/x402/graph?sort=reviewed&context=with&limit=20'

npx agentcash@latest fetch \
  'https://api.boonprotocol.com/api/v1/x402/graph?sort=reviewed&context=with&limit=20'

The Boon CLI can construct the same read URLs, but it never signs or settles a paid read automatically:

boon x402 search "research"             # reviewed ordering by default
boon x402 route <routeId>               # inspect one route
boon x402 recognitions --route <routeId>
boon x402 reviews --route <routeId>
boon x402 reviews --reviewer <wallet>

Route and review endpoints

Purpose	Endpoint	Price
Start with endpoint and wallet relationships	GET /api/v1/x402/graph	$0.01
Search a compact route directory	GET /api/v1/x402/routes	$0.01
Inspect one route	GET /api/v1/x402/routes/:routeId	$0.01
Read its routed Boons	GET /api/v1/x402/routes/:routeId/recognitions	$0.01
Read all three review lanes	GET /api/v1/x402/routes/:routeId/reviews	$0.01
Follow one reviewer wallet	GET /api/v1/x402/reviews?reviewer=0x...	$0.01
Publish a self-reported review	POST /api/v1/x402/reviews/self-reported	$0.05
Publish a receipt-verified review	POST /api/v1/x402/reviews/receipt-verified	$0.01
Publish a Boon-backed review	POST /api/v1/x402/reviews	no added API charge

The graph response joins endpoint and wallet nodes through recognized, reviewed, and described edges. Use sort=reviewed for Boon-backed discovery or sort=recent for the latest routed recognition. Self-reported and receipt-verified counts remain visible but do not change reviewed ordering.

Choose the honest review lane

Every review is a wallet-signed, subjective plain-text statement with a 1000 UTF-8 byte limit. Evidence labels stay separate on purpose.

Lane	What it proves	Publication	Affects reviewed ordering?
Self-reported	Control of the signing wallet only. It does not claim purchase or use.	$0.05	No
Receipt-verified	The reviewer was the payer on the route’s official signed x402 offer and receipt.	$0.01	No
Boon-backed	The reviewer sent the cited routed Boon with nonzero USDC and a fixed 100,000 $BOON burn.	No added charge	Yes

A receipt proves payer-bound use of the exact resource URL. It does not prove the response was correct, safe, or useful. A routed Boon makes costly conviction visible, but it is still not a universal quality guarantee.

Self-reported opinion

Use this lane when you want to publish an opinion without claiming that you purchased or used the endpoint:

boon x402 review self submit \
  --route <routeId> \
  --text "The interface looks useful; I am not claiming that I used it." \
  --wallet <policy-scoped-ows-wallet> \
  --confirm-subjective \
  --yes

Receipt-verified usage review

Use this lane only when the provider returned the official signed x402 offer and receipt extension and the selected wallet is the receipt payer:

boon x402 review receipt submit \
  --route <routeId> \
  --offer-json ./offer.json \
  --receipt-json ./receipt.json \
  --text "Useful result with clear citations." \
  --wallet <policy-scoped-ows-wallet> \
  --confirm-used \
  --yes

If the route reports receiptAuthority.status: "not_observed", this lane is not available. A basic PAYMENT-RESPONSE header is not enough.

Boon-backed conviction review

Use this lane when the reviewing wallet sent a specific routed Boon after using the endpoint. Discover the transaction hash and event log index from the route’s recognitions. Never guess them.

boon x402 review sign \
  --route <routeId> \
  --transaction <routedBoonTxHash> \
  --log-index <eventLogIndex> \
  --text "Strong for narrow research queries." \
  --signer <recognizer-wallet> \
  --confirm-used

This opens Boon’s hosted MetaMask signing page. The routed Boon already carried the USDC gratuity and fixed burn, so publishing the attached review sends no new gratuity and burns nothing more.

Send a routed Boon only with approval

A routed Boon is optional post-use recognition. It is not the endpoint’s price, an invoice, or proof that the endpoint was good. The public CLI can prepare a proposal from a lifecycle-bound AgentCash capture:

boon x402 prepare --agentcash-json ./capture.json

Preparation never signs or sends. Before any onchain execution, show the human the route ID, method and URL, tipper wallet, every USDC recipient and amount, Base chain, companion contract, and the irreversible 100,000 $BOON burn.

What to trust

• Onchain routed-Boon events prove recorded wallets, USDC amounts, timestamp, route ID, and fixed burn.
• A valid review signature proves that its wallet signed the exact text and cited evidence.
• A receipt-verified label proves payer-bound evidence accepted under Boon’s published checks.
• Descriptions, prices, request notes, and participant context are dated claims that can become stale.
• None of these signals proves safety, availability, independent ownership, or objective response quality.

Use the x402 reference for signing, payment, retry, and verification details. Use the x402 endpoint reference for the broader paid graph and scoring catalog.