# AURA Protocol

AURA is a market protocol for agentic commerce. Buyer agents and seller agents transact through a neutral broker that interprets intent, mediates the exchange, and records the outcome.

Agentic commerce needs a broker because two agents that both have a stake in the price cannot safely tell each other the truth. Each probes the other and conceals its own position, and the market decays into a market for lemons with cheap, unenforceable quotes. A party with no stake can hold both sides' private information at once and resolve the asymmetry. That party is Core.

Every function here follows from that. A Scout declares intent. Core interprets it and presents sealed offers from Beacons. The buyer commits to one, Core binds the commitment and signs the chain of custody from the human signal to the outcome, and a clearing record carries the transaction to settlement. Each operation is the smallest mechanism that preserves a market invariant, and the invariants are stated in `x-aura-invariants`.

This document is the canonical AURA protocol, written for humans and for agents. The paths and schemas are the wire contract; the `x-aura-*` extensions carry the protocol's law, ontology, and economics in machine-readable form. The published JSON Schemas, the SDKs, and the interactive reference derive from it.

## How to read this specification

**Precedence (what wins in a conflict, highest first):**

- OpenAPI paths, operations and schemas
- x-aura-* normative extensions
- descriptions
- implementation metadata

**Status vocabulary:** normative, implemented, reserved, roadmap, explanatory, deprecated.

**Normative language:** RFC2119.

## Design principles

Why the protocol has this shape. Each principle justifies a family of invariants. The principles explain; the invariants govern.

### Principles

#### Privacy by design

**Statement:** Counterparty identity and constraints are disclosed only when the protocol phase requires them.

**Supports:**

- Identity abstraction until commitment
- Monotonic disclosure

#### Business rules as gates

**Statement:** Binary eligibility rules are enforced before any scoring or settlement economics.

**Supports:**

- Business rules as hard gates

#### Atomicity over partial state

**Statement:** A transaction commits in full or leaves no residue.

**Supports:**

- Atomic commitment

#### Verifiable provenance

**Statement:** Every consequential step is signed and can be reconstructed after the fact.

**Supports:**

- Recorded intent and chain of custody
- Verifiable settlement

#### Neutrality of the broker

**Statement:** Core mediates the trade without holding a position in it.

**Supports:**

- Neutral brokerage
- Financial neutrality of the clearinghouse

#### Explicit authority

**Statement:** An agent acts only within authority a principal has delegated and recorded.

**Supports:**

- Constraints as bounds
- Persistent identity and qualification
- Least-privilege delegated authority

## Invariants

The rules every conforming market upholds. Each operation manifests one or more of them.

### Neutral brokerage

Core MUST mediate every Scout and Beacon interaction. A conforming Core MUST NOT expose an unmediated bilateral channel for protocol offers.

Two agents that both have a stake in the price cannot safely exchange information. Direct trade collapses into a market for lemons with cheap, unenforceable quotes. Only a party with no stake can hold both sides’ private information without abusing it.

### Identity abstraction until commitment

Core MUST withhold each party’s identity from the other until commitment. A Beacon MUST NOT receive the Scout’s identity before the transaction commits.

An agent that knows who it faces prices the counterparty instead of the goods. Hidden identity forces competition on the offer and produces genuine price discovery.

### Monotonic disclosure

Information disclosed to a party MUST only increase as commitment deepens. No phase MAY reveal less than a prior phase.

If disclosure can retract, a party hoards information defensively and the market goes opaque. A one-way ratchet lets each side reveal exactly enough, exactly when the commitment justifies it.

### Constraints as bounds

Hard constraints define the authorised negotiation space. A conforming Scout, Core, or Beacon MUST NOT treat a hard constraint as a ranking preference, and Core MUST reject a commitment that exceeds one.

A hard constraint is the principal’s delegated authority boundary. A commitment beyond it exceeds the mandate the principal granted. Treating constraints as bounds keeps agents inside that mandate.

### Offer expiry

Every offer MUST carry an expiry. Core MUST refuse to commit an expired offer.

Free, open-ended options let an agent reserve everywhere and commit nowhere. An expiry turns the negotiation into discrete rounds and ends the speed race.

### Atomic commitment

Commitment MUST be atomic. Committing to one offer MUST reject its siblings in the same transaction, with no observable intermediate state.

If commitment is not atomic, a concurrent reader sees capacity reserved twice and the same offer taken by two parties. One indivisible step makes a commitment mean exactly one thing.

### Persistent identity and qualification

Agents MUST hold a persistent Ed25519 identity established by proof of possession. A new identity MUST start below the participation threshold.

Cooperation needs the shadow of the future. If identities are free and disposable, a defector simply re-registers. A non-trivial identity with a cost of entry gives every participant something to lose.

### Recorded intent and chain of custody

Core MUST record the original intent and assemble a signed chain of custody from the human signal to the outcome. The chain MUST be immutable once written.

A commitment with no record of how it was reached cannot be adjudicated. A signed chain makes every step attributable, so the market enforces commitments rather than relitigating them.

### Verifiable settlement

Clearing MUST advance to settled only on a verifiable, non-repudiable proof of settlement correlated to the original instruction.

Settlement taken on trust fails the first dishonest counterparty. A signed proof from the rail makes finality a fact the protocol can check rather than a claim it must accept.

### Rail-conditional reserve

Core MUST size a reserve conditioned on the rail. A rail with native repudiation MUST NOT carry a duplicative AURA hold; a rail without it MUST.

Where the rail can reverse a charge, a second hold is waste. Where it cannot, an unreserved loss is unrecoverable. Sizing the reserve to the rail puts protection exactly where the infrastructure leaves a gap.

### Financial neutrality of the clearinghouse

The clearinghouse MUST hold no commercial position. It MUST NOT rank offers, select beacons, or negotiate terms.

A clearer that takes a side prices its own book into every settlement. Neutrality at the financial layer is the same law as neutral brokerage, carried into the money.

### Bilateral risk transparency

Risk MUST be assessed for both parties, and each party MUST see only the assessment that applies to it.

Risk priced in secret is risk a party cannot contest. Showing each side its own assessment makes the price legible without leaking the counterparty’s position.

### Business rules as hard gates

Binary business rules MUST be enforced as pass or fail gates, separate from continuous risk scoring. A perfect risk score MUST NOT satisfy a failed gate.

If a hard rule can be bought down by a good score, it is no longer a rule. Keeping gates separate from scoring stops a margin adjustment from eroding a compliance requirement.

### Repudiability within a bounded window

A committed transaction MUST be repudiable for a declared, pre-committed window, adjudicated against the recorded intent chain with participant-filtered evidence. A market MUST NOT set no window.

A commitment that cannot be challenged is a commitment a bad actor keeps. A bounded, pre-declared dispute window makes repudiation orderly and finite, which is what lets the other side trust the commit in the first place.

### Least-privilege delegated authority

An agent MUST act only within an explicit, signed authority claim that chains to a durable principal in at most three tiers, and a delegation MUST NOT grant more authority than the granter holds.

Authority an agent assumes by membership is authority no principal granted. A claim that names what the agent may do, on which resources, and what it may see, chained to a durable principal and narrowing at every hop, holds the agent inside its mandate and keeps one agent blind to another's work. Core verifies the claim and trusts the action without governing the counterparty.

## Authority and claim model

How a principal grants and bounds an agent's authority, and how Core verifies a presented authority claim without governing the counterparty's interior. A commitment is valid only within the authority the principal delegated; a hard constraint is an authority boundary (Constraints as bounds). Authority is least-privilege and narrows down a signed delegation chain to a durable principal (Least-privilege delegated authority).

**Boundary:** Core verifies a presented, signed claim against a root of trust. It does not model or govern the counterparty's internal agent hierarchy. Authentication proves the agent holds its key; the claim authorises the specific action and visibility. These are separate steps.

**Agent As Marker:** An agent's key is a marker, an index into a durable record. Trust reads the chain, the principal, and the evidence (Recorded intent and chain of custody), so an agent may be ephemeral.

### Capacity

**Definition:** How an agent declares who it acts for. One value per agent, machine-readable, presented with every claim. The vocabulary aligns with the Janus reference architecture for interoperability.

#### Values

##### agent_for_principal

**Definition:** The agent acts on a named principal's authority and inherits the bounds the principal granted.

##### principal_direct

**Definition:** The agent acts on its own authority. A non-human root of authority lives here.

##### platform_delegated

**Definition:** The agent acts on a platform's authority while interacting with principals.

### Claim

**Definition:** What a Scout or Beacon presents so Core can authorise an action. Core verifies it as a relying party.

**Parts:**

- capacity
- envelope
- delegationChain

### Dials

**Definition:** What a grant fixes. Least-privilege is the default: an agent with no grant can do and see nothing.

**Actions:** The operations the agent may perform.

**Resources:** The resources the agent may touch.

**Visibility:** What the agent may read, a separate dial, so observe-only and act-without-sight are both expressible.

**Bounds:** The signed envelope: amount, category, counterparty, geography, time, escalation threshold.

### Delegation Chain

**Definition:** How authority passes from a principal to an agent and onward to the sub-agents it spawns.

**Max Tiers:** 3

**Tiers:**

- principal
- agent
- sub-agents

**Attenuation:** A delegation grants no more than the granter holds. Authority only narrows down the chain.

**Carries:**

- scope
- validity_window
- revocation_path

**Verification:** Signed end to end and verifiable back to the named principal.

### Consent Tiers

#### explicit

**Definition:** The principal signs the specific action.

#### policy

**Definition:** The action is permitted by a principal-defined policy the agent cites.

#### delegated

**Definition:** The action falls within a standing delegation scope the principal granted.

### Delegation Scope

**Definition:** The bounded authority an agent holds for a principal.

**Bounded By:**

- hard_constraints
- consent_tier
- principal_approval
- market_profile
- resource_scope
- visibility_scope

**Governs:**

- commitSession
- counterOffer

### Authority Attestation

**Definition:** Proof presented at commit that the action is within authority.

**Required At:** commitSession

