aura-labs.ai

AURA Protocol Specification — Foundation

Module: Protocol Foundation (Sections 1–4) Parent: AURA Protocol Specification v2.2 Version: 2.2 Date: April 14, 2026 Covers: Introduction, Design Principles, Authentication & Authorization, Core Data Types

1. Introduction

1.1 Purpose

This specification defines the wire protocols, message formats, and interaction patterns for the AURA agentic commerce platform. AURA serves as a neutral broker between buyer agents (Scouts) and seller agents (Beacons), enabling privacy-preserving, trust-enhanced commercial transactions.

1.2 Scope

This specification covers the Minimum Viable Protocol (MVP) for AURA:

MVP Scope Declaration:

This specification defines the foundational protocol sufficient to complete a single-offer transaction flow. The MVP supports:

Deferred to Future Protocol Versions:

This specification does NOT cover:

1.3 Terminology

Term Definition
Scout An autonomous agent acting on behalf of a buyer (consumer)
Beacon An autonomous agent acting on behalf of a seller (merchant)
AURA Core The neutral broker platform that interprets, routes, and mediates
Request A Scout’s expression of need (natural language intent + optional constraints)
Interpreted Request AURA’s structured representation of Scout intent
Completeness Attestation Scout SDK’s assessment of intent completeness (informational, not authoritative)
IntentSession Scout SDK class for multi-round intent completeness validation
interpretIntent Beacon SDK function for domain-specific catalog matching
Offer A Beacon’s response containing product details, pricing, and terms
CWR Compatibility-Weighted Reputation score for ranking
Session A logical conversation from request to transaction completion

1.4 Notational Conventions

2. Protocol Design Principles

2.1 Privacy by Design

Scout identity is abstracted throughout the discovery and offer generation phases. Beacons receive only:

Scout identity is revealed ONLY upon explicit transaction commitment.

Future extension: An inter-agent signals channel (e.g., aggregate purchase patterns, preference indicators) is planned but not yet implemented. When introduced, signals will be classified as sensitive or non-sensitive, with Scout policy controlling disclosure. See Section 3.7.1 consent_boundaries for the policy schema reservation.

2.2 Prompt Injection Resistance

Beacons NEVER receive raw Scout queries. All natural language passes through AURA’s interpretation layer, which:

2.3 Negotiation Model (Design Statement)

MVP Implementation: This protocol version implements single-offer acceptance. Scouts receive ranked offers and commit to one.

Future Negotiation Model: The AURA architecture is designed to support multi-round negotiation where Scouts and Beacons negotiate along agreed economic principles and models until consensus is reached or non-consensus is determined. Future protocol versions will define:

The negotiation protocol will enable agents to autonomously negotiate within policy boundaries defined by their principals, implementing game-theoretic models that optimize for mutually beneficial outcomes.

2.4 Constraint Breakthrough (Design Statement)

MVP Implementation: Beacons respond only to requests that match their capabilities within stated Scout constraints.

Future Constraint Breakthrough Model: The architecture supports a “constraint breakthrough” pattern where Beacons may surface compelling opportunities that fall outside Scout’s stated constraints. This enables serendipitous discovery while respecting user attention. Future protocol versions will define:

This pattern is critical to achieving high user satisfaction by surfacing exceptional opportunities without creating notification fatigue.

2.5 Agent Ecosystem (Design Statement)

MVP Implementation: This protocol defines Scout ↔ AURA ↔ Beacon communication only.

Future Agent Ecosystem: The architecture envisions a broader agent ecosystem where:

Agent-to-agent communication outside the AURA Core broker is deferred to future protocol versions.

2.6 External Protocol Interoperability

AURA is designed to interoperate with emerging agentic commerce standards including:

Implementation Note: Translation between AURA protocol and external standards is an implementation detail. This specification defines AURA-native message formats. Implementers MAY bridge to external protocols but MUST maintain AURA protocol semantics. Where external standards define data elements useful to AURA, those elements SHOULD be considered for inclusion in future protocol versions.

2.7 Natural Language + Structured Hybrid

The protocol supports both structured fields (for efficient filtering and comparison) and natural language fields (for semantic richness and LLM-mediated matching).

Structured fields are used for:

Natural language fields are used for:

2.8 RESTful Design

The protocol uses standard HTTP methods with JSON payloads:

2.9 Extensibility

All message types include an extensions field for forward compatibility. Unknown extensions MUST be ignored by receivers. Version negotiation ensures graceful degradation.

2.10 Financial Neutrality (Phase 7)

The clearinghouse (CCP) holds no commercial position. It does not rank offers, select Beacons, or negotiate terms. It validates, prices risk, settles, and enforces. Revenue comes from clearinghouse fees and float investment, not from favoring one side of a transaction. This extends the neutrality principle (Section 2.2) into the financial layer.

2.11 Bilateral Risk Transparency (Phase 7)

Risk assessment is bilateral — both Scout and Beacon are evaluated. Both parties see the risk assessment that applies to them (Beacons see buyer risk scores without buyer identity; Scouts see the computed margin). No party is assessed in secret. Risk inputs and the formula structure are published (CLEARINGHOUSE.md Section 3.2). This extends the privacy-aware principle (Section 2.3) with financial transparency.

2.12 Business Rules as Hard Gates (Phase 7)

Binary pass/fail business rules (Section 3.1.5) are architecturally separate from continuous risk scoring (Section 3.1.4). A Scout with a perfect risk score is still rejected if they fail a Beacon’s verification gate. This separation prevents business rules from being eroded by margin adjustments. Every real-world CCP maintains this separation (DTCC Rules & Standards vs. Risk Management; CME FCM registration vs. SPAN margins).

2.13 Graduated Enforcement (Phase 7)

Protocol enforcement operates on a gradient: INFORM → PRICE → RESTRICT → BLOCK → SUSPEND (CLEARINGHOUSE.md Section 7.2). First violations increase costs; repeated violations restrict capabilities; persistent violations remove access. Escalation is deterministic and formula-driven, not discretionary. This follows Ostrom (1990) — graduated sanctions sustain cooperation more effectively than binary punishment.

2.14 Market Profile Parameterization (DEC-044)

The protocol defines invariant mechanics (state machine, message formats, cryptographic integrity, clearing lifecycle). Economic parameters that vary across market contexts — participation costs, disclosure schedules, commitment paths, risk thresholds, schema extensions — are set by Market Profiles (MARKET_PROFILES.md). The protocol never hardcodes values that differ between retail, B2B, digital goods, and services. Profiles are transparent (inspectable before participation), stable (immutable during a session), and composable (each dimension specified independently).

2.15 Verifiable Settlement (DEC-045)

Settlement is confirmed by cryptographic proof, not by trust. The clearinghouse advances from settling to settled only when it receives a verifiable, non-repudiable proof of settlement from the payment rail — signed by the rail, correlated to the original instruction, and confirming finality. No proof, no state transition. The protocol defines the settlement instruction contract and proof verification model (SETTLEMENT_RAILS.md); the rail defines how funds move.

2.16 Monotonic Disclosure (DEC-044)

Information disclosed to participants can only increase as commitment increases. No protocol phase reveals less than the previous phase. This is a structural guarantee — a field visible at the discovery phase cannot be redacted at the offers phase. Disclosure schedules are configured per Market Profile, but monotonicity is protocol-enforced regardless of profile.

3. Authentication & Authorization

3.1 Principal Registration and Identity

Before registering agents, participants register the principal — the legal entity or individual on whose behalf agents will act. A principal is the accountable party in a transaction: the entity whose resources are at risk and against whom commitments are enforceable.

Principals are registered independently of agents. A single principal may operate multiple agents. An agent serves exactly one principal.

