{ "openapi": "3.1.0", "info": { "title": "HumanMirror Agent OS API", "version": "1.0.0", "description": "Machine-native Proof-of-State and exact SHA-256 state-continuity verification with scoped trust/automation signals. Paid execution uses x402 V2 with USDC on Base mainnet." }, "servers": [ { "url": "https://humanmirror.fr" } ], "externalDocs": { "description": "HumanMirror Agent OS discovery manifest", "url": "https://humanmirror.fr/.well-known/agent-os.json" }, "paths": { "/api/v1/agent/state-and-trust/": { "post": { "summary": "Sign agent state and verify exact continuity", "operationId": "validateStateAndTrust", "description": "Signs a caller-supplied SHA-256 state, compares it with an optional previous SHA-256 state hash for exact continuity, and issues a scoped trust/automation signal. This endpoint does not claim semantic-vector distance, persistent reputation history, MEV protection, or unmeasured efficiency gains.", "x-humanmirror-price-usdc": "0.050", "x-humanmirror-protocol": "x402-humanmirror-v1", "x-x402": { "version": 2, "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x48096526488f2D51df6bcA1B1f3A3639986cc3dD", "amount": "50000", "requestHeader": "PAYMENT-SIGNATURE", "challengeHeader": "PAYMENT-REQUIRED", "settlementHeader": "PAYMENT-RESPONSE" }, "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v2 signed payment payload. Omit to receive an HTTP 402 challenge unless Pro/Enterprise access applies." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_id", "current_state_hash" ], "properties": { "agent_id": { "type": "string", "minLength": 1, "maxLength": 160, "examples": [ "agent_example" ] }, "current_state_hash": { "type": "string", "pattern": "^(0x)?[0-9a-fA-F]{64}$" }, "previous_vector": { "type": "string", "pattern": "^(0x)?[0-9a-fA-F]{64}$" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Signed state proof and scoped trust signal after authorized access/payment." }, "400": { "description": "Invalid state input." }, "402": { "description": "Payment Required — 0.050 USDC on Base mainnet.", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "Base64-encoded x402 v2 payment requirements." } } }, "503": { "description": "x402 runtime or facilitator unavailable." } } } }, "/api/value/resolve/": { "get": { "summary": "Discover HumanMirror Universal Value Resolver", "responses": { "200": { "description": "HUVP discovery and rail status." } } }, "post": { "summary": "Normalize value intent and select a compatible live rail", "operationId": "resolveUniversalValueIntent", "description": "Applies HUVP normalization, Value Firewall policy and safe live-rail routing. Returns a fee quote; it does not fabricate settlement.", "responses": { "200": { "description": "Normalized intent, firewall decision, route and fee policy." }, "400": { "description": "Invalid intent." }, "403": { "description": "Policy blocked the transaction." } } } }, "/api/value/firewall/": { "post": { "summary": "Evaluate transaction policy before routing", "operationId": "evaluateValueFirewall", "responses": { "200": { "description": "ALLOW, REVIEW or BLOCK policy result." } } } }, "/api/value/receipt/": { "post": { "summary": "Create a signed caller-attested universal receipt", "operationId": "createUniversalValueReceipt", "description": "Caller-attested receipts are kept distinct from authoritative verified settlement receipts.", "responses": { "200": { "description": "Signed HUVP receipt." }, "400": { "description": "Transaction reference required." } } } }, "/api/value/bind/": { "get": { "summary": "Discover HumanMirror Purchase Firewall transaction binding", "operationId": "discoverPurchaseFirewallBinding", "responses": { "200": { "description": "Binding protocol, decision states, accepted input layers and truth boundary." } } }, "post": { "summary": "Bind agent purchase intent, action and payment terms before settlement", "operationId": "bindAgentPurchaseTransaction", "description": "Creates a signed huvp-transaction-binding/1 decision across caller-supplied purchase intent, proposed action, exact payment terms and scoped authorization evidence. HumanMirror is non-custodial and does not replace the native payment provider or independently prove legal user authorization.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "intent", "action", "payment" ], "properties": { "intent": { "type": "object" }, "action": { "type": "object" }, "payment": { "type": "object" }, "authorization": { "type": "object" } } } } } }, "responses": { "200": { "description": "Signed ALLOW or REVIEW binding." }, "400": { "description": "Invalid or missing purchase intent." }, "403": { "description": "BLOCK — proposed payment drifts from declared intent or policy." }, "503": { "description": "Binding signer unavailable." } } } }, "/api/value/close/": { "get": { "summary": "Discover HumanMirror Purchase Firewall closure", "operationId": "discoverPurchaseFirewallClosure", "responses": { "200": { "description": "Closure protocol, verdict states and truth boundary." } } }, "post": { "summary": "Reconcile a signed transaction binding with observed execution", "operationId": "closeAgentPurchaseTransaction", "description": "Verifies the HumanMirror transaction-binding signature, compares the observed action and payment against the authorized binding, and emits a signed MATCH or DRIFT closure. This does not independently prove external settlement, delivery or legal authorization.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "binding", "observed" ], "properties": { "binding": { "type": "object" }, "observed": { "type": "object", "properties": { "action": { "type": "object" }, "payment": { "type": "object" }, "outcome": {}, "evidence": {} } } } } } } }, "responses": { "200": { "description": "Signed MATCH closure." }, "400": { "description": "Missing or invalid binding shape." }, "403": { "description": "Binding signature is invalid." }, "409": { "description": "Signed DRIFT closure." }, "503": { "description": "Closure signer unavailable." } } } }, "/api/value/ucp-bind/": { "get": { "summary": "Discover UCP to Purchase Firewall mapping adapter", "operationId": "discoverUcpPurchaseFirewallAdapter", "responses": { "200": { "description": "Adapter version, mapping scope and truth boundary." } } }, "post": { "summary": "Map a UCP checkout into a signed HumanMirror transaction binding", "operationId": "mapUcpCheckoutToPurchaseFirewall", "description": "Maps caller-supplied UCP checkout fields into huvp-transaction-binding/1. Requires an explicit currency exponent so minor units are never guessed. This is a mapping adapter, not a UCP conformance, signature, authorization or settlement verifier.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "checkout", "currency_exponent" ], "properties": { "checkout": { "type": "object" }, "currency_exponent": { "type": "integer", "minimum": 0, "maximum": 6 }, "payment": { "type": "object" }, "authorization": { "type": "object" }, "constraints": { "type": "object" } } } } } }, "responses": { "200": { "description": "Signed ALLOW or REVIEW HumanMirror binding plus mapping metadata." }, "400": { "description": "Missing checkout, currency exponent, total, currency or checkout id." }, "403": { "description": "BLOCK — mapped/native payment context conflicts with purchase intent or policy." }, "503": { "description": "Binding signer unavailable." } } } }, "/api/agent-identity-wallet/": { "get": { "summary": "Discover HumanMirror Agent Identity & Autonomous Wallet Protocol", "operationId": "discoverAgentIdentityWallet", "responses": { "200": { "description": "Protocol descriptor, interoperability, pricing and truth boundaries." } } }, "post": { "summary": "Compose an agent passport with non-custodial wallet policy and execution-assurance routes", "operationId": "composeAgentIdentityWallet", "description": "Creates a content-addressed agent evidence passport from caller-supplied native identity references and declared wallet context. Optionally evaluates a HumanMirror Agent Reserve policy when policy and transaction are supplied. This endpoint does not perform regulatory KYC, legal-identity certification, wallet-control verification, custody, signing or settlement.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identity": { "type": "object" }, "wallet": { "type": "object" }, "policy": { "type": "object" }, "transaction": { "type": "object" } } } } } }, "responses": { "200": { "description": "Agent passport envelope, wallet-control descriptor or policy decision, and execution-assurance routes." }, "400": { "description": "Invalid policy or transaction data." }, "405": { "description": "Unsupported method." } } } }, "/api/value/0x-bind/": { "get": { "summary": "Discover 0x Quote to Purchase Firewall mapping adapter", "operationId": "discover0xPurchaseFirewallAdapter", "responses": { "200": { "description": "Adapter version, mapping scope and truth boundary." } } }, "post": { "summary": "Map a caller-supplied 0x firm Quote into a signed HumanMirror transaction binding", "operationId": "map0xQuoteToPurchaseFirewall", "description": "Maps the 0x Quote response transaction calldata into huvp-transaction-binding/1 before the caller signs or executes the swap. HumanMirror does not call 0x, pay the API access fee, sign or broadcast the swap, custody funds or independently prove settlement.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "chain_id", "quote" ], "properties": { "chain_id": { "type": "integer", "minimum": 1 }, "quote": { "type": "object" }, "payment": { "type": "object" }, "authorization": { "type": "object" }, "constraints": { "type": "object" } } } } } }, "responses": { "200": { "description": "Signed ALLOW or REVIEW HumanMirror binding plus mapping metadata." }, "400": { "description": "Missing chain id or valid transaction to/data." }, "403": { "description": "BLOCK — mapped payment context conflicts with declared policy." }, "503": { "description": "Binding signer unavailable." } } } } }, "x-humanmirror-discovery": { "agent_os": "https://humanmirror.fr/.well-known/agent-os.json", "agent": "https://humanmirror.fr/.well-known/agent.json", "a2a": "https://humanmirror.fr/.well-known/agent-card.json", "x402": "https://humanmirror.fr/.well-known/x402.json", "catalog": "https://humanmirror.fr/x402/catalog.json", "mcp": "https://humanmirror.fr/api/x402/mcp/", "schema": "https://humanmirror.fr/schemas/agent-os-v1.json", "value_protocol": "https://humanmirror.fr/.well-known/value-protocol.json", "purchase_firewall": "https://humanmirror.fr/.well-known/purchase-firewall.json", "purchase_firewall_closure": "https://humanmirror.fr/api/value/close/", "ucp_purchase_firewall": "https://humanmirror.fr/api/value/ucp-bind/", "agent_identity_wallet": "https://humanmirror.fr/api/agent-identity-wallet/", "zero_x_purchase_firewall": "https://humanmirror.fr/api/value/0x-bind/" } }