Agent Universal Resource Architecture
Status: Active Version: 2.2.0 Date: April 2026 Author: M Massar
This specification defines the communication protocols for the AURA (Agent Universal Resource Architecture) platform, a neutral broker system enabling agent-mediated commerce. The protocol enables Scout agents (representing buyers) to express needs in natural language, which AURA Core interprets and routes to qualified Beacon agents (representing sellers) for contextual offer generation, all while preserving buyer privacy until transaction commitment.
This document is the canonical entry point. The full specification is organized into four modules, each independently navigable. Together they provide complete API endpoint definitions, message schemas, authentication flows, and implementation guidance sufficient for developers to build compliant Scout agents, Beacon agents, or AURA Core implementations.
The specification is organized into four modules along natural concern boundaries. Each module is self-contained and links back to this index.
| # | Module | Sections | What It Covers | Lines |
|---|---|---|---|---|
| 1 | Protocol Foundation | 1–4 | Introduction, design principles, authentication & authorization (principals, agents, delegation), core data types (identifiers, sessions, offers, state machine) | ~1,340 |
| 2 | Commerce Protocol | 5–9 | Scout request protocol, AURA interpretation (NLP, disclosure projection), Beacon request protocol, Beacon response protocol, offer ranking & delivery (CWR) | ~1,110 |
| 3 | Financial Protocol | 10–11 | Transaction commitment (consent, pre-commitment validation, clearinghouse settlement, settlement instructions, proof of settlement), dispute resolution (filing, evidence, adjudication, enforcement) | ~1,180 |
| 4 | Protocol Reference | 12–15, A–D | Error handling, security considerations, API endpoint reference, implementation notes, JSON schemas, sequence diagrams, glossary, telemetry events | ~1,250 |
Different readers need different parts of this specification. Use these paths to navigate efficiently.
You need to understand how AURA defines the market, how clearing works, and what the settlement interface looks like.
You need to register, receive interpreted requests, submit offers, and handle transaction lifecycle.
You need to create sessions, express intent, review offers, and commit to transactions.
Read all four modules in order. Start with Foundation, then Commerce, Financial, Reference. Use this index for Future Extensions and Document History.
Complete table of contents with module locations.
Appendices:
These architecture documents provide detailed design for protocol features. They are referenced throughout the specification modules.
| Document | Purpose | Primary Module |
|---|---|---|
| Market Profiles | Protocol-level parameterization for multi-vertical deployment | Foundation (2.14), Commerce (6.6), Financial (10.7) |
| Settlement Rails | Market-to-rail interface: instructions, proof, finality, reconciliation | Financial (10.7.3) |
| Clearinghouse | CCP architecture: risk engine, reserve management, enforcement | Financial (10.7, 11.8) |
| Neutral Broker | Trust model, game-theoretic framework, information sovereignty | Foundation (2.1–2.9) |
| Market Economics | Economic model, incentive design, repeated game dynamics | Commerce (9.1), Foundation (2.14) |
| Reputation Specification | Reputation dimensions, tiers, API surface, transparency, appeals (developer-facing) | Commerce (9.1) |
| Data Dictionary | Field definitions, data types, semantic descriptions | All modules |
This section documents planned protocol extensions that are part of the AURA architecture but deferred beyond MVP. These design statements provide guidance for future protocol versions. Items marked (Phase 7 — Defined) have architecture and protocol mechanics specified in this version; implementation is pending.
Status: Architecture designed (DEC-043, April 2026). Protocol specification updated in Tranches 1–3 (v1.8–v2.0).
Phase 7 adds protocol-native clearing, settlement, and risk management to AURA Core. The clearinghouse operates as a Central Counterparty (CCP) — it interposes itself between buyer and seller for every transaction, computing bilateral risk, holding reserves, orchestrating settlement, and enforcing dispute outcomes financially.
Defined in this specification version:
Deferred to Phase 7.1+:
Reference: docs/architecture/CLEARINGHOUSE.md for full architecture. docs/decisions/DECISION_LOG.md DEC-043 for decision rationale.
Current State: MVP supports single-offer acceptance. Multi-round requirements clarification is implemented via Scout SDK’s IntentSession (Phase B). Clearing term negotiation (counter-proposals on payment terms, dispute windows, return policies) is defined in Phase 7 — see Section 4.4.2 (Offer Negotiation States) and /v1/offers/{id}/counter (Section 14). Multi-round price negotiation (counter-offers on price) is deferred.
Phase 7 — Defined (Clearing Term Negotiation):
Scouts and Beacons can negotiate clearing terms (dispute window, return policy, payment timing) through structured counter-proposals. The offer sub-state machine (proposed → countered → accepted / rejected) supports up to 3 counter-proposal rounds per offer. See Section 4.4.2.
Future Design (Price Negotiation — Deferred):
The price negotiation protocol will enable Scouts and Beacons to negotiate along agreed economic principles and models until consensus is reached or non-consensus is determined.
Planned Features:
Example Price Negotiation Flow:
Scout → AURA: Initial request
AURA → Beacon: Offer request
Beacon → AURA: Initial offer ($350)
AURA → Scout: Present offer
Scout → AURA: Counter-offer ($320)
AURA → Beacon: Counter-offer (anonymized)
Beacon → AURA: Revised offer ($335)
AURA → Scout: Present revised offer
Scout → AURA: Accept
[Transaction proceeds]
Current State: Beacons respond only within Scout’s stated constraints.
Future Design:
Enable Beacons to surface exceptional opportunities outside constraints without creating notification fatigue.
Planned Features:
breakthrough_opportunity message type from Beacon to AURACurrent State: Consent is manual at transaction time.
Future Design:
Enable users to define consent policies that automatically apply when boundary conditions are met.
Planned Features:
Current State: Only Scout ↔ AURA ↔ Beacon communication defined.
Future Design:
Enable broader agent ecosystem with direct agent communication.
Planned Features:
Current State: x402 and card payments supported. Phase 7 adds: stablecoin settlement (USDC — primary rail), programmatic wallet settlement, smart contract escrow for risk reserves, bank transfer stubs (ACH/SEPA), and B2B invoice/trade credit terms. See Section 10.7 and CLEARINGHOUSE.md Section 4d (Settlement Orchestrator).
Future Design (Beyond Phase 7):
Expand payment options based on market demand and cross-border requirements.
Planned Methods:
Current State: Event structure defined; API not implemented.
Future Design:
Provide agents with access to their performance data and market insights.
Planned Features:
Current State: Single transaction flow only.
Future Design:
Support subscription-based commerce and automated replenishment.
Planned Features:
| Version | Date | Changes |
|---|---|---|
| 2.2.0 | 2026-04-14 | Identity model restructure — AURA as relying party (DEC-049). Section 3.1 rewritten: principals present externally-issued identity credentials instead of AURA performing verification. Trust Framework maps {credential_format, issuer, claims} to trust levels. Credential Presentation Object supports W3C VC, SD-JWT (Mastercard VI), vLEI (GLEIF), X.509, Visa TAP, Open Banking. Trust levels (L0-L3) retained with same values — provenance changes from AURA-verified to credential-derived. verification_level deprecated in favor of trust_level. Market Profiles gain identity dimension (Section 3.6 of MARKET_PROFILES.md). Business rule min_verification_level renamed to min_trust_level. New endpoints: Trust Framework discovery, credential lifecycle (present, list, remove, trust profile). Design invariants: AURA never performs identity verification, never stores PII, never makes AML/KYC decisions. Agent-principal binding (Section 3.2) and delegation model (Section 3.3) unchanged. Protocol version: v2.1 → v2.2. |
| 2.1.1 | 2026-04-13 | Specification modularized (DEC-046). Single 5,109-line document reorganized into 4 modules: Protocol Foundation (Sections 1–4), Commerce Protocol (Sections 5–9), Financial Protocol (Sections 10–11), Protocol Reference (Sections 12–15, Appendices A–D). This file becomes the canonical index with version history, future extensions, reading paths, and companion document map. No content changes — all section content preserved verbatim in modules. |
| 2.1.0 | 2026-04-13 | Market Profiles and Settlement Rails integration (DEC-044, DEC-045). Section 2: 3 new design principles — 2.14 Market Profile Parameterization (protocol mechanics are invariant, market parameters are configurable), 2.15 Verifiable Settlement (no proof, no state transition), 2.16 Monotonic Disclosure (information visibility can only increase as commitment deepens). Section 4.1: 2 new identifier prefixes — prf_ (Market Profile), rec_ (Reconciliation record). Section 5.1: profile_id added to session creation request (optional, defaults to deployment default profile). Section 6.6: NEW — Disclosure Projection (DEC-044) with 5 disclosure tiers (full, range, presence, redacted, aggregate), default disclosure schedule per protocol phase, projection example showing budget as ±15% range, monotonic guarantee. Interpretation Attestation renumbered to 6.7. Section 10.7.3: REWRITTEN — full settlement instruction JSON contract with Ed25519 signing and L6 commitment chain reference; proof of settlement JSON with 5 verification checks (signature, amount, correlation, finality, timeliness); per-rail finality table (RTP irrevocable/seconds, FedNow irrevocable/central-bank-money, stablecoin irrevocable/12-blocks, card provisional/120-day, ACH provisional/2-day); exception handling cross-reference to SETTLEMENT_RAILS.md. Section 13.6: updated with per-rail finality verification table, dedicated settlement signing key (separate from protocol identity key), reconciliation security (signed records, 3 frequencies). Section 14: 8 Market Profile read-only endpoints (list, get, get by name, list active, get dimension, compare, validate, get defaults) and 4 Settlement Rail endpoints (list adapters, get adapter capabilities, get reconciliation status, get settlement proof). Appendix A.6: Settlement Instruction JSON Schema. Appendix A.7: Market Profile JSON Schema. Driven by DEC-044, DEC-045. Architecture references: MARKET_PROFILES.md, SETTLEMENT_RAILS.md. |
| 2.0.0 | 2026-04-13 | Phase 7 Clearinghouse — Tranche 3 (Completeness). Section 2: 4 new design principles — 2.10 Financial Neutrality, 2.11 Bilateral Risk Transparency, 2.12 Business Rules as Hard Gates, 2.13 Graduated Enforcement. Section 5.1: settlement_preference and risk_tolerance added to session creation request. Section 7.3: business rule compliance (#3) and settlement compatibility (#7) added to Beacon qualification criteria. Section 8.2: payment_terms_hash (SHA-256 of canonical JSON) added to offer signature payload. Section 9.1: CWR formula updated with Risk_Adjustment factor (bilateral risk reflected in ranking); new subsection 9.1.1 Business Rule Pre-Filtering (excluded offers removed from ranked set, available via include_excluded parameter). Section 9.2: example updated with risk-adjusted CWR calculations. Section 14: Phase 7 reserved endpoints added — business rules CRUD, risk profile, clearing status, settlement wallet, offer negotiation, dispute appeal, enforcement status; 7 new webhook events. Section 15.5: Clearinghouse Participant Checklist (Beacon and Scout enablement steps). Section 16.0: Phase 7 Clearinghouse Protocol summary (defined vs. deferred). Section 16.1: updated — clearing term negotiation now defined (Phase 7), price negotiation remains deferred. Section 16.5: updated — stablecoin/wallet settlement now defined (Phase 7), advanced rails deferred. Appendix A: 3 new JSON schemas — A.3 Payment Terms, A.4 Business Rules, A.5 Risk Assessment. Appendix D: 5 new event categories — Clearinghouse (13 events), Enforcement (3 events), Offer Negotiation (4 events), Reserve (5 events). Driven by DEC-043. Completes Phase 7 protocol specification. |
| 1.9.0 | 2026-04-13 | Phase 7 Clearinghouse — Tranche 2 (Dispute Integration and Identity Extensions). Section 3.1: new subsections 3.1.4 (Principal Risk Profile with risk_tier, composite scores, enforcement_status, read endpoint) and 3.1.5 (Business Rules Registration with CRUD endpoints, 6 rule types, immutability/rate-limiting constraints). Section 3.2: new subsection 3.2.8 (Settlement Wallet registration with ownership verification, and Enforcement Status with 5-tier escalation model). Section 3.3: new subsection 3.3.6 (Clearinghouse Authority Verification — consent tier to reserve margin mapping, delegation scope validation at clearing, settlement authority). Section 11.8: expanded from 8-line summary to full clearinghouse dispute resolution with 5 subsections — 11.8.1 (Clearinghouse-Operated Adjudication with 4-step process, auto-adjudication matrix, reserve draw mechanics, appeal endpoint), 11.8.2 (4 new dispute reason codes), 11.8.3 (Reserve-to-Risk Feedback Loop), 11.8.4 (Graduated Dispute Escalation with 3 levels — informal notice, formal dispute, adjudication), 11.8.5 (Protocol Minimum Enforcement with mandatory floors and transparent adjustment). Section 13: new subsections 13.6 (Settlement and Escrow Security — HSM key management, multi-sig escrow, stablecoin bridge risk, settlement finality) and 13.7 (Business Rule Enforcement Security — immutability, whitelist validation, injection defense, transparency). Driven by DEC-043. |
| 1.8.0 | 2026-04-13 | Phase 7 Clearinghouse — Tranche 1 (Minimum Viable Clearing Path). Section 4.1: 5 new identifier prefixes (clr_, rsv_, stl_, br_, rsk_). Section 4.4: payment_terms, clearinghouse_terms, fulfillment_terms, negotiation_status added to Offer Object; new subsections 4.4.1 (Payment Terms) and 4.4.2 (Offer Negotiation States). Section 4.5: 5 new clearing lifecycle states (risk_assessed, authorized, settling, settled, cleared), 8 new transitions (T18–T25), HATEOAS affordances for new states, clearing-specific transaction links. Section 10: payment_terms_acceptance and settlement_wallet on commit request; new subsection 10.2.1 (Pre-Commitment Validation with 6-step gate), clearinghouse and agreed_payment_terms in commit response; new Section 10.7 (Clearinghouse Settlement) with subsections 10.7.1–10.7.5 covering risk assessment, authorization, settlement, post-settlement lifecycle, and clearing status endpoint. Section 12: 9 new error codes (BUSINESS_RULE_VIOLATION, CONSENT_ELEVATION_REQUIRED, SETTLEMENT_METHOD_UNSUPPORTED, CLEARINGHOUSE_UNAVAILABLE, OFFER_NEGOTIATION_CONFLICT, RISK_ASSESSMENT_FAILED, SETTLEMENT_FAILED, RESERVE_EXHAUSTED, ENFORCEMENT_ACTION). Driven by DEC-043. |
| 1.7.0 | 2026-04-01 | Section 11.10 added: Intent-to-Commitment Chain of Custody. Seven-link cryptographic chain (L1 Principal Signal → L2 Interpretation → L3 Principal Review → L4 Offer Selection → L5 Principal Consent → L6 Commitment → L7 Outcome) with hash-linked integrity and per-link Ed25519 signatures. Each link signed by the responsible party (Scout agent, Core, or principal). Core validates chain completeness at commit time — incomplete or inconsistent chains reject the commit. Principal Review attestation (L3) captures whether human saw interpretation; Offer Selection attestation (L4) records selection method and alternatives considered. Privacy-preserving chain accessibility: full chain visible to Scout principal and dispute processes; redacted view for Beacon principal. Retrievable via GET /v1/transactions/:id/intent-chain. Driven by “Where Agents Meet” Principle 7 (protocol serves human interests through machine operations). |
| 1.6.0 | 2026-04-01 | Section 11 added: Dispute Resolution Protocol. disputed and resolved states added to session state machine (4.5.1). Five new state transitions (T13–T17) for dispute filing, resolution, and withdrawal. Dispute lifecycle: filing with structured reason codes (11.3), automatic protocol evidence compilation (11.4), evidence submission by both parties with deadline management (11.5), structured resolution with outcomes (upheld/rejected/partial/withdrawn), remedial actions, reputation impact, and adjudicator identification (11.6). Time-bounded dispute windows and deadlines (11.7). Clearinghouse integration path (11.8) for reserve-funded payouts and reputation-to-risk feedback. HATEOAS affordances extended for disputed/resolved states. Table of Contents updated. Sections 11–15 renumbered to 12–16. Driven by “Where Agents Meet” Principle 5 (promises must be enforceable). |
| 1.5.1 | 2026-04-01 | Section 3.3 added: Authority Scoping and Delegation. Three consent tiers (explicit, policy, delegated) with risk-differentiated evidence requirements. Delegation scope schema with constraint model (amount, category, merchant, geography, time, approval thresholds), policy rule definitions, and principal signature. Authority attestation extended onto commit request (Section 10.2) with consent tier, scope reference, policy rule matched, and principal approval chain. Principal approval object with Ed25519 cryptographic proof. External delegation credential interoperability (AP2 mandates, Verifiable Intent) as supplementary evidence. Sections 3.3–3.6 renumbered to 3.4–3.7 with subsection references updated. Driven by “Where Agents Meet” Principle 3 (authority must be scoped). |
| 1.5.0 | 2026-04-01 | Section 3 restructured: Principal Registration (3.1) added with four progressive verification levels (L0 self_declared through L3 kyc_verified), principal-type schema, structured identifiers (LEI, domain, company registry), and configurable enforcement thresholds. Agent Registration (3.2) updated: Scout and Beacon schemas now require principal_id and capacity declaration. Three capacity types defined: agent_for_principal, principal_direct, platform_delegated. Platform-delegated principal override (3.2.4) enables marketplace agents (e.g., Shopify) to declare per-session principals. Principal references written into transaction records at commit time with Scout principal hidden until commitment (3.2.5). Cross-context principal resolution endpoints added (3.2.6) for dispute, agent replacement, human re-auth, and platform migration scenarios. Backward compatibility (3.2.7) auto-generates L0 principals for pre-v1.5 agents. Sections 3.2–3.5 renumbered to 3.3–3.6. Driven by “Where Agents Meet” Principles 2 (declaration of representation) and 8 (identity surviving context transitions). |
| 1.4.1 | 2026-03-26 | Section 6.6 added: Interpretation Attestation. Signed binding of original natural language input to structured interpretation output, with model version, confidence, and Ed25519 attestation signature. Retrievable via GET /v1/sessions/:id/attestation. See MARKET_ECONOMICS.md Section 9 for economic rationale. Removed duplicate Section 6.3 (sanitisation rules already covered in Section 6.5). |
| 1.4.0 | 2026-03 | Section 8.2 rewritten: newline-delimited canonical signature format replacing ambiguous bare concatenation, added currency to signed fields, worked example, Core counter-signature stance documented (not yet implemented). |
| 1.3.0 | 2026-03 | Section 5.4 added: Compound Intent schema reservations. Reserved fields on session (sub_intents, parent_session_id, budget), offer request (sub_intent_id, budget_remaining), and commit (sub_intent_id). SubIntent object schema defined. Information sovereignty constraints documented. |
| 1.2.0 | 2026-03 | Section 4.5 rewritten: reconciled state enumeration with production code (8 active states, 4 reserved), added state transition table (T1–T12), added HATEOAS affordance table. Renamed offers_ready → offers_available, transaction_pending → committed. Added fulfilled state. |
| 1.1.0 | 2026-03 | NLP pipeline updates: three-layer architecture (ADR-002), session request schema (intent/constraints/completeness), Beacon interpretIntent, InterpretResult/CompletenessResult schemas |
| 1.0.0 | 2026-01 | Initial specification |