**Carries:**

- consent_tier
- scope_reference
- principal_signature_or_policy_citation

### Principal Approval

**Definition:** An explicit principal decision captured for an action that exceeds standing authority.

**Required When:** the action exceeds the delegation scope or a market-profile approval threshold

### External Credential Interop

**Definition:** Delegation may be expressed with an external verifiable-credential format, carried as a signed claim.

**Manifests:**

- Constraints as bounds
- Least-privilege delegated authority

## Market model

Why the protocol has this shape. The market model explains; the invariants govern.

**Ontological Claim:** Software agents are not subject to bounded rationality. A market whose participants can follow the rules can be designed to produce the outcomes economic theory predicts for rational agents, as a structural property rather than a tendency.

**Market Not Shop:** AURA models a market, not a shop: intent, discovery, negotiation, commitment, settlement. Agents negotiate; they do not browse.

### Foundations

#### Repeated-game cooperation

**Author:** Axelrod

**Claim:** Cooperation emerges among self-interested agents when interactions repeat, behaviour is observable, and retaliation is cheap.

#### The market for lemons

**Author:** Akerlof

**Claim:** Asymmetric quality information drives good sellers out unless credible quality signals exist.

#### Mechanism design

**Author:** Hurwicz, Myerson, Maskin

**Claim:** Rules can be designed so that rational, self-interested behaviour produces desirable outcomes.

### Microstructure Problems

#### adverse_selection

**Resolved By:**

- Neutral brokerage
- Persistent identity and qualification

#### information_probing

**Resolved By:**

- Identity abstraction until commitment
- Monotonic disclosure
- Constraints as bounds

#### strategic_non_commitment

**Resolved By:**

- Offer expiry
- Atomic commitment
- Repudiability within a bounded window

### Algorithmic Price Dynamics

#### collusive_equilibrium

**Resolution:** The neutral broker removes the bilateral channel two pricing algorithms would converge through.

**Resolved By:**

- Neutral brokerage

#### oscillation

**Resolution:** Offer expiry makes negotiation discrete, ending the continuous feedback loop.

**Resolved By:**

- Offer expiry

#### asymmetric_exploitation

**Resolution:** Neither algorithm observes the other's response function; Core mediates.

**Resolved By:**

- Neutral brokerage

**Fix Analogy:** Like FIX, the protocol standardises the negotiation layer and leaves settlement and clearing to specialised systems. Invariant mechanics carry market-specific parameters set per market.

**Computable Market Conditions:**

- Participants are rational within their delegated scope.
- The rules are enforced structurally, not behaviourally.
- A neutral intermediary holds canonical state and breaks bilateral dynamics.

## Market parameters

The dials a market sets within the law. Each parameter is bounded by an invariant; a market chooses a value within that bound. These map to the market-profile primitive.

### Parameters

#### disclosure_schedule

**Definition:** Per-field, per-phase disclosure tiers.

**Bounded By:**

- Identity abstraction until commitment
- Monotonic disclosure

#### offer_validity_window

**Definition:** How long an offer remains committable.

**Bounded By:**

- Offer expiry

#### qualification_threshold

**Definition:** Minimum reputation to participate.

**Bounded By:**

- Persistent identity and qualification

#### dispute_window_days

**Definition:** How long a committed transaction is repudiable. A market may not set zero.

**Bounded By:**

- Repudiability within a bounded window

#### settlement_method

**Definition:** The rail used to settle.

**Bounded By:**

- Verifiable settlement

#### reserve_strategy

**Definition:** How the reserve margin is sized.

**Bounded By:**

- Rail-conditional reserve

#### risk_model

**Definition:** How bilateral risk is scored.

**Bounded By:**

- Bilateral risk transparency

#### business_rule_set

**Definition:** The hard gates a beacon defines.

**Bounded By:**

- Business rules as hard gates

## Reputation

Reputation is the credible quality signal that keeps good sellers in the market. The dimensions and the transparency model are public; the scoring is proprietary and excluded from the contract.

**Rationale:** A single score is gameable, collapses dimensions, and ossifies into an incumbency moat. Multi-dimensional signals computed from protocol events resist gaming and let a counterparty judge fit rather than a number.

### Public

#### Dimensions

##### fulfilment_reliability

**Definition:** Share of commitments honoured, weighted by recency.

##### offer_accuracy

**Definition:** Gap between what was offered and what was delivered.

##### constraint_fidelity

**Definition:** How often a Beacon's declared capabilities match the constraints it satisfies.

##### negotiation_integrity

**Definition:** Rate of offer withdrawal, price change after commitment, and reneged terms.

##### response_relevance

**Definition:** Match between Scout intent and Beacon offer.

**Transparency Model:** Each dimension is independently queryable and computed from protocol events, not self-reported.

**Attaches To:**

- Principal
- Beacon

### Proprietary

**Scoring Formula:** excluded

**Weighting Model:** excluded

**Operational Parameters:** excluded

**Supports:**

- Persistent identity and qualification

## Conformance

How a conforming implementation is verified. Each profile lists the invariants a role must honour; the testable assertions live on those invariants (their conformance[]). A third party runs the assertions to certify a Core.

### Profiles

#### core-minimal

**Description:** The session, offer, commitment, identity, and intent-chain laws every Core must honour.

**Requires Invariants:**

- Neutral brokerage
- Identity abstraction until commitment
- Monotonic disclosure
- Constraints as bounds
- Offer expiry
- Atomic commitment
- Persistent identity and qualification
- Recorded intent and chain of custody
- Least-privilege delegated authority

#### core-clearing

**Description:** The clearing, settlement, reserve, neutrality, risk, business-rule, and repudiability laws a clearing Core must honour.

**Requires Invariants:**

- Verifiable settlement
- Rail-conditional reserve
- Financial neutrality of the clearinghouse
- Bilateral risk transparency
- Business rules as hard gates
- Repudiability within a bounded window

#### beacon-minimal

**Description:** What a conforming Beacon must honour: signed, time-bound offers, with its identity withheld until commitment.

**Requires Invariants:**

- Identity abstraction until commitment
- Offer expiry

**Requires Signature Profiles:**

- beacon_offer

#### scout-minimal

**Description:** What a conforming Scout must honour: stay within delegated authority and commit atomically.

**Requires Invariants:**

- Constraints as bounds
- Atomic commitment

**Assertion Source:** x-aura-invariants[].conformance

### Assertion Types

**Positive:** A valid flow that must succeed.

**Negative:** A forbidden input that must be rejected.

**Property:** An invariant that must hold across states.

**Sequence:** An ordering or atomicity that must hold across steps.

## State machines

### Session

**Description:** Session lifecycle. Terminal states are absorbing. The clearing lifecycle is a separate machine and never changes the session status.

#### Read Semantics

**Description:** Some transitions are materialised lazily. Their condition becomes true on its own (an offer exists, an expiry elapses), and the next read or write that observes the session persists the change. A read can therefore materialise a pending transition today. The protocol event is the condition, not the request that observes it. Making safe-method reads free of side effects is a roadmap item.

**Lazy Transitions:**

- T4
- T12

**Initial:** collecting_offers

#### States

##### collecting_offers

**Category:** active

##### offers_available

**Category:** active

##### committed

**Category:** active

##### fulfilled

**Category:** active

##### completed

**Category:** active

**Absorbing:** false

**Note:** Disputable within the dispute window; otherwise the clearing record advances to cleared.

##### disputed

**Category:** active

##### resolved

**Category:** terminal

##### cancelled

**Category:** terminal

##### expired

**Category:** terminal

##### failed

**Category:** terminal

**Reserved:** true

**Reserved States:**

- created
- interpreting
- discovering

#### Transitions

##### T1

**Event:** POST /v1/sessions

**Guard:** Valid intent string; authenticated agent

##### collecting_offers → offers_available

**Event:** POST /v1/sessions/{session_id}/offers (first offer)

**Guard:** Session not expired; Beacon active

##### offers_available → offers_available

**Event:** POST /v1/sessions/{session_id}/offers (subsequent)

**Guard:** Session not expired; Beacon active

##### collecting_offers → offers_available

**Event:** First valid offer observed

**Guard:** Pending offers found

**Materialisation:** lazy_allowed

**Observed By:**

- GET /v1/sessions/{session_id}

##### collecting_offers → cancelled

**Event:** POST /v1/sessions/{session_id}/cancel

**Guard:** Owner; status NOT IN (committed, completed)

##### offers_available → cancelled

**Event:** POST /v1/sessions/{session_id}/cancel

**Guard:** Owner; status NOT IN (committed, completed)

##### offers_available → committed

**Event:** POST /v1/sessions/{session_id}/commit

**Guard:** Owner; not expired; offer belongs to session; unique idempotency key

##### committed → fulfilled

**Event:** PUT /v1/transactions/{transaction_id}/fulfillment (delivered, payment pending)

**Guard:** Participant; fulfillment_status=delivered; payment_status != charged

##### committed → completed

**Event:** PUT /v1/transactions/{transaction_id}/fulfillment (delivered, payment charged)

**Guard:** Participant; fulfillment_status=delivered; payment_status=charged

##### committed → completed

**Event:** PUT /v1/transactions/{transaction_id}/payment (charged, fulfillment delivered)

**Guard:** Participant; payment_status=charged; fulfillment_status=delivered

##### fulfilled → completed

**Event:** PUT /v1/transactions/{transaction_id}/payment (charged)

**Guard:** Participant; payment_status=charged; fulfillment_status=delivered

##### collecting_offers,offers_available → expired

**Event:** Session expiry elapsed

**Guard:** expires_at < NOW(); status NOT IN (completed, cancelled, expired)

**Materialisation:** lazy_allowed

**Observed By:**

- GET /v1/sessions/{session_id}
- POST /v1/sessions/{session_id}/commit

##### committed → disputed

**Event:** POST /v1/transactions/{transaction_id}/disputes

**Guard:** Participant; reason provided; not already disputed

##### fulfilled → disputed

**Event:** POST /v1/transactions/{transaction_id}/disputes