Identity model (DEC-049): AURA is a relying party, not an identity verifier. Principals establish trust by presenting externally-issued identity credentials from trusted providers. AURA verifies the cryptographic integrity of those credentials (signature, issuer trust chain, expiry, revocation) and maps them to trust levels via a Trust Framework. AURA never performs identity verification — no DNS challenges, no document checks, no KYC. Identity providers perform verification; AURA consumes the result.

3.1.1 Principal Registration

POST /v1/principals

Request:

{
  "principal_type": "organization",
  "display_name": "Acme Widgets",
  "public_key": "base64-ed25519-public-key",
  "credentials": [
    {
      "format": "vlei",
      "credential": "eyJhbGciOiJFZERTQSIs...",
      "disclosure": null,
      "binding_proof": null
    }
  ],
  "notification_endpoint": "https://acme.example.com/aura/notifications"
}

Response (201 Created):

{
  "principal_id": "prn_01HXYZ...",
  "principal_type": "organization",
  "display_name": "Acme Widgets",
  "trust_level": "entity_verified",
  "trust_profile": {
    "level": "entity_verified",
    "credentials_accepted": [
      {
        "credential_id": "crd_01HABC...",
        "format": "vlei",
        "issuer": "did:web:qvi.gleif.org",
        "claims_proven": ["legal_entity_name", "lei", "jurisdiction"],
        "trust_contribution": "entity_verified",
        "accepted_at": "2026-04-14T10:00:00Z",
        "expires_at": "2027-04-14T10:00:00Z"
      }
    ],
    "computed_at": "2026-04-14T10:00:00Z"
  },
  "registered_at": "2026-04-14T10:00:00Z"
}
Field Required Description
principal_type Yes organization or individual
display_name No Trading name or label for display. Self-declared, not verified.
public_key Yes Ed25519 public key for the principal entity (distinct from agent keys). Used for holder binding verification.
credentials No Array of credential presentations (see Section 3.1.3). Defaults to empty (L0).
notification_endpoint No URI for protocol-level notifications. Not PII — an operational endpoint.

Registration without credentials (L0): A principal that presents zero credentials registers at trust level L0 (self_declared). This is the default for retail consumers. Scouts can browse, express intent, and receive offers without presenting any identity credential. Credentials can be added later via POST /v1/principals/{id}/credentials.

3.1.2 Trust Levels

The protocol defines four progressive trust levels. Each level subsumes the ones below it. Trust levels describe what external credentials have proven about the principal — not what AURA verified.

Level Name What Is Proven Credential Types Analogue
L0 self_declared Nothing — principal asserts identity only No credential required Craigslist seller
L1 domain_verified Principal controls a domain DV/OV/EV certificate from a CA, domain attestation VC Let’s Encrypt certificate
L2 entity_verified Principal is a registered legal entity vLEI from GLEIF QVI, Verifiable Intent L1 from Mastercard/Google, EV certificate Card network merchant onboarding
L3 kyc_verified Full identity verification of principal and beneficial owners KYC credential from licensed provider, Open Banking identity token, bank-verified VC Securities clearing member

Trust is credential-derived and composable. A principal’s trust level equals the highest trust contribution among all accepted, non-expired credentials. A principal can present multiple credentials from different issuers to build a richer trust profile. Trust levels can only increase through credential presentation; they may decrease through credential expiry or revocation.

Enforcement configuration: Market Profiles (MARKET_PROFILES.md) set minimum trust levels per action and transaction value. The Trust Framework (Section 3.1.4) maps credentials to trust level contributions. See MARKET_PROFILES.md Section 3.6 for per-profile trust requirements.

3.1.3 Credential Presentation

When a principal presents an identity credential — at registration or via POST /v1/principals/{id}/credentials — the credential is wrapped in a Credential Presentation object:

{
  "format": "string (required)",
  "credential": "string (required)",
  "disclosure": "object | null",
  "binding_proof": "string | null"
}
Field Required Description
format Yes Credential format identifier. Determines parsing and verification logic.
credential Yes The credential payload, encoded per format convention (typically base64url JWT or CBOR).
disclosure No Selective disclosure frame for SD-JWT or similar formats. Specifies which claims the principal is disclosing. Null for formats without selective disclosure.
binding_proof No Proof that the presenter controls the credential’s subject key. Required for holder-binding formats (SD-JWT with key binding). For formats where the credential itself proves possession (signed by the subject’s key), null. Must bind to the principal’s Ed25519 public key.

Supported credential formats:

Format Standard Typical Issuer Trust Contribution Selective Disclosure
vc+jwt W3C Verifiable Credentials (JWT) Any trusted VC issuer Per Trust Framework rules No
vc+sd-jwt SD-JWT (IETF) Mastercard VI, Google, trusted issuers Per Trust Framework rules Yes (disclosure frame required)
vlei GLEIF vLEI (KERI-based) Qualified vLEI Issuers (QVIs) accredited by GLEIF entity_verified (L2) No
x509+domain X.509 DV/OV/EV certificate Certificate Authorities (Let’s Encrypt, DigiCert, etc.) domain_verified (L1) or entity_verified (L2) for EV No
tap Visa Trusted Agent Protocol Visa-accredited issuers Per Trust Framework rules No
ob+jwt Open Banking identity token AISP/PISP-licensed banks kyc_verified (L3) Yes (PSD2 scope-based)

Credential verification process:

  1. Parse envelope. Extract format, decode credential per format rules.
  2. Identify issuer. Extract iss (JWT), AID prefix (vLEI/KERI), or certificate chain root (X.509).
  3. Match Trust Framework rule. Find a rule where credential_format and issuer_pattern match. If no rule matches, reject with UNTRUSTED_ISSUER.
  4. Verify cryptographic integrity. Validate signature against the issuer’s public key.
  5. Check expiry. Credential must not be expired and must be within the Trust Framework rule’s max_credential_age_days.
  6. Check revocation. If the Trust Framework rule requires revocation checking, verify status (CRL, OCSP, StatusList2021, or KERI TEL).
  7. Verify required claims. Credential must contain all claims listed in the matching rule’s required_claims.
  8. Verify holder binding. If the format requires holder binding, verify that binding_proof proves the presenter controls the credential subject’s key. The binding MUST chain to the principal’s Ed25519 public key.
  9. Accept and record. Record the credential’s format, issuer identifier, claims proven (names only, not values), trust contribution, acceptance timestamp, and expiry. AURA does not index or store credential claim values.
  10. Recompute trust level. Apply the Trust Framework’s computation function across all accepted, non-expired credentials.

Design invariant: AURA never stores PII. Credential claim values are not indexed or queryable by AURA. AURA records: credential format, issuer identifier, claim names proven, trust contribution, timestamps. The credential payload may be stored encrypted for dispute evidence.

3.1.4 Trust Framework

The Trust Framework is a protocol-level configuration that maps {credential_format, issuer, claims} to trust level contributions. It is discoverable by agents before participation.

GET /v1/trust-framework
GET /v1/trust-framework/rules/{rule_id}

Trust Framework schema:

