Open Agent Spend Attribution (OASA) Specification

Abstract

OASA defines a canonical record format for agent spend attribution: attributing AI-agent resource consumption and spend to agent identity, task, and cost object, and joining runtime telemetry, normalized billing, and payment settlement into a single auditable ledger — a system of record for agent spend. It is designed to interoperate with OpenTelemetry GenAI semantic conventions (telemetry), the FOCUS specification (billing), and x402 payment-rail records (settlement). It is not a payment protocol and not a billing format; it is the join between settlement, billing, and attribution.

Partial records are valid. Every field outside the envelope is optional so adapters can emit what they know and reconcile later. Within a major version, the schema is additive-only.

OASA is the record format behind FinOps for agentic AI.

Design principles

• Hub-and-spoke: canonical middle, adapters at the edges.
• Settlement-agnostic: invoice, card, wire, and on-chain rails reconcile into the same spine.
• Additive to FOCUS and OpenTelemetry — never competing with them.
• Envelope required; all other groups optional so partial records remain valid.
• Versioned; additive-only within a major version.

The three-layer model

Record schema v0.1.2

Deterministic record IDs

Receivers deduplicate on record_id. An adapter that generates a fresh random ID on every attempt turns each retry into a duplicate row. Adapters whose source has a stable key SHOULD derive record_id from it with the procedure below; two implementations given the same inputs then produce the same ID, and the result is still a valid UUIDv7 under RFC 9562.

Inputs: occurred_at and source_record_id of the record being emitted.

1. ms = occurred_at as Unix time in milliseconds, truncated (not rounded) to the millisecond.
2. h = SHA-256 of the UTF-8 bytes of source_record_id.
3. Build 16 bytes b: b[0..5] = ms as a 48-bit big-endian integer; b[6] = 0x70 | (h[0] & 0x0F) (version 7); b[7] = h[1]; b[8] = 0x80 | (h[2] & 0x3F) (RFC 9562 variant); b[9..15] = h[3..9].
4. Format b as a lowercase hyphenated UUID string (8-4-4-4-12).

For OpenTelemetry spans, source_record_id is the trace ID and span ID in lowercase hex joined by a slash (trace_id/span_id), and occurred_at is the span end time.

Test vector: occurred_at = 2026-09-01T15:04:05Z, source_record_id = 4bf92f3577b34da6a3ce929d0e0e4736/00f067aa0ba902b7 → record_id = 01a05d7f-b288-7532-8207-8cb53896d9e1.

Derived IDs are predictable from their inputs. They are identifiers, not secrets, and MUST NOT be used as access tokens.

Machine-readable schema

The record tables above are published as JSON Schema (draft 2020-12) for adapters to validate their output: the record schema (one record, schema_version 0.1.x), the batch schema (a batch header plus an array of records), and golden examples that validate against the record schema.

Schema identifiers ($id) live under https://oasaspec.org/schema/0.1/ and never change once published; consumers may reference them directly. The schema is generated from the specification text and never edited by hand, and CI fails if the committed schema drifts from these tables.

Decimal fields, including every money field, are JSON numbers. Consumers SHOULD parse them with decimal precision rather than binary floating point.

The schema files, examples, and scripts are licensed Apache-2.0; the specification text remains CC BY 4.0. The 0.2.0 draft is not covered yet; it gets its own schema when 0.2.0 is published.

Batch envelope

Adapters that send records in bulk wrap them in this header. Every record in records is validated independently; the header carries no attribution.

Mapping tables

OpenTelemetry GenAI and x402 mappings verified against upstream docs on 2026-09-15; FOCUS columns verified against focus.finops.org on 2026-10-05. OpenTelemetry GenAI conventions are still experimental and may drift; attribute names here are current as of their date, and unmapped OASA fields are noted where no ratified equivalent exists. FOCUS token-economics columns track 1.4 (ratified) and 1.5 (scheduled). x402 V2 communicates requirements via PAYMENT-REQUIRED payloads (network, asset, amount, payTo).

OASA ↔ OpenTelemetry GenAI

OASA ↔ FOCUS