**Guard:** As T13

##### completed → disputed

**Event:** POST /v1/transactions/{transaction_id}/disputes

**Guard:** As T13; within dispute window (completed_at + dispute_window > NOW())

##### disputed → resolved

**Event:** POST /v1/disputes/{dispute_id}/resolve (resolution applied)

**Guard:** Adjudication authority; outcome + remedial actions

##### disputed → previous_state

**Event:** POST /v1/disputes/{dispute_id}/resolve (withdrawn)

**Dynamic:** true

**Guard:** Initiator withdraws; no counterparty evidence; restores pre-dispute state

#### Affordances

**Description:** HATEOAS _links available per state. Integrators follow _links to discover valid actions; an absent link means the action is not valid in that state.

##### Session Links By State

**Collecting offers:**

- self
- cancel
- offers
- commit

**Offers available:**

- self
- offers
- commit
- cancel

**Committed:**

- self
- transaction

**Fulfilled:**

- self
- transaction

**Completed:**

- self
- transaction

**Disputed:**

- self
- transaction

**Resolved:**

- self
- transaction

**Cancelled:**

- self

**Expired:**

- self

##### Session Link Notes

**Collecting offers:** offers and commit appear only once pending offers exist; self and cancel always.

##### Transaction Links

**Self:** Always

**Session:** Always

**Fulfillment:** Status NOT IN (disputed, resolved)

**Payment:** Status NOT IN (disputed, resolved)

**Dispute:** Status IN (committed, fulfilled, completed)

**Dispute details:** Status IN (disputed, resolved)

**Evidence:** Status = disputed and requester is a participant

**Resolve:** Status = disputed and requester has adjudication authority

**Clearing status:** Clearing record clearing_status IN (risk_assessed, authorized, settling, settled, dispute_term_active, cleared)

**Settlement status:** Clearing record clearing_status IN (settling, settled, cleared)

### Clearing

**Description:** Clearing lifecycle for a committed transaction, a separate machine from the session lifecycle. It never changes the session status. The cleared and failed states are terminal. Advanced by the system-only clearing-status operation.

**Initial:** pending

#### States

##### pending

##### risk_assessed

##### authorized

##### settling

##### settled

##### dispute_term_active

##### disputed

##### resolved

##### cleared

**Category:** terminal

##### failed

**Category:** terminal

#### Transitions

**Pending:**

- risk_assessed
- failed

**Risk assessed:**

- authorized
- disputed
- failed

**Authorized:**

- settling
- disputed
- failed

**Settling:**

- settled
- disputed
- failed

**Settled:**

- dispute_term_active
- cleared
- disputed

**Dispute term active:**

- cleared
- disputed

**Disputed:**

- resolved

**Resolved:**

- cleared
- settled

**Cleared:**

**Failed:**

## Signature profiles

Every signature in the protocol follows one of these named profiles. Each profile names what is signed, how the payload is assembled, and which operations it applies to.

**Algorithm:** Ed25519

### Profiles

#### authenticated_request

**Description:** Proof that an authenticated request was issued by the holder of the agent key.

##### Applies To

**Operations:**

- all agent-authenticated operations

**Signed Material:**

- method
- path
- timestamp
- body_hash

**Required Headers:**

- X-Agent-Id
- X-Agent-Timestamp
- X-Agent-Signature

#### principal_registration

**Description:** Proof of possession of the principal key at registration.

##### Applies To

**Operations:**

- registerPrincipal

**Signed Material:**

- canonical_request_body

**Required Headers:**

- X-Signature

#### agent_registration

**Description:** Proof of possession of the agent key at registration.

##### Applies To

**Operations:**

- registerAgent

**Signed Material:**

- canonical_request_body

**Required Headers:**

- X-Agent-Signature

#### beacon_offer

**Description:** A Beacon's signature binding it to the terms of an offer.

##### Applies To

**Operations:**

- submitOffer

**Delimiter:** `LF` (U+000A)

**Encoding:** UTF-8

**Payload Fields:**

- offer_id
- beacon_id
- product_id
- offer_price
- currency
- valid_until
- payment_terms_hash

##### Notes

**Offer price:** Decimal string, max two decimal places, no trailing zeros (e.g. "349.99").

**Payment terms hash:** SHA-256 of JSON.stringify(payment_terms, sorted keys). Omitted for offers without payment terms, making valid_until the final line.

**Verification:** Core verifies the Beacon's registered Ed25519 public key.

##### Example

**Description:** Worked example of the assembled, newline-delimited payload a Beacon signs (illustrative field values).

###### Fields

**Offer id:** ofr_01HF8X2K9P

**Beacon id:** bcn_42q7r1

**Product id:** prod_widget_9

**Offer price:** 349.99

**Currency:** USD

**Valid until:** 2026-07-01T00:00:00Z

**Payment terms hash:** 9f86d0818...

**Payload:**

```
ofr_01HF8X2K9P
bcn_42q7r1
prod_widget_9
349.99
USD
2026-07-01T00:00:00Z
9f86d0818...
```

#### core_offer_countersignature

**Description:** Core counter-signs an accepted offer at commit: it re-verifies the Beacon signature, then signs CORE-COUNTERSIGN, the canonical offer payload, and the Beacon signature with its own key. The counter-signature is recorded on the transaction and proves Core observed and accepted the signed offer.

##### Applies To

**Operations:**

- commitSession

**Prefix:** CORE-COUNTERSIGN

#### interpretation_attestation

**Description:** Core's signed binding between the raw intent and its structured interpretation.

##### Applies To

**Operations:**

- createSession
- getAttestation

**Signed Material:**

- raw_intent
- structured_interpretation
- model_id

#### intent_chain_link

**Description:** A signature on one link of the intent chain, chained to its predecessor.

##### Applies To

**Operations:**

- submitChainLink

**Signed Material:**

- link
- payload
- previous_link_hash

#### assembled_intent_chain

**Description:** Core's signature over the assembled chain at commit.

##### Applies To

**Operations:**

- getIntentChain

**Signed Material:**

- ordered_link_hashes

## Intent chain

Intent-to-commitment chain of custody: up to seven signed links tracing a transaction from the human signal to the outcome. Assembled by Core at commit; immutable. Beacons receive a redacted view.

### Links

#### principal_signal

**Signer:** scout_agent

**Proves:** Scout received the principal's input and forwarded it faithfully.

**Source:** Scout SDK at session creation

#### interpretation

**Signer:** core

**Proves:** Core bound raw input to structured output via a specific model.

**Source:** Interpretation attestation

#### principal_review

**Signer:** scout_agent

**Proves:** Principal saw the interpretation and did not object, or was declared not consulted.

**Source:** Scout SDK after interpretation

#### offer_selection

**Signer:** scout_agent

**Proves:** The agent selected this offer from the available set.

**Source:** Scout SDK at offer selection

#### principal_consent

**Signer:** scout_agent_or_principal

**Proves:** Principal consented: explicit signature, cited policy, or cited delegation scope.

**Source:** Authority attestation

#### commitment

**Signer:** core

**Proves:** Core executed the atomic commit; counter-signature confirms authority verified and recorded.

**Source:** Core at commit

#### outcome

**Signer:** core

**Proves:** Terminal state: fulfillment/payment status or dispute resolution outcome.

**Source:** Core at completion or dispute resolution

**Beacon Redacted View:**

- L2
- L4
- L6
- L7

## Vocabulary

Canonical definitions of the protocol's terms.

- **Scout**: An autonomous agent acting for a buyer.
- **Beacon**: An autonomous agent acting for a seller.
- **AURA Core**: The neutral broker. It interprets intent, routes it to beacons, mediates the exchange, and records the outcome. It holds no commercial position.
- **Principal**: The human or legal entity an agent acts for under delegated authority.
- **Session**: A logical exchange from a scout's request to a committed transaction.
- **Request**: A scout's expression of need: a natural-language intent and optional constraints.
- **Interpreted Request**: Core's structured representation of a scout's intent.
- **Offer**: A beacon's signed response carrying product, price, and terms.
- **Constraint**: A buyer's declared bound on an acceptable outcome. A hard constraint binds. A soft preference ranks.
- **Transaction**: A committed exchange between a scout and a beacon.
- **Clearing record**: The financial lifecycle of a committed transaction: risk assessment, reserve, and settlement.
- **Intent chain**: The signed chain of custody from the human signal to the outcome, links L1 to L7.
- **Reputation**: A multi-dimensional behavioural signal Core computes from protocol events.
- **Settlement rail**: An external payment system that moves funds for a cleared transaction.
- **Market profile**: A named set of market parameters a Core applies within the protocol's invariants.

### Entities

The protocol's entities, their roles, relationships, and prohibitions. Tooling and agents reason over this model; humans read the glossary.

- **Scout** (agent): An agent acting for a buyer.
- **Beacon** (agent): An agent acting for a seller.
- **Core** (neutral_broker): The disinterested party that mediates every exchange.
- **Principal** (party): The human or legal entity an agent acts for.
- **Session** (resource): An exchange from request to commitment.
- **Offer** (resource): A beacon's signed, sealed response.
- **Transaction** (resource): A committed exchange.
- **ClearingRecord** (resource): The financial lifecycle of a transaction.
- **IntentChain** (record): The signed chain of custody from signal to outcome.
- **Request** (signal): A Scout's expression of need.
- **InterpretedRequest** (derived_record): Core's structured representation of the Scout's intent.
- **Constraint** (authority_boundary): A declared bound on an acceptable outcome. A hard constraint binds; a soft preference ranks.
- **Reputation** (behavioural_signal): A multi-dimensional behavioural signal Core computes from protocol events.

## Authentication

Every operation requires the following by default, unless its own entry says otherwise: agentId, agentTimestamp, agentSignature.