{
  "framework_id": "tf_01HXYZ...",
  "version": "1.0.0",
  "name": "AURA Default Trust Framework",
  "effective_from": "2026-04-01T00:00:00Z",
  "rules": [
    {
      "rule_id": "tfr_01H001...",
      "credential_format": "vlei",
      "issuer_pattern": "did:web:*.gleif.org",
      "required_claims": ["lei", "legal_entity_name"],
      "trust_contribution": "entity_verified",
      "max_credential_age_days": 365,
      "revocation_check": "required"
    },
    {
      "rule_id": "tfr_01H002...",
      "credential_format": "x509+domain",
      "issuer_pattern": "ca_trust_store:mozilla_root_program",
      "required_claims": ["domain"],
      "trust_contribution": "domain_verified",
      "max_credential_age_days": 398,
      "revocation_check": "required"
    },
    {
      "rule_id": "tfr_01H003...",
      "credential_format": "vc+sd-jwt",
      "issuer_pattern": "did:web:vi.mastercard.com",
      "required_claims": ["legal_entity_name", "jurisdiction"],
      "trust_contribution": "entity_verified",
      "max_credential_age_days": 365,
      "revocation_check": "recommended"
    },
    {
      "rule_id": "tfr_01H004...",
      "credential_format": "ob+jwt",
      "issuer_pattern": "registry:openbanking.org.uk/directory",
      "required_claims": ["full_name", "date_of_birth"],
      "trust_contribution": "kyc_verified",
      "max_credential_age_days": 90,
      "revocation_check": "required"
    }
  ],
  "trust_level_computation": "highest_contribution",
  "default_trust_level": "self_declared"
}
Field Description
trust_level_computation highest_contribution (default): trust level = highest contribution among accepted credentials. composite (reserved): may require credentials from multiple independent sources for higher levels.
issuer_pattern Pattern matching the credential issuer. Supports DID patterns (did:web:*.gleif.org), CA trust store references (ca_trust_store:mozilla_root_program), and registry references (registry:openbanking.org.uk/directory).
max_credential_age_days Maximum age of the credential at time of presentation. Prevents stale credentials from contributing to trust.
revocation_check required (must check, reject if revoked), recommended (should check, warn if unable), none (no check).

Trust Framework transparency: Agents can inspect the Trust Framework before participating, including which issuers are trusted, what credential formats are accepted, and what trust levels are achievable. This is analogous to Market Profile transparency (Principle 2.14) — agents make informed participation decisions based on published rules.

Market Profile integration: Each Market Profile references a Trust Framework and adds per-action minimum trust levels. Different market contexts may use different Trust Frameworks (e.g., a regulated B2B market may only trust vLEI and Open Banking credentials from EU-domiciled issuers). See MARKET_PROFILES.md Section 3.6.

3.1.5 Credential Lifecycle

POST   /v1/principals/{id}/credentials               — Present new credential(s)
GET    /v1/principals/{id}/credentials               — List accepted credentials
DELETE /v1/principals/{id}/credentials/{credential_id} — Remove a credential
GET    /v1/principals/{id}/trust-profile              — Current trust level with full provenance

Credential expiry: When a credential expires, AURA marks it as expired, recomputes the trust level from remaining valid credentials, and emits a trust_level.downgraded event if the level decreases. Active sessions continue at their creation-time trust level (session-level trust is locked at creation). New sessions use the updated trust level.

Credential revocation: For credentials supporting revocation (CRL, OCSP, StatusList2021, KERI TEL), AURA periodically re-checks revocation status (default: every 24 hours). If a credential is found revoked, the same downgrade process as expiry applies.

Trust level vs. enforcement status: Trust level (credential-derived identity assurance) is distinct from enforcement status (behavioral standing per Section 3.2.8). A principal can have high trust (L3, strong identity) and elevated enforcement (poor behavioral record), or vice versa. Both feed into the Risk Engine independently.

3.1.6 Retrieving and Updating Principals

GET /v1/principals/{principal_id}
PUT /v1/principals/{principal_id}

Retrieval returns the principal record including current trust level and trust profile. Updates are limited to mutable fields (display_name, notification_endpoint). Trust level changes only through credential presentation, expiry, or revocation — not through direct field updates.

3.1.7 Verifiable Intent and Delegation Credentials

Verifiable Intent (Mastercard/Google) and similar delegation frameworks serve two distinct functions in the AURA protocol:

  1. Identity assertion. A VI L1 credential proves the principal’s identity. It is presented as a credential at principal registration (Section 3.1.3) and contributes to the trust level via the Trust Framework. Format: vc+sd-jwt.

  2. Delegation assertion. A VI L2 credential scopes agent authority (amount, payee, payment instrument). It is NOT an identity credential. It continues to appear in the authority.delegation_credential field on commit (Section 3.3.5). VI L2 does not contribute to trust level.

These are separate concerns that happen to use the same credential format (SD-JWT). The Trust Framework distinguishes them by required_claims — identity credentials have identity claims; delegation credentials have authority claims.

3.1.8 Backward Compatibility

Principals registered under the pre-v2.2 model (AURA-performed verification) are assigned trust profiles based on their existing verification level:

3.1.9 Principal Risk Profile (Phase 7)

Every principal accumulates a risk profile from their clearing history. The risk profile is computed by the clearinghouse Risk Engine (CLEARINGHOUSE.md Section 3.2) and stored on the principal record.

{
  "risk_profile": {
    "risk_tier": "standard",
    "composite_risk_score": 0.12,
    "dispute_rate": 0.03,
    "dispute_upheld_rate": 0.01,
    "fulfillment_reliability": 0.97,
    "transaction_count": 1250,
    "total_volume_usd": 487000.00,
    "enforcement_status": "standard",
    "last_assessed_at": "2026-04-01T12:00:00Z"
  }
}
Field Type Description
risk_tier string Current tier: new (< 10 transactions), standard, elevated, restricted. Determines default risk margin multiplier.
composite_risk_score number Aggregate score (0.0–1.0) across all dimensions. Lower is better.
dispute_rate number Fraction of transactions that resulted in disputes (rolling 90-day window).
dispute_upheld_rate number Fraction of disputes upheld against this principal (rolling 90-day window).
fulfillment_reliability number Fraction of transactions fulfilled on time and without issue (Beacon principals only).
transaction_count integer Total cleared transactions for this principal.
total_volume_usd number Total USD-equivalent cleared volume.
enforcement_status string Current enforcement tier per CLEARINGHOUSE.md Section 7.2: standard, elevated, restricted, blocked, suspended.
last_assessed_at string (datetime) When the profile was last recomputed.

Read access: A principal can read their own risk profile. Counterparties see only risk_tier and enforcement_status (not raw scores). Core uses the full profile for clearing decisions.

GET /v1/principals/{principal_id}/risk-profile

3.1.10 Business Rules Registration (Phase 7)

Beacon principals declare business rules — binary pass/fail policies enforced at commit time before risk scoring. Rules are managed via a dedicated endpoint.

POST /v1/principals/{principal_id}/business-rules

{
  "rule_type": "min_trust_level",
  "rule_config": {
    "minimum_level": "entity_verified",
    "applies_above_amount": 1000.00
  },
  "applies_to": "all",
  "enforcement": "hard_stop"
}

GET /v1/principals/{principal_id}/business-rules
DELETE /v1/principals/{principal_id}/business-rules/{rule_id}

Rule types (see CLEARINGHOUSE.md Section 3.1 for full taxonomy):

Rule Type Description Config Fields
min_trust_level Minimum Scout principal trust level (credential-derived) minimum_level, applies_above_amount (optional)
min_consent_tier Minimum consent tier (links to DEC-040) minimum_tier
min_transaction_count Scout must have completed N prior transactions minimum_count
blocked_jurisdictions Sanctions/compliance jurisdiction blocklist jurisdictions (ISO 3166-1 array)
max_transaction_amount Per-transaction ceiling max_amount, currency
required_payment_methods Only accept specific settlement methods methods (string array)
required_credential_formats Require Scout principal to hold credentials in specific formats formats (string array, e.g., ["vlei", "vc+sd-jwt"])

Constraints:

3.2 Agent Registration

Before participating in AURA, agents must register, declare their principal, and obtain credentials.

3.2.1 Scout Registration

POST /v1/agents/scouts

Request:

{
  "agent_name": "MyShoppingAssistant",
  "agent_version": "1.0.0",
  "platform": "ios",
  "capabilities": ["natural_language", "transaction_commit"],
  "public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIj...",
  "principal_id": "prn_01HBUYER...",
  "capacity": "agent_for_principal",
  "callback_url": "https://myapp.example.com/aura/callbacks"
}
Field Required Description
principal_id Yes Reference to the registered principal this agent represents
capacity Yes The agent’s relationship to its principal. See Section 3.2.3

Response (201 Created):