FOCUS, the FinOps Foundation's open billing specification, added token-economics columns in 1.4; FOCUS 1.5 (Dec 2026 target) adds native token tracking and a Price Sheet dataset. OASA tracks those columns as they ratify.

Full column-by-column mapping, including the Invoice Detail dataset and worked examples: OASA ↔ FOCUS 1.4 mapping.

OASA ↔ x402

Worked example

One agent tool-call as a usage row, later joined by a charge row and an x402 settlement row sharing trace_id / settlement_ref.

1. Usage (telemetry)

{
  "record_id": "0193f0a0-0000-7000-8000-000000000001",
  "record_type": "usage",
  "schema_version": "0.1",
  "occurred_at": "2026-09-01T15:04:05Z",
  "recorded_at": "2026-09-01T15:04:06Z",
  "source_system": "otel-collector",
  "source_record_id": "span-9f2c",
  "currency": "USD",
  "agent_id": "agent-support-47",
  "agent_name": "Support Triage",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "span_id": "00f067aa0ba902b7",
  "task_type": "ticket_resolve",
  "provider": "openai",
  "model": "gpt-4.1",
  "operation": "tool_call",
  "tool_name": "crm.lookup",
  "input_tokens": 1200,
  "output_tokens": 340,
  "cached_tokens": 800,
  "session_id": "sess-2f91",
  "unit_type": "tokens",
  "units_consumed": 1540,
  "cost_source": "measured"
}

2. Charge (billing)

{
  "record_id": "0193f0a0-0000-7000-8000-000000000002",
  "record_type": "charge",
  "schema_version": "0.1",
  "occurred_at": "2026-09-02T00:00:00Z",
  "recorded_at": "2026-09-02T06:12:00Z",
  "source_system": "openai-billing",
  "source_record_id": "inv_line_88421",
  "currency": "USD",
  "agent_id": "agent-support-47",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "invoice_id": "INV-2026-09-01",
  "focus_charge_ref": "focus:row:88421",
  "list_cost": 0.042,
  "billed_cost": 0.038,
  "effective_cost": 0.038,
  "cost_source": "invoiced"
}

3. Settlement (x402)

{
  "record_id": "0193f0a0-0000-7000-8000-000000000003",
  "record_type": "settlement",
  "schema_version": "0.1",
  "occurred_at": "2026-09-01T15:04:07Z",
  "recorded_at": "2026-09-01T15:04:08Z",
  "source_system": "x402-facilitator",
  "source_record_id": "pay_0xabc…",
  "currency": "eip155:8453/erc20:0x…",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "settlement_rail": "x402",
  "settlement_network": "eip155:8453",
  "settlement_asset": "eip155:8453/erc20:0x…",
  "settlement_amount": 0.038,
  "settlement_ref": "0xdeadbeef…",
  "settled_at": "2026-09-01T15:04:07Z",
  "reconciliation_status": "matched"
}

References

Upstream specifications and standards this document maps to or depends on.

Referencing these specifications does not imply endorsement by their stewards. OASA is an independent publication of Onaro (BrianOnAI LLC).

Changelog

• v0.1.2 (2026-10-08) — Adds allocated to cost_source. Adds machine-readable JSON Schema, golden examples and validation tooling. Documents deterministic record IDs. FOCUS mapping: provider maps to ServiceProviderName (FOCUS 1.4; formerly ProviderName). No fields added, removed, or renamed; schema_version remains "0.1".
• v0.1.1 (2026-09-15) — Extended the OpenTelemetry GenAI mapping with tool, cached-token, conversation, and reasoning attributes; added a Notes column. Mapped cached_tokens to gen_ai.usage.cache_read.input_tokens (registry name as of 2026-09-15). No schema fields added, removed, or renamed; schema_version remains "0.1".
• v0.1 (2026-09-14) — initial public draft.

Contributing

The specification is developed in the open at github.com/onaro-io/agent-spend-attribution. Open an issue for anything wrong, missing, or ambiguous — especially an upstream attribute name that has drifted — or a pull request against SPEC.md for concrete changes. Implementation reports are the most useful contribution: if you have tried to map real agent spend with this schema, what broke is what the next version needs to fix.

General comments: hello@onaro.io