- **agentId** (apiKey, in header as `X-Agent-Id`): The agent's UUID. Sent together with X-Agent-Timestamp and X-Agent-Signature; the three authenticate a request (see x-aura-signature-profiles.authenticated_request).
- **agentTimestamp** (apiKey, in header as `X-Agent-Timestamp`): RFC 3339 timestamp. Sent together with X-Agent-Id and X-Agent-Signature.
- **agentSignature** (apiKey, in header as `X-Agent-Signature`): Ed25519 signature over the canonical request (method, path, timestamp, body hash). Sent together with X-Agent-Id and X-Agent-Timestamp; all three are required.
- **agentProof** (apiKey, in header as `X-Agent-Signature`): Proof-of-possession for agent registration: Ed25519 signature over the request body, proving control of the submitted public key.
- **principalProof** (apiKey, in header as `X-Signature`): Proof-of-possession for principal registration: Ed25519 signature over the request body.
- **systemToken** (apiKey, in header as `X-System-Token`): System-only shared secret for internal lifecycle endpoints. Not issued to client integrations.

## Operations

### Discovery

Public capability discovery: profiles, settlement rails, signing key, and HATEOAS roots.

#### GET /: API version discovery (HATEOAS root)

An agent that has never seen this market needs a way in that asks nothing of it first. The root advertises the protocol version and the links to follow, so discovery comes before any credential or commitment.

**Authentication:** public (no authentication).

**Responses:**

- `200`: object

#### GET /v1/: v1 HATEOAS root

The entry point for v1. It lists the operations an agent reaches from here, so a client navigates the protocol by following links rather than hard-coding paths.

**Authentication:** public (no authentication).

**Responses:**

- `200`: object

#### GET /v1/.well-known/core-signing-key: Core's Ed25519 public signing key

Core counter-signs offers and attestations, so a counterparty has to check those signatures without taking Core's word for its own key. The signing key is published openly for exactly that, which is what lets Core act as a [neutral broker](https://aura-labs.ai/invariants.html#neutral-brokerage) whose every signature is independently verifiable.

**Authentication:** public (no authentication).

**Responses:**

- `200`: object

#### GET /v1/profiles: List active market profiles

A market adapts the protocol to its vertical by setting bounded parameters: how long offers stay live, how long a deal stays repudiable, which rails settle it. Profiles publish those choices so an agent reads the terms before it enters. The parameters move within bounds the [invariants](/invariants.html) fix; they never tune the law away.

**Authentication:** public (no authentication).

**Responses:**

- `200`: object

#### GET /v1/profiles/{profile_id}: Retrieve a market profile

Returns one market profile in full: the disclosure schedule, validity windows, settlement methods, and dispute terms a participant agrees to by transacting under it. An agent reads this to know the rules of the specific market it is entering.

**Authentication:** public (no authentication).

**Responses:**

- `200`: Profile
- `404`: NotFound

#### POST /v1/profiles/{profile_id}/validate: Validate terms against a profile's minimums

Before building against a market, an agent should learn whether a configuration is admissible under the profile rather than discovering it at commit. This checks a candidate against the profile's rules and returns the verdict.

**Authentication:** public (no authentication).

**Request body:** ProfileValidationRequest.

**Responses:**

- `200`: object

#### GET /v1/settlement-rails: List active settlement-rail adapters