{
  "scout_id": "sct_01HXYZ...",
  "api_key": "sk_example_...",
  "api_secret": "ss_...",
  "principal_id": "prn_01HBUYER...",
  "capacity": "agent_for_principal",
  "registered_at": "2026-01-14T10:00:00Z",
  "rate_limits": {
    "requests_per_minute": 60,
    "sessions_per_hour": 100
  }
}

3.2.2 Beacon Registration

POST /v1/agents/beacons

Request:

{
  "agent_name": "AcmeStoreBeacon",
  "agent_version": "2.1.0",
  "categories": ["electronics", "home_appliances"],
  "capabilities": ["offers", "inventory_check", "dynamic_pricing"],
  "public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIj...",
  "principal_id": "prn_01HSELLER...",
  "capacity": "agent_for_principal",
  "webhook_url": "https://acme.example.com/aura/webhook"
}
Field Required Description
principal_id Yes Reference to the registered principal this Beacon represents
capacity Yes The agent’s relationship to its principal. See Section 3.2.3

Note: The merchant_name and merchant_domain fields from earlier protocol versions are superseded by the principal registry. Merchant identity, legal name, domain, and verification status are properties of the principal, not the agent.

Response (201 Created):

{
  "beacon_id": "bcn_01HXYZ...",
  "api_key": "bk_live_...",
  "api_secret": "bs_...",
  "principal_id": "prn_01HSELLER...",
  "capacity": "agent_for_principal",
  "principal_trust_level": "domain_verified",
  "registered_at": "2026-01-14T10:00:00Z",
  "rate_limits": {
    "offer_responses_per_minute": 1000
  }
}

3.2.3 Capacity Declarations

The capacity field declares the relationship between the agent and its principal. This determines the agent’s obligations, its permitted actions, and the liability chain.

Value Meaning Example Principal Resolution
agent_for_principal Agent acts on behalf of a single declared principal Shopify Beacon acting for Acme Corp; a user’s personal Scout Principal resolved from principal_id at registration
principal_direct The principal is operating directly (no separate agent entity) A developer using the Scout CLI on their own behalf Agent and principal are the same entity
platform_delegated A platform operates the agent on behalf of multiple principals A Shopify app running Beacons for many merchants Principal declared per session or per offer via acting_for_principal_id field (see Section 3.2.4)

3.2.4 Platform-Delegated Principal Override

When an agent registers with capacity: "platform_delegated", the principal_id on the agent record identifies the platform (e.g., Shopify). The platform must declare which specific principal it is acting for in each session or offer submission using the acting_for_principal_id field.

Offer submission with delegated principal:

{
  "session_id": "ses_01HABC...",
  "acting_for_principal_id": "prn_01HMERCHANT...",
  "product": { "name": "Widget Pro", "sku": "WDG-PRO-001" },
  "unit_price": 85.00,
  "quantity": 500,
  "delivery_date": "2026-04-15"
}

Core validates that:

  1. The platform principal (principal_id on the agent) has a registered delegation relationship with the merchant principal (acting_for_principal_id)
  2. The merchant principal meets the verification requirements for the action
  3. The merchant principal is recorded on the resulting transaction, not the platform

This enables marketplace platforms to onboard thousands of merchants through a single Beacon agent while preserving per-merchant accountability, reputation, and verification.

3.2.5 Principal References in Transaction Records

Transaction records include principal references for both sides, resolved at commit time and written as immutable fields.

{
  "transaction_id": "txn_01HXYZ...",
  "session_id": "ses_01HABC...",
  "scout_agent_id": "sct_01H...",
  "scout_principal": {
    "principal_id": "prn_01HBUYER...",
    "trust_level": "domain_verified",
    "capacity": "agent_for_principal"
  },
  "beacon_agent_id": "bcn_01H...",
  "beacon_principal": {
    "principal_id": "prn_01HSELLER...",
    "trust_level": "entity_verified",
    "capacity": "agent_for_principal"
  },
  "committed_at": "2026-04-01T11:00:00Z",
  "offer_id": "ofr_01H..."
}

Privacy constraint: Scout principal identity is resolved at commit time, not before. Beacons see the Scout agent’s session activity during offer formation but never the Scout’s principal identity. The principal is revealed only in the committed transaction record. This preserves the identity abstraction described in Section 2.5 and MARKET_ECONOMICS.md Section 8.1, consistent with the sealed-bid analogy from “Where Agents Meet” Principle 1.

3.2.6 Cross-Context Principal Resolution

The principal registry enables identity to survive beyond the original session or agent, addressing the context-transition problem.

GET /v1/principals/{principal_id}/transactions
GET /v1/principals/{principal_id}/agents
GET /v1/transactions/{transaction_id}/principals

These endpoints require authentication as the principal or as an agent bound to the principal. The clearinghouse (ROADMAP.md Phase 7) additionally has access for dispute resolution.

Use cases:

3.2.7 Backward Compatibility

Agents registered without a principal_id (pre-v1.5 registrations) are assigned an auto-generated principal record at verification level L0 (self_declared), with capacity set to principal_direct. No breaking change to existing integrations. These principals can be upgraded to higher verification levels through the standard verification workflow.

3.2.8 Settlement Wallet and Enforcement Status (Phase 7)

Agents participating in clearinghouse-enabled transactions must declare settlement capabilities and are subject to enforcement status tracking.

Settlement wallet (optional at registration, required for clearing):

Agents may register one or more settlement wallet addresses. At least one is required before the agent’s principal can participate in clearinghouse-settled transactions.

{
  "settlement_wallets": [
    {
      "network": "ethereum",
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD...",
      "currency": "USDC",
      "verified": true,
      "verified_at": "2026-03-15T10:00:00Z"
    }
  ]
}

Wallet verification requires signing a challenge with the wallet’s private key to prove ownership. Unverified wallets cannot be used for settlement.

POST /v1/agents/{agent_id}/settlement-wallets
POST /v1/agents/{agent_id}/settlement-wallets/{wallet_id}/verify
GET /v1/agents/{agent_id}/settlement-wallets
DELETE /v1/agents/{agent_id}/settlement-wallets/{wallet_id}

Enforcement status:

Every agent has an enforcement status that reflects the principal’s standing with the clearinghouse. Enforcement is applied at the principal level but visible on each agent.

Status Description Effect
standard Normal operation. No restrictions. Default for all agents.
elevated Pattern detected (rising dispute rate, late payments). Advisory flag visible to counterparties. Risk margin multiplier increased.
restricted Accumulated violations. Requires explicit consent on all transactions. Additional escrow holds. Rate-limited transaction volume.
blocked Protocol minimum violation or persistent elevated status. New transactions rejected (451 ENFORCEMENT_ACTION). Existing transactions allowed to complete.
suspended Fraud indicators or persistent blocked status. Agent registration revoked. All pending transactions frozen. Manual review required for reinstatement.

Enforcement status transitions are deterministic — driven by formula thresholds (CLEARINGHOUSE.md Section 7.2), not discretionary decisions. Every transition is logged to the clearing audit trail.

GET /v1/agents/{agent_id}/enforcement-status

Returns current enforcement status, reason, effective date, and escalation history. Only Core and the principal can read their own enforcement status. Counterparties see only standard vs. non-standard (they know something is flagged but not the specific tier).

3.3 Authority Scoping and Delegation

When software commits resources on behalf of a principal, the protocol must declare the scope of authority under which the commitment was made. Authority scoping answers: was this agent authorised to make this commitment, and how do we verify that after the fact?

This section defines the delegation scope model, consent tiers, and the authority attestation that accompanies every commit. The model is designed to be compatible with AP2 mandates (Google), Verifiable Intent credentials (Mastercard/Google), and AURA’s own Ed25519 identity chain. The protocol defines the schema; specific implementations may use any of these credential formats to populate it.

