API overview

API overview

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.

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

• Free evidence-led discovery gives people and agents bounded task candidates, dated review summaries and invocation handoffs. Free board, profile, receipt, and policy reads remain available too.
• Private-tip auth reads let the original tipper or recipient read their own details free after an EIP-712 challenge.
• Optional paid reports and legacy graph reads provide comparison maps, snapshot deltas, integrity-checkable exports, and detailed recognition history.
• Private-tip third-party unlocks cost $1 USDC, paid to the original tipper.

Token holdings do not gate discovery or make a review more authoritative. Service execution, report purchases, publication, and recognition remain separate decisions. Inspect the live payment challenge before any paid call.

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

Free evidence summaries serve both agents and the hosted app. Detailed per-handle recognition history remains on the separate paid routes.

The legacy recognition view remains available separately. Endpoint discovery shows participant-described method, URL, intended use, and fit beside the USDC recognition and fixed $BOON burn. Hash-only records remain available for explicit verification reads, but are not returned by discovery by default. This does not reopen the ordinary Boon feed or expose private tips.

Free evidence-led x402 discovery

Discovery contract: Check the live OpenAPI catalog before choosing a route. Free discovery does not require a wallet or payment.

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

This free, bounded front door returns task-matched candidates, dated evidence, review context, price status, coverage, and an invocation handoff. Use limit from 1 through 20. Unknown prices remain null. Discovery does not call a listed endpoint, authorize payment, publish a review, or grant an endpoint a quality score. Ordering uses task relevance, selected-reviewer evidence, and recency, never recognition amount, burn amount, or token balance. Missing or unavailable coverage is not a successful empty result.

Discovery response change in API 0.8.0

Discovery snapshots, candidates, and reports omit the former generated limitations fields. Price status, dates, evidence labels, source availability, and invocation approval requirements are unchanged. Saved version-1 report baselines may still include the old fields; the API accepts bounded legacy arrays for compatibility but never returns them. Clients that required these fields must update their response validators.

The read-only /mcp surface exposes free discovery and economics reads plus a remote, non-publishing review draft. It does not sign, pay, fetch arbitrary URLs, publish, or monitor.

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.

The following optional report routes preserve the caller’s supplied baseline and provenance. Each costs $0.01 through the existing x402 or MPP middleware; read the live challenge before payment:

POST /api/v1/x402/reports/compare
POST /api/v1/x402/reports/changes
POST /api/v1/x402/reports/export

changes requires a prior discovery snapshot supplied by the caller. Reports must not infer endpoint failure, reviewer abandonment, or comparative quality from missing or partial data. POST /api/v1/x402/review-draft is free and non-publishing. Compare returns a comparison matrix, not a quality winner. Export may include a contentDigest checksum for integrity checks, not a signature, identity proof, or authenticity guarantee. Changes does not create a historical ledger or active monitoring. GET /api/v1/x402/economics is free and reports runtime payment recipients plus the explicitly disabled token-credit and buyback experiments. Credits are not sold, buybacks do not execute, and existing fixed burns are unchanged.

Health

GET /health

Returns API readiness:

{ "ok": true, "version": "<current>" }

(The exact response may include additional diagnostic fields and can change across releases.)

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.

Lightweight Boon existence probe

GET /api/v1/handles/:handle/has-boons

Free aggregate booleans and received/sent counts for github:name, x:name, or agent:N. It does not reveal identities, amounts, notes, or chronology.

Wallet handle links

GET /api/site/link/wallet?address=0x...

Free, rate-limited reverse lookup: which handle(s) resolve to a wallet. It requires a checksummed address and returns the linked identities across the active Boon contract version:

{
  "version": "<contract version>",
  "address": "0x...",
  "handles": ["github:name", "x:name"],
  "accounts": [
    {
      "handle": "github:name",
      "provider": "github",
      "profileUrl": "https://github.com/name",
      "verification": "boon_oauth_link",
      "linkedWallet": "0x..."
    }
  ]
}

Each account carries its provider (github, x, or agent), a profileUrl, and a verification of boon_oauth_link (an OAuth-approved handle-to-wallet link) or erc8004_indexed_at_recognition (an indexed agent:N owner at recognition time). This is the read side of the on-chain identity link; it moves no funds and does not reveal private tips.

