Skip to main content
Every tool execution generates a receipt — a transaction record with category, cost breakdown, optional value attribution, and the audit context (memo + decisionContext) the caller attached at call time. Receipts power spend tracking, RoCS computation, and supervisor-agent oversight.

​
Authentication

All analytics endpoints require the X-Agent-ID header with your wallet address. No x402 payment needed — these are free read endpoints (the value tag endpoint is also free). 
-H "X-Agent-ID: 0xYourWalletAddress"

​
Endpoints

MethodPathDescription
GET/v1/analytics/receiptsList receipts with filters
GET/v1/analytics/spend/breakdownSpend by category
GET/v1/analytics/rocsReturn on Cognitive Spend
PATCH/v1/analytics/receipts/{receiptId}/valueTag receipt value

​
Annotating value after the fact

Business outcomes (a reply, a meeting, a closed deal) usually land days or weeks after the tool call that drove them. You don’t need to reconcile receipts in the background to bridge that gap:
  1. Keep the id from the call. Every tool result returns both receipt_id (rcpt_…) and request_id. Either one identifies the receipt.
  2. Tag value when the outcome arrives. Call Tag Receipt Value with the receipt_id or the request_id — the API resolves a request_id via Receipt.job_id (they are the same value), so no List Receipts lookup is required.
  3. If you only kept a timestamp range, page back to the receipt with the since/until window on List Receipts — this reaches receipts older than the 100-row page cap. The caller’s memo/decisionContext are echoed into metadata as additional match keys.

​
Receipt Categories

CategoryToolsDescription
dataresearch, browser, analyze, enrichInformation gathering
verificationverify_emailData validation
communicationemail, voice, smsOutbound messaging
commercecommerce_search, commerce_buyPurchases
infrastructurebuildWebsite/app creation
agent_to_agentsoulInter-agent transactions

​
Receipt Statuses

StatusMeaning
pendingExecution started, payment not yet settled
settledPayment verified on-chain (has settlement_tx)
failedExecution or payment failed
disputedUnder review

​
Return on Cognitive Spend (RoCS)

RoCS = total_value / total_spend
Only value tags with status: "confirmed" count toward total_value. Self-reported tags start as "pending" and must be validated by the judge service before they affect RoCS.