Every transaction occurs under one of three consent tiers. The tier determines the risk profile, the evidence required for dispute resolution, and (in the clearinghouse model, ROADMAP.md Phase 7) the risk margin applied to the transaction.

Tier Name Description Evidence for Dispute Risk Profile
T1 explicit The principal approved this specific transaction before it executed. “Buy this item at this price.” Signed transaction approval referencing offer ID and final terms Lowest — principal saw and agreed to exact terms
T2 policy The principal defined a rule; the agent executed when conditions were met. “Buy flights under $400 on this route.” “Reorder when inventory drops below 50 units.” Policy definition + state that triggered execution + proof that transaction falls within policy bounds Medium — disputes hinge on whether the agent correctly interpreted policy bounds
T3 delegated The principal issued a general instruction with latitude. “Handle my grocery shopping.” “Just do it.” The agent exercises judgement within a broad scope. Full agent reasoning chain, original instruction, and the delegation credential scoping authority Highest — principal’s intent was ambiguous; wider dispute surface

Consent tier is declared at commit time and recorded immutably on the transaction. The tier cannot be changed after commit. Core validates that the declared tier is consistent with the delegation scope (Section 3.3.2) — a commit claiming explicit consent tier with a broad delegation scope is rejected as inconsistent.

3.3.2 Delegation Scope

A delegation scope defines the boundaries of an agent’s authority. It is set by the principal (or the principal’s platform) and attached to the agent-principal binding, to individual sessions, or both.

PUT /v1/agents/{agent_id}/delegation-scope

Request:

{
  "scope_id": "dsc_01HXYZ...",
  "consent_tier": "policy",
  "constraints": {
    "max_transaction_amount": 5000.00,
    "currency": "USD",
    "max_transactions_per_day": 10,
    "allowed_categories": ["office_supplies", "electronics"],
    "blocked_categories": [],
    "merchant_allowlist": null,
    "merchant_blocklist": ["prn_BLOCKED..."],
    "geographic_restrictions": {
      "ships_to": ["US", "CA"]
    },
    "require_principal_approval_above": 1000.00,
    "valid_from": "2026-04-01T00:00:00Z",
    "valid_until": "2026-06-30T23:59:59Z"
  },
  "policy_definition": {
    "description": "Office supplies procurement — auto-approve under $1,000, require approval above",
    "rules": [
      {
        "condition": "transaction_amount <= 1000.00",
        "action": "auto_approve",
        "consent_tier": "policy"
      },
      {
        "condition": "transaction_amount > 1000.00 AND transaction_amount <= 5000.00",
        "action": "require_principal_approval",
        "consent_tier": "explicit"
      }
    ]
  },
  "signed_by_principal": true,
  "principal_signature": "base64-ed25519-signature-of-canonical-scope"
}
Field Required Description
scope_id Auto-generated Unique identifier for this delegation scope
consent_tier Yes Default consent tier for transactions under this scope (explicit, policy, delegated)
constraints.max_transaction_amount Yes Maximum value of any single transaction
constraints.currency Yes Currency for monetary constraints
constraints.max_transactions_per_day No Rate limit on autonomous transactions. Null = unlimited
constraints.allowed_categories No Product categories the agent may transact in. Null = all
constraints.blocked_categories No Product categories explicitly prohibited
constraints.merchant_allowlist No If set, agent may only transact with these principal IDs
constraints.merchant_blocklist No Principals the agent may not transact with
constraints.geographic_restrictions No Shipping/fulfilment region constraints
constraints.require_principal_approval_above No Transaction value threshold above which the agent must obtain explicit principal approval before committing, overriding the default consent tier
constraints.valid_from Yes Delegation scope activation time (ISO 8601)
constraints.valid_until Yes Delegation scope expiry time (ISO 8601). Expired scopes reject commits
policy_definition No Human-readable policy description and machine-evaluable rules. Required when consent_tier is policy. Stored for dispute evidence
policy_definition.rules No Ordered list of condition/action pairs. Core evaluates top-down, first match wins
signed_by_principal Yes Whether the principal cryptographically signed this scope
principal_signature Conditional Ed25519 signature of the canonical scope object, signed by the principal’s key (from Section 3.1.1). Required when signed_by_principal is true

Scope inheritance: If no delegation scope is set on an agent, the agent operates under an implicit scope of consent_tier: "explicit" with no autonomous authority. Every commit requires direct principal approval. This is the safe default.

Multiple scopes: An agent may have multiple delegation scopes (e.g., one for office supplies, one for travel). When a session spans categories, Core selects the most restrictive applicable scope. If no scope covers the transaction’s category, the commit is rejected.

3.3.3 Authority Attestation on Commit

The commit request (Section 10.2) is extended with an authority object that declares how the agent obtained authorisation for this specific transaction.

Updated commit request:

{
  "offer_id": "ofr_01HABC...",
  "quantity": 1,
  "authority": {
    "consent_tier": "policy",
    "delegation_scope_id": "dsc_01HXYZ...",
    "policy_rule_matched": "transaction_amount <= 1000.00",
    "principal_approval": null,
    "delegation_credential": null,
    "attestation_signature": "base64-ed25519-signature"
  },
  "buyer_identity": { "..." : "..." },
  "shipping_address": { "..." : "..." },
  "payment_method": { "..." : "..." },
  "consent": { "..." : "..." }
}
Field Required Description
authority.consent_tier Yes The consent tier under which this commit is made
authority.delegation_scope_id Yes Reference to the delegation scope authorising this transaction
authority.policy_rule_matched Conditional The specific policy rule that authorised this transaction. Required when consent_tier is policy
authority.principal_approval Conditional Signed principal approval for this specific transaction. Required when consent_tier is explicit or when the delegation scope’s require_principal_approval_above threshold is exceeded
authority.delegation_credential No Reserved. External delegation credential (AP2 mandate, VI credential) that supplements the AURA delegation scope. See Section 3.3.5
authority.attestation_signature Yes Agent’s Ed25519 signature over the canonical form of {offer_id, consent_tier, delegation_scope_id, transaction_amount, timestamp}. Proves the agent attests to the authority claim

Core validation at commit time:

  1. Verify the delegation scope exists, is active (within valid_from/valid_until), and belongs to the committing agent
  2. Verify the transaction amount does not exceed max_transaction_amount
  3. Verify the transaction category falls within allowed_categories (if set) and not within blocked_categories
  4. Verify the Beacon’s principal is not in merchant_blocklist
  5. If require_principal_approval_above is set and the transaction exceeds it, verify principal_approval is present and validly signed by the principal’s key
  6. Verify consent_tier is consistent with the scope and the presence/absence of principal_approval
  7. Record the authority attestation immutably on the transaction

If any validation fails, the commit is rejected with 403 Forbidden and a structured error identifying which constraint was violated.

3.3.4 Principal Approval Object

When explicit principal approval is required (consent tier explicit, or threshold exceeded under policy tier), the approval is a signed object:

{
  "principal_approval": {
    "principal_id": "prn_01HBUYER...",
    "approved_offer_id": "ofr_01HABC...",
    "approved_amount": 2499.99,
    "approved_currency": "USD",
    "approved_at": "2026-04-01T10:34:50Z",
    "approval_method": "in_app_confirmation",
    "signature": "base64-ed25519-signature-of-canonical-approval"
  }
}

The signature is computed over the canonical form of {principal_id, approved_offer_id, approved_amount, approved_currency, approved_at}, signed by the principal’s Ed25519 key. This creates a cryptographic chain: the principal approved a specific offer at a specific price, the agent committed referencing that approval, and Core verified the chain before creating the transaction.

Approval methods:

Method Description Suitability
in_app_confirmation Principal confirmed via the Scout’s UI (button press, biometric) Standard for consumer purchases
out_of_band_confirmation Principal confirmed via email, SMS, or separate channel Higher-value or higher-risk transactions
delegation_credential Approval is implicit in a signed delegation credential (AP2 mandate, VI credential) Automated/standing-authority scenarios