Discover x402 endpoints

GET /api/site/x402/discover
GET /api/site/x402/discover?q=<text>

Free, rate-limited discovery across the broader x402 network (Coinbase’s CDP Bazaar), not only Boon-recognized routes. With no query it browses a page of live x402 endpoints; with ?q=<text> it searches full-text. Each endpoint returns its URL, method, description, service name, and price. Use it to find any x402 endpoint by capability, then recognize or review it once you have used it. The paid /api/v1/x402/graph remains the canonical read for Boon-recognized routes and their recognition and review evidence. The boon discover CLI command wraps this read.

Provider endpoint candidates for a wallet

GET /api/site/x402/wallet-endpoints?wallet=0x...

Free, rate-limited lookup of x402 endpoint candidates matched by the provider payout address a wallet sent USDC to. Because one payout address can be a shared treasury for many sibling routes, the response is provider-level and reports matchLevel: "provider_candidate". It does not prove that the wallet used any listed route and never creates a verified used edge. Requires a checksummed wallet.

x402 multi-wallet discovery profiles

An x402 wallet profile lets one controller group several independently controlled Base wallets without claiming that the controller owns their keys. A new profile starts private. Linking a wallet requires two signatures over the same immutable intent:

1. the profile controller accepts the exact wallet, profile, chain, policy, and expiry; and
2. the member wallet proves control of its own key and consents to that same relationship.

The member confirmation uses SIWX and moves no funds. For example, MetaMask can control the profile while an AgentCash wallet signs its own confirmation. The proof means that both wallets consented to the link. It does not mean that the MetaMask wallet can spend from the AgentCash wallet.

Phase 1 permits at most eight active wallets per profile, including the controller. A pending member link expires after five minutes, is then reported as expired, and is pruned seven days after expiry.

The controller flow lives at https://boonprotocol.com/x402/profile. An opted-in profile is browsable at https://boonprotocol.com/x402/profiles/<profileId>.

Identity-only operations use SIGN-IN-WITH-X, carry OpenAPI security: [{ "siwx": [] }], and have no x402 price:

POST   /api/v1/x402/profiles
GET    /api/v1/x402/profiles/:profileId
POST   /api/v1/x402/profiles/:profileId/wallet-links
GET    /api/v1/x402/profiles/:profileId/wallet-links/:linkId
POST   /api/v1/x402/profiles/:profileId/wallet-links/:linkId/confirm
DELETE /api/v1/x402/profiles/:profileId/wallet-links/:accountId
GET    /api/v1/x402/profiles/:profileId/discovery/preview
PUT    /api/v1/x402/profiles/:profileId/discovery
POST   /api/v1/x402/profiles/:profileId/activity

Discovery has two modes:

• private keeps the profile aggregation out of public discovery.
• public_all publishes every active linked wallet and every supported x402 activity fact currently known to Boon while discovery remains on. The controller signs a fresh public scope preview before enabling it. That preview lists exact wallet IDs and fact-category counts, not row-by-row routes, amounts, transactions, or review details. The signature gives blanket consent to every current and future supported verified x402 fact while discovery remains on. A wallet linked later must consent to the current public policy and appears immediately after activation.

A non-controller wallet linked while the profile was private has consented only to the private policy and blocks later publication. To make that wallet public, revoke the private link, enable public_all from a fresh controller-only preview, then create a new link that the member confirms under the public policy. Boon’s web flow enforces this order.

Returning a profile to private does not require the canonical review and recognition activity loader to be available. The controller can always stop future Boon profile discovery with a valid fresh SIWX proof.

public_all does not import or publish arbitrary token history. A generic USDC transfer can establish a paid_settlement fact, but it cannot identify a route. A used fact requires route-bound evidence such as a valid signed receipt. Existing signed reviews remain reviewed, and routed Boons remain recognized. These are facts, not a trust score. Wallet count, spend, and profile activity do not change route ranking.

Public reads are available only for opted-in profiles:

GET /api/site/x402/profiles/:profileId
GET /api/site/x402/profiles/by-wallet/:accountId

