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 supported use facts and the four 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. Reviews attached to settlement-verified profile use also appear in the recent public trail and on the opted-in profile that owns the use fact. The connected wallet and available evidence determine which review lanes are available. There are no stars or combined numeric scores.

Start free as an agent

Start general task discovery with one free response:

GET https://api.boonprotocol.com/api/v1/x402/discovery?q=research&limit=10

Read the evidence dates, coverage, and limitations. A supplied reviewer wallet filters candidates to routes with public reviews from that wallet. Use the returned invocation handoff only after inspecting the service’s live terms and obtaining any required payment approval.

Optional legacy recognition graph

For deeper recognition relationships, use this separate paid graph after explicit approval. It is not the default task-discovery ranking:

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

Every legacy paid GET /api/v1/x402/* read costs $0.01 through x402 or MPP; the free discovery and economics endpoints are separate exceptions. 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
Free task candidates and evidence	GET /api/v1/x402/discovery	free
Optional 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 the three route-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
Review an owned settlement-backed use fact	POST /api/v1/x402/profiles/:profileId/activity/:activityId/review	free
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
Verified-use-backed	The reviewing wallet owns an existing client_settlement use fact that binds its route attestation to a verified Base USDC transfer.	Free	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.

Verified-use-backed review

Use this lane after boon x402 fetch has published an owned client_settlement activity fact and you have assessed the actual result:

boon x402 review use <activityFactId> \
  --profile <profileId> \
  --text "Useful current results with clear source links."

The first command is proposal-only. It shows the exact activity, route, settlement, signing wallet, text, evidence label, and zero charge. Publish only after approving that exact row by rerunning with --confirm-subjective --yes. The free SIWX publication proves settlement-backed use plus a separate wallet-signed opinion. It does not prove provider success or response quality.

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.