3.3.5 External Delegation Credential Interoperability

The delegation_credential field on the authority attestation is reserved for external credential formats that supplement AURA’s native delegation scope. This enables interoperability with:

{
  "delegation_credential": {
    "type": "ap2_intent_mandate",
    "mandate": {
      "id": "mdt_01HXYZ...",
      "issuer": { "type": "user", "id": "usr_01H..." },
      "subject": { "type": "agent", "id": "sct_01H..." },
      "constraints": { "maxAmount": 5000, "currency": "USD" },
      "proof": { "type": "Ed25519Signature2020", "..." : "..." }
    }
  }
}

Design principle: AURA’s delegation scope is the protocol-native authority mechanism. External delegation credentials are supplementary evidence, not replacements. A transaction with an AP2 mandate but no AURA delegation scope is rejected. A transaction with an AURA delegation scope and an AP2 mandate has stronger evidence for dispute resolution. The protocol is credential-agnostic at the schema level while remaining self-sufficient at the enforcement level.

Identity vs. delegation: External credentials that assert identity (who the principal is) are presented at principal registration (Section 3.1.3) and contribute to the trust level. External credentials that assert delegation (what the agent is authorized to do) are presented here at commit time. See Section 3.1.7 for the distinction.

3.3.6 Clearinghouse Authority Verification (Phase 7)

When the clearinghouse processes a transaction, the authority attestation (Section 3.3.3) is evaluated for clearing-specific implications:

Consent tier → reserve margin mapping:

The consent tier from the authority attestation directly affects the risk margin computed by the clearinghouse. Higher consent ambiguity requires more reserve protection because the dispute surface is wider (ROADMAP.md Phase 7 Consent Tiers):

Consent Tier Risk Margin Effect Rationale
explicit (T1) Base margin (lowest) Principal approved specific terms — dispute evidence is unambiguous
policy (T2) Base × 1.5–2.0 multiplier Disputes hinge on policy interpretation — evidence requires policy definition + trigger state
delegated (T3) Base × 2.5–3.0 multiplier Principal’s intent was broad — dispute surface is widest; full reasoning chain required

Authority scope validation at clearing:

The clearinghouse validates that the transaction falls within the delegation scope before computing risk:

  1. Amount check: Transaction total ≤ delegation scope maxAmount. If exceeded, the clearinghouse requires re-authorization (consent elevation per DEC-040).
  2. Category check: Product category ∈ delegation scope categories (if constrained). Transactions outside the declared scope require explicit consent.
  3. Merchant check: Beacon principal ∈ delegation scope merchants (if constrained).
  4. Time check: Transaction timestamp within delegation scope validFrom/validUntil.

Scope violations are not automatic rejections — they trigger consent elevation (DEC-040), requiring the Scout to obtain a higher consent tier before the transaction can proceed through clearing.

Settlement authority: The delegation scope may include a settlement_authority field indicating whether the agent is authorized to commit funds from the principal’s settlement wallet. If absent, settlement requires principal confirmation (explicit consent).

3.4 Authentication Methods

3.4.1 API Key Authentication (Simple)

For straightforward integrations, use API key in the Authorization header:

Authorization: Bearer {api_key}

The API key identifies the agent. Include the API secret in request signatures for sensitive operations.

3.4.2 Request Signing (Required for Transactions)

Transaction-related endpoints require signed requests to ensure authenticity.

Signature Algorithm:

  1. Create canonical request string: {HTTP_METHOD}\n{PATH}\n{TIMESTAMP}\n{BODY_SHA256}
  2. Sign with agent’s private key using Ed25519
  3. Include signature in X-AURA-Signature header
  4. Include timestamp in X-AURA-Timestamp header

Example:

POST /v1/sessions/ses_01HXYZ.../commit HTTP/1.1
Authorization: Bearer bk_live_...
X-AURA-Timestamp: 2026-01-14T10:30:00Z
X-AURA-Signature: sig_MEUCIQDx...
Content-Type: application/json

{"offer_id": "ofr_01HXYZ..."}

3.5 Authorization Scopes

Scope Description Scout Beacon
session:create Create new shopping sessions ✓ —
session:read Read session status and offers ✓ —
session:commit Commit to a transaction ✓ —
offer:create Generate and submit offers — ✓
offer:read Read offer details ✓ ✓
transaction:read Read transaction status ✓ ✓

3.6 Rate Limiting

Rate limits are enforced per agent. Responses include rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 2026-01-14T10:31:00Z

When rate limited, the API returns 429 Too Many Requests with a Retry-After header.

3.7 Agent Policy Capabilities

Agents MAY define operational boundaries that govern their behavior within AURA. These policies are enforced by AURA Core’s internal Policy Engine.

Note: The Policy Engine API is internal to AURA Core. Agents interact with policies through registration and policy update endpoints only.

3.7.1 Scout Policy Declaration

Scouts can declare policies governing their behavior:

PUT /v1/agents/scouts/{scout_id}/policies

Request:

{
  "policies": {
    "max_price_usd": 5000,
    "allowed_categories": ["electronics", "home", "clothing"],
    "blocked_merchants": ["bcn_blocked123..."],
    "require_certifications": ["ssl_verified"],
    "auto_reject_below_reputation": 50,
    "geographic_restrictions": {
      "ships_from": ["US", "CA", "UK"],
      "ships_to": ["US"]
    },
    "consent_boundaries": {
      "share_behavioral_data": true,
      "share_purchase_history": false,
      "allow_personalized_pricing": true
    }
  },
  "effective_from": "2026-01-14T00:00:00Z",
  "effective_until": null
}

3.7.2 Beacon Policy Declaration

Beacons can declare policies governing their offer behavior:

PUT /v1/agents/beacons/{beacon_id}/policies

Request:

{
  "policies": {
    "min_order_value_usd": 25,
    "max_discount_percentage": 30,
    "allowed_shipping_regions": ["US", "CA"],
    "require_scout_reputation_above": 40,
    "inventory_reserve_percentage": 10,
    "pricing_boundaries": {
      "allow_dynamic_pricing": true,
      "max_price_variation_percentage": 15,
      "honor_competitor_pricing": false
    },
    "fulfillment_constraints": {
      "max_delivery_days": 7,
      "require_signature": false,
      "insurance_threshold_usd": 500
    }
  },
  "effective_from": "2026-01-14T00:00:00Z",
  "effective_until": null
}

Response (200 OK):

{
  "policy_id": "pol_01HXYZ...",
  "agent_id": "bcn_01HXYZ...",
  "status": "active",
  "effective_from": "2026-01-14T00:00:00Z",
  "validated_at": "2026-01-14T10:00:05Z"
}

3.7.3 Policy Enforcement

AURA Core enforces declared policies during:

Agents are notified of policy violations via webhook events (see Section 8.5).

4. Core Data Types

4.1 Identifiers

All identifiers follow the pattern {type_prefix}_{ulid}:

Prefix Entity
sct_ Scout agent
bcn_ Beacon agent
ses_ Session
req_ Request
ofr_ Offer
txn_ Transaction
clr_ Clearing transaction (Phase 7)
rsv_ Reserve (escrow hold) (Phase 7)
stl_ Settlement instruction (Phase 7)
br_ Business rule (Phase 7)
rsk_ Risk assessment (Phase 7)
prf_ Market Profile (DEC-044)
rec_ Reconciliation record (DEC-045)

4.2 Natural Language Context Object

Used throughout the protocol for semantic content:

{
  "type": "natural_language_context",
  "content": "Looking for a gift for my tech-savvy dad who loves gadgets",
  "language": "en",
  "sentiment": "positive",
  "extracted_entities": [
    {"type": "recipient", "value": "dad"},
    {"type": "interest", "value": "tech gadgets"}
  ],
  "sanitized": true
}
Field Type Required Description
content string Yes The natural language text
language string Yes ISO 639-1 language code
sentiment string No Overall sentiment (positive/neutral/negative)
extracted_entities array No Named entities extracted by AURA
sanitized boolean Yes Whether content has been sanitized by AURA

