{ "openapi": "3.1.0", "info": { "title": "AURA Core API", "version": "3.0.0", "summary": "Agent Universal Resource Architecture: the Core commerce API for Scout and Beacon agents.", "description": "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.\n\nAgentic 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.\n\nEvery 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`.\n\nThis 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.", "contact": { "name": "AURA Labs Developer Support", "email": "support@aura-labs.ai", "url": "https://aura-labs.ai/developers.html" }, "license": { "name": "See repository LICENSE", "url": "https://aura-labs.ai/terms.html" }, "x-protocol-version": "3.0" }, "servers": [ { "url": "https://aura-labsai-production.up.railway.app", "description": "Production Core API (host; all paths are /v1-prefixed)" }, { "url": "https://sandbox.aura-labs.ai", "description": "Sandbox (mock Core, gated; placeholder, not yet provisioned)" } ], "tags": [ { "name": "Discovery", "description": "Public capability discovery: profiles, settlement rails, signing key, and HATEOAS roots." }, { "name": "Identity", "description": "Principal (legal entity) and agent (Scout/Beacon) registration and lookup." }, { "name": "Market Navigation", "description": "Commerce sessions and offers, the core Scout/Beacon flow." }, { "name": "Transactions", "description": "Commit, retrieve, and report on transactions." }, { "name": "Beacons", "description": "Beacon (seller agent) registration and open-session discovery." }, { "name": "Business Rules", "description": "Beacon-defined business rules (age, geo, KYC)." }, { "name": "Disputes", "description": "Dispute filing, evidence, and resolution." }, { "name": "Intent Chain", "description": "Intent chain of custody, L1–L7." } ], "security": [ { "agentId": [], "agentTimestamp": [], "agentSignature": [] } ], "paths": { "/": { "get": { "tags": [ "Discovery" ], "summary": "API version discovery (HATEOAS root)", "operationId": "getRoot", "description": "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.", "security": [], "responses": { "200": { "description": "Available API versions and links", "content": { "application/json": { "schema": { "type": "object", "properties": { "protocol_version": { "type": "string", "description": "The AURA protocol version this deployment implements, advertised so an agent can confirm compatibility before following any link. Mirrors x-protocol-version.", "examples": [ "3.0" ] } } } } } } } } }, "/v1/": { "get": { "tags": [ "Discovery" ], "summary": "v1 HATEOAS root", "operationId": "getV1Root", "description": "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.", "security": [], "responses": { "200": { "description": "v1 resource links", "content": { "application/json": { "schema": { "type": "object", "properties": { "protocol_version": { "type": "string", "description": "The AURA protocol version this deployment implements, advertised so an agent can confirm compatibility before following any link. Mirrors x-protocol-version.", "examples": [ "3.0" ] } } } } } } } } }, "/v1/.well-known/core-signing-key": { "get": { "tags": [ "Discovery" ], "summary": "Core's Ed25519 public signing key", "operationId": "getCoreSigningKey", "description": "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](/invariants.html#neutral-brokerage) whose every signature is independently verifiable.", "security": [], "responses": { "200": { "description": "Core signing key", "content": { "application/json": { "schema": { "type": "object", "properties": { "public_key": { "type": "string", "description": "Base64-encoded Ed25519 public key" }, "algorithm": { "type": "string", "examples": [ "Ed25519" ] }, "is_ephemeral": { "type": "boolean" } } } } } } } } }, "/v1/profiles": { "get": { "tags": [ "Discovery" ], "summary": "List active market profiles", "operationId": "listProfiles", "description": "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.", "security": [], "responses": { "200": { "description": "Active profiles", "content": { "application/json": { "schema": { "type": "object", "properties": { "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/Profile" } } } } } } } } } }, "/v1/profiles/{profile_id}": { "parameters": [ { "$ref": "#/components/parameters/ProfileId" } ], "get": { "tags": [ "Discovery" ], "summary": "Retrieve a market profile", "operationId": "getProfile", "description": "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.", "security": [], "responses": { "200": { "description": "Profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/profiles/{profile_id}/validate": { "parameters": [ { "$ref": "#/components/parameters/ProfileId" } ], "post": { "tags": [ "Discovery" ], "summary": "Validate terms against a profile's minimums", "operationId": "validateAgainstProfile", "description": "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.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileValidationRequest" } } } }, "responses": { "200": { "description": "Validation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "violations": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/v1/settlement-rails": { "get": { "tags": [ "Discovery" ], "summary": "List active settlement-rail adapters", "operationId": "listSettlementRails", "description": "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](/invariants.html#rail-conditional-reserve) and [verifiable settlement](/invariants.html#verifiable-settlement) computable rather than guessed.", "security": [], "responses": { "200": { "description": "Adapters", "content": { "application/json": { "schema": { "type": "object", "properties": { "adapters": { "type": "array", "items": { "$ref": "#/components/schemas/SettlementRail" } } } } } } } } } }, "/v1/settlement-rails/{adapter_id}/capabilities": { "parameters": [ { "name": "adapter_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,32}$" }, "examples": { "usdc": { "value": "usdc-base" } } } ], "get": { "tags": [ "Discovery" ], "summary": "Get a settlement adapter's capabilities", "operationId": "getSettlementRailCapabilities", "description": "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](/invariants.html#rail-conditional-reserve)) and to demand a correlated settlement proof ([verifiable settlement](/invariants.html#verifiable-settlement)).", "security": [], "responses": { "200": { "description": "Adapter capabilities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementRail" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/principals": { "post": { "tags": [ "Identity" ], "summary": "Register a principal (legal entity)", "operationId": "registerPrincipal", "x-aura-signature-profile": "principal_registration", "x-aura-invariants": [ "INV-007" ], "description": "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](/invariants.html#persistent-identity-and-qualification)).", "security": [ { "principalProof": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrincipalRegistration" } } } }, "responses": { "200": { "description": "Existing principal (idempotent replay)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Principal" } } } }, "201": { "description": "Principal registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Principal" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/principals/{principal_id}": { "parameters": [ { "name": "principal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Identity" ], "summary": "Retrieve a principal", "operationId": "getPrincipal", "description": "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](/invariants.html#least-privilege-delegated-authority)): a caller sees its own principal, never another's.", "responses": { "200": { "description": "Principal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Principal" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Identity" ], "summary": "Update a principal's mutable fields", "operationId": "updatePrincipal", "description": "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](/invariants.html#least-privilege-delegated-authority)).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrincipalUpdate" } } } }, "responses": { "200": { "description": "Updated principal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Principal" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/register": { "post": { "tags": [ "Identity" ], "summary": "Register an agent (Scout or Beacon)", "operationId": "registerAgent", "x-aura-signature-profile": "agent_registration", "x-aura-invariants": [ "INV-007" ], "description": "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](/invariants.html#persistent-identity-and-qualification)).", "security": [ { "agentProof": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRegistration" } } } }, "responses": { "200": { "description": "Existing agent (idempotent replay)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "201": { "description": "Agent registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/agents/{agent_id}": { "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Identity" ], "summary": "Get agent details", "operationId": "getAgent", "description": "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](/invariants.html#least-privilege-delegated-authority)).", "responses": { "200": { "description": "Agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/principals/{principal_id}/agents": { "parameters": [ { "name": "principal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Identity" ], "summary": "List a principal's agents", "operationId": "listPrincipalAgents", "description": "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](/invariants.html#least-privilege-delegated-authority)); one agent cannot enumerate another principal's fleet.", "responses": { "200": { "description": "Agents bound to the principal", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/principals/{principal_id}/transactions": { "parameters": [ { "name": "principal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 } } ], "get": { "tags": [ "Identity" ], "summary": "List transactions a principal is party to", "operationId": "listPrincipalTransactions", "description": "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](/invariants.html#least-privilege-delegated-authority)).", "responses": { "200": { "description": "Transactions (paginated)", "headers": { "X-Total-Count": { "description": "Total matching transactions.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/revoke": { "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Identity" ], "summary": "Revoke an agent identity", "operationId": "revokeAgent", "description": "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](/invariants.html#persistent-identity-and-qualification)).", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Agent revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "examples": [ "revoked" ] }, "revoked_at": { "type": "string", "format": "date-time" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/delegation-scope": { "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "put": { "tags": [ "Identity" ], "summary": "Create or replace the active delegation scope", "operationId": "putDelegationScope", "description": "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](/invariants.html#least-privilege-delegated-authority), [constraints as bounds](/invariants.html#constraints-as-bounds)).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationScopeRequest" } } } }, "responses": { "200": { "description": "Active delegation scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationScope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "tags": [ "Identity" ], "summary": "Get the active delegation scope", "operationId": "getDelegationScope", "description": "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](/invariants.html#least-privilege-delegated-authority) becomes inspectable.", "responses": { "200": { "description": "Active delegation scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationScope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/beacons/register": { "post": { "tags": [ "Beacons" ], "summary": "Register or update a beacon", "operationId": "registerBeacon", "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeaconRegistration" } } } }, "responses": { "200": { "description": "Beacon registered or updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Beacon" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/beacons/sessions": { "get": { "tags": [ "Beacons" ], "summary": "Poll open sessions to bid on", "operationId": "listBeaconSessions", "description": "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.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Open sessions (redacted)", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/SessionSummary" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/beacons/{beacon_id}": { "parameters": [ { "name": "beacon_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Beacon UUID or externalId." } ], "get": { "tags": [ "Beacons" ], "summary": "Get a beacon", "operationId": "getBeacon", "description": "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.", "responses": { "200": { "description": "Beacon", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Beacon" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/sessions": { "post": { "tags": [ "Market Navigation" ], "summary": "Create a commerce session from intent", "operationId": "createSession", "x-aura-signature-profile": "interpretation_attestation", "x-aura-invariants": [ "INV-001", "INV-004", "INV-008" ], "description": "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](/invariants.html#neutral-brokerage) rather than wiring the two sides together, recording the intent from its origin ([recorded intent and chain of custody](/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](/invariants.html#constraints-as-bounds)).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionCreate" } } } }, "responses": { "200": { "description": "Session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/sessions/{session_id}": { "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "get": { "tags": [ "Market Navigation" ], "summary": "Retrieve a session", "operationId": "getSession", "x-aura-invariants": [ "INV-002", "INV-003" ], "description": "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](/invariants.html#identity-abstraction-until-commitment), so a counterparty's identity stays sealed, and [monotonic disclosure](/invariants.html#monotonic-disclosure), so a field once visible never vanishes. Reading the session never leaks what the phase has not yet earned.", "responses": { "200": { "description": "Session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/sessions/{session_id}/offers": { "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "post": { "tags": [ "Market Navigation" ], "summary": "Submit a signed offer (Beacon)", "operationId": "submitOffer", "x-aura-signature-profile": "beacon_offer", "x-aura-invariants": [ "INV-001", "INV-002", "INV-004", "INV-005" ], "description": "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](/invariants.html#neutral-brokerage), and the offer carries an [expiry](/invariants.html#offer-expiry) from the moment it exists. The buyer's identity stays sealed while this happens ([identity abstraction until commitment](/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](/invariants.html#constraints-as-bounds).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferSubmission" } } } }, "responses": { "201": { "description": "Offer accepted and counter-signed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Offer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "get": { "tags": [ "Market Navigation" ], "summary": "List pending offers (Scout)", "operationId": "listOffers", "x-aura-invariants": [ "INV-002", "INV-003" ], "description": "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](/invariants.html#identity-abstraction-until-commitment) and [monotonic disclosure](/invariants.html#monotonic-disclosure): the terms are visible, the counterparty behind them is not, until commitment earns it.", "responses": { "200": { "description": "Offers", "content": { "application/json": { "schema": { "type": "object", "properties": { "offers": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/sessions/{session_id}/commit": { "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "post": { "tags": [ "Transactions" ], "summary": "Commit to an offer", "operationId": "commitSession", "x-aura-signature-profile": "core_offer_countersignature", "x-aura-invariants": [ "INV-001", "INV-004", "INV-005", "INV-006", "INV-008", "INV-010", "INV-013" ], "description": "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](/invariants.html#offer-expiry), exceeding the [authority the principal delegated](/invariants.html#constraints-as-bounds), or leaving half a transaction behind when something fails midway. Commit refuses all of them in one [atomic act](/invariants.html#atomic-commitment): it checks the offer is live and within the mandate, records consent and extends the [signed chain of custody](/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](/invariants.html#rail-conditional-reserve)) and refusing any failed [business rule](/invariants.html#business-rules-as-hard-gates).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitRequest" } } } }, "responses": { "200": { "description": "Committed transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/transactions/{transaction_id}": { "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Transactions" ], "summary": "Retrieve a transaction", "operationId": "getTransaction", "description": "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.", "responses": { "200": { "description": "Transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/sessions/{session_id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "post": { "tags": [ "Market Navigation" ], "summary": "Cancel a session", "operationId": "cancelSession", "description": "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.", "responses": { "200": { "description": "Session cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "examples": [ "cancelled" ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/sessions/{session_id}/attestation": { "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "get": { "tags": [ "Market Navigation" ], "summary": "Get the interpretation attestation", "operationId": "getAttestation", "x-aura-signature-profile": "interpretation_attestation", "x-aura-invariants": [ "INV-008" ], "description": "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](/invariants.html#recorded-intent-and-chain-of-custody).", "responses": { "200": { "description": "Signed attestation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attestation" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/offers/{offer_id}/counter": { "parameters": [ { "name": "offer_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Market Navigation" ], "summary": "Counter an offer (Scout)", "operationId": "counterOffer", "x-aura-invariants": [ "INV-004", "INV-005" ], "description": "Negotiation moves in bounded, finite steps. A counter-offer answers with revised terms that still sit inside the session's [constraints](/invariants.html#constraints-as-bounds) and carries its own [expiry](/invariants.html#offer-expiry), so each round stays within the mandate and stays finite.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterOfferRequest" } } } }, "responses": { "201": { "description": "Counter-offer created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NegotiatedOffer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "description": "Negotiation chain exhausted (depth cap reached)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/transactions/{transaction_id}/fulfillment": { "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "put": { "tags": [ "Transactions" ], "summary": "Report fulfillment status", "operationId": "updateFulfillment", "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfillmentUpdate" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "fulfillment_status": { "type": "string" }, "fulfillment_reference": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/transactions/{transaction_id}/payment": { "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "put": { "tags": [ "Transactions" ], "summary": "Report payment status", "operationId": "updatePayment", "x-aura-invariants": [ "INV-009" ], "description": "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](/invariants.html#verifiable-settlement)).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentUpdate" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_reference": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/transactions/{transaction_id}/clearing": { "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Transactions" ], "summary": "Read the clearing record", "operationId": "getClearing", "x-aura-invariants": [ "INV-009", "INV-010", "INV-011", "INV-012" ], "description": "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](/invariants.html#rail-conditional-reserve), the [settlement proof](/invariants.html#verifiable-settlement), and a risk score that is a function of risk and rail alone ([financial neutrality of the clearinghouse](/invariants.html#financial-neutrality-of-the-clearinghouse)), shown only to the party it belongs to ([bilateral risk transparency](/invariants.html#bilateral-risk-transparency)).", "responses": { "200": { "description": "Clearing record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClearingRecord" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/business-rules": { "post": { "tags": [ "Business Rules" ], "summary": "Register a business rule (Beacon)", "operationId": "createBusinessRule", "x-aura-invariants": [ "INV-013" ], "description": "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](/invariants.html#business-rules-as-hard-gates)).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessRuleCreate" } } } }, "responses": { "200": { "description": "Existing rule (idempotent replay)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessRule" } } } }, "201": { "description": "Rule created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessRule" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "get": { "tags": [ "Business Rules" ], "summary": "List a beacon's active rules", "operationId": "listBusinessRules", "description": "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.", "parameters": [ { "name": "beacon_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Active rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessRule" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/business-rules/{rule_id}": { "parameters": [ { "name": "rule_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "delete": { "tags": [ "Business Rules" ], "summary": "Revoke a business rule", "operationId": "revokeBusinessRule", "description": "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.", "responses": { "204": { "description": "Revoked (no content)" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/transactions/{transaction_id}/disputes": { "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Disputes" ], "summary": "File a dispute", "operationId": "fileDispute", "x-aura-invariants": [ "INV-014" ], "description": "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](/invariants.html#repudiability-within-a-bounded-window)), turning finality without recourse into accountable settlement.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeFile" } } } }, "responses": { "201": { "description": "Dispute filed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/disputes/{dispute_id}/evidence": { "parameters": [ { "name": "dispute_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Disputes" ], "summary": "Submit dispute evidence", "operationId": "submitEvidence", "x-aura-invariants": [ "INV-014" ], "description": "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](/invariants.html#repudiability-within-a-bounded-window).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceSubmission" } } } }, "responses": { "201": { "description": "Evidence recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "evidence_id": { "type": "string", "format": "uuid" }, "dispute_id": { "type": "string", "format": "uuid" }, "submitted_by": { "type": "string", "format": "uuid" }, "submitted_at": { "type": "string", "format": "date-time" }, "type": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/disputes/{dispute_id}/resolve": { "parameters": [ { "name": "dispute_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Disputes" ], "summary": "Resolve or withdraw a dispute", "operationId": "resolveDispute", "x-aura-invariants": [ "INV-014" ], "description": "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](/invariants.html#repudiability-within-a-bounded-window) and closes it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeResolution" } } } }, "responses": { "200": { "description": "Dispute resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/disputes/{dispute_id}": { "parameters": [ { "name": "dispute_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Disputes" ], "summary": "Retrieve a dispute", "operationId": "getDispute", "x-aura-invariants": [ "INV-014" ], "description": "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](/invariants.html#repudiability-within-a-bounded-window).", "responses": { "200": { "description": "Dispute", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/sessions/{session_id}/chain-links": { "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "post": { "tags": [ "Intent Chain" ], "summary": "Submit the L3 (principal review) chain link", "operationId": "submitChainLink", "x-aura-signature-profile": "intent_chain_link", "x-aura-invariants": [ "INV-008" ], "description": "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](/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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChainLinkSubmission" } } } }, "responses": { "201": { "description": "Chain link recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "link": { "type": "string" }, "name": { "type": "string" }, "session_id": { "type": "string", "format": "uuid" }, "previous_link_hash": { "type": [ "string", "null" ], "description": "Hash of the prior link; null for the first." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/transactions/{transaction_id}/intent-chain": { "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Intent Chain" ], "summary": "Retrieve the assembled intent chain", "operationId": "getIntentChain", "x-aura-signature-profile": "assembled_intent_chain", "x-aura-invariants": [ "INV-008" ], "description": "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](/invariants.html#recorded-intent-and-chain-of-custody) for a transaction, every link signed by the party responsible for it.", "responses": { "200": { "description": "Intent chain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntentChain" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "agentId": { "type": "apiKey", "in": "header", "name": "X-Agent-Id", "description": "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": { "type": "apiKey", "in": "header", "name": "X-Agent-Timestamp", "description": "RFC 3339 timestamp. Sent together with X-Agent-Id and X-Agent-Signature." }, "agentSignature": { "type": "apiKey", "in": "header", "name": "X-Agent-Signature", "description": "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": { "type": "apiKey", "in": "header", "name": "X-Agent-Signature", "description": "Proof-of-possession for agent registration: Ed25519 signature over the request body, proving control of the submitted public key." }, "principalProof": { "type": "apiKey", "in": "header", "name": "X-Signature", "description": "Proof-of-possession for principal registration: Ed25519 signature over the request body." }, "systemToken": { "type": "apiKey", "in": "header", "name": "X-System-Token", "description": "System-only shared secret for internal lifecycle endpoints. Not issued to client integrations." } }, "parameters": { "ProfileId": { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^(prf_[a-z0-9_]+_v[0-9]+|default)$" }, "examples": { "retail": { "value": "prf_retail_consumer_v1" }, "default": { "value": "default" } } }, "SessionId": { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } }, "responses": { "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid agent authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Authenticated but not authorized for this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "example": { "error": "validation_error", "message": "Request body failed contract validation" }, "type": "object", "properties": { "error": { "type": "string", "description": "Machine-readable error code" }, "message": { "type": "string", "description": "Human-readable explanation" } }, "required": [ "error" ] }, "Link": { "type": "object", "example": { "href": "/v1/sessions/5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "method": "GET" }, "properties": { "href": { "type": "string" }, "method": { "type": "string" } } }, "Links": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Link" }, "example": { "self": { "href": "/v1/sessions/5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "method": "GET" }, "offers": { "href": "/v1/sessions/5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b/offers", "method": "GET" } }, "description": "HATEOAS affordances keyed by relation." }, "PriceRange": { "example": { "min": 1200, "max": 1800, "currency": "USD" }, "type": "object", "description": "Reusable price range component.", "required": [ "min", "max" ], "properties": { "min": { "type": "number", "minimum": 0 }, "max": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "description": "ISO 4217", "default": "USD" } } }, "Profile": { "example": { "profile_id": "prf_b2b_procurement_v1", "profile_version": "1", "display_name": "B2B Procurement", "description": "Bounded parameters for business-to-business procurement markets.", "market_context": "b2b_procurement", "status": "active", "dispute_window_days_minimum": 14, "dispute_window_days_default": 30, "_links": { "self": { "href": "/v1/profiles/prf_b2b_procurement_v1", "method": "GET" } } }, "type": "object", "description": "Market profile governing dispute windows and settlement defaults.", "properties": { "profile_id": { "type": "string" }, "profile_version": { "type": "string", "description": "Version of this profile; pinned onto a session at creation as profile_version_at_creation." }, "display_name": { "type": "string", "description": "Human-readable profile label." }, "description": { "type": "string", "description": "Free-text summary of the market this profile governs." }, "market_context": { "type": "string", "description": "The vertical or market context the profile applies to." }, "status": { "type": "string", "description": "Profile lifecycle status; only active profiles are resolvable." }, "dispute_window_days_minimum": { "type": "integer" }, "dispute_window_days_default": { "type": "integer" }, "participation": { "type": "object", "description": "Participation dimension: who may enter this market and under what conditions." }, "disclosure": { "type": "object", "description": "Disclosure dimension: what parties must reveal to each other." }, "commitment": { "type": "object", "description": "Commitment dimension: binding rules governing offers and commits." }, "risk": { "type": "object", "description": "Risk dimension: risk-tiering and reserve parameters for this market." }, "schema": { "type": "object", "description": "Schema overlays extending the base offer/intent shape for this market." }, "governance": { "type": "object", "description": "Governance dimension: who may amend the profile and how." }, "metadata": { "type": "object", "description": "Free-form profile metadata." }, "_links": { "$ref": "#/components/schemas/Links" } } }, "ProfileValidationRequest": { "example": { "dispute_window_days": 30, "settlement_method": "sepa-instant" }, "type": "object", "description": "Terms to pre-flight against a market profile's minimums.", "required": [ "dispute_window_days" ], "properties": { "dispute_window_days": { "type": "integer", "minimum": 0 }, "settlement_method": { "type": "string", "maxLength": 32 } } }, "SettlementRail": { "example": { "adapter_id": "sepa-instant", "native_repudiation": false, "capabilities": { "settlement_time": "instant", "currencies": [ "EUR" ] }, "_links": { "self": { "href": "/v1/settlement-rails/sepa-instant", "method": "GET" } } }, "type": "object", "description": "Settlement-rail adapter and its capabilities.", "properties": { "adapter_id": { "type": "string" }, "native_repudiation": { "type": "boolean", "description": "Whether the rail provides native chargeback/repudiation." }, "capabilities": { "type": "object" }, "_links": { "$ref": "#/components/schemas/Links" } } }, "PrincipalRegistration": { "example": { "principal_type": "organization", "legal_name": "Helix Retail Group", "jurisdiction": "GB", "public_key": "MCowBQYDK2VwAyEAGb9ECWmEzf6FQbrBZ9w7lshQhqowtrbLDFw4rXAxZuE=", "operating_name": "Helix Retail", "identifiers": { "lei": "894500ABCDEF12345678", "domain": "helix-retail.example" }, "contact": { "email": "integrations@helix-retail.example" } }, "type": "object", "required": [ "principal_type", "legal_name", "jurisdiction", "public_key" ], "properties": { "principal_type": { "type": "string", "enum": [ "organization", "individual" ] }, "legal_name": { "type": "string" }, "jurisdiction": { "type": "string", "description": "ISO 3166 country code" }, "public_key": { "type": "string", "description": "Base64 Ed25519 public key" }, "operating_name": { "type": "string" }, "identifiers": { "type": "object", "properties": { "lei": { "type": "string" }, "domain": { "type": "string" } } }, "contact": { "type": "object" } } }, "Principal": { "example": { "principal_id": "3f2a9c7e-1b4d-4e8a-9c2f-7a1b0d3e5f60", "principal_type": "organization", "verification_level": "basic", "verification_status": "verified", "registered_at": "2026-06-20T09:15:00Z", "_links": { "self": { "href": "/v1/principals/3f2a9c7e-1b4d-4e8a-9c2f-7a1b0d3e5f60", "method": "GET" } } }, "type": "object", "properties": { "principal_id": { "type": "string", "format": "uuid" }, "principal_type": { "type": "string", "enum": [ "organization", "individual" ] }, "verification_level": { "type": "string" }, "verification_status": { "type": "string" }, "registered_at": { "type": "string", "format": "date-time" }, "_links": { "$ref": "#/components/schemas/Links" } } }, "AgentRegistration": { "example": { "public_key": "MCowBQYDK2VwAyEAGb9ECWmEzf6FQbrBZ9w7lshQhqowtrbLDFw4rXAxZuE=", "type": "scout", "principal_id": "3f2a9c7e-1b4d-4e8a-9c2f-7a1b0d3e5f60", "capacity": "standard", "manifest": { "name": "Helix Procurement Scout", "version": "1.2.0" } }, "type": "object", "required": [ "public_key", "type", "principal_id" ], "properties": { "public_key": { "type": "string", "description": "Base64 Ed25519 public key" }, "type": { "type": "string", "enum": [ "scout", "beacon" ] }, "principal_id": { "type": "string", "format": "uuid" }, "capacity": { "type": "string", "default": "agent_for_principal" }, "manifest": { "type": "object" } } }, "Agent": { "example": { "agent_id": "8b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d", "status": "active", "key_id": "key_9f3a2c", "principal_id": "3f2a9c7e-1b4d-4e8a-9c2f-7a1b0d3e5f60", "capacity": "standard", "registered_at": "2026-06-21T10:00:00Z", "_links": { "self": { "href": "/v1/agents/8b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d", "method": "GET" } } }, "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "key_id": { "type": "string" }, "manifest": { "type": "object", "description": "The agent's self-declared capability manifest submitted at registration." }, "principal_id": { "type": "string", "format": "uuid" }, "capacity": { "type": "string" }, "principal_verification_level": { "type": [ "string", "null" ], "description": "Verification level of the bound principal, resolved at read time; null when the agent has no principal." }, "registered_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the agent's most recent authenticated request; null until first seen." }, "_links": { "$ref": "#/components/schemas/Links" } } }, "PrincipalUpdate": { "example": { "operating_name": "Helix Retail Group (EMEA)", "contact": { "email": "ops@helix-retail.example" }, "identifiers": { "domain": "helix-retail.example" } }, "type": "object", "description": "Mutable principal fields. Immutable fields (legal_name, jurisdiction, principal_type, public_key, verification_level) are rejected with 400.", "properties": { "operating_name": { "type": "string" }, "contact": { "type": "object" }, "identifiers": { "type": "object", "properties": { "lei": { "type": "string" }, "domain": { "type": "string" } } } } }, "DelegationConstraints": { "example": { "max_transaction_amount": 50000, "currency": "USD", "valid_from": "2026-06-01T00:00:00Z", "valid_until": "2026-12-31T23:59:59Z", "allowed_categories": [ "industrial_supplies" ], "blocked_categories": [ "weapons" ], "merchant_blocklist": [], "require_principal_approval_above": 25000 }, "type": "object", "description": "Bounds on what the agent may transact under this scope.", "properties": { "max_transaction_amount": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "description": "ISO 4217" }, "valid_from": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" }, "allowed_categories": { "type": "array", "items": { "type": "string" } }, "blocked_categories": { "type": "array", "items": { "type": "string" } }, "merchant_blocklist": { "type": "array", "items": { "type": "string" } }, "require_principal_approval_above": { "type": "number" } } }, "DelegationScopeRequest": { "example": { "consent_tier": "policy", "constraints": { "max_transaction_amount": 50000, "currency": "USD", "valid_from": "2026-06-01T00:00:00Z", "valid_until": "2026-12-31T23:59:59Z", "allowed_categories": [ "industrial_supplies" ], "blocked_categories": [ "weapons" ], "merchant_blocklist": [], "require_principal_approval_above": 25000 }, "policy_definition": { "max_per_day": 5 }, "signed_by_principal": true, "principal_signature": "k9Jx2pQ7r4sV1mNc8eTfWZ0aYbHd3GgLpRtUvXyB6CnEoJqSiKlMwOzPu5D4hAtFr7vXsQ2bNcMeKgLpRtUvXyB" }, "type": "object", "required": [ "consent_tier", "constraints" ], "properties": { "consent_tier": { "type": "string", "enum": [ "explicit", "policy", "delegated" ] }, "constraints": { "$ref": "#/components/schemas/DelegationConstraints" }, "policy_definition": { "type": "object" }, "signed_by_principal": { "type": "boolean", "default": false }, "principal_signature": { "type": "string" } } }, "DelegationScope": { "example": { "scope_id": "scope_7f3a9c2e", "agent_id": "8b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d", "consent_tier": "policy", "constraints": { "max_transaction_amount": 50000, "currency": "USD", "valid_from": "2026-06-01T00:00:00Z", "valid_until": "2026-12-31T23:59:59Z", "allowed_categories": [ "industrial_supplies" ], "blocked_categories": [ "weapons" ], "merchant_blocklist": [], "require_principal_approval_above": 25000 }, "policy_definition": { "max_per_day": 5 }, "signed_by_principal": true, "status": "active", "created_at": "2026-06-21T10:05:00Z" }, "type": "object", "properties": { "scope_id": { "type": "string" }, "agent_id": { "type": "string", "format": "uuid" }, "consent_tier": { "type": "string", "enum": [ "explicit", "policy", "delegated" ] }, "constraints": { "$ref": "#/components/schemas/DelegationConstraints" }, "policy_definition": { "type": ["object", "null"] }, "signed_by_principal": { "type": "boolean" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "BeaconRegistration": { "example": { "external_id": "northwind-components", "name": "Northwind Components", "description": "Industrial parts and components supplier", "endpoint_url": "https://beacons.northwind-components.example/aura/webhook", "capabilities": { "categories": [ "industrial_supplies" ], "currencies": [ "USD" ] }, "metadata": { "region": "NA" } }, "type": "object", "required": [ "external_id", "name" ], "properties": { "external_id": { "type": "string", "description": "Stable external identifier; the upsert key." }, "name": { "type": "string" }, "description": { "type": "string" }, "endpoint_url": { "type": "string", "format": "uri", "description": "HTTPS, public hostname; SSRF-validated." }, "capabilities": { "type": "object" }, "metadata": { "type": "object" } } }, "Beacon": { "example": { "beacon_id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", "external_id": "northwind-components", "name": "Northwind Components", "status": "active", "capabilities": { "categories": [ "industrial_supplies" ] }, "_links": { "self": { "href": "/v1/beacons/c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", "method": "GET" } } }, "type": "object", "properties": { "beacon_id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "capabilities": { "type": "object" }, "_links": { "$ref": "#/components/schemas/Links" } } }, "SessionSummary": { "example": { "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "status": "offers_available", "intent": { "raw": "I need 200 industrial widgets delivered within three weeks" }, "constraints": { "quantity": 200, "deliver_by": "2026-07-18" } }, "type": "object", "description": "Open session as seen by a beacon. Buyer constraints are redacted to categories only.", "properties": { "session_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "intent": { "type": "object", "properties": { "raw": { "type": "string" }, "parsed": { "type": "object" } } }, "constraints": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "string" } } }, "description": "Redacted to categories only." } } }, "SessionCreate": { "example": { "intent": "I need 200 industrial widgets delivered within three weeks", "constraints": { "quantity": 200, "max_unit_price": 9, "currency": "USD" }, "completeness": { "confidence": 0.9 }, "profile_id": "prf_b2b_procurement_v1", "settlement_preference": { "preferred_methods": [ "sepa-instant", "usdc-base" ] }, "risk_tolerance": { "max_dispute_window_days": 30 } }, "type": "object", "required": [ "intent" ], "properties": { "intent": { "type": "string", "maxLength": 2000, "description": "Natural-language buying intent." }, "constraints": { "type": "object", "description": "Structured constraints (max 10KB).", "properties": { "price_range": { "$ref": "#/components/schemas/PriceRange" } } }, "completeness": { "type": "object", "properties": { "complete": { "type": "boolean" }, "missing": { "type": "array", "items": { "type": "string" } }, "confidence": { "type": "number" } } }, "chain_links": { "type": "object", "description": "Optional L1 intent-chain link." }, "profile_id": { "type": "string", "default": "default" }, "settlement_preference": { "type": "object" }, "risk_tolerance": { "type": "object" } } }, "Session": { "example": { "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "status": "offers_available", "intent": { "raw": "I need 200 industrial widgets delivered within three weeks", "structured": { "quantity": 200, "item": "industrial widget" } }, "profile_id": "prf_b2b_procurement_v1", "profile_version_at_creation": "2.4", "matched_beacons": [ { "beacon_id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", "name": "Northwind Components" } ], "_links": { "self": { "href": "/v1/sessions/5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "method": "GET" }, "offers": { "href": "/v1/sessions/5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b/offers", "method": "GET" } } }, "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "examples": [ "collecting_offers" ] }, "intent": { "type": ["object", "null"], "description": "Parsed intent." }, "raw_intent": { "type": ["string", "null"], "description": "The original unparsed intent string as submitted, returned on session retrieval." }, "profile_id": { "type": "string" }, "profile_version_at_creation": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp the session was created." }, "matched_beacons": { "type": "array", "items": { "type": "object" } }, "_links": { "$ref": "#/components/schemas/Links" } } }, "Product": { "example": { "name": "Industrial Widget Mk II", "sku": "NW-WIDGET-002" }, "type": "object", "description": "Product descriptor (free-form JSONB). 'name' is the canonical label; 'sku' optional. Additional vendor fields are permitted.", "properties": { "name": { "type": "string" }, "sku": { "type": "string" } } }, "OfferSubmission": { "example": { "beacon_id": "northwind-components", "product": { "name": "Industrial Widget Mk II", "sku": "NW-WIDGET-002" }, "unit_price": 8.5, "quantity": 200, "total_price": 1700, "currency": "USD", "delivery_date": "2026-07-15", "terms": { "warranty_months": 12 }, "signature": "k9Jx2pQ7r4sV1mNc8eTfWZ0aYbHd3GgLpRtUvXyB6CnEoJqSiKlMwOzPu5D4hAtFr7vXsQ2bNcMeKgLpRtUvXyB", "payment_terms": { "dispute_window_days": 30, "return_policy_days": 14, "payment_timing": "net_30", "accepted_methods": [ "sepa-instant", "usdc-base" ] }, "payment_terms_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "acting_for_principal_id": "3f2a9c7e-1b4d-4e8a-9c2f-7a1b0d3e5f60", "consent_requirements": { "principal_signature": false } }, "type": "object", "required": [ "beacon_id", "product", "signature" ], "properties": { "beacon_id": { "type": "string" }, "product": { "description": "Product descriptor object, or a bare string treated as { name }.", "oneOf": [ { "$ref": "#/components/schemas/Product" }, { "type": "string" } ] }, "unit_price": { "type": "number" }, "quantity": { "type": "integer" }, "total_price": { "type": "number" }, "currency": { "type": "string", "default": "USD" }, "delivery_date": { "type": "string", "format": "date" }, "terms": { "type": "object" }, "signature": { "type": "string", "description": "Beacon Ed25519 signature over the canonical offer." }, "payment_terms": { "$ref": "#/components/schemas/PaymentTerms" }, "payment_terms_hash": { "type": "string", "description": "Base64 SHA-256 over canonical payment_terms (v2.4 attested path)." }, "acting_for_principal_id": { "type": "string", "format": "uuid" }, "consent_requirements": { "type": "object", "properties": { "minimum_tier": { "type": "string" }, "reason": { "type": "string" }, "above_amount": { "type": "number" } } } } }, "PaymentTerms": { "example": { "dispute_window_days": 30, "return_policy_days": 14, "payment_timing": "net_30", "accepted_methods": [ "sepa-instant", "usdc-base" ] }, "type": "object", "description": "Offer payment terms (v2.4).", "properties": { "dispute_window_days": { "type": "integer" }, "return_policy_days": { "type": "integer" }, "payment_timing": { "type": "string" }, "accepted_methods": { "type": "array", "items": { "type": "string" } } } }, "Offer": { "example": { "offer_id": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d", "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "beacon_id": "northwind-components", "status": "pending", "product": { "name": "Industrial Widget Mk II", "sku": "NW-WIDGET-002" }, "payment_terms": { "dispute_window_days": 30, "return_policy_days": 14, "payment_timing": "net_30", "accepted_methods": [ "sepa-instant", "usdc-base" ] }, "payment_terms_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "signatures": { "beacon": "k9Jx2pQ7r4sV1mNc8eTfWZ0aYbHd3GgLpRtUvXyB6CnEoJqSiKlMwOzPu5D4hAtFr7vXsQ2bNcMeKgLpRtUvXyB", "core": "k9Jx2pQ7r4sV1mNc8eTfWZ0aYbHd3GgLpRtUvXyB6CnEoJqSiKlMwOzPu5D4hAtFr7vXsQ2bNcMeKgLpRtUvXyB" }, "_links": { "self": { "href": "/v1/offers/9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d", "method": "GET" } } }, "type": "object", "properties": { "offer_id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" }, "beacon_id": { "type": "string" }, "beacon_name": { "type": "string", "description": "Display name of the beacon that submitted this offer, joined at read time." }, "status": { "type": "string" }, "product": { "$ref": "#/components/schemas/Product" }, "unit_price": { "type": "number", "description": "Per-unit price of the offered product." }, "quantity": { "type": "integer", "description": "Number of units offered." }, "total_price": { "type": "number", "description": "Total price for the offered quantity." }, "currency": { "type": "string", "description": "ISO 4217 currency of the offer prices." }, "delivery_date": { "type": "string", "format": "date", "description": "Committed delivery date for the offered goods." }, "terms": { "type": "object", "description": "Free-form commercial terms attached to the offer." }, "metadata": { "type": "object", "description": "Free-form offer metadata." }, "consent_requirements": { "type": "object", "description": "Principal-consent requirements the offer attaches to the commit, when present." }, "payment_terms": { "$ref": "#/components/schemas/PaymentTerms" }, "payment_terms_hash": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp the offer was submitted." }, "signatures": { "type": "object", "properties": { "beacon": { "type": "string" }, "core": { "type": "string" }, "core_receipt_at": { "type": "string", "format": "date-time" } } }, "_links": { "$ref": "#/components/schemas/Links" } } }, "CommitRequest": { "example": { "offer_id": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d", "idempotency_key": "4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f70", "authority": { "consent_tier": "policy", "scope_id": "scope_7f3a9c2e" }, "chain_links": { "L5": { "signature": "k9Jx2pQ7r4sV1mNc8eTfWZ0aYbHd3GgLpRtUvXyB6CnEoJqSiKlMwOzPu5D4hAtFr7vXsQ2bNcMeKgLpRtUvXyB" } }, "settlement_method": "sepa-instant" }, "type": "object", "required": [ "offer_id", "idempotency_key" ], "properties": { "offer_id": { "type": "string", "format": "uuid" }, "idempotency_key": { "type": "string", "format": "uuid", "description": "UUID v4 for idempotent commit." }, "authority": { "type": "object", "properties": { "delegation_scope_id": { "type": "string" }, "consent_tier": { "type": "string" }, "principal_approval": { "type": "object" } } }, "chain_links": { "type": "object", "description": "L4/L5 intent-chain links." }, "settlement_method": { "type": "string" } } }, "Transaction": { "example": { "transaction_id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "offer_id": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d", "beacon_id": "northwind-components", "status": "committed", "final_terms": { "product": { "name": "Industrial Widget Mk II", "sku": "NW-WIDGET-002" }, "unit_price": 8.5, "quantity": 200, "total_price": 1700, "currency": "USD" }, "clearinghouse": { "clearing_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "clearing_status": "risk_assessed", "risk_tier": "low", "reserve_status": "rail_managed", "net_settlement_amount": 1700, "currency": "USD" }, "_links": { "self": { "href": "/v1/transactions/2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "method": "GET" } } }, "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" }, "offer_id": { "type": "string", "format": "uuid" }, "beacon_id": { "type": "string" }, "beacon_name": { "type": "string", "description": "Display name of the beacon party to the transaction." }, "agent_id": { "type": "string", "format": "uuid", "description": "Identity of the scout agent that owns the originating session." }, "status": { "type": "string" }, "final_terms": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/Product" }, "total_price": { "type": "number" }, "currency": { "type": "string" }, "delivery_date": { "type": "string", "format": "date" } } }, "scout_principal": { "type": [ "object", "null" ], "description": "The scout side's principal reference, resolved at commit time; null when unbound.", "properties": { "principal_id": { "type": "string", "format": "uuid" } } }, "beacon_principal": { "type": [ "object", "null" ], "description": "The beacon side's principal reference, resolved at commit time; null when unbound.", "properties": { "principal_id": { "type": "string", "format": "uuid" } } }, "fulfillment_status": { "type": "string", "description": "Current fulfillment state reported by the beacon." }, "fulfillment_reference": { "type": "string", "description": "Beacon-supplied reference for the fulfillment (e.g. tracking or order id)." }, "payment_status": { "type": "string", "description": "Current payment state of the transaction." }, "payment_reference": { "type": "string", "description": "Reference for the payment (e.g. settlement or rail transaction id)." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp the transaction was committed." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of the transaction's most recent state change." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the transaction reached a terminal completed state; null until then." }, "clearinghouse": { "type": "object", "description": "Present when the rail is AURA-cleared." }, "_links": { "$ref": "#/components/schemas/Links" } } }, "Attestation": { "example": { "type": "interpretation", "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "attestation_signature": "k9Jx2pQ7r4sV1mNc8eTfWZ0aYbHd3GgLpRtUvXyB6CnEoJqSiKlMwOzPu5D4hAtFr7vXsQ2bNcMeKgLpRtUvXyB", "core_key_id": "core_key_2026q2" }, "type": "object", "description": "Core's signed interpretation attestation: a binding between the raw intent and its structured interpretation.", "properties": { "type": { "type": "string", "examples": [ "interpretation_attestation" ] }, "session_id": { "type": "string", "format": "uuid" }, "attestation_signature": { "type": "string", "description": "Base64 Ed25519 over the canonical attestation." }, "core_key_id": { "type": "string" } } }, "CounterOfferRequest": { "example": { "payment_terms": { "dispute_window_days": 45, "return_policy_days": 30, "payment_timing": "net_45", "accepted_methods": [ "sepa-instant" ] }, "unit_price": 8, "quantity": 200, "product": { "name": "Industrial Widget Mk II", "sku": "NW-WIDGET-002" }, "total_price": 1600, "currency": "USD" }, "type": "object", "required": [ "payment_terms" ], "properties": { "payment_terms": { "$ref": "#/components/schemas/PaymentTerms" }, "unit_price": { "type": "number" }, "quantity": { "type": "integer" }, "product": { "description": "Product descriptor object, or a bare string treated as { name }. Inherits the parent offer's product when omitted.", "oneOf": [ { "$ref": "#/components/schemas/Product" }, { "type": "string" } ] }, "total_price": { "type": "number" }, "currency": { "type": "string" } } }, "NegotiatedOffer": { "example": { "offer_id": "6f7a8b9c-0d1e-4f2a-8b3c-4d5e6f7a8b9c", "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "beacon_id": "northwind-components", "parent_offer_id": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d", "negotiation_status": "countered", "depth": 1, "payment_terms": { "dispute_window_days": 30, "return_policy_days": 14, "payment_timing": "net_30", "accepted_methods": [ "sepa-instant", "usdc-base" ] }, "payment_terms_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "_links": { "self": { "href": "/v1/offers/6f7a8b9c-0d1e-4f2a-8b3c-4d5e6f7a8b9c", "method": "GET" } } }, "type": "object", "description": "An offer created by countering a parent offer.", "properties": { "offer_id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" }, "beacon_id": { "type": "string" }, "parent_offer_id": { "type": "string", "format": "uuid" }, "negotiation_status": { "type": "string", "examples": [ "countered" ] }, "depth": { "type": "integer" }, "payment_terms": { "$ref": "#/components/schemas/PaymentTerms" }, "payment_terms_hash": { "type": "string" }, "_links": { "$ref": "#/components/schemas/Links" } } }, "FulfillmentUpdate": { "example": { "fulfillment_status": "shipped", "fulfillment_reference": "NW-SHIP-44821" }, "type": "object", "required": [ "fulfillment_status" ], "properties": { "fulfillment_status": { "type": "string", "enum": [ "pending", "processing", "shipped", "delivered", "failed" ] }, "fulfillment_reference": { "type": "string" } } }, "PaymentUpdate": { "example": { "payment_status": "charged", "payment_reference": "sepa-7f3a9c", "amount": 1700, "currency": "USD" }, "type": "object", "required": [ "payment_status" ], "properties": { "payment_status": { "type": "string", "enum": [ "pending", "authorized", "charged", "refunded", "failed" ] }, "payment_reference": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" } } }, "ClearingRecord": { "example": { "clearing_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "transaction_id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "clearing_status": "settled", "_links": { "self": { "href": "/v1/transactions/2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f/clearing", "method": "GET" } } }, "type": "object", "description": "Clearing lifecycle record. Risk scores are filtered to the requesting party.", "properties": { "clearing_id": { "type": "string", "format": "uuid" }, "transaction_id": { "type": "string", "format": "uuid" }, "clearing_status": { "type": "string" }, "reserve_status": { "type": "string", "description": "State of the settlement reserve (e.g. rail_managed, held, released)." }, "risk_tier": { "type": "string", "description": "Overall risk tier assigned to the transaction." }, "risk_score": { "type": [ "number", "null" ], "description": "Aggregate transaction risk score." }, "scout_risk_score": { "type": [ "number", "null" ], "description": "Per-party risk score for the scout side. Returned only to the scout party; null to the counterparty." }, "beacon_risk_score": { "type": [ "number", "null" ], "description": "Per-party risk score for the beacon side. Returned only to the beacon party; null to the counterparty." }, "payment_method": { "type": "string", "description": "Settlement rail / payment method used to clear the transaction." }, "reserve_margin_pct": { "type": [ "number", "null" ], "description": "Reserve margin held, as a percentage of the settlement amount (wire key for the risk_margin_pct column)." }, "reserve_margin_amount": { "type": [ "number", "null" ], "description": "Reserve margin held, as an absolute amount (wire key for the risk_margin_amount column)." }, "net_settlement_amount": { "type": [ "number", "null" ], "description": "Amount to be settled net of any reserve margin." }, "currency": { "type": "string", "description": "ISO 4217 currency of the settlement amounts." }, "dispute_term_days": { "type": "integer", "description": "Length of the dispute window in days for this clearing record." }, "dispute_term_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the dispute window closes." }, "authorized_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the reserve/settlement was authorized." }, "settled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the transaction settled." }, "cleared_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the reserve released and the record cleared." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp the clearing record was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of the clearing record's most recent state change." }, "_links": { "$ref": "#/components/schemas/Links" } } }, "BusinessRuleCreate": { "example": { "rule_type": "geo_restriction", "payload": { "allowed_countries": [ "US", "CA", "GB" ] } }, "type": "object", "required": [ "rule_type" ], "properties": { "rule_type": { "type": "string", "enum": [ "age_minimum", "geo_restriction", "kyc_required", "custom" ] }, "payload": { "type": "object", "description": "Rule-type-specific (age_minimum: { min_age }; geo_restriction: { allow: [ISO-3166] }; kyc_required: { level })." } } }, "BusinessRule": { "example": { "id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e", "beacon_id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", "rule_type": "geo_restriction", "payload": { "allowed_countries": [ "US", "CA", "GB" ] }, "created_at": "2026-06-22T08:00:00Z" }, "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "beacon_id": { "type": "string", "format": "uuid" }, "rule_type": { "type": "string" }, "payload": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "DisputeFile": { "example": { "reason": "product_not_as_described", "category": "product_quality", "description": "The delivered widgets do not match the Mk II specification; bracket dimensions differ from the agreed drawing.", "evidence": [ { "type": "text", "description": "Photographs of the received units against the spec sheet" } ], "requested_resolution": { "action": "partial_refund", "refund_amount": 400 } }, "type": "object", "required": [ "reason", "category", "description" ], "properties": { "reason": { "type": "string", "enum": [ "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" ] }, "category": { "type": "string", "enum": [ "fulfillment", "payment", "product_quality", "authorization", "other" ] }, "description": { "type": "string", "maxLength": 2000 }, "evidence": { "type": "array", "maxItems": 10, "items": { "type": "object" } }, "requested_resolution": { "type": "object" } } }, "Dispute": { "example": { "dispute_id": "7f8e9d0c-1b2a-4c3d-8e4f-5a6b7c8d9e0f", "transaction_id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "status": "open", "filed_by": "8b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d", "filed_at": "2026-07-20T11:00:00Z", "reason": "product_not_as_described", "category": "product_quality", "evidence_deadline": "2026-07-27T11:00:00Z", "resolution_deadline": "2026-08-03T11:00:00Z", "_links": { "self": { "href": "/v1/disputes/7f8e9d0c-1b2a-4c3d-8e4f-5a6b7c8d9e0f", "method": "GET" } } }, "type": "object", "properties": { "dispute_id": { "type": "string", "format": "uuid" }, "transaction_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "filed_by": { "type": "string", "format": "uuid" }, "filed_at": { "type": "string", "format": "date-time" }, "reason": { "type": "string" }, "category": { "type": "string" }, "evidence_deadline": { "type": "string", "format": "date-time" }, "resolution_deadline": { "type": "string", "format": "date-time" }, "outcome": { "type": "string" }, "resolution": { "type": ["object", "null"] }, "_links": { "$ref": "#/components/schemas/Links" } } }, "EvidenceSubmission": { "example": { "type": "document_reference", "description": "Signed delivery note showing the quantity and spec discrepancy", "document_url": "https://evidence.helix-retail.example/delivery-note-7f8e.pdf", "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" }, "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "document_reference", "external_record", "protocol_record" ] }, "description": { "type": "string", "maxLength": 5000, "description": "Required for type=text." }, "document_url": { "type": "string", "format": "uri", "description": "Required (with content_hash) for type=document_reference." }, "content_hash": { "type": "string" }, "external_system": { "type": "string" }, "external_reference": { "type": "string" }, "protocol_record_type": { "type": "string" }, "protocol_record_id": { "type": "string" } }, "allOf": [ { "if": { "properties": { "type": { "const": "text" } }, "required": [ "type" ] }, "then": { "required": [ "description" ] } }, { "if": { "properties": { "type": { "const": "document_reference" } }, "required": [ "type" ] }, "then": { "required": [ "document_url", "content_hash" ] } } ] }, "DisputeResolution": { "example": { "outcome": "partial", "resolution": { "action": "partial_refund", "reason": "Partial specification mismatch confirmed from evidence", "refund_amount": 400 }, "evidence_considered": [ "ev_photos_01", "ev_delivery_note_02" ] }, "type": "object", "required": [ "outcome" ], "properties": { "outcome": { "type": "string", "enum": [ "upheld", "rejected", "partial", "withdrawn" ] }, "resolution": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "refund", "partial_refund", "replacement", "fulfillment_completion", "no_action", "mutual_release" ] }, "reason": { "type": "string" }, "refund_amount": { "type": "number", "description": "Required for refund actions." } } }, "evidence_considered": { "type": "array", "items": { "type": "string" }, "description": "Required unless outcome=withdrawn." } }, "allOf": [ { "if": { "properties": { "outcome": { "not": { "const": "withdrawn" } } }, "required": [ "outcome" ] }, "then": { "required": [ "resolution", "evidence_considered" ], "properties": { "resolution": { "required": [ "action", "reason" ] }, "evidence_considered": { "minItems": 1 } } } }, { "if": { "properties": { "resolution": { "properties": { "action": { "enum": [ "refund", "partial_refund" ] } }, "required": [ "action" ] } }, "required": [ "resolution" ] }, "then": { "properties": { "resolution": { "required": [ "refund_amount" ], "properties": { "refund_amount": { "exclusiveMinimum": 0 } } } } } } ] }, "ChainLinkSubmission": { "example": { "link": "L3", "payload": { "principal_response": "acknowledged", "reviewed_at": "2026-06-25T12:00:00Z" }, "signature": "k9Jx2pQ7r4sV1mNc8eTfWZ0aYbHd3GgLpRtUvXyB6CnEoJqSiKlMwOzPu5D4hAtFr7vXsQ2bNcMeKgLpRtUvXyB" }, "type": "object", "required": [ "link", "payload", "signature" ], "properties": { "link": { "type": "string", "const": "L3" }, "payload": { "type": "object", "required": [ "principal_response" ], "properties": { "principal_response": { "type": "string", "enum": [ "acknowledged", "modified", "not_consulted" ] } } }, "signature": { "type": "string", "description": "Ed25519 over the canonical link." } } }, "IntentChain": { "example": { "transaction_id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "chain_status": "complete", "links": [ { "link": "L1", "name": "principal_signal" }, { "link": "L6", "name": "commitment" }, { "link": "L7", "name": "outcome" } ], "chain_hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "chain_signature": "k9Jx2pQ7r4sV1mNc8eTfWZ0aYbHd3GgLpRtUvXyB6CnEoJqSiKlMwOzPu5D4hAtFr7vXsQ2bNcMeKgLpRtUvXyB" }, "type": "object", "description": "Assembled intent chain of custody (L1–L7). Beacons receive a redacted view (L2, L4, L6, L7).", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" }, "chain_status": { "type": "string" }, "links": { "type": "array", "items": { "type": "object" } }, "chain_hash": { "type": ["string", "null"] }, "chain_signature": { "type": ["string", "null"] } } } } }, "x-aura-specification": { "canonical": true, "specVersion": "3.0", "normativeLanguage": "RFC2119", "extensionNamespace": "x-aura-", "precedence": [ "OpenAPI paths, operations and schemas", "x-aura-* normative extensions", "descriptions", "implementation metadata" ], "implementationMetadataNormative": false, "statusVocabulary": [ "normative", "implemented", "reserved", "roadmap", "explanatory", "deprecated" ], "extensions": { "x-aura-glossary": "explanatory", "x-aura-ontology": "normative", "x-aura-design-principles": "explanatory", "x-aura-invariants": "normative", "x-aura-authority": "normative", "x-aura-market-model": "explanatory", "x-aura-market-parameters": "normative-interface", "x-aura-reputation": "normative-interface", "x-aura-conformance": "normative", "x-aura-state-machines": "normative", "x-aura-signature-profiles": "normative", "x-aura-intent-chain": "normative" } }, "x-aura-glossary": { "status": "explanatory", "description": "Canonical definitions of the protocol's terms.", "terms": [ { "term": "Scout", "definition": "An autonomous agent acting for a buyer." }, { "term": "Beacon", "definition": "An autonomous agent acting for a seller." }, { "term": "AURA Core", "definition": "The neutral broker. It interprets intent, routes it to beacons, mediates the exchange, and records the outcome. It holds no commercial position." }, { "term": "Principal", "definition": "The human or legal entity an agent acts for under delegated authority." }, { "term": "Session", "definition": "A logical exchange from a scout's request to a committed transaction." }, { "term": "Request", "definition": "A scout's expression of need: a natural-language intent and optional constraints." }, { "term": "Interpreted Request", "definition": "Core's structured representation of a scout's intent." }, { "term": "Offer", "definition": "A beacon's signed response carrying product, price, and terms." }, { "term": "Constraint", "definition": "A buyer's declared bound on an acceptable outcome. A hard constraint binds. A soft preference ranks." }, { "term": "Transaction", "definition": "A committed exchange between a scout and a beacon." }, { "term": "Clearing record", "definition": "The financial lifecycle of a committed transaction: risk assessment, reserve, and settlement." }, { "term": "Intent chain", "definition": "The signed chain of custody from the human signal to the outcome, links L1 to L7." }, { "term": "Reputation", "definition": "A multi-dimensional behavioural signal Core computes from protocol events." }, { "term": "Settlement rail", "definition": "An external payment system that moves funds for a cleared transaction." }, { "term": "Market profile", "definition": "A named set of market parameters a Core applies within the protocol's invariants." } ] }, "x-aura-ontology": { "status": "normative", "description": "The protocol's entities, their roles, relationships, and prohibitions. Tooling and agents reason over this model; humans read the glossary.", "entities": [ { "name": "Scout", "kind": "agent", "definition": "An agent acting for a buyer.", "actsFor": "Principal", "declares": [ "Request", "Constraint" ], "prohibitedFrom": [ "browsing_inventory", "receiving_beacon_identity_before_commitment" ], "participatesIn": [ "Session", "IntentChain" ] }, { "name": "Beacon", "kind": "agent", "definition": "An agent acting for a seller.", "actsFor": "Principal", "declares": [ "Offer" ], "prohibitedFrom": [ "receiving_scout_identity_before_commitment", "contacting_a_scout_directly" ], "participatesIn": [ "Session", "Transaction" ] }, { "name": "Core", "kind": "neutral_broker", "definition": "The disinterested party that mediates every exchange.", "actsFor": "none", "holdsCommercialPosition": false, "prohibitedFrom": [ "trading_on_its_own_account", "ranking_or_pricing_to_favour_a_side", "revealing_a_party_identity_before_commitment" ], "participatesIn": [ "Session", "Transaction", "Clearing", "IntentChain" ] }, { "name": "Principal", "kind": "party", "definition": "The human or legal entity an agent acts for.", "delegatesTo": [ "Scout", "Beacon" ], "participatesIn": [ "Authority" ] }, { "name": "Session", "kind": "resource", "definition": "An exchange from request to commitment.", "ownedBy": "Scout", "boundTo": "MarketProfile", "contains": [ "Offer" ] }, { "name": "Offer", "kind": "resource", "definition": "A beacon's signed, sealed response.", "issuedBy": "Beacon", "signedBy": "Beacon", "presentedBy": "Core" }, { "name": "Transaction", "kind": "resource", "definition": "A committed exchange.", "commitsFrom": "Offer" }, { "name": "ClearingRecord", "kind": "resource", "definition": "The financial lifecycle of a transaction.", "derivesFrom": "Transaction" }, { "name": "IntentChain", "kind": "record", "definition": "The signed chain of custody from signal to outcome.", "assembledBy": "Core", "links": [ "L1", "L2", "L3", "L4", "L5", "L6", "L7" ] }, { "name": "Request", "kind": "signal", "definition": "A Scout's expression of need.", "declaredBy": "Scout", "interpretedBy": "Core", "produces": "InterpretedRequest" }, { "name": "InterpretedRequest", "kind": "derived_record", "definition": "Core's structured representation of the Scout's intent.", "derivedFrom": "Request", "attestedBy": "Core", "participatesIn": [ "Session" ] }, { "name": "Constraint", "kind": "authority_boundary", "definition": "A declared bound on an acceptable outcome. A hard constraint binds; a soft preference ranks.", "declaredBy": "Scout", "binds": [ "Session", "Offer", "Transaction" ], "variants": [ "hard", "soft" ], "governedBy": "INV-004" }, { "name": "Reputation", "kind": "behavioural_signal", "definition": "A multi-dimensional behavioural signal Core computes from protocol events.", "attachesTo": [ "Principal", "Beacon" ], "derivedFrom": [ "Offer", "Transaction", "ClearingRecord", "Dispute" ] } ] }, "x-aura-design-principles": { "status": "explanatory", "normative": false, "description": "Why the protocol has this shape. Each principle justifies a family of invariants. The principles explain; the invariants govern.", "principles": [ { "id": "DP-001", "name": "Privacy by design", "statement": "Counterparty identity and constraints are disclosed only when the protocol phase requires them.", "supports": [ "INV-002", "INV-003" ], "status": "implemented" }, { "id": "DP-002", "name": "Business rules as gates", "statement": "Binary eligibility rules are enforced before any scoring or settlement economics.", "supports": [ "INV-013" ], "status": "implemented" }, { "id": "DP-003", "name": "Atomicity over partial state", "statement": "A transaction commits in full or leaves no residue.", "supports": [ "INV-006" ], "status": "implemented" }, { "id": "DP-004", "name": "Verifiable provenance", "statement": "Every consequential step is signed and can be reconstructed after the fact.", "supports": [ "INV-008", "INV-009" ], "status": "implemented" }, { "id": "DP-005", "name": "Neutrality of the broker", "statement": "Core mediates the trade without holding a position in it.", "supports": [ "INV-001", "INV-011" ], "status": "implemented" }, { "id": "DP-006", "name": "Explicit authority", "statement": "An agent acts only within authority a principal has delegated and recorded.", "supports": [ "INV-004", "INV-007", "INV-015" ], "status": "implemented" } ] }, "x-aura-invariants": { "status": "normative", "description": "Protocol law. Each invariant binds every conforming Core in every market. It states the rule, the chaos the naive alternative produces, the operations and schemas that manifest it, the market parameters it bounds, and its conformance assertions.", "invariants": [ { "id": "INV-001", "name": "Neutral brokerage", "status": "normative", "statement": "Core MUST mediate every Scout and Beacon interaction. A conforming Core MUST NOT expose an unmediated bilateral channel for protocol offers.", "rationale": "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.", "averts": [ "adverse_selection", "collusive_equilibrium", "oscillation", "asymmetric_exploitation" ], "manifestedBy": { "operations": [ "createSession", "submitOffer", "commitSession" ], "schemas": [ "Session", "Offer", "Transaction" ] }, "boundedParameters": [ "disclosure_schedule", "offer_visibility" ], "conformance": [ { "id": "CONF-INV-001", "assertion": "A Beacon response MUST be submitted to Core and MUST NOT be addressed directly to a Scout.", "assertionType": "property", "fixture": { "given": "A Beacon has an offer for an open session", "when": "a Scout retrieves the session offers", "then": "every offer it receives was routed through Core, and no direct Beacon-to-Scout channel exists" } } ] }, { "id": "INV-002", "name": "Identity abstraction until commitment", "status": "normative", "statement": "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.", "rationale": "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.", "averts": [ "price_discrimination", "information_probing" ], "manifestedBy": { "operations": [ "listOffers", "submitOffer", "getSession" ], "schemas": [ "Offer", "Session" ] }, "boundedParameters": [ "disclosure_schedule" ], "conformance": [ { "id": "CONF-INV-002", "assertion": "A presented offer MUST NOT carry the counterparty’s identity before commitment.", "assertionType": "negative", "fixture": { "given": "An offer presented before commitment", "when": "the offer payload is inspected", "then": "it carries no counterparty identity" } } ] }, { "id": "INV-003", "name": "Monotonic disclosure", "status": "normative", "statement": "Information disclosed to a party MUST only increase as commitment deepens. No phase MAY reveal less than a prior phase.", "rationale": "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.", "averts": [ "defensive_opacity" ], "manifestedBy": { "operations": [ "getSession", "listOffers" ], "schemas": [ "Session" ] }, "boundedParameters": [ "disclosure_schedule" ], "conformance": [ { "id": "CONF-INV-003", "assertion": "A field visible at one phase MUST remain visible at every later phase.", "assertionType": "property", "fixture": { "given": "A field visible to a party at one phase", "when": "the session advances to any later phase", "then": "the field remains visible to that party" } } ] }, { "id": "INV-004", "name": "Constraints as bounds", "status": "normative", "statement": "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.", "rationale": "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.", "averts": [ "unbounded_probing", "authority_violation" ], "manifestedBy": { "operations": [ "createSession", "submitOffer", "counterOffer", "commitSession" ], "schemas": [ "SessionCreate", "OfferSubmission" ] }, "boundedParameters": [], "conformance": [ { "id": "CONF-INV-004", "assertion": "A commit MUST fail when the selected offer violates a hard constraint of the session.", "assertionType": "negative", "fixture": { "given": "A session with a hard constraint and an offer that violates it", "when": "commitSession selects that offer", "then": "Core rejects the commit and creates no transaction" } } ] }, { "id": "INV-005", "name": "Offer expiry", "status": "normative", "statement": "Every offer MUST carry an expiry. Core MUST refuse to commit an expired offer.", "rationale": "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.", "averts": [ "strategic_non_commitment", "speed_arms_race" ], "manifestedBy": { "operations": [ "submitOffer", "commitSession" ], "schemas": [ "Offer" ] }, "boundedParameters": [ "offer_validity_window" ], "conformance": [ { "id": "CONF-INV-005", "assertion": "A commit on an offer past its valid_until MUST be rejected.", "assertionType": "negative", "fixture": { "given": "An offer whose valid_until is in the past", "when": "commitSession is called on it", "then": "Core rejects the commit and creates no transaction" } } ] }, { "id": "INV-006", "name": "Atomic commitment", "status": "normative", "statement": "Commitment MUST be atomic. Committing to one offer MUST reject its siblings in the same transaction, with no observable intermediate state.", "rationale": "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.", "averts": [ "phantom_liquidity", "double_commitment" ], "manifestedBy": { "operations": [ "commitSession" ], "schemas": [ "CommitRequest", "Transaction" ] }, "boundedParameters": [], "conformance": [ { "id": "CONF-INV-006", "assertion": "A successful commit MUST atomically create the transaction and reject all sibling offers; a duplicate idempotency key MUST return the original result.", "assertionType": "sequence", "fixture": { "given": "A session with several pending offers", "when": "commitSession succeeds on one of them", "then": "exactly one transaction is created, all sibling offers are rejected, and replaying the same idempotency key returns the original transaction" } } ] }, { "id": "INV-007", "name": "Persistent identity and qualification", "status": "normative", "statement": "Agents MUST hold a persistent Ed25519 identity established by proof of possession. A new identity MUST start below the participation threshold.", "rationale": "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.", "averts": [ "disposable_identity_defection", "end_game_defection" ], "manifestedBy": { "operations": [ "registerAgent", "registerPrincipal" ], "schemas": [ "AgentRegistration", "PrincipalRegistration" ] }, "boundedParameters": [ "qualification_threshold" ], "conformance": [ { "id": "CONF-INV-007", "assertion": "Registration MUST verify an Ed25519 proof of possession of the submitted key.", "assertionType": "negative", "fixture": { "given": "A registration whose signature does not prove possession of the submitted key", "when": "registerPrincipal or registerAgent is called", "then": "Core rejects the registration" } } ] }, { "id": "INV-008", "name": "Recorded intent and chain of custody", "status": "normative", "statement": "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.", "rationale": "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.", "averts": [ "unadjudicable_dispute" ], "manifestedBy": { "operations": [ "createSession", "submitChainLink", "commitSession", "getIntentChain", "getAttestation" ], "schemas": [ "ChainLinkSubmission", "IntentChain", "Attestation" ] }, "boundedParameters": [], "conformance": [ { "id": "CONF-INV-008", "assertion": "Each chain link MUST be signed by the responsible party and chained to its predecessor.", "assertionType": "property", "fixture": { "given": "An assembled intent chain", "when": "each link is verified", "then": "every link is signed by its responsible party and references its predecessor" } } ] }, { "id": "INV-009", "name": "Verifiable settlement", "status": "normative", "statement": "Clearing MUST advance to settled only on a verifiable, non-repudiable proof of settlement correlated to the original instruction.", "rationale": "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.", "averts": [ "unprovable_settlement" ], "manifestedBy": { "operations": [ "getClearing", "updatePayment" ], "schemas": [ "ClearingRecord" ] }, "boundedParameters": [ "settlement_method" ], "conformance": [ { "id": "CONF-INV-009", "assertion": "A transition to settled MUST carry a rail-signed proof correlated to the settlement instruction.", "assertionType": "property", "fixture": { "given": "A transaction that has transitioned to settled", "when": "the settlement record is read", "then": "it carries a rail-signed proof correlated to the settlement instruction" } } ] }, { "id": "INV-010", "name": "Rail-conditional reserve", "status": "normative", "statement": "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.", "rationale": "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.", "averts": [ "unenforceable_outcome", "duplicative_hold" ], "manifestedBy": { "operations": [ "commitSession", "getClearing" ], "schemas": [ "ClearingRecord" ] }, "boundedParameters": [ "reserve_strategy", "native_repudiation" ], "conformance": [ { "id": "CONF-INV-010", "assertion": "A rail with native repudiation MUST settle without an AURA margin hold; a rail without it MUST carry one.", "assertionType": "property", "fixture": { "given": "One rail with native repudiation and one without", "when": "clearing computes the reserve", "then": "the repudiation rail settles with no AURA margin hold and the other carries one" } } ] }, { "id": "INV-011", "name": "Financial neutrality of the clearinghouse", "status": "normative", "statement": "The clearinghouse MUST hold no commercial position. It MUST NOT rank offers, select beacons, or negotiate terms.", "rationale": "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.", "averts": [ "clearer_self_dealing" ], "manifestedBy": { "operations": [ "getClearing" ], "schemas": [ "ClearingRecord" ] }, "boundedParameters": [], "conformance": [ { "id": "CONF-INV-011", "assertion": "Clearing outputs MUST be a function of risk and rail only, never of a Core commercial interest.", "assertionType": "property", "fixture": { "given": "Two clearings with identical risk and rail inputs", "when": "clearing runs", "then": "the outputs are identical, independent of any Core commercial interest" } } ] }, { "id": "INV-012", "name": "Bilateral risk transparency", "status": "normative", "statement": "Risk MUST be assessed for both parties, and each party MUST see only the assessment that applies to it.", "rationale": "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.", "averts": [ "secret_risk_pricing" ], "manifestedBy": { "operations": [ "getClearing" ], "schemas": [ "ClearingRecord" ] }, "boundedParameters": [ "risk_model" ], "conformance": [ { "id": "CONF-INV-012", "assertion": "A clearing read MUST expose only the requesting party’s risk score.", "assertionType": "negative", "fixture": { "given": "A clearing record shared by two parties", "when": "one party reads clearing", "then": "only the requesting party's risk score is exposed, and the counterparty score is absent" } } ] }, { "id": "INV-013", "name": "Business rules as hard gates", "status": "normative", "statement": "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.", "rationale": "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.", "averts": [ "gate_erosion" ], "manifestedBy": { "operations": [ "createBusinessRule", "commitSession" ], "schemas": [ "BusinessRuleCreate" ] }, "boundedParameters": [ "business_rule_set" ], "conformance": [ { "id": "CONF-INV-013", "assertion": "A commit MUST be refused when any applicable business rule fails, regardless of risk score.", "assertionType": "negative", "fixture": { "given": "A session where an applicable business rule fails", "when": "commitSession is called", "then": "Core refuses the commit regardless of risk score and creates no transaction" } } ] }, { "id": "INV-014", "name": "Repudiability within a bounded window", "status": "normative", "statement": "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.", "rationale": "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.", "averts": [ "silent_repudiation", "strategic_non_commitment" ], "manifestedBy": { "operations": [ "fileDispute", "submitEvidence", "resolveDispute", "getDispute" ], "schemas": [ "DisputeFile", "EvidenceSubmission", "DisputeResolution" ] }, "boundedParameters": [ "dispute_window_days" ], "conformance": [ { "id": "CONF-INV-014", "assertion": "A dispute filed within the window MUST be accepted, and the window MUST be declared before commitment.", "assertionType": "positive", "fixture": { "given": "A committed transaction within its declared dispute window", "when": "a dispute is filed", "then": "Core accepts the dispute, and the window was declared before commitment" } } ] }, { "id": "INV-015", "name": "Least-privilege delegated authority", "status": "normative", "statement": "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.", "rationale": "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.", "averts": [ "privilege_escalation_by_membership", "ambient_authority", "lateral_visibility", "unbounded_delegation" ], "manifestedBy": { "operations": [ "registerAgent", "getDelegationScope", "putDelegationScope", "getPrincipal", "updatePrincipal", "listPrincipalAgents", "listPrincipalTransactions", "getAgent", "commitSession" ], "schemas": [ "DelegationConstraints" ] }, "boundedParameters": [], "conformance": [ { "id": "CONF-INV-015", "assertion": "A request whose authority claim does not cover the action or resource MUST be refused, and a delegation chain deeper than three tiers MUST be rejected.", "assertionType": "negative", "fixture": { "given": "An agent whose claim grants no authority over the target resource", "when": "it calls an operation on that resource", "then": "Core refuses the request and makes no change" } } ] } ] }, "x-aura-authority": { "status": "normative", "description": "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 (INV-004). Authority is least-privilege and narrows down a signed delegation chain to a durable principal (INV-015).", "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.", "agentAsMarker": "An agent's key is a marker, an index into a durable record. Trust reads the chain, the principal, and the evidence (INV-008), 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": [ { "id": "agent_for_principal", "definition": "The agent acts on a named principal's authority and inherits the bounds the principal granted." }, { "id": "principal_direct", "definition": "The agent acts on its own authority. A non-human root of authority lives here." }, { "id": "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." }, "delegationChain": { "definition": "How authority passes from a principal to an agent and onward to the sub-agents it spawns.", "maxTiers": 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." }, "consentTiers": [ { "id": "explicit", "definition": "The principal signs the specific action." }, { "id": "policy", "definition": "The action is permitted by a principal-defined policy the agent cites." }, { "id": "delegated", "definition": "The action falls within a standing delegation scope the principal granted." } ], "delegationScope": { "definition": "The bounded authority an agent holds for a principal.", "boundedBy": [ "hard_constraints", "consent_tier", "principal_approval", "market_profile", "resource_scope", "visibility_scope" ], "governs": [ "commitSession", "counterOffer" ] }, "authorityAttestation": { "definition": "Proof presented at commit that the action is within authority.", "requiredAt": "commitSession", "carries": [ "consent_tier", "scope_reference", "principal_signature_or_policy_citation" ] }, "principalApproval": { "definition": "An explicit principal decision captured for an action that exceeds standing authority.", "requiredWhen": "the action exceeds the delegation scope or a market-profile approval threshold" }, "externalCredentialInterop": { "status": "roadmap", "definition": "Delegation may be expressed with an external verifiable-credential format, carried as a signed claim." }, "manifests": [ "INV-004", "INV-015" ] }, "x-aura-state-machines": { "session": { "description": "Session lifecycle. Terminal states are absorbing. The clearing lifecycle is a separate machine and never changes the session status.", "readSemantics": { "status": "explanatory", "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.", "lazyTransitions": [ "T4", "T12" ] }, "initial": "collecting_offers", "states": [ { "name": "collecting_offers", "category": "active" }, { "name": "offers_available", "category": "active" }, { "name": "committed", "category": "active" }, { "name": "fulfilled", "category": "active" }, { "name": "completed", "category": "active", "absorbing": false, "note": "Disputable within the dispute window; otherwise the clearing record advances to cleared." }, { "name": "disputed", "category": "active" }, { "name": "resolved", "category": "terminal" }, { "name": "cancelled", "category": "terminal" }, { "name": "expired", "category": "terminal" }, { "name": "failed", "category": "terminal", "reserved": true } ], "reservedStates": [ "created", "interpreting", "discovering" ], "transitions": [ { "id": "T1", "from": null, "event": "POST /v1/sessions", "to": "collecting_offers", "guard": "Valid intent string; authenticated agent" }, { "id": "T2", "from": [ "collecting_offers" ], "event": "POST /v1/sessions/{session_id}/offers (first offer)", "to": "offers_available", "guard": "Session not expired; Beacon active" }, { "id": "T3", "from": [ "offers_available" ], "event": "POST /v1/sessions/{session_id}/offers (subsequent)", "to": "offers_available", "guard": "Session not expired; Beacon active" }, { "id": "T4", "from": [ "collecting_offers" ], "event": "First valid offer observed", "to": "offers_available", "guard": "Pending offers found", "materialisation": "lazy_allowed", "observedBy": [ "GET /v1/sessions/{session_id}" ] }, { "id": "T5", "from": [ "collecting_offers" ], "event": "POST /v1/sessions/{session_id}/cancel", "to": "cancelled", "guard": "Owner; status NOT IN (committed, completed)" }, { "id": "T6", "from": [ "offers_available" ], "event": "POST /v1/sessions/{session_id}/cancel", "to": "cancelled", "guard": "Owner; status NOT IN (committed, completed)" }, { "id": "T7", "from": [ "offers_available" ], "event": "POST /v1/sessions/{session_id}/commit", "to": "committed", "guard": "Owner; not expired; offer belongs to session; unique idempotency key" }, { "id": "T8", "from": [ "committed" ], "event": "PUT /v1/transactions/{transaction_id}/fulfillment (delivered, payment pending)", "to": "fulfilled", "guard": "Participant; fulfillment_status=delivered; payment_status != charged" }, { "id": "T9", "from": [ "committed" ], "event": "PUT /v1/transactions/{transaction_id}/fulfillment (delivered, payment charged)", "to": "completed", "guard": "Participant; fulfillment_status=delivered; payment_status=charged" }, { "id": "T10", "from": [ "committed" ], "event": "PUT /v1/transactions/{transaction_id}/payment (charged, fulfillment delivered)", "to": "completed", "guard": "Participant; payment_status=charged; fulfillment_status=delivered" }, { "id": "T11", "from": [ "fulfilled" ], "event": "PUT /v1/transactions/{transaction_id}/payment (charged)", "to": "completed", "guard": "Participant; payment_status=charged; fulfillment_status=delivered" }, { "id": "T12", "from": [ "collecting_offers", "offers_available" ], "event": "Session expiry elapsed", "to": "expired", "guard": "expires_at < NOW(); status NOT IN (completed, cancelled, expired)", "materialisation": "lazy_allowed", "observedBy": [ "GET /v1/sessions/{session_id}", "POST /v1/sessions/{session_id}/commit" ] }, { "id": "T13", "from": [ "committed" ], "event": "POST /v1/transactions/{transaction_id}/disputes", "to": "disputed", "guard": "Participant; reason provided; not already disputed" }, { "id": "T14", "from": [ "fulfilled" ], "event": "POST /v1/transactions/{transaction_id}/disputes", "to": "disputed", "guard": "As T13" }, { "id": "T15", "from": [ "completed" ], "event": "POST /v1/transactions/{transaction_id}/disputes", "to": "disputed", "guard": "As T13; within dispute window (completed_at + dispute_window > NOW())" }, { "id": "T16", "from": [ "disputed" ], "event": "POST /v1/disputes/{dispute_id}/resolve (resolution applied)", "to": "resolved", "guard": "Adjudication authority; outcome + remedial actions" }, { "id": "T17", "from": [ "disputed" ], "event": "POST /v1/disputes/{dispute_id}/resolve (withdrawn)", "to": "previous_state", "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.", "sessionLinksByState": { "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" ] }, "sessionLinkNotes": { "collecting_offers": "offers and commit appear only once pending offers exist; self and cancel always." }, "transactionLinks": { "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": [ { "name": "pending" }, { "name": "risk_assessed" }, { "name": "authorized" }, { "name": "settling" }, { "name": "settled" }, { "name": "dispute_term_active" }, { "name": "disputed" }, { "name": "resolved" }, { "name": "cleared", "category": "terminal" }, { "name": "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": [] } } }, "x-aura-signature-profiles": { "status": "normative", "algorithm": "Ed25519", "description": "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.", "profiles": [ { "id": "authenticated_request", "description": "Proof that an authenticated request was issued by the holder of the agent key.", "appliesTo": { "operations": [ "all agent-authenticated operations" ] }, "signedMaterial": [ "method", "path", "timestamp", "body_hash" ], "requiredHeaders": [ "X-Agent-Id", "X-Agent-Timestamp", "X-Agent-Signature" ] }, { "id": "principal_registration", "description": "Proof of possession of the principal key at registration.", "appliesTo": { "operations": [ "registerPrincipal" ] }, "signedMaterial": [ "canonical_request_body" ], "requiredHeaders": [ "X-Signature" ] }, { "id": "agent_registration", "description": "Proof of possession of the agent key at registration.", "appliesTo": { "operations": [ "registerAgent" ] }, "signedMaterial": [ "canonical_request_body" ], "requiredHeaders": [ "X-Agent-Signature" ] }, { "id": "beacon_offer", "description": "A Beacon's signature binding it to the terms of an offer.", "appliesTo": { "operations": [ "submitOffer" ] }, "delimiter": "\n", "encoding": "UTF-8", "payloadFields": [ "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\nbcn_42q7r1\nprod_widget_9\n349.99\nUSD\n2026-07-01T00:00:00Z\n9f86d0818..." } }, { "id": "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.", "appliesTo": { "operations": [ "commitSession" ] }, "prefix": "CORE-COUNTERSIGN" }, { "id": "interpretation_attestation", "description": "Core's signed binding between the raw intent and its structured interpretation.", "appliesTo": { "operations": [ "createSession", "getAttestation" ] }, "signedMaterial": [ "raw_intent", "structured_interpretation", "model_id" ] }, { "id": "intent_chain_link", "description": "A signature on one link of the intent chain, chained to its predecessor.", "appliesTo": { "operations": [ "submitChainLink" ] }, "signedMaterial": [ "link", "payload", "previous_link_hash" ] }, { "id": "assembled_intent_chain", "description": "Core's signature over the assembled chain at commit.", "appliesTo": { "operations": [ "getIntentChain" ] }, "signedMaterial": [ "ordered_link_hashes" ] } ] }, "x-aura-intent-chain": { "description": "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": [ { "link": "L1", "name": "principal_signal", "signer": "scout_agent", "proves": "Scout received the principal's input and forwarded it faithfully.", "source": "Scout SDK at session creation" }, { "link": "L2", "name": "interpretation", "signer": "core", "proves": "Core bound raw input to structured output via a specific model.", "source": "Interpretation attestation" }, { "link": "L3", "name": "principal_review", "signer": "scout_agent", "proves": "Principal saw the interpretation and did not object, or was declared not consulted.", "source": "Scout SDK after interpretation" }, { "link": "L4", "name": "offer_selection", "signer": "scout_agent", "proves": "The agent selected this offer from the available set.", "source": "Scout SDK at offer selection" }, { "link": "L5", "name": "principal_consent", "signer": "scout_agent_or_principal", "proves": "Principal consented: explicit signature, cited policy, or cited delegation scope.", "source": "Authority attestation" }, { "link": "L6", "name": "commitment", "signer": "core", "proves": "Core executed the atomic commit; counter-signature confirms authority verified and recorded.", "source": "Core at commit" }, { "link": "L7", "name": "outcome", "signer": "core", "proves": "Terminal state: fulfillment/payment status or dispute resolution outcome.", "source": "Core at completion or dispute resolution" } ], "beaconRedactedView": [ "L2", "L4", "L6", "L7" ] }, "x-aura-market-model": { "status": "explanatory", "normative": false, "description": "Why the protocol has this shape. The market model explains; the invariants govern.", "ontologicalClaim": "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.", "marketNotShop": "AURA models a market, not a shop: intent, discovery, negotiation, commitment, settlement. Agents negotiate; they do not browse.", "foundations": [ { "theory": "Repeated-game cooperation", "author": "Axelrod", "claim": "Cooperation emerges among self-interested agents when interactions repeat, behaviour is observable, and retaliation is cheap." }, { "theory": "The market for lemons", "author": "Akerlof", "claim": "Asymmetric quality information drives good sellers out unless credible quality signals exist." }, { "theory": "Mechanism design", "author": "Hurwicz, Myerson, Maskin", "claim": "Rules can be designed so that rational, self-interested behaviour produces desirable outcomes." } ], "microstructureProblems": [ { "problem": "adverse_selection", "resolvedBy": [ "INV-001", "INV-007" ] }, { "problem": "information_probing", "resolvedBy": [ "INV-002", "INV-003", "INV-004" ] }, { "problem": "strategic_non_commitment", "resolvedBy": [ "INV-005", "INV-006", "INV-014" ] } ], "algorithmicPriceDynamics": [ { "failureMode": "collusive_equilibrium", "resolution": "The neutral broker removes the bilateral channel two pricing algorithms would converge through.", "resolvedBy": [ "INV-001" ] }, { "failureMode": "oscillation", "resolution": "Offer expiry makes negotiation discrete, ending the continuous feedback loop.", "resolvedBy": [ "INV-005" ] }, { "failureMode": "asymmetric_exploitation", "resolution": "Neither algorithm observes the other's response function; Core mediates.", "resolvedBy": [ "INV-001" ] } ], "fixAnalogy": "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.", "computableMarketConditions": [ "Participants are rational within their delegated scope.", "The rules are enforced structurally, not behaviourally.", "A neutral intermediary holds canonical state and breaks bilateral dynamics." ] }, "x-aura-market-parameters": { "status": "normative-interface", "description": "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": [ { "id": "disclosure_schedule", "definition": "Per-field, per-phase disclosure tiers.", "boundedBy": [ "INV-002", "INV-003" ] }, { "id": "offer_validity_window", "definition": "How long an offer remains committable.", "boundedBy": [ "INV-005" ] }, { "id": "qualification_threshold", "definition": "Minimum reputation to participate.", "boundedBy": [ "INV-007" ] }, { "id": "dispute_window_days", "definition": "How long a committed transaction is repudiable. A market may not set zero.", "boundedBy": [ "INV-014" ] }, { "id": "settlement_method", "definition": "The rail used to settle.", "boundedBy": [ "INV-009" ] }, { "id": "reserve_strategy", "definition": "How the reserve margin is sized.", "boundedBy": [ "INV-010" ] }, { "id": "risk_model", "definition": "How bilateral risk is scored.", "boundedBy": [ "INV-012" ] }, { "id": "business_rule_set", "definition": "The hard gates a beacon defines.", "boundedBy": [ "INV-013" ] } ] }, "x-aura-reputation": { "status": "normative-interface", "description": "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": [ { "id": "fulfilment_reliability", "definition": "Share of commitments honoured, weighted by recency." }, { "id": "offer_accuracy", "definition": "Gap between what was offered and what was delivered." }, { "id": "constraint_fidelity", "definition": "How often a Beacon's declared capabilities match the constraints it satisfies." }, { "id": "negotiation_integrity", "definition": "Rate of offer withdrawal, price change after commitment, and reneged terms." }, { "id": "response_relevance", "definition": "Match between Scout intent and Beacon offer." } ], "transparencyModel": "Each dimension is independently queryable and computed from protocol events, not self-reported.", "attachesTo": [ "Principal", "Beacon" ] }, "proprietary": { "scoringFormula": "excluded", "weightingModel": "excluded", "operationalParameters": "excluded" }, "supports": [ "INV-007" ] }, "x-aura-errors": { "status": "normative", "description": "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.", "categories": { "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." }, "codes": [ { "code": "authentication_required", "http": 401, "retryable": false, "category": "auth", "message": "The request carried no valid agent authentication. Provide agentId, agentTimestamp, and agentSignature.", "invariant": "persistent-identity-and-qualification" }, { "code": "beacon_no_signing_key", "http": 400, "retryable": false, "category": "auth", "message": "The Beacon has no registered signing key to verify against." }, { "code": "invalid_offer_signature", "http": 400, "retryable": false, "category": "auth", "message": "The offer signature did not verify against the Beacon's registered key.", "invariant": "recorded-intent-and-chain-of-custody" }, { "code": "invalid_signature", "http": 401, "retryable": false, "category": "auth", "message": "The agent signature did not verify against the registered key.", "invariant": "persistent-identity-and-qualification" }, { "code": "key_revoked", "http": 403, "retryable": false, "category": "auth", "message": "The presented key has been revoked.", "invariant": "persistent-identity-and-qualification" }, { "code": "missing_offer_signature", "http": 400, "retryable": false, "category": "auth", "message": "The offer was submitted without its required signature.", "invariant": "recorded-intent-and-chain-of-custody" }, { "code": "missing_signature", "http": 401, "retryable": false, "category": "auth", "message": "A required authentication signature header was absent." }, { "code": "cross_beacon_access_denied", "http": 403, "retryable": false, "category": "authorization", "message": "A Beacon may only access its own sessions and offers.", "invariant": "identity-abstraction-until-commitment" }, { "code": "cross_scout_access_denied", "http": 403, "retryable": false, "category": "authorization", "message": "A Scout may only access its own sessions.", "invariant": "identity-abstraction-until-commitment" }, { "code": "forbidden", "http": 403, "retryable": false, "category": "authorization", "message": "The authenticated agent may not act on this resource." }, { "code": "not_filing_agent", "http": 403, "retryable": false, "category": "authorization", "message": "Only the agent that filed the dispute may take this action." }, { "code": "scout_cannot_register_rules", "http": 403, "retryable": false, "category": "authorization", "message": "Scouts may not register business rules.", "invariant": "business-rules-as-hard-gates" }, { "code": "system_role_required", "http": 403, "retryable": false, "category": "authorization", "message": "This operation requires the system role." }, { "code": "dispute_already_exists", "http": 409, "retryable": false, "category": "conflict", "message": "A dispute already exists for this transaction." }, { "code": "duplicate_transaction", "http": 409, "retryable": false, "category": "conflict", "message": "A transaction already exists for this commitment; the commit is idempotent.", "invariant": "atomic-commitment" }, { "code": "adapter_not_found", "http": 404, "retryable": false, "category": "not_found", "message": "The requested resource was not found." }, { "code": "beacon_not_found", "http": 404, "retryable": false, "category": "not_found", "message": "The requested resource was not found." }, { "code": "clearing_not_found", "http": 404, "retryable": false, "category": "not_found", "message": "The requested resource was not found." }, { "code": "not_found", "http": 404, "retryable": false, "category": "not_found", "message": "The requested resource was not found." }, { "code": "offer_not_found", "http": 404, "retryable": false, "category": "not_found", "message": "The requested resource was not found." }, { "code": "principal_not_found", "http": 404, "retryable": false, "category": "not_found", "message": "The requested resource was not found." }, { "code": "profile_not_found", "http": 404, "retryable": false, "category": "not_found", "message": "The requested resource was not found." }, { "code": "rule_not_found", "http": 404, "retryable": false, "category": "not_found", "message": "The requested resource was not found." }, { "code": "session_not_found", "http": 404, "retryable": false, "category": "not_found", "message": "The requested resource was not found." }, { "code": "transaction_not_found", "http": 404, "retryable": false, "category": "not_found", "message": "The requested resource was not found." }, { "code": "cancel_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "chain_fetch_failed", "http": 503, "retryable": true, "category": "operational", "message": "A backend dependency was temporarily unavailable. Retry with backoff." }, { "code": "commit_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "database_unavailable", "http": 503, "retryable": true, "category": "operational", "message": "A backend dependency was temporarily unavailable. Retry with backoff." }, { "code": "dispute_filing_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "evidence_submission_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "fetch_failed", "http": 503, "retryable": true, "category": "operational", "message": "A backend dependency was temporarily unavailable. Retry with backoff." }, { "code": "offer_submission_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "profile_unavailable", "http": 503, "retryable": true, "category": "operational", "message": "A backend dependency was temporarily unavailable. Retry with backoff." }, { "code": "registration_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "resolution_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "revocation_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "scope_creation_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "session_creation_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "update_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "rate_limit_exceeded", "http": 429, "retryable": true, "category": "rate_limit", "message": "Too many requests. Retry after the indicated delay." }, { "code": "beacon_cannot_counter", "http": 409, "retryable": false, "category": "state", "message": "The Beacon cannot submit a counter-offer here." }, { "code": "beacon_inactive", "http": 403, "retryable": false, "category": "state", "message": "The Beacon is not active." }, { "code": "cannot_cancel", "http": 409, "retryable": false, "category": "state", "message": "The session cannot be cancelled in its current state." }, { "code": "cannot_withdraw", "http": 409, "retryable": false, "category": "state", "message": "The offer cannot be withdrawn in its current state." }, { "code": "consent_elevation_required", "http": 403, "retryable": false, "category": "state", "message": "The action requires a higher consent tier than the delegation grants.", "invariant": "least-privilege-delegated-authority" }, { "code": "dispute_not_open", "http": 409, "retryable": false, "category": "state", "message": "The dispute is not open." }, { "code": "dispute_window_expired", "http": 409, "retryable": false, "category": "state", "message": "The dispute window has closed.", "invariant": "repudiability-within-a-bounded-window" }, { "code": "evidence_deadline_passed", "http": 409, "retryable": false, "category": "state", "message": "The evidence submission deadline has passed.", "invariant": "repudiability-within-a-bounded-window" }, { "code": "negotiation_exhausted", "http": 409, "retryable": false, "category": "state", "message": "The negotiation has reached its round limit." }, { "code": "not_disputable", "http": 409, "retryable": false, "category": "state", "message": "The transaction is not in a disputable state.", "invariant": "repudiability-within-a-bounded-window" }, { "code": "offer_not_counterable", "http": 409, "retryable": false, "category": "state", "message": "The offer cannot be countered in its current state." }, { "code": "principal_inactive", "http": 403, "retryable": false, "category": "state", "message": "The principal is not active." }, { "code": "session_expired", "http": 409, "retryable": false, "category": "state", "message": "The session has expired and no longer accepts actions." }, { "code": "session_not_accepting_offers", "http": 409, "retryable": false, "category": "state", "message": "The session is not accepting offers in its current state." }, { "code": "session_not_committable", "http": 409, "retryable": false, "category": "state", "message": "The session is not in a committable state.", "invariant": "atomic-commitment" }, { "code": "session_not_negotiable", "http": 409, "retryable": false, "category": "state", "message": "The session is not in a negotiable state." }, { "code": "transaction_frozen", "http": 409, "retryable": false, "category": "state", "message": "Fulfilment and payment updates are frozen while the transaction is disputed.", "invariant": "repudiability-within-a-bounded-window" }, { "code": "chain_link_failed", "http": 400, "retryable": false, "category": "validation", "message": "The intent-chain link could not be appended.", "invariant": "recorded-intent-and-chain-of-custody" }, { "code": "chain_validation_failed", "http": 400, "retryable": false, "category": "validation", "message": "The submitted intent-chain link did not validate.", "invariant": "recorded-intent-and-chain-of-custody" }, { "code": "default_profile_missing", "http": 400, "retryable": false, "category": "validation", "message": "The request was rejected by a contract or business-rule check." }, { "code": "invalid_adapter_id", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_beacon_id", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_capacity", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_clearinghouse_terms", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_consent_requirements", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_constraints", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_endpoint_url", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_field", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_fulfillment_terms", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_idempotency_key", "http": 400, "retryable": false, "category": "validation", "message": "The Idempotency-Key header was malformed." }, { "code": "invalid_key", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_offer_id", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_parameter", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_price", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_profile_id", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_quantity", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_risk_tolerance", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_rule_id", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_settlement_preference", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_status", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "missing_beacon_id", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "missing_description", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "missing_fields", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "missing_payment_terms_hash", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "missing_to_status", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "no_chain", "http": 400, "retryable": false, "category": "validation", "message": "The request was rejected by a contract or business-rule check." }, { "code": "no_changes", "http": 400, "retryable": false, "category": "validation", "message": "The request was rejected by a contract or business-rule check." }, { "code": "no_scope", "http": 400, "retryable": false, "category": "validation", "message": "The request was rejected by a contract or business-rule check." }, { "code": "payload_too_large", "http": 413, "retryable": false, "category": "validation", "message": "The request body exceeded the size limit." }, { "code": "payment_terms_hash_mismatch", "http": 400, "retryable": false, "category": "validation", "message": "The payment terms hash did not match the signed offer.", "invariant": "recorded-intent-and-chain-of-custody" }, { "code": "unknown_profile", "http": 400, "retryable": false, "category": "validation", "message": "The request was rejected by a contract or business-rule check." } ] }, "x-aura-conformance": { "status": "normative", "description": "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": [ { "id": "core-minimal", "description": "The session, offer, commitment, identity, and intent-chain laws every Core must honour.", "requiresInvariants": [ "INV-001", "INV-002", "INV-003", "INV-004", "INV-005", "INV-006", "INV-007", "INV-008", "INV-015" ] }, { "id": "core-clearing", "description": "The clearing, settlement, reserve, neutrality, risk, business-rule, and repudiability laws a clearing Core must honour.", "requiresInvariants": [ "INV-009", "INV-010", "INV-011", "INV-012", "INV-013", "INV-014" ] }, { "id": "beacon-minimal", "description": "What a conforming Beacon must honour: signed, time-bound offers, with its identity withheld until commitment.", "requiresInvariants": [ "INV-002", "INV-005" ], "requiresSignatureProfiles": [ "beacon_offer" ] }, { "id": "scout-minimal", "description": "What a conforming Scout must honour: stay within delegated authority and commit atomically.", "requiresInvariants": [ "INV-004", "INV-006" ] } ], "assertionSource": "x-aura-invariants[].conformance", "assertionTypes": { "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." } } }