MCP Billing Spec v0.1

SS1 Billing envelope

Source: src/app/api/bazaar/proxy/route.ts.

The success response is {result, meta:{tool, provider, cost_cents, cost, latency_ms, remaining_balance_cents, receipt, receipt_persisted}}. result is mcpResponse.result || mcpResponse; tool is the tool name and provider is the provider name. cost_cents is the actual cost; cost is "Free" for zero, otherwise $ followed by (actualCost / 100).toFixed(4). latency_ms is elapsed time, and remaining_balance_cents is the balance returned by the debit (bazaar_debit_balance), or (owner.balance_cents ?? 0) - actualCost on the read-modify-write fallback.

Success responses and upstream failure responses carry these headers:

The price is tool.price_cents_override ?? provider.default_price_cents ?? 0. Only status === "success" has a nonzero actual cost, and the balance is debited only when that cost is positive. The route sets success when the upstream HTTP response is successful and its body parses as JSON; it does not separately inspect JSON-RPC errors.

SS2 Metering event

Source: src/app/api/v1/bazaar/meter/route.ts, including its bazaar_usage_logs insert. Stored receipt statuses come from the CHECK constraint in sql/004_trust_layer.sql.

The route looks up an active tool. The resolved tool ID is tool?.id || toolId || "unknown"; the provider ID is tool?.provider_id || (owner.type === "provider" ? owner.id : "unknown"). Price is tool?.price_cents_override ?? tool?.bazaar_providers?.default_price_cents ?? 0.

The usage insert maps agent_id to consumer_id, includes provider_id and resolved tool_id, and records status. cost_cents is the price only for status === "success", otherwise zero. duration_ms becomes latency_ms; input_tokens and output_tokens become request_size_bytes and response_size_bytes. Stored metadata spreads the supplied metadata, then overwrites source with "meter_api" and input_tokens and output_tokens with their defaulted values.

The HTTP 201 response is {metered, tool_id, agent_id, cost_microcents, cost_cents, status, timestamp, receipt:{receipt_id, signature, verify_url}}, with metered: true and a generated ISO timestamp. cost_microcents is (status === "success" ? priceCents : 0) * 10_000. The response's cost_cents is always priceCents, including on failed calls; it can therefore differ from the usage insert's zero cost. Receipt persistence failure is logged but does not fail the meter response.

SS3 Signed receipt

Sources: src/lib/receipts.ts, the bazaar_receipts table in sql/004_trust_layer.sql, and the meter route's receipt insert and verification URL.

Public envelope verification

The response is {receipt, verification:{valid, reason, checked:{canonical, algorithm:"HMAC-SHA256"}, verified_at}}. checked.canonical is built only from caller-supplied fields; it is empty when a signed field is missing or incorrectly typed. Invalid envelopes return HTTP 200 with valid:false; unparsable JSON returns HTTP 400 with {error:true, code:"BAD_REQUEST"}.

The required fields are the seven canonical fields above plus signature. Signed string fields must be nonempty and must not contain |; delimiter collisions return ambiguous_fields before signature comparison. cost_microcents must be an integer. Receipt IDs must match ^rcpt_[0-9a-f]{16,}$ and signatures must be 64 lowercase hexadecimal characters. The verifier uses a timing-safe signature comparison. Reasons are ok, missing_fields (with a missing field list), bad_receipt_id, bad_signature_format, signature_mismatch, and ambiguous_fields.

Legacy stored-receipt endpoint

The separate legacy endpoint is GET /api/v1/bazaar/receipts/{receipt_id}. As implemented in src/app/api/v1/bazaar/receipts/[receiptId]/route.ts, it returns {receipt, verification:{valid, algorithm:"HMAC-SHA256", verified_at}}. The returned receipt contains receipt_id, tool_id, tool_name, agent_id, provider_id, timestamp, duration_ms, cost_microcents, status, signature, and created_at. It does not return input_hash, output_hash, or verify_url. verified_at is an ISO timestamp.

Example receipt

The example amount is 500 microcents = 0.05 cents ($0.0005). This fixed development fixture is generated by tests/fixtures/generate-receipt-fixtures.mjs using the real signer and its committed development fallback.

{
  "receipt_id": "rcpt_0123456789abcdef",
  "tool_id": "b0771337-b070-4000-b001-000000000001",
  "tool_name": "wallet.balance",
  "agent_id": "agent_fixture",
  "provider_id": "b0771337-b070-4000-a000-000000000001",
  "timestamp": "2026-09-21T00:00:00.000Z",
  "duration_ms": 42,
  "cost_microcents": 500,
  "status": "success",
  "signature": "ebfbeca8e4fa6d83596d2e4a261c81ad0494d25f68e81be765fe60e1e19bd26b",
  "verify_url": "https://noui.bot/api/v1/bazaar/receipts/rcpt_0123456789abcdef"
}

SS4 Implementation notes

The current meter, pricing, stats, and balance routes use cost_microcents = cost_cents * 10_000 (including the corresponding per-call pricing, aggregate revenue, and balance fields). 1 cent = 10,000 microcents, consistent with public/specs/mcp-billing-v1.md. Failed metering records zero microcents as described in SS2. Existing stored receipts and their signatures are unchanged.

The meter route stores stringified token counts in input_hash and output_hash, rather than SHA-256 digests: inputTokens ? String(inputTokens) : null and outputTokens ? String(outputTokens) : null. This token-count storage behavior is unchanged.

SS5 Relationship to the v1 draft