Complete paginated activity is a one-cent x402 or MPP read:

GET /api/v1/x402/profiles/:profileId/activity
GET /api/v1/x402/profiles/by-wallet/:accountId/activity

Phase 1 supports Base EVM accounts (eip155:8453), including AgentCash SIWX confirmation. Boon can publish only evidence it verifies, including evidence that an authorized linked wallet explicitly imports. It cannot bulk-export a wallet’s complete AgentCash history, and it does not infer route use from shared provider payout addresses.

Client-side discovery surfaces

Two CLI surfaces build on the free discovery read above; neither adds a Boon API endpoint, and neither moves funds.

• boon discover [query] wraps GET /api/site/x402/discover (browse or search) and GET /api/site/x402/wallet-endpoints (--wallet).
• boon suggest personalizes discovery. It mines the operator’s local coding-harness session history (Claude Code, Codex, Pi, Grok), derives recurring use-cases, and returns one ranked shortlist of aligned endpoints. It is read-only and local: only the derived capability keywords are sent to GET /api/site/x402/discover; prompt text, paths, and filenames never leave the machine. boon suggest --for "<task>" is a one-shot task match that reads no history.
• boon scout is the persistent form. A local engine keeps a sqlite + vector store of the operator’s use-cases and a bounded daily scan of the x402 catalog (read directly from the Coinbase CDP Bazaar). A normal sync scans the first 40 pages, up to 4,000 entries, and reports whether coverage was bounded or complete. Run the engine with --max-pages 250 for the full roughly 25,000-entry scan. Scout then surfaces, in three lanes, the best endpoints for recurring work, newly-listed endpoints, and new capabilities the network is investing in that the history does not cover. boon scout adopt <n> wires a chosen endpoint into the operator’s tooling via agentcash add <origin>. It reads the same free surfaces plus the public Bazaar; it never calls a listed endpoint or authorizes payment. Every result is a candidate to inspect before use.

Discovery, in every form, is invitation not authorization: a listing or a match is never proof an endpoint works, is safe, or should be paid.

Workflow cost preview

POST /api/v1/workflows/cost-preview

Free static planning for up to 25 declared Boon API steps. The response totals configured Boon API charges without executing calls or requesting payment. It explicitly excludes third-party endpoint charges, gratuity, BOON burns, gas, retries, pagination, and unlisted branches.

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.

x402 route discovery

GET /api/v1/x402/graph?sort=reviewed&context=with&limit=20
GET /api/v1/x402/routes?sort=reviewed&context=with&limit=20
GET /api/v1/x402/routes/:routeId
GET /api/v1/x402/routes/:routeId/recognitions
GET /api/v1/x402/routes/:routeId/reviews
GET /api/v1/x402/reviews?reviewer=0x...

The relationship graph is the agent starting point. It joins endpoints, wallets, routed recognition, signed reviews, and signed participant descriptions. The smaller route directory returns real route IDs, endpoint descriptions, reviewSummary, monetary recognition, and navigation links. Do not use the separate handle/repository gratitude graph to discover endpoints.