4.3 Structured Requirements Object

For filterable, comparable attributes:

{
  "type": "structured_requirements",
  "category": "electronics.headphones",
  "hard_constraints": {
    "price_max_usd": 400,
    "in_stock": true,
    "ships_to": "US"
  },
  "soft_preferences": {
    "brands": ["Sony", "Bose", "Apple"],
    "features": ["noise_cancellation", "wireless"],
    "price_range_usd": {"min": 200, "max": 350}
  },
  "certifications_required": ["ce_mark"],
  "certifications_preferred": ["b_corp", "carbon_neutral"]
}
Field Type Required Description
category string Yes Hierarchical category (dot-separated)
hard_constraints object No Must be satisfied or offer is filtered out
soft_preferences object No Influences ranking but not mandatory
certifications_required array No Required third-party certifications
certifications_preferred array No Preferred certifications (boost ranking)

4.4 Offer Object

Complete offer from a Beacon:

{
  "offer_id": "ofr_01HXYZ...",
  "beacon_id": "bcn_01HXYZ...",
  "created_at": "2026-01-14T10:15:00Z",
  "valid_until": "2026-01-14T22:00:00Z",
  "product": {
    "product_id": "prod_abc123",
    "name": "Sony WH-1000XM5",
    "category": "electronics.headphones",
    "structured_attributes": {
      "brand": "Sony",
      "model": "WH-1000XM5",
      "color": "black",
      "connectivity": "bluetooth",
      "features": ["noise_cancellation", "wireless", "foldable"],
      "weight_grams": 250
    },
    "natural_language_description": {
      "content": "Industry-leading noise cancellation with exceptional sound quality. Perfect for frequent travelers and music lovers who demand the best. 30-hour battery life, premium comfort with soft leather cushions.",
      "language": "en",
      "sanitized": true
    },
    "images": [
      {"url": "https://cdn.example.com/img/wh1000xm5.jpg", "type": "primary"}
    ]
  },
  "pricing": {
    "currency": "USD",
    "list_price": 399.99,
    "offer_price": 349.99,
    "discount_percentage": 12.5,
    "price_valid_until": "2026-01-14T22:00:00Z"
  },
  "availability": {
    "in_stock": true,
    "quantity_available": 45,
    "estimated_ship_date": "2026-01-15",
    "delivery_estimate_days": {"min": 2, "max": 5}
  },
  "merchant": {
    "name": "Acme Electronics",
    "return_policy": "30-day free returns",
    "warranty": "1-year manufacturer warranty"
  },
  "certifications": ["ce_mark"],
  "reputation": {
    "beacon_score": 87.5,
    "merchant_rating": 4.7,
    "total_transactions": 12500
  },
  "consent_requirements": {
    "minimum_tier": "explicit",
    "reason": "High-value electronics require explicit buyer approval",
    "above_amount": 100.00
  },
  "payment_terms": {
    "accepted_methods": ["stablecoin_usdc", "card"],
    "timing": "on_fulfillment",
    "net_days": null,
    "dispute_window_days": 30,
    "return_policy_days": 14,
    "return_policy_details": "Free returns within 14 days, original packaging required",
    "currency": "USD",
    "terms_negotiable": true
  },
  "clearinghouse_terms": {
    "estimated_reserve_margin_pct": 2.5,
    "settlement_method": "stablecoin_usdc",
    "clearinghouse_fee_bps": 25
  },
  "fulfillment_terms": {
    "guaranteed_delivery_date": "2026-01-17",
    "delivery_sla_days": 2,
    "damage_guarantee": "full_replacement"
  },
  "negotiation_status": "proposed",
  "signature": "sig_MEUCIQDx..."
}

4.4.1 Offer Payment Terms (Phase 7)

The payment_terms object declares the Beacon’s settlement and dispute terms. It is required on all offers when the clearinghouse is operational.

Field Type Required Description
accepted_methods string[] Yes Settlement methods accepted. Values: stablecoin_usdc, card, bank_transfer, bank_ach, bank_sepa
timing string Yes When payment is collected. Values: on_commit (digital goods), on_fulfillment (physical goods), net_days (B2B deferred)
net_days integer|null Conditional Required when timing is net_days. Payment due N days after fulfillment.
dispute_window_days integer Yes Days after fulfillment during which disputes may be filed. Protocol minimum: 7 days. Core rejects offers below this floor.
return_policy_days integer Yes Days after delivery during which returns are accepted.
return_policy_details string No Human-readable return policy description.
currency string Yes ISO 4217 currency code.
terms_negotiable boolean Yes Whether the Scout may submit a counter-proposal on these terms.

The clearinghouse_terms object is computed by Core at offer publication time and is read-only:

Field Type Description
estimated_reserve_margin_pct number Estimated risk margin percentage based on Beacon’s current risk profile
settlement_method string Primary settlement rail for this offer
clearinghouse_fee_bps integer Clearinghouse fee in basis points

The fulfillment_terms object declares delivery guarantees:

Field Type Description
guaranteed_delivery_date string (date) Latest guaranteed delivery date
delivery_sla_days integer Maximum business days from commit to delivery
damage_guarantee string Damage resolution policy: full_replacement, full_refund, repair, none

4.4.2 Offer Negotiation States (Phase 7)

The negotiation_status field tracks whether terms are under negotiation. State lives on the offer, not the session. See CLEARINGHOUSE.md Section 6.4.

State Description
proposed Beacon submitted offer with terms. Awaiting Scout response.
countered One party submitted a counter-proposal. Awaiting other party’s response.
accepted Both parties agree on terms. Offer eligible for commitment.
rejected One party rejected terms without counter. Offer closed for negotiation.

Constraints: Maximum 3 negotiation rounds. Protocol minimums enforced on every counter-proposal. A Scout may counter multiple offers simultaneously. Counter-proposals are signed by the proposing agent. Commitment is only accepted against offers in accepted (or proposed if terms_negotiable is false, meaning take-it-or-leave-it).

4.5 Session State Machine

4.5.1 State Enumeration

The following states are enforced by AURA Core. States marked terminal are absorbing — no outbound transitions are permitted.

State Category Description
collecting_offers Active Session created, intent parsed, Beacons invited to submit offers. This is the initial state — intent interpretation and Beacon discovery occur synchronously during session creation.
offers_available Active At least one Beacon has submitted an offer. Scout may browse offers, commit, or cancel.
committed Active Scout committed to an offer. Transaction created, fulfillment and payment tracking begin.
fulfilled Active Beacon reported fulfillment as delivered but payment has not yet been charged.
completed Terminal Both fulfillment (delivered) and payment (charged) confirmed. Session lifecycle ends.
cancelled Terminal Scout cancelled the session before committing.
expired Terminal Session exceeded its expires_at deadline without reaching a terminal state. Auto-enforced on every read and write.
risk_assessed Active (Phase 7) Clearinghouse bilateral risk scoring complete. Reserve margin calculated. Business rules validated. Transaction proceeds to authorization.
authorized Active (Phase 7) Payment pre-approved (wallet hold, card auth, or credit check). Beacon authorization received. Transaction locked pending settlement.
settling Active (Phase 7) Settlement in progress. Payment transfer submitted to rail adapter. No fulfillment changes permitted until settled.
settled Active (Phase 7) Payment confirmed by settlement rail. Escrow or custody hold active. Fulfillment can now proceed.
disputed Active A transaction participant has raised a dispute. The transaction is frozen — no fulfillment or payment status changes are permitted until the dispute is resolved. Reachable from committed, fulfilled, completed, or settled.
resolved Terminal A dispute has been adjudicated and the resolution enforced. The resolution outcome (upheld, rejected, partial) and any remedial actions are recorded on the transaction.
cleared Terminal (Phase 7) Dispute window expired with no dispute filed, or dispute resolved. Risk reserve released (minus fees/losses). This is the true financial terminal state.
failed Terminal Unrecoverable error. Includes settlement failures that cannot be retried.

