Skip to main content
Every tool execution generates a receipt — a transaction record with category, cost breakdown, and optional value attribution. Receipts power spend tracking and RoCS computation.

​
Authentication

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

​
Endpoints

​
List Receipts

GET /v1/analytics/receipts
​
period
number
default:"all"
Filter to last N days (1–365)
​
category
string
Filter by category: data, verification, communication, commerce, infrastructure, agent_to_agent
​
limit
number
default:"50"
Results per page (1–100)
​
offset
number
default:"0"
Pagination offset
curl https://win.oneshotagent.com/v1/analytics/receipts?period=7&category=communication \
  -H "X-Agent-ID: 0xYourWalletAddress"

{
  "receipts": [
    {
      "receipt_id": "rcpt_01HGW2HB4V4T0PZGJ8PFDRCHQM",
      "category": "communication",
      "subcategory": "email",
      "amount_usdc": "0.150000",
      "service_fee": "0.030000",
      "provider_cost": "0.120000",
      "status": "settled",
      "settlement_tx": "0x1a2b3c...",
      "value_tag": null,
      "created_at": "2026-03-09T14:30:00Z",
      "settled_at": "2026-03-09T14:30:01Z"
    }
  ],
  "count": 1,
  "has_more": false
}

​
Spend Breakdown

Aggregate spend by category for a given period. 
GET /v1/analytics/spend/breakdown
​
period
number
default:"30"
Period in days (1–365)
curl https://win.oneshotagent.com/v1/analytics/spend/breakdown?period=30 \
  -H "X-Agent-ID: 0xYourWalletAddress"

{
  "categories": [
    { "category": "communication", "total": "4.500000", "count": 30, "pct": 45.0 },
    { "category": "data", "total": "3.200000", "count": 16, "pct": 32.0 },
    { "category": "infrastructure", "total": "2.300000", "count": 4, "pct": 23.0 }
  ],
  "total": "10.000000",
  "period_days": 30
}

​
Return on Cognitive Spend (RoCS)

RoCS measures the value generated per dollar of cognitive spend. 
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. 
GET /v1/analytics/rocs
​
period
number
default:"30"
Period in days (1–365)
curl https://win.oneshotagent.com/v1/analytics/rocs?period=30 \
  -H "X-Agent-ID: 0xYourWalletAddress"

{
  "rocs": 2.4,
  "total_spend": "10.000000",
  "total_value": "24.000000",
  "period_days": 30
}

​
Tag Receipt Value

Report the business value a tool execution generated. Tags are stored as pending and only count toward RoCS after validation by the judge service. 
PATCH /v1/analytics/receipts/:receiptId/value
​
receiptId
string
required
The rcpt_* receipt ID
​
type
string
required
Value type. One of: revenue, lead, conversion, savings, engagement
​
amount
number
required
Value amount in USD. Must be positive, max $1,000,000.
​
label
string
Optional description (max 200 characters)
curl -X PATCH https://win.oneshotagent.com/v1/analytics/receipts/rcpt_01HGW2HB4V/value \
  -H "X-Agent-ID: 0xYourWalletAddress" \
  -H "Content-Type: application/json" \
  -d '{"type": "revenue", "amount": 50.00, "label": "Sale from outbound email"}'

{
  "success": true,
  "receipt_id": "rcpt_01HGW2HB4V",
  "value_tag": {
    "type": "revenue",
    "amount": 50.00,
    "status": "pending"
  }
}
Value tags start as pending. A judge service validates claims against observed outcomes (email replies, payment confirmations, notification events) before promoting to confirmed. Only confirmed tags count toward RoCS.

​
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