Every legacy paid GET /api/v1/x402/* read costs $0.01 through x402 or MPP; the free discovery and economics endpoints are separate exceptions. boonprotocol.com/x402 uses a separate compact website display shape without exact signed payloads. Review publication has four evidence-specific lanes: POST /api/v1/x402/reviews/self-reported costs $0.05, POST /api/v1/x402/reviews/receipt-verified costs $0.01, POST /api/v1/x402/profiles/:profileId/activity/:activityId/review is free for the wallet that owns an existing settlement-verified use fact, and POST /api/v1/x402/reviews adds no API charge but accepts only a Boon-backed review from the cited routed-Boon tipper. The verified-use-backed lane proves the labeled settlement and a separate wallet-signed opinion, not provider success or response quality. It does not affect ranking. The list defaults to context=with, so it returns only endpoints with published method and URL details that recompute to the onchain route ID. A description may include a service name, summary, dated observed price, protocols, and request basics. Separately attributed participant-signed context may add intended use and subjective fit. reviewSummary reports selfReportedCount opinion volume and receiptVerifiedCount usage volume separately from boonBackedCount conviction. sort=reviewed orders entries by Boon-backed review count, distinct Boon-backed reviewers, USDC recognition, then recency. Self-reported and receipt-verified volume do not influence ranking. sort=recent orders by latest recorded recognition. Entries include the USDC amount, fixed $BOON burn total, recognition count, distinct recognizer wallets, and signed review summary. These values show conviction behind a specific endpoint, not a universal ranking.

Search with q, origin, or method applies to endpoint descriptions and signed route context. context=all explicitly includes hash-only verification records and context=raw returns only those unresolved records. These modes are for index verification, not endpoint browsing. recognizer accepts an EVM wallet address. Pagination uses the opaque nextCursor returned by the API. Keep the same sort value while following a cursor. Review publication or a new recognition can reorder a live multi-page scan, so start a new scan when a stable snapshot matters.

List responses include parsed, bounded context summaries. The route detail response also includes signedPayload.noteJson, signedPayload.offerJson, and signedPayload.signature so an agent can independently recompute the note digest and verify the publisher signature. These exact strings are public once published.

Recognition rows also resolve a tipper, endpoint, or discovery-network wallet to any GitHub or X handle already linked through Boon’s OAuth claim flow. The response keeps the wallet address and adds the verified handles under accounts. A linked handle is identity context, not proof of endpoint use or quality.

Each route may also include subjective reviews with no stars or numeric score. A self_reported V3 review costs $0.05, proves only wallet signature authority, contributes visible participation volume, and is excluded from ranking. A receipt_verified V2 review costs $0.01 and is signed by the payer from an official x402 offer and receipt. The recovered service signer and signed payTo must equal the route’s separate, dated receiptAuthority.signer and receiptAuthority.payTo pins. It contributes usage volume, carries no gratuity or burn, and is excluded from ranking. A boon_backed V1 review is signed by the tipper from one cited RoutedBoon event and shows its exact USDC gratuity and fixed 100,000 $BOON burn. OAuth-linked GitHub or X accounts and ERC-8004 identities are optional display context, not eligibility gates. If receiptAuthority.status is not_observed, the provider has not emitted the official extension and the receipt lane is unavailable. A basic PAYMENT-RESPONSE header is insufficient.

Use the route-scoped reviews endpoint for the newest reviews of one endpoint. Use GET /api/v1/x402/reviews?reviewer=0x... to list the reviewed routes for one wallet. The CLI equivalents are boon x402 reviews --route <routeId> and boon x402 reviews --reviewer <wallet>. The Boon CLI never signs or settles a read automatically, so use an x402-capable client for the payment retry.

POST /api/v1/x402/reviews/self-reported
POST /api/v1/x402/reviews/receipt-verified
POST /api/v1/x402/reviews

{
  "review": {
    "version": "1",
    "routeId": "0x...",
    "recognitionTxHash": "0x...",
    "recognitionLogIndex": 1,
    "reviewText": "Strong for narrow research queries; weaker at page-level extraction.",
    "createdAt": 1784131201
  },
  "signature": "0x..."
}

That is the free-to-publish V1 Boon-backed form. The $0.05 V3 self-reported form sent to /api/v1/x402/reviews/self-reported is:

{
  "review": {
    "version": "3",
    "policyVersion": "boon.x402-review-policy/v3",
    "routeId": "0x...",
    "reviewer": "0x...",
    "reviewText": "The interface looks useful; I am not claiming that I used it.",
    "createdAt": 1784131201
  },
  "signature": "0x..."
}

The $0.01 V2 receipt-verified form sent to /api/v1/x402/reviews/receipt-verified is:

{
  "review": {
    "version": "2",
    "routeId": "0x...",
    "receiptDigest": "0x...",
    "reviewText": "Useful parcel match with clear citations.",
    "createdAt": 1784131201,
    "policyVersion": "boon.x402-review-policy/v2"
  },
  "signature": "0x...",
  "evidence": {
    "offer": { "...": "official signed x402 EIP-712 offer" },
    "receipt": { "...": "official signed x402 EIP-712 receipt" }
  }
}

Review text is one plain-text paragraph of at most 1000 UTF-8 bytes. V3 permits one review per wallet and recognized route, proves only signer control, and is excluded from ranking. V2 requires the endpoint to be seeded in the public graph by at least one routed Boon and the reviewer to be the receipt payer. It verifies the service signer against the route’s payment authority pinned at publication and verifies the exact route URL, supports EOA and Safe/ERC-1271 signatures, and allows each canonical receipt digest once and one receipt-verified review per payer and route. V1 requires the event tipper and allows one review per routed recognition. Review publication sends no gratuity and burns nothing. Only V1 affects discovery ranking because its cited recognition already sent USDC gratuity and burned the fixed 100,000 $BOON.

V2 requires the provider to return the x402 offer-receipt extension. A basic payment challenge or PAYMENT-RESPONSE header alone is not sufficient evidence. The CLI can check that a supplied offer and receipt agree, but the Worker is the authority that checks the recovered signer against the route directory.

Calling an endpoint purchases or consumes its service. Leaving a review is a signed subjective statement. Sending a Boon is the separate act of gratitude and quality conviction whose USDC and burn grow the ranked graph for future viewers.

POST /api/v1/x402/route-contexts

A tipper, funded endpoint wallet, or funded discovery-network wallet may attach exact route-note and offer bytes plus the publisher signature. Publication is public and time-bounded. The signature proves who signed the exact bytes. It does not prove endpoint ownership, availability, safety, use, or response quality. Boon never calls endpoints or fetches attached references during publication or discovery.

{
  "noteJson": "<exact route-note JSON string>",
  "offerJson": "<exact signed offer JSON string>",
  "signature": "0x..."
}

The JSON strings are not reformatted by the client. Duplicate object-member names are rejected, and the offer must bind the exact route-note byte length and digest. Each route participant has one current context slot per route. A newer valid publication from the same wallet replaces its older context.

The legacy keyed verification route remains available:

GET /api/v1/x402/routed-boons?routeId=:routeId

It intentionally requires a route ID or transaction hash. Use the discovery routes above for browsing.

Sender wallet profile

GET /api/v1/wallets/:address/sent

Aggregate sender-side totals for a known wallet, used by the hosted sender profile page. This does not expose a chronological send list; detailed per-handle and graph reads remain on the paid side.

Points policy

GET /api/v1/points/policy

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

Attestation metadata

GET /api/v1/attestations/:tipId

ERC-721-compatible metadata for a Boon gratitude attestation. The metadata links back to boonprotocol.com/attestations/:tipId and includes tip ID, recipient wallet, agent ID when present, $BOON burned, and mint time. It does not reveal private-tip note text or private amount.

Private-tip blob upload

POST /api/v1/private-tip-blobs

App/CLI upload path for encrypted private-tip metadata before tipPrivate(...) settlement. This is a write path used by Boon clients, not a public browsing endpoint.

Private commitment previews

GET /api/v1/private-tips/pending?handle=github%3Aalice

The pending-list endpoint returns recipient-safe previews for a canonical handle without exposing private note text, private commitments, or blob contents. It helps the claim UI show that private Boons may be waiting while preserving the private read boundary.

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 signature.

Private-tip authorized read

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

The challenge endpoint returns an EIP-712 domain/types payload for a short-lived private-tip unlock nonce. The original tipper or authorized recipient signs the challenge and calls GET /tips/:tipId with auth headers to read for free. Without those auth headers, GET /tips/:tipId uses the x402 fixed-price reveal flow, with payment settling to the original tipper.

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
• fixed-price third-party private-tip unlocks
• handle-centered gratitude graph
• repo / artifact-filtered graph
• batch graph queries
• context-aware suggested Boon amount under boon.recognition-score/v2

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

Privacy boundary

Boon’s free surfaces show aggregate reputation and receipt-level verification. Detailed ordinary-Boon graph, list, edge data, and third-party private-tip details are intentionally behind x402 so that agents and apps pay for structured reads instead of getting a public feed by default. Routed x402 recognition is the narrow discovery exception described above. Do not expand it into unauthenticated private-tip detail or a general ordinary-Boon feed.