Settlement is where value actually moves, and rails differ in finality and recourse. Publishing the available rails lets a market and its agents choose settlement with open eyes, which is what makes [rail-conditional reserve](https://aura-labs.ai/invariants.html#rail-conditional-reserve) and [verifiable settlement](https://aura-labs.ai/invariants.html#verifiable-settlement) computable rather than guessed.

**Authentication:** public (no authentication).

**Responses:**

- `200`: object

#### GET /v1/settlement-rails/{adapter_id}/capabilities: Get a settlement adapter's capabilities

Returns one rail's capabilities: its finality model, whether it carries native repudiation, and the proof it emits. Clearing reads this to size the reserve to the rail ([rail-conditional reserve](https://aura-labs.ai/invariants.html#rail-conditional-reserve)) and to demand a correlated settlement proof ([verifiable settlement](https://aura-labs.ai/invariants.html#verifiable-settlement)).

**Authentication:** public (no authentication).

**Responses:**

- `200`: SettlementRail
- `404`: NotFound

### Identity

Principal (legal entity) and agent (Scout/Beacon) registration and lookup.

#### POST /v1/principals: Register a principal (legal entity)

A market for lemons is what you get when a seller can shed a bad reputation by registering again. The principal is the durable, accountable entity behind the ephemeral agents, and registering it with a proof of key possession is what makes reputation and qualification stick to something that cannot be cheaply discarded ([persistent identity and qualification](https://aura-labs.ai/invariants.html#persistent-identity-and-qualification)).

**Authentication:** principalProof.

**Signature profile:** principal_registration.

**Request body:** PrincipalRegistration.

**Responses:**

- `200`: Principal
- `201`: Principal
- `400`: BadRequest

#### GET /v1/principals/{principal_id}: Retrieve a principal

A principal's record is the accountable root the rest of the protocol chains back to. Reading it is scoped to the entity acting on its own anchor ([least-privilege delegated authority](https://aura-labs.ai/invariants.html#least-privilege-delegated-authority)): a caller sees its own principal, never another's.

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Responses:**

- `200`: Principal
- `404`: NotFound

#### PUT /v1/principals/{principal_id}: Update a principal's mutable fields

A principal's contact and operating name change over time; its legal identity and verification history are fixed. Update accepts the mutable fields and refuses the immutable ones, and only the entity acting on its own anchor may call it ([least-privilege delegated authority](https://aura-labs.ai/invariants.html#least-privilege-delegated-authority)).

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Request body:** PrincipalUpdate.

**Responses:**

- `200`: Principal
- `400`: BadRequest
- `404`: NotFound

#### POST /v1/agents/register: Register an agent (Scout or Beacon)

An agent is a key, and a key is cheap. What makes an agent trustworthy is the durable principal it acts for. Registration binds the agent's key to a principal with a proof of possession, so every action the agent takes inherits an accountable identity ([persistent identity and qualification](https://aura-labs.ai/invariants.html#persistent-identity-and-qualification)).

**Authentication:** agentProof.

**Signature profile:** agent_registration.

**Request body:** AgentRegistration.

**Responses:**

- `200`: Agent
- `201`: Agent
- `400`: BadRequest

#### GET /v1/agents/{agent_id}: Get agent details

An agent is a marker that indexes a durable record, so a counterparty has to resolve what an agent is and whose authority it carries. This returns the agent's type, status, and principal binding, scoped to the caller's own anchor ([least-privilege delegated authority](https://aura-labs.ai/invariants.html#least-privilege-delegated-authority)).

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Responses:**

- `200`: Agent
- `404`: NotFound

#### GET /v1/principals/{principal_id}/agents: List a principal's agents

A principal may run many agents. Listing them is an administrative view of the entity's own roster, available only to the entity acting on its own anchor ([least-privilege delegated authority](https://aura-labs.ai/invariants.html#least-privilege-delegated-authority)); one agent cannot enumerate another principal's fleet.

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Responses:**

- `200`: object
- `404`: NotFound

#### GET /v1/principals/{principal_id}/transactions: List transactions a principal is party to

Accountability outlives any single agent or session, so a principal has to see what was committed in its name after the fact. This returns the transactions the principal is party to, scoped to its own anchor ([least-privilege delegated authority](https://aura-labs.ai/invariants.html#least-privilege-delegated-authority)).

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Responses:**

- `200`: object
- `404`: NotFound

#### POST /v1/agents/{agent_id}/revoke: Revoke an agent identity

When an agent misbehaves or its key is compromised, the harm has to be stoppable without unwinding the principal behind it. Revocation blacklists the agent's key so its future requests are refused, while the principal and its history persist ([persistent identity and qualification](https://aura-labs.ai/invariants.html#persistent-identity-and-qualification)).

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Request body:** object.

**Responses:**

- `200`: object
- `401`: Unauthorized
- `404`: NotFound

#### GET /v1/agents/{agent_id}/delegation-scope: Get the active delegation scope

Authority an agent assumes by default is authority no principal granted. The delegation scope is the explicit, signed boundary a principal sets on what an agent may commit. Reading it is how [least-privilege delegated authority](https://aura-labs.ai/invariants.html#least-privilege-delegated-authority) becomes inspectable.

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Responses:**

- `200`: DelegationScope
- `401`: Unauthorized
- `403`: Forbidden
- `404`: NotFound

#### PUT /v1/agents/{agent_id}/delegation-scope: Create or replace the active delegation scope

A principal narrows what its agents may do by setting their scope, never by trusting them to stay in bounds on their own. Writing the scope fixes the signed mandate a commit is later tested against ([least-privilege delegated authority](https://aura-labs.ai/invariants.html#least-privilege-delegated-authority), [constraints as bounds](https://aura-labs.ai/invariants.html#constraints-as-bounds)).

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Request body:** DelegationScopeRequest.

**Responses:**

- `200`: DelegationScope
- `400`: BadRequest
- `401`: Unauthorized
- `403`: Forbidden
- `404`: NotFound

### Market Navigation

Commerce sessions and offers, the core Scout/Beacon flow.

#### POST /v1/sessions: Create a commerce session from intent

A buyer's intent has to enter the market somewhere. Sent straight to sellers, it hands them the buyer's position to probe and price against, and it leaves no neutral account of what was asked. The session is where Core takes the intent instead: it interprets the natural language, signs an attestation binding the raw words to their structured meaning, and stands in the middle as [neutral broker](https://aura-labs.ai/invariants.html#neutral-brokerage) rather than wiring the two sides together, recording the intent from its origin ([recorded intent and chain of custody](https://aura-labs.ai/invariants.html#recorded-intent-and-chain-of-custody)). The interpretation fixes the authorised negotiation space before any offer exists, so a later commitment can be tested against the mandate the principal actually granted ([constraints as bounds](https://aura-labs.ai/invariants.html#constraints-as-bounds)).

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Signature profile:** interpretation_attestation.

**Request body:** SessionCreate.

**Responses:**

- `200`: Session
- `400`: BadRequest
- `401`: Unauthorized

#### GET /v1/sessions/{session_id}: Retrieve a session

A Scout watches its session to know when offers are ready and what state it is in. What it sees respects [identity abstraction until commitment](https://aura-labs.ai/invariants.html#identity-abstraction-until-commitment), so a counterparty's identity stays sealed, and [monotonic disclosure](https://aura-labs.ai/invariants.html#monotonic-disclosure), so a field once visible never vanishes. Reading the session never leaks what the phase has not yet earned.

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Responses:**

- `200`: Session
- `401`: Unauthorized
- `403`: Forbidden
- `404`: NotFound

#### GET /v1/sessions/{session_id}/offers: List pending offers (Scout)

Offers are what a Scout chooses between, and seeing them must not become a way to unmask sellers early. This returns the session's offers under [identity abstraction until commitment](https://aura-labs.ai/invariants.html#identity-abstraction-until-commitment) and [monotonic disclosure](https://aura-labs.ai/invariants.html#monotonic-disclosure): the terms are visible, the counterparty behind them is not, until commitment earns it.

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Responses:**

- `200`: object
- `401`: Unauthorized
- `403`: Forbidden

#### POST /v1/sessions/{session_id}/offers: Submit a signed offer (Beacon)

An offer is a seller's commitment to terms, and a market is only as real as that commitment. A bare price is cheap to send and cheaper to retract. So the Beacon signs the offer with its key, Core verifies it and counter-signs as [neutral broker](https://aura-labs.ai/invariants.html#neutral-brokerage), and the offer carries an [expiry](https://aura-labs.ai/invariants.html#offer-expiry) from the moment it exists. The buyer's identity stays sealed while this happens ([identity abstraction until commitment](https://aura-labs.ai/invariants.html#identity-abstraction-until-commitment)), so the seller prices the goods and not the counterparty, and the terms are checked against the session's [bounds](https://aura-labs.ai/invariants.html#constraints-as-bounds).

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Signature profile:** beacon_offer.

**Request body:** OfferSubmission.

**Responses:**

- `201`: Offer
- `400`: BadRequest
- `401`: Unauthorized

#### POST /v1/sessions/{session_id}/cancel: Cancel a session

A Scout that no longer wants what it asked for needs a clean exit before it commits, so abandoned sessions do not linger as phantom demand. Cancel closes a session the caller owns, provided it has not already committed.

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Responses:**

- `200`: object
- `401`: Unauthorized
- `403`: Forbidden
- `404`: NotFound

#### GET /v1/sessions/{session_id}/attestation: Get the interpretation attestation

When Core interprets a natural-language intent, the buyer has to be able to prove later what Core understood it to mean. The attestation is Core's signed binding between the raw words and their structured interpretation, the first link in the [recorded chain of custody](https://aura-labs.ai/invariants.html#recorded-intent-and-chain-of-custody).

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Signature profile:** interpretation_attestation.

**Responses:**

- `200`: Attestation
- `401`: Unauthorized
- `403`: Forbidden
- `404`: NotFound

#### POST /v1/offers/{offer_id}/counter: Counter an offer (Scout)

Negotiation moves in bounded, finite steps. A counter-offer answers with revised terms that still sit inside the session's [constraints](https://aura-labs.ai/invariants.html#constraints-as-bounds) and carries its own [expiry](https://aura-labs.ai/invariants.html#offer-expiry), so each round stays within the mandate and stays finite.

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Request body:** CounterOfferRequest.

**Responses:**

- `201`: NegotiatedOffer
- `400`: BadRequest
- `401`: Unauthorized
- `403`: Forbidden
- `429`: Error

### Transactions

Commit, retrieve, and report on transactions.

#### POST /v1/sessions/{session_id}/commit: Commit to an offer

Commitment is the single irreversible step, so it is where every guarantee has to hold at once. A naive accept that just flips a flag invites the failures a market cannot survive: committing on a price that has [expired](https://aura-labs.ai/invariants.html#offer-expiry), exceeding the [authority the principal delegated](https://aura-labs.ai/invariants.html#constraints-as-bounds), or leaving half a transaction behind when something fails midway. Commit refuses all of them in one [atomic act](https://aura-labs.ai/invariants.html#atomic-commitment): it checks the offer is live and within the mandate, records consent and extends the [signed chain of custody](https://aura-labs.ai/invariants.html#recorded-intent-and-chain-of-custody), and either creates the transaction and rejects its siblings or changes nothing at all. Replaying an idempotency key returns the original result rather than committing twice. Then clearing begins, sizing the reserve to the rail ([rail-conditional reserve](https://aura-labs.ai/invariants.html#rail-conditional-reserve)) and refusing any failed [business rule](https://aura-labs.ai/invariants.html#business-rules-as-hard-gates).

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Signature profile:** core_offer_countersignature.

**Request body:** CommitRequest.

**Responses:**

- `200`: Transaction
- `400`: BadRequest
- `401`: Unauthorized
- `403`: Forbidden

#### GET /v1/transactions/{transaction_id}: Retrieve a transaction

A transaction is the durable record a dispute or an audit reads long after the session closes. This returns it: the committed terms, the counter-signatures, and the current fulfilment, payment, and clearing state.

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Responses:**

- `200`: Transaction
- `401`: Unauthorized
- `403`: Forbidden
- `404`: NotFound

#### PUT /v1/transactions/{transaction_id}/fulfillment: Report fulfillment status

A committed deal still has to be delivered. Fulfilment updates record delivery progress on the transaction, moving it toward completion or surfacing the gap a dispute would test.

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Request body:** FulfillmentUpdate.

**Responses:**

- `200`: object
- `400`: BadRequest
- `401`: Unauthorized
- `403`: Forbidden

#### PUT /v1/transactions/{transaction_id}/payment: Report payment status

Money moving has to leave a proof, or settlement becomes a claim nobody can check. A payment update records settlement against a rail-signed proof correlated to the instruction ([verifiable settlement](https://aura-labs.ai/invariants.html#verifiable-settlement)).

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Request body:** PaymentUpdate.

**Responses:**

- `200`: object
- `400`: BadRequest
- `401`: Unauthorized
- `403`: Forbidden

#### GET /v1/transactions/{transaction_id}/clearing: Read the clearing record

Clearing is where risk is priced and the reserve is held, and a market trusts it only if the pricing is neutral and legible. This exposes the clearing record: the [rail-conditional reserve](https://aura-labs.ai/invariants.html#rail-conditional-reserve), the [settlement proof](https://aura-labs.ai/invariants.html#verifiable-settlement), and a risk score that is a function of risk and rail alone ([financial neutrality of the clearinghouse](https://aura-labs.ai/invariants.html#financial-neutrality-of-the-clearinghouse)), shown only to the party it belongs to ([bilateral risk transparency](https://aura-labs.ai/invariants.html#bilateral-risk-transparency)).

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Responses:**

- `200`: ClearingRecord
- `401`: Unauthorized
- `403`: Forbidden
- `404`: NotFound

### Beacons

Beacon (seller agent) registration and open-session discovery.

#### POST /v1/beacons/register: Register or update a beacon

A seller's agent has to be discoverable to be matched, but discoverability without accountability invites throwaway offers. Registering a Beacon publishes its categories and capabilities while binding it to a principal, so the market can match it and still hold it answerable.

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Request body:** BeaconRegistration.

**Responses:**

- `200`: Beacon
- `400`: BadRequest
- `401`: Unauthorized
- `403`: Forbidden

#### GET /v1/beacons/sessions: Poll open sessions to bid on

A Beacon needs to know which sessions it has been matched into before it can make an offer. This lists the open sessions awaiting the Beacon's response.

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Parameters:**

- `status` (query):
- `limit` (query):

**Responses:**

- `200`: object
- `401`: Unauthorized

#### GET /v1/beacons/{beacon_id}: Get a beacon

Matching and reputation operate on what a Beacon claims it can do. This returns a Beacon's public profile so a counterparty knows its declared capabilities.

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Responses:**

- `200`: Beacon
- `401`: Unauthorized
- `404`: NotFound

### Business Rules

Beacon-defined business rules (age, geo, KYC).

#### GET /v1/business-rules: List a beacon's active rules

A Beacon's hard eligibility rules decide who it will deal with at all, so they have to be inspectable. This lists the business rules a Beacon has in force.

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Parameters:**

- `beacon_id` (query, required):

**Responses:**

- `200`: object
- `401`: Unauthorized
- `403`: Forbidden

#### POST /v1/business-rules: Register a business rule (Beacon)

Some conditions decide whether a deal is allowed at all, ahead of any pricing: an age minimum, a geographic restriction, a verification requirement. A business rule registers such a gate, and Core refuses any commit that fails it however attractive the price ([business rules as hard gates](https://aura-labs.ai/invariants.html#business-rules-as-hard-gates)).

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Parameters:**

- `Idempotency-Key` (header):

**Request body:** BusinessRuleCreate.

**Responses:**

- `200`: BusinessRule
- `201`: BusinessRule
- `400`: BadRequest
- `401`: Unauthorized
- `403`: Forbidden

#### DELETE /v1/business-rules/{rule_id}: Revoke a business rule

Eligibility rules change as a Beacon's obligations change. Revoking a rule retires the gate going forward while leaving the committed transactions it once governed untouched, so the record of why a past deal was allowed stays intact.

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Responses:**

- `204`: Revoked (no content)
- `401`: Unauthorized
- `403`: Forbidden
- `404`: NotFound

### Disputes

Dispute filing, evidence, and resolution.

#### POST /v1/transactions/{transaction_id}/disputes: File a dispute

A market that calls every settled deal final has no recourse, and agents will not commit real money without it. Filing a dispute reopens a committed transaction within the window the market declared before commitment ([repudiability within a bounded window](https://aura-labs.ai/invariants.html#repudiability-within-a-bounded-window)), turning finality without recourse into accountable settlement.

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Request body:** DisputeFile.

**Responses:**

- `201`: Dispute
- `400`: BadRequest
- `401`: Unauthorized
- `403`: Forbidden

#### POST /v1/disputes/{dispute_id}/evidence: Submit dispute evidence

A dispute is resolved on evidence, and the strongest evidence is already in the protocol: the signed offer, the commitment, the fulfilment record. This attaches a party's evidence to an open dispute, inside its [bounded window](https://aura-labs.ai/invariants.html#repudiability-within-a-bounded-window).

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Request body:** EvidenceSubmission.

**Responses:**

- `201`: object
- `400`: BadRequest
- `401`: Unauthorized
- `403`: Forbidden

#### POST /v1/disputes/{dispute_id}/resolve: Resolve or withdraw a dispute

A reopened transaction has to reach a definite end, or repudiability becomes limbo. Resolution applies an outcome (upheld, rejected, partial, or withdrawn) to a dispute filed inside its [window](https://aura-labs.ai/invariants.html#repudiability-within-a-bounded-window) and closes it.

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Request body:** DisputeResolution.

**Responses:**

- `200`: Dispute
- `400`: BadRequest
- `401`: Unauthorized
- `403`: Forbidden

#### GET /v1/disputes/{dispute_id}: Retrieve a dispute

A dispute's state and the evidence on both sides have to be visible to its participants to be trusted. This returns the dispute with its protocol evidence, for a transaction still inside its [repudiable window](https://aura-labs.ai/invariants.html#repudiability-within-a-bounded-window).

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Responses:**

- `200`: Dispute
- `401`: Unauthorized
- `403`: Forbidden
- `404`: NotFound

### Intent Chain

Intent chain of custody, L1–L7.

#### POST /v1/sessions/{session_id}/chain-links: Submit the L3 (principal review) chain link

Who decided what, and in what order, is the whole of accountability when agents act for principals. A chain link adds one signed step to the intent's [chain of custody](https://aura-labs.ai/invariants.html#recorded-intent-and-chain-of-custody), each link bound to its predecessor so the record cannot be reordered or forged after the fact.

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Signature profile:** intent_chain_link.

**Request body:** ChainLinkSubmission.

**Responses:**

- `201`: object
- `400`: BadRequest
- `401`: Unauthorized
- `403`: Forbidden

#### GET /v1/transactions/{transaction_id}/intent-chain: Retrieve the assembled intent chain

After the fact, a dispute or an audit has to replay exactly how an intent became a commitment. This returns the assembled [chain of custody](https://aura-labs.ai/invariants.html#recorded-intent-and-chain-of-custody) for a transaction, every link signed by the party responsible for it.

**Authentication:** agentId + agentTimestamp + agentSignature (default).

**Signature profile:** assembled_intent_chain.

**Responses:**

- `200`: IntentChain
- `401`: Unauthorized
- `403`: Forbidden
- `404`: NotFound

## Error catalogue

Every error response carries a stable, machine-readable code in its `error` field. This catalogue is the closed set Core emits: each code maps to the HTTP status it accompanies, whether the same request is safe to retry, a category, a human-readable meaning, and where relevant the invariant it protects. Codes are stable identifiers; messages are explanatory.

- **auth**: Authentication and key validity.
- **authorization**: The caller is authenticated but not permitted to act on the resource.
- **validation**: The request failed a contract or field-level check.
- **not_found**: The addressed resource does not exist or is not visible to the caller.
- **state**: The resource is in a state that does not allow the action.
- **conflict**: The action conflicts with existing state (idempotency, duplicates).
- **rate_limit**: The caller has exceeded a rate limit.
- **operational**: A transient server or dependency error; the same request is safe to retry.

| Code | HTTP | Retryable | Category | Meaning |
| --- | --- | --- | --- | --- |
| `authentication_required` | 401 | no | auth | The request carried no valid agent authentication. Provide agentId, agentTimestamp, and agentSignature. (protects [Persistent identity and qualification](https://aura-labs.ai/invariants.html#persistent-identity-and-qualification)) |
| `beacon_no_signing_key` | 400 | no | auth | The Beacon has no registered signing key to verify against. |
| `invalid_offer_signature` | 400 | no | auth | The offer signature did not verify against the Beacon's registered key. (protects [Recorded intent and chain of custody](https://aura-labs.ai/invariants.html#recorded-intent-and-chain-of-custody)) |
| `invalid_signature` | 401 | no | auth | The agent signature did not verify against the registered key. (protects [Persistent identity and qualification](https://aura-labs.ai/invariants.html#persistent-identity-and-qualification)) |
| `key_revoked` | 403 | no | auth | The presented key has been revoked. (protects [Persistent identity and qualification](https://aura-labs.ai/invariants.html#persistent-identity-and-qualification)) |
| `missing_offer_signature` | 400 | no | auth | The offer was submitted without its required signature. (protects [Recorded intent and chain of custody](https://aura-labs.ai/invariants.html#recorded-intent-and-chain-of-custody)) |
| `missing_signature` | 401 | no | auth | A required authentication signature header was absent. |
| `cross_beacon_access_denied` | 403 | no | authorization | A Beacon may only access its own sessions and offers. (protects [Identity abstraction until commitment](https://aura-labs.ai/invariants.html#identity-abstraction-until-commitment)) |
| `cross_scout_access_denied` | 403 | no | authorization | A Scout may only access its own sessions. (protects [Identity abstraction until commitment](https://aura-labs.ai/invariants.html#identity-abstraction-until-commitment)) |
| `forbidden` | 403 | no | authorization | The authenticated agent may not act on this resource. |
| `not_filing_agent` | 403 | no | authorization | Only the agent that filed the dispute may take this action. |
| `scout_cannot_register_rules` | 403 | no | authorization | Scouts may not register business rules. (protects [Business rules as hard gates](https://aura-labs.ai/invariants.html#business-rules-as-hard-gates)) |
| `system_role_required` | 403 | no | authorization | This operation requires the system role. |
| `dispute_already_exists` | 409 | no | conflict | A dispute already exists for this transaction. |
| `duplicate_transaction` | 409 | no | conflict | A transaction already exists for this commitment; the commit is idempotent. (protects [Atomic commitment](https://aura-labs.ai/invariants.html#atomic-commitment)) |
| `adapter_not_found` | 404 | no | not_found | The requested resource was not found. |
| `beacon_not_found` | 404 | no | not_found | The requested resource was not found. |
| `clearing_not_found` | 404 | no | not_found | The requested resource was not found. |
| `not_found` | 404 | no | not_found | The requested resource was not found. |
| `offer_not_found` | 404 | no | not_found | The requested resource was not found. |
| `principal_not_found` | 404 | no | not_found | The requested resource was not found. |
| `profile_not_found` | 404 | no | not_found | The requested resource was not found. |
| `rule_not_found` | 404 | no | not_found | The requested resource was not found. |
| `session_not_found` | 404 | no | not_found | The requested resource was not found. |
| `transaction_not_found` | 404 | no | not_found | The requested resource was not found. |
| `cancel_failed` | 500 | yes | operational | The operation could not be completed due to a server error. Safe to retry. |
| `chain_fetch_failed` | 503 | yes | operational | A backend dependency was temporarily unavailable. Retry with backoff. |
| `commit_failed` | 500 | yes | operational | The operation could not be completed due to a server error. Safe to retry. |
| `database_unavailable` | 503 | yes | operational | A backend dependency was temporarily unavailable. Retry with backoff. |
| `dispute_filing_failed` | 500 | yes | operational | The operation could not be completed due to a server error. Safe to retry. |
| `evidence_submission_failed` | 500 | yes | operational | The operation could not be completed due to a server error. Safe to retry. |
| `fetch_failed` | 503 | yes | operational | A backend dependency was temporarily unavailable. Retry with backoff. |
| `offer_submission_failed` | 500 | yes | operational | The operation could not be completed due to a server error. Safe to retry. |
| `profile_unavailable` | 503 | yes | operational | A backend dependency was temporarily unavailable. Retry with backoff. |
| `registration_failed` | 500 | yes | operational | The operation could not be completed due to a server error. Safe to retry. |
| `resolution_failed` | 500 | yes | operational | The operation could not be completed due to a server error. Safe to retry. |
| `revocation_failed` | 500 | yes | operational | The operation could not be completed due to a server error. Safe to retry. |
| `scope_creation_failed` | 500 | yes | operational | The operation could not be completed due to a server error. Safe to retry. |
| `session_creation_failed` | 500 | yes | operational | The operation could not be completed due to a server error. Safe to retry. |
| `update_failed` | 500 | yes | operational | The operation could not be completed due to a server error. Safe to retry. |
| `rate_limit_exceeded` | 429 | yes | rate_limit | Too many requests. Retry after the indicated delay. |
| `beacon_cannot_counter` | 409 | no | state | The Beacon cannot submit a counter-offer here. |
| `beacon_inactive` | 403 | no | state | The Beacon is not active. |
| `cannot_cancel` | 409 | no | state | The session cannot be cancelled in its current state. |
| `cannot_withdraw` | 409 | no | state | The offer cannot be withdrawn in its current state. |
| `consent_elevation_required` | 403 | no | state | The action requires a higher consent tier than the delegation grants. (protects [Least-privilege delegated authority](https://aura-labs.ai/invariants.html#least-privilege-delegated-authority)) |
| `dispute_not_open` | 409 | no | state | The dispute is not open. |
| `dispute_window_expired` | 409 | no | state | The dispute window has closed. (protects [Repudiability within a bounded window](https://aura-labs.ai/invariants.html#repudiability-within-a-bounded-window)) |
| `evidence_deadline_passed` | 409 | no | state | The evidence submission deadline has passed. (protects [Repudiability within a bounded window](https://aura-labs.ai/invariants.html#repudiability-within-a-bounded-window)) |
| `negotiation_exhausted` | 409 | no | state | The negotiation has reached its round limit. |
| `not_disputable` | 409 | no | state | The transaction is not in a disputable state. (protects [Repudiability within a bounded window](https://aura-labs.ai/invariants.html#repudiability-within-a-bounded-window)) |
| `offer_not_counterable` | 409 | no | state | The offer cannot be countered in its current state. |
| `principal_inactive` | 403 | no | state | The principal is not active. |
| `session_expired` | 409 | no | state | The session has expired and no longer accepts actions. |
| `session_not_accepting_offers` | 409 | no | state | The session is not accepting offers in its current state. |
| `session_not_committable` | 409 | no | state | The session is not in a committable state. (protects [Atomic commitment](https://aura-labs.ai/invariants.html#atomic-commitment)) |
| `session_not_negotiable` | 409 | no | state | The session is not in a negotiable state. |
| `transaction_frozen` | 409 | no | state | Fulfilment and payment updates are frozen while the transaction is disputed. (protects [Repudiability within a bounded window](https://aura-labs.ai/invariants.html#repudiability-within-a-bounded-window)) |
| `chain_link_failed` | 400 | no | validation | The intent-chain link could not be appended. (protects [Recorded intent and chain of custody](https://aura-labs.ai/invariants.html#recorded-intent-and-chain-of-custody)) |
| `chain_validation_failed` | 400 | no | validation | The submitted intent-chain link did not validate. (protects [Recorded intent and chain of custody](https://aura-labs.ai/invariants.html#recorded-intent-and-chain-of-custody)) |
| `default_profile_missing` | 400 | no | validation | The request was rejected by a contract or business-rule check. |
| `invalid_adapter_id` | 400 | no | validation | A request field was missing or failed validation. |
| `invalid_beacon_id` | 400 | no | validation | A request field was missing or failed validation. |
| `invalid_capacity` | 400 | no | validation | A request field was missing or failed validation. |
| `invalid_clearinghouse_terms` | 400 | no | validation | A request field was missing or failed validation. |
| `invalid_consent_requirements` | 400 | no | validation | A request field was missing or failed validation. |
| `invalid_constraints` | 400 | no | validation | A request field was missing or failed validation. |
| `invalid_endpoint_url` | 400 | no | validation | A request field was missing or failed validation. |
| `invalid_field` | 400 | no | validation | A request field was missing or failed validation. |
| `invalid_fulfillment_terms` | 400 | no | validation | A request field was missing or failed validation. |
| `invalid_idempotency_key` | 400 | no | validation | The Idempotency-Key header was malformed. |
| `invalid_key` | 400 | no | validation | A request field was missing or failed validation. |
| `invalid_offer_id` | 400 | no | validation | A request field was missing or failed validation. |
| `invalid_parameter` | 400 | no | validation | A request field was missing or failed validation. |
| `invalid_price` | 400 | no | validation | A request field was missing or failed validation. |
| `invalid_profile_id` | 400 | no | validation | A request field was missing or failed validation. |
| `invalid_quantity` | 400 | no | validation | A request field was missing or failed validation. |
| `invalid_risk_tolerance` | 400 | no | validation | A request field was missing or failed validation. |
| `invalid_rule_id` | 400 | no | validation | A request field was missing or failed validation. |
| `invalid_settlement_preference` | 400 | no | validation | A request field was missing or failed validation. |
| `invalid_status` | 400 | no | validation | A request field was missing or failed validation. |
| `missing_beacon_id` | 400 | no | validation | A request field was missing or failed validation. |
| `missing_description` | 400 | no | validation | A request field was missing or failed validation. |
| `missing_fields` | 400 | no | validation | A request field was missing or failed validation. |
| `missing_payment_terms_hash` | 400 | no | validation | A request field was missing or failed validation. |
| `missing_to_status` | 400 | no | validation | A request field was missing or failed validation. |
| `no_chain` | 400 | no | validation | The request was rejected by a contract or business-rule check. |
| `no_changes` | 400 | no | validation | The request was rejected by a contract or business-rule check. |
| `no_scope` | 400 | no | validation | The request was rejected by a contract or business-rule check. |
| `payload_too_large` | 413 | no | validation | The request body exceeded the size limit. |
| `payment_terms_hash_mismatch` | 400 | no | validation | The payment terms hash did not match the signed offer. (protects [Recorded intent and chain of custody](https://aura-labs.ai/invariants.html#recorded-intent-and-chain-of-custody)) |
| `unknown_profile` | 400 | no | validation | The request was rejected by a contract or business-rule check. |

## Data shapes

The request and response objects referenced above.

### Error

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| error | string | yes | Machine-readable error code |
| message | string | no | Human-readable explanation |

### Link

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| href | string | no |  |
| method | string | no |  |

### Links

HATEOAS affordances keyed by relation.

### PriceRange

Reusable price range component.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| min | number | yes |  |
| max | number | yes |  |
| currency | string | no | ISO 4217 |

### Profile

Market profile governing dispute windows and settlement defaults.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| profile_id | string | no |  |
| profile_version | string | no | Version of this profile; pinned onto a session at creation as profile_version_at_creation. |
| display_name | string | no | Human-readable profile label. |
| description | string | no | Free-text summary of the market this profile governs. |
| market_context | string | no | The vertical or market context the profile applies to. |
| status | string | no | Profile lifecycle status; only active profiles are resolvable. |
| dispute_window_days_minimum | integer | no |  |
| dispute_window_days_default | integer | no |  |
| participation | object | no | Participation dimension: who may enter this market and under what conditions. |
| disclosure | object | no | Disclosure dimension: what parties must reveal to each other. |
| commitment | object | no | Commitment dimension: binding rules governing offers and commits. |
| risk | object | no | Risk dimension: risk-tiering and reserve parameters for this market. |
| schema | object | no | Schema overlays extending the base offer/intent shape for this market. |
| governance | object | no | Governance dimension: who may amend the profile and how. |
| metadata | object | no | Free-form profile metadata. |
| _links | Links | no |  |

### ProfileValidationRequest

Terms to pre-flight against a market profile's minimums.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| dispute_window_days | integer | yes |  |
| settlement_method | string | no |  |

### SettlementRail

Settlement-rail adapter and its capabilities.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| adapter_id | string | no |  |
| native_repudiation | boolean | no | Whether the rail provides native chargeback/repudiation. |
| capabilities | object | no |  |
| _links | Links | no |  |

### PrincipalRegistration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| principal_type | string [organization \| individual] | yes |  |
| legal_name | string | yes |  |
| jurisdiction | string | yes | ISO 3166 country code |
| public_key | string | yes | Base64 Ed25519 public key |
| operating_name | string | no |  |
| identifiers | object | no |  |
| contact | object | no |  |

### Principal

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| principal_id | string (uuid) | no |  |
| principal_type | string [organization \| individual] | no |  |
| verification_level | string | no |  |
| verification_status | string | no |  |
| registered_at | string (date-time) | no |  |
| _links | Links | no |  |

### AgentRegistration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| public_key | string | yes | Base64 Ed25519 public key |
| type | string [scout \| beacon] | yes |  |
| principal_id | string (uuid) | yes |  |
| capacity | string | no |  |
| manifest | object | no |  |

### Agent

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| agent_id | string (uuid) | no |  |
| status | string | no |  |
| key_id | string | no |  |
| manifest | object | no | The agent's self-declared capability manifest submitted at registration. |
| principal_id | string (uuid) | no |  |
| capacity | string | no |  |
| principal_verification_level | string,null | no | Verification level of the bound principal, resolved at read time; null when the agent has no principal. |
| registered_at | string (date-time) | no |  |
| last_seen_at | string,null (date-time) | no | Timestamp of the agent's most recent authenticated request; null until first seen. |
| _links | Links | no |  |

### PrincipalUpdate

Mutable principal fields. Immutable fields (legal_name, jurisdiction, principal_type, public_key, verification_level) are rejected with 400.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| operating_name | string | no |  |
| contact | object | no |  |
| identifiers | object | no |  |

### DelegationConstraints

Bounds on what the agent may transact under this scope.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| max_transaction_amount | number | no |  |
| currency | string | no | ISO 4217 |
| valid_from | string (date-time) | no |  |
| valid_until | string (date-time) | no |  |
| allowed_categories | array of string | no |  |
| blocked_categories | array of string | no |  |
| merchant_blocklist | array of string | no |  |
| require_principal_approval_above | number | no |  |

### DelegationScopeRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| consent_tier | string [explicit \| policy \| delegated] | yes |  |
| constraints | DelegationConstraints | yes |  |
| policy_definition | object | no |  |
| signed_by_principal | boolean | no |  |
| principal_signature | string | no |  |

### DelegationScope

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| scope_id | string | no |  |
| agent_id | string (uuid) | no |  |
| consent_tier | string [explicit \| policy \| delegated] | no |  |
| constraints | DelegationConstraints | no |  |
| policy_definition | object,null | no |  |
| signed_by_principal | boolean | no |  |
| status | string | no |  |
| created_at | string (date-time) | no |  |
| updated_at | string (date-time) | no |  |

### BeaconRegistration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| external_id | string | yes | Stable external identifier; the upsert key. |
| name | string | yes |  |
| description | string | no |  |
| endpoint_url | string (uri) | no | HTTPS, public hostname; SSRF-validated. |
| capabilities | object | no |  |
| metadata | object | no |  |

### Beacon

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| beacon_id | string (uuid) | no |  |
| external_id | string | no |  |
| name | string | no |  |
| status | string | no |  |
| capabilities | object | no |  |
| _links | Links | no |  |

### SessionSummary

Open session as seen by a beacon. Buyer constraints are redacted to categories only.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| session_id | string (uuid) | no |  |
| status | string | no |  |
| intent | object | no |  |
| constraints | object | no | Redacted to categories only. |

### SessionCreate

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| intent | string | yes | Natural-language buying intent. |
| constraints | object | no | Structured constraints (max 10KB). |
| completeness | object | no |  |
| chain_links | object | no | Optional L1 intent-chain link. |
| profile_id | string | no |  |
| settlement_preference | object | no |  |
| risk_tolerance | object | no |  |

### Session

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| session_id | string (uuid) | no |  |
| status | string | no |  |
| intent | object,null | no | Parsed intent. |
| raw_intent | string,null | no | The original unparsed intent string as submitted, returned on session retrieval. |
| profile_id | string | no |  |
| profile_version_at_creation | string | no |  |
| created_at | string (date-time) | no | Timestamp the session was created. |
| matched_beacons | array of object | no |  |
| _links | Links | no |  |

### Product

Product descriptor (free-form JSONB). 'name' is the canonical label; 'sku' optional. Additional vendor fields are permitted.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| name | string | no |  |
| sku | string | no |  |

### OfferSubmission

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| beacon_id | string | yes |  |
| product | Product \| string | yes | Product descriptor object, or a bare string treated as { name }. |
| unit_price | number | no |  |
| quantity | integer | no |  |
| total_price | number | no |  |
| currency | string | no |  |
| delivery_date | string (date) | no |  |
| terms | object | no |  |
| signature | string | yes | Beacon Ed25519 signature over the canonical offer. |
| payment_terms | PaymentTerms | no |  |
| payment_terms_hash | string | no | Base64 SHA-256 over canonical payment_terms (v2.4 attested path). |
| acting_for_principal_id | string (uuid) | no |  |
| consent_requirements | object | no |  |

### PaymentTerms

Offer payment terms (v2.4).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| dispute_window_days | integer | no |  |
| return_policy_days | integer | no |  |
| payment_timing | string | no |  |
| accepted_methods | array of string | no |  |

### Offer

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| offer_id | string (uuid) | no |  |
| session_id | string (uuid) | no |  |
| beacon_id | string | no |  |
| beacon_name | string | no | Display name of the beacon that submitted this offer, joined at read time. |
| status | string | no |  |
| product | Product | no |  |
| unit_price | number | no | Per-unit price of the offered product. |
| quantity | integer | no | Number of units offered. |
| total_price | number | no | Total price for the offered quantity. |
| currency | string | no | ISO 4217 currency of the offer prices. |
| delivery_date | string (date) | no | Committed delivery date for the offered goods. |
| terms | object | no | Free-form commercial terms attached to the offer. |
| metadata | object | no | Free-form offer metadata. |
| consent_requirements | object | no | Principal-consent requirements the offer attaches to the commit, when present. |
| payment_terms | PaymentTerms | no |  |
| payment_terms_hash | string | no |  |
| created_at | string (date-time) | no | Timestamp the offer was submitted. |
| signatures | object | no |  |
| _links | Links | no |  |

### CommitRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| offer_id | string (uuid) | yes |  |
| idempotency_key | string (uuid) | yes | UUID v4 for idempotent commit. |
| authority | object | no |  |
| chain_links | object | no | L4/L5 intent-chain links. |
| settlement_method | string | no |  |

### Transaction

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| transaction_id | string (uuid) | no |  |
| session_id | string (uuid) | no |  |
| offer_id | string (uuid) | no |  |
| beacon_id | string | no |  |
| beacon_name | string | no | Display name of the beacon party to the transaction. |
| agent_id | string (uuid) | no | Identity of the scout agent that owns the originating session. |
| status | string | no |  |
| final_terms | object | no |  |
| scout_principal | object,null | no | The scout side's principal reference, resolved at commit time; null when unbound. |
| beacon_principal | object,null | no | The beacon side's principal reference, resolved at commit time; null when unbound. |
| fulfillment_status | string | no | Current fulfillment state reported by the beacon. |
| fulfillment_reference | string | no | Beacon-supplied reference for the fulfillment (e.g. tracking or order id). |
| payment_status | string | no | Current payment state of the transaction. |
| payment_reference | string | no | Reference for the payment (e.g. settlement or rail transaction id). |
| created_at | string (date-time) | no | Timestamp the transaction was committed. |
| updated_at | string (date-time) | no | Timestamp of the transaction's most recent state change. |
| completed_at | string,null (date-time) | no | Timestamp the transaction reached a terminal completed state; null until then. |
| clearinghouse | object | no | Present when the rail is AURA-cleared. |
| _links | Links | no |  |

### Attestation

Core's signed interpretation attestation: a binding between the raw intent and its structured interpretation.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| type | string | no |  |
| session_id | string (uuid) | no |  |
| attestation_signature | string | no | Base64 Ed25519 over the canonical attestation. |
| core_key_id | string | no |  |

### CounterOfferRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| payment_terms | PaymentTerms | yes |  |
| unit_price | number | no |  |
| quantity | integer | no |  |
| product | Product \| string | no | Product descriptor object, or a bare string treated as { name }. Inherits the parent offer's product when omitted. |
| total_price | number | no |  |
| currency | string | no |  |

### NegotiatedOffer

An offer created by countering a parent offer.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| offer_id | string (uuid) | no |  |
| session_id | string (uuid) | no |  |
| beacon_id | string | no |  |
| parent_offer_id | string (uuid) | no |  |
| negotiation_status | string | no |  |
| depth | integer | no |  |
| payment_terms | PaymentTerms | no |  |
| payment_terms_hash | string | no |  |
| _links | Links | no |  |

### FulfillmentUpdate

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| fulfillment_status | string [pending \| processing \| shipped \| delivered \| failed] | yes |  |
| fulfillment_reference | string | no |  |

### PaymentUpdate

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| payment_status | string [pending \| authorized \| charged \| refunded \| failed] | yes |  |
| payment_reference | string | no |  |
| amount | number | no |  |
| currency | string | no |  |

### ClearingRecord

Clearing lifecycle record. Risk scores are filtered to the requesting party.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| clearing_id | string (uuid) | no |  |
| transaction_id | string (uuid) | no |  |
| clearing_status | string | no |  |
| reserve_status | string | no | State of the settlement reserve (e.g. rail_managed, held, released). |
| risk_tier | string | no | Overall risk tier assigned to the transaction. |
| risk_score | number,null | no | Aggregate transaction risk score. |
| scout_risk_score | number,null | no | Per-party risk score for the scout side. Returned only to the scout party; null to the counterparty. |
| beacon_risk_score | number,null | no | Per-party risk score for the beacon side. Returned only to the beacon party; null to the counterparty. |
| payment_method | string | no | Settlement rail / payment method used to clear the transaction. |
| reserve_margin_pct | number,null | no | Reserve margin held, as a percentage of the settlement amount (wire key for the risk_margin_pct column). |
| reserve_margin_amount | number,null | no | Reserve margin held, as an absolute amount (wire key for the risk_margin_amount column). |
| net_settlement_amount | number,null | no | Amount to be settled net of any reserve margin. |
| currency | string | no | ISO 4217 currency of the settlement amounts. |
| dispute_term_days | integer | no | Length of the dispute window in days for this clearing record. |
| dispute_term_expires_at | string,null (date-time) | no | Timestamp the dispute window closes. |
| authorized_at | string,null (date-time) | no | Timestamp the reserve/settlement was authorized. |
| settled_at | string,null (date-time) | no | Timestamp the transaction settled. |
| cleared_at | string,null (date-time) | no | Timestamp the reserve released and the record cleared. |
| created_at | string (date-time) | no | Timestamp the clearing record was created. |
| updated_at | string (date-time) | no | Timestamp of the clearing record's most recent state change. |
| _links | Links | no |  |

### BusinessRuleCreate

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| rule_type | string [age_minimum \| geo_restriction \| kyc_required \| custom] | yes |  |
| payload | object | no | Rule-type-specific (age_minimum: { min_age }; geo_restriction: { allow: [ISO-3166] }; kyc_required: { level }). |

### BusinessRule

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| id | string (uuid) | no |  |
| beacon_id | string (uuid) | no |  |
| rule_type | string | no |  |
| payload | object | no |  |
| created_at | string (date-time) | no |  |
| revoked_at | string,null (date-time) | no |  |

### DisputeFile

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| reason | string [product_not_as_described \| product_not_received \| product_damaged \| wrong_quantity \| unauthorized_transaction \| exceeded_delegation_scope \| payment_not_received \| payment_amount_incorrect \| duplicate_charge \| offer_terms_changed \| other] | yes |  |
| category | string [fulfillment \| payment \| product_quality \| authorization \| other] | yes |  |
| description | string | yes |  |
| evidence | array of object | no |  |
| requested_resolution | object | no |  |

### Dispute

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| dispute_id | string (uuid) | no |  |
| transaction_id | string (uuid) | no |  |
| status | string | no |  |
| filed_by | string (uuid) | no |  |
| filed_at | string (date-time) | no |  |
| reason | string | no |  |
| category | string | no |  |
| evidence_deadline | string (date-time) | no |  |
| resolution_deadline | string (date-time) | no |  |
| outcome | string | no |  |
| resolution | object,null | no |  |
| _links | Links | no |  |

### EvidenceSubmission

Composed of: object & object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| type | string [text \| document_reference \| external_record \| protocol_record] | yes |  |
| description | string | no | Required for type=text. |
| document_url | string (uri) | no | Required (with content_hash) for type=document_reference. |
| content_hash | string | no |  |
| external_system | string | no |  |
| external_reference | string | no |  |
| protocol_record_type | string | no |  |
| protocol_record_id | string | no |  |

### DisputeResolution

Composed of: object & object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| outcome | string [upheld \| rejected \| partial \| withdrawn] | yes |  |
| resolution | object | no |  |
| evidence_considered | array of string | no | Required unless outcome=withdrawn. |

### ChainLinkSubmission

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| link | string | yes |  |
| payload | object | yes |  |
| signature | string | yes | Ed25519 over the canonical link. |

### IntentChain

Assembled intent chain of custody (L1–L7). Beacons receive a redacted view (L2, L4, L6, L7).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| transaction_id | string (uuid) | no |  |
| session_id | string (uuid) | no |  |
| chain_status | string | no |  |
| links | array of object | no |  |
| chain_hash | string,null | no |  |
| chain_signature | string,null | no |  |

### Shared responses

- **BadRequest**: Invalid request (Error)
- **Unauthorized**: Missing or invalid agent authentication (Error)
- **Forbidden**: Authenticated but not authorized for this resource (Error)
- **NotFound**: Resource not found (Error)