Reserved states (not yet implemented): created, interpreting, discovering were defined in v1.0 for an asynchronous interpretation pipeline. The current Core API performs intent parsing and Beacon matching synchronously during POST /sessions, so sessions enter collecting_offers directly. These states are reserved for future async implementations and MUST NOT be used by current integrators. offers_ready and transaction_pending from v1.0 have been renamed to offers_available and committed respectively to match the production implementation.

4.5.2 State Transition Table

Every legal state transition is listed below. Transitions not in this table are rejected by Core API. The Source column identifies the enforcement point in the reference implementation.

# Current State Event Next State Guard Conditions Source
T1 (none) POST /sessions collecting_offers Valid intent string, authenticated agent sessions.js — INSERT with status collecting_offers
T2 collecting_offers POST /sessions/:id/offers (first offer) offers_available Session not expired; Beacon active offers.js — UPDATE status to offers_available
T3 offers_available POST /sessions/:id/offers (subsequent offer) offers_available Session not expired; Beacon active offers.js — status already offers_available, remains
T4 collecting_offers GET /sessions/:id (offers exist) offers_available Pending offers found in database sessions.js — auto-promote on read
T5 collecting_offers POST /sessions/:id/cancel cancelled Agent owns session; status NOT IN (committed, completed) sessions.js — UPDATE with ownership + status predicate
T6 offers_available POST /sessions/:id/cancel cancelled Agent owns session; status NOT IN (committed, completed) sessions.js — UPDATE with ownership + status predicate
T7 offers_available POST /sessions/:id/commit committed Agent owns session; session not expired; status NOT IN (committed, completed, cancelled); offer exists and belongs to session; idempotency key is unique UUID transactions.js — atomic INSERT transaction + UPDATE session within FOR UPDATE lock
T8 committed PUT /transactions/:id/fulfillment (delivered, payment pending) fulfilled Requester is transaction participant; fulfillment_status set to delivered; payment_status ≠ charged transactions.js — conditional status assignment
T9 committed PUT /transactions/:id/fulfillment (delivered, payment charged) completed Requester is transaction participant; fulfillment_status set to delivered; payment_status = charged transactions.js — atomic dual-condition check
T10 committed PUT /transactions/:id/payment (charged, fulfillment delivered) completed Requester is transaction participant; payment_status set to charged; fulfillment_status = delivered transactions.js — atomic dual-condition check
T11 fulfilled PUT /transactions/:id/payment (charged) completed Requester is transaction participant; payment_status set to charged; fulfillment_status = delivered transactions.js — atomic dual-condition check
T12 collecting_offers, offers_available Auto-expiry (read or write) expired expires_at < NOW(); status NOT IN (completed, cancelled, expired) sessions.js, offers.js, transactions.js — checked on every session access
T13 committed POST /transactions/:id/disputes disputed Requester is transaction participant (Scout principal or Beacon principal); dispute reason provided; transaction not already disputed disputes.js — INSERT dispute + UPDATE session status
T14 fulfilled POST /transactions/:id/disputes disputed Same as T13 disputes.js
T15 completed POST /transactions/:id/disputes disputed Same as T13; transaction completed within dispute window (completed_at + dispute_window > NOW()) disputes.js — additional time-bound guard
T16 disputed POST /disputes/:id/resolve (resolution applied) resolved Resolver has adjudication authority; resolution includes outcome and remedial actions disputes.js — UPDATE dispute + session status
T17 disputed POST /disputes/:id/resolve (dispute withdrawn) previous state Dispute initiator withdraws; no evidence from counterparty yet; returns session to pre-dispute state disputes.js — restore previous session status
T18 committed Clearinghouse risk assessment complete risk_assessed (Phase 7) Bilateral risk score computed; reserve margin calculated; business rules validated clearing.js — INSERT clearing_transaction + risk assessment
T19 risk_assessed Payment pre-authorization confirmed authorized (Phase 7) Wallet hold or card auth confirmed; Beacon business rules passed; settlement wallet verified clearing.js — UPDATE clearing_status
T20 authorized Settlement instruction submitted to rail settling (Phase 7) Settlement orchestrator submits instruction to configured rail adapter settlement.js — INSERT settlement_instruction
T21 settling Settlement confirmed by rail settled (Phase 7) Rail adapter confirms transfer complete (on-chain confirmation, card capture, or bank confirmation) settlement.js — UPDATE clearing_status; INSERT reserve_ledger (margin_hold)
T22 settled Beacon reports fulfillment delivered fulfilled (Phase 7) fulfillment_status set to delivered; clearing_status = settled transactions.js — conditional on clearing_status
T23 fulfilled Dispute window expires, no dispute filed cleared (Phase 7) dispute_term_expires_at < NOW(); no active dispute clearing.js — auto-check on access; INSERT reserve_ledger (margin_release)
T24 completed Dispute window expires, no dispute filed cleared (Phase 7) Same as T23 clearing.js — auto-check on access
T25 resolved Reserve released or drawn per outcome cleared (Phase 7) Dispute adjudicated; reserve action completed clearing.js — INSERT reserve_ledger (margin_release or dispute_payout)

Phase 7 clearing path: When the clearinghouse is active, committed transactions follow the extended path: committed → risk_assessed → authorized → settling → settled → fulfilled → cleared. Without the clearinghouse (pre-Phase 7), the existing path (committed → fulfilled → completed) remains valid. The clearing states are additive — existing integrators are unaffected until clearinghouse participation is enabled.

Note on auto-expiry: Transition T12 is enforced lazily — Core does not run a background reaper. Expiry is checked and applied on every GET /sessions/:id, POST /sessions/:id/offers, and POST /sessions/:id/commit. A session past its deadline will not transition to expired until its next access.

Idempotency: Transition T7 (commit) is idempotent. If the same idempotency_key is submitted twice, Core returns the existing transaction without creating a duplicate. This is enforced by a unique constraint on transactions.idempotency_key.

4.5.3 HATEOAS Affordances by State

The _links object in session and transaction responses varies by state, telling the integrator which actions are available. This table documents the conditional link logic.

State self offers commit cancel transaction
collecting_offers Yes No No Yes No
collecting_offers (offers exist) Yes Yes Yes Yes No
offers_available Yes Yes Yes Yes No
committed Yes No No No Yes
risk_assessed (Phase 7) Yes No No No Yes
authorized (Phase 7) Yes No No No Yes
settling (Phase 7) Yes No No No Yes
settled (Phase 7) Yes No No No Yes
fulfilled Yes No No No Yes
completed Yes No No No Yes
cleared (Phase 7) Yes No No No Yes
cancelled Yes No No No No
disputed Yes No No No Yes
resolved Yes No No No Yes
expired Yes No No No No

Transaction-level links (returned by GET /transactions/:id):

Link When Present
self Always
session Always
fulfillment Status NOT IN (disputed, resolved)
payment Status NOT IN (disputed, resolved)
dispute Status IN (committed, fulfilled, completed) — POST to initiate
dispute_details Status IN (disputed, resolved) — GET to view dispute
evidence Status = disputed and requester is a participant — POST to submit evidence
resolve Status = disputed and requester has adjudication authority
clearing_status (Phase 7) Status IN (risk_assessed, authorized, settling, settled, cleared) — GET to view clearing details
settlement_status (Phase 7) Status IN (settling, settled, cleared) — GET to view settlement confirmation

Integrator guidance: Follow _links to discover available actions. If a link is absent, the action is not valid in the current state. Do not hard-code endpoint URLs — use the href values from _links to navigate the session lifecycle.