{ "openapi": "3.1.0", "info": { "title": "RealAddr for Agents API", "version": "0.8.0-spec", "description": "Implementation contract, not a deployed service. Hackathon mail scope is approval, enabled status and a human-entered destination; no physical forwarding. ENSv2 names on Ethereum Sepolia reference leases; public resolution does not disclose forwarding addresses." }, "servers": [ { "url": "https://address.chain.tokyo", "description": "Planned hackathon service origin. Domain and DNS setup are performed by the operator; deployment and availability are not yet verified." } ], "paths": { "/health": { "get": { "operationId": "getHealth", "summary": "Process liveness only; external dependencies are not checked", "security": [], "responses": { "200": { "description": "API process is running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } } } }, "/openapi.json": { "get": { "operationId": "getOpenApi", "summary": "Read the planned public OpenAPI contract", "security": [], "responses": { "200": { "description": "OpenAPI 3.1 document", "content": { "application/vnd.oai.openapi+json": { "schema": { "$ref": "#/components/schemas/OpenApiDocument" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } } } }, "/v1/auth/challenges": { "post": { "operationId": "createAgentChallenge", "summary": "Create domain-bound, expiring wallet challenge", "security": [], "parameters": [], "responses": { "201": { "description": "Expiring wallet authentication challenge created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Challenge" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "400": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "401": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "403": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "404": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "409": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "410": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "422": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "429": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "503": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthChallengeRequest" } } } } } }, "/v1/auth/sessions": { "post": { "operationId": "createAgentSession", "summary": "Consume challenge and issue agent credential", "security": [], "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSession" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "400": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "401": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "403": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "404": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "409": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "410": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "422": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "429": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "503": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureProof" } } } } } }, "/v1/auth/session": { "delete": { "operationId": "revokeAgentSession", "summary": "Revoke current agent credential", "security": [ { "agentBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "responses": { "204": { "description": "Revoked", "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "400": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "401": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "403": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "404": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "409": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "410": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "422": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "429": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "503": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } } } }, "/v1/locations": { "get": { "operationId": "listBuildings", "summary": "List public buildings and current plans", "security": [ { "agentBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Buildings" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "400": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "401": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "403": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "404": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "409": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "410": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "422": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "429": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "503": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } } } }, "/v1/locations/{locationId}/floors/{floor}": { "get": { "operationId": "getFloorAvailability", "summary": "Read the current availability of a virtual slot without disclosing other owners", "parameters": [ { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "floor", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 65535 } } ], "responses": { "200": { "description": "Authoritative snapshot; reserve again in the payment intent transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FloorAvailability" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "401": { "description": "Agent credential missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "404": { "description": "Location unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "422": { "description": "Floor must be an integer from 1 through 65535", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } } } }, "/v1/payment-intents": { "post": { "operationId": "createLeaseOrder", "summary": "Create an address purchase, renewal, or one-time ENS add-on payment intent", "description": "ens_addon defaults to a standard floor name; nameType custom requires a customLabel. The quoted nameType, label, canonical FQDN, pricingVersion and fee are immutable through pay. A canonical-name collision returns 409 ens_name_unavailable without disclosing the other lease. An owned active subscription and a verified environment/nameType fee are required. Missing or mismatched fee returns 503 ens_pricing_unavailable without a 402; unavailable parent-name or registry prerequisites return 503 ens_dependency_unavailable. An existing paid entitlement returns 409 ens_already_purchased; an entitlement refunded after confirmed issuance failure returns 409 ens_repurchase_unavailable; an in-progress add-on returns 409 ens_purchase_in_progress with its intentId as resourceId. Only a confirmed unpaid intent releases pending name and entitlement guards. Unknown or unowned subscriptions return 404; inactive subscriptions return 409 lease_not_active. The add-on inherits locationId and floor from the subscription, creates no new slot hold, and does not consume new-lease quota. Normal risk, x402, nonce, and spend limits still apply.", "security": [ { "agentBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "400": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "401": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "403": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "404": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "409": { "description": "sold_out only after confirmed exhaustion, or an idempotency/state conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "410": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "422": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "429": { "description": "Rate, hold quota, or daily_purchase_limit reached; existing payment reconciliation remains available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "503": { "description": "Dependency unavailable or reservation_retry after bounded contention retries; reuse the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseOrderRequest" } } } } }, "get": { "operationId": "listPaymentIntents", "summary": "List payment intents owned by the authenticated agent", "security": [ { "agentBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntents" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "400": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "401": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "403": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "404": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "409": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "410": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "422": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "429": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "503": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } }, "description": "Cursor pagination of the authenticated agent payment intents, newest createdAt first with a stable ID tie-breaker. Never returns signed payment payloads or another agent data." } }, "/v1/payment-intents/{intentId}": { "get": { "operationId": "getOrder", "summary": "Read owned order and settlement evidence", "security": [ { "agentBearer": [] } ], "parameters": [ { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "400": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "401": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "403": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "404": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "409": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "410": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "422": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "429": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "503": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } } } }, "/v1/payment-intents/{intentId}/pay": { "post": { "operationId": "executeOrder", "summary": "Execute an order through screened x402 settlement", "security": [ { "agentBearer": [] } ], "parameters": [ { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 } }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "description": "Encoded x402 v2 payload, produced and verified with the pinned official SDK.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Fulfilled" }, { "$ref": "#/components/schemas/Refunded" } ] } } }, "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "Verified settlement data encoded by the x402 SDK." }, "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "202": { "description": "Settlement, issuance review, or a confirmed issuance-failure refund is pending. Poll the same intent without authorizing a new payment or refund transfer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pending" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "400": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "401": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "402": { "description": "Valid order requires payment. Body and header follow the pinned x402 v2 SDK.", "headers": { "PAYMENT-REQUIRED": { "required": true, "schema": { "type": "string" } }, "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Official x402 v2 PaymentRequired shape; validate with the pinned SDK." } } } }, "403": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "404": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "409": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "410": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "422": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "429": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "503": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "description": "Never deliver the lease before confirmed settlement. Same path/body/key with PAYMENT-SIGNATURE continues the order. A 402 is not a final idempotency snapshot. The first accepted payment request persists a Firestore outbox and returns 202; a Cloud Tasks worker settles and reconciles it. Enqueue failure is recovered from the outbox. Retry the same execution after fulfillment to obtain 200." } }, "/v1/subscriptions": { "get": { "operationId": "listLeases", "summary": "List owned leases", "security": [ { "agentBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Leases" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "400": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "401": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "403": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "404": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "409": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "410": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "422": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "429": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "503": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } } } }, "/v1/subscriptions/{subscriptionId}": { "get": { "operationId": "getLease", "summary": "Read lease, chain and safe mail status; no forwarding destination", "security": [ { "agentBearer": [] } ], "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lease" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "400": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "401": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "403": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "404": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "409": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "410": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "422": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "429": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "503": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } } } }, "/v1/subscriptions/{subscriptionId}/mail-approval": { "post": { "operationId": "requestMailApproval", "summary": "Request human mail.enable approval", "security": [ { "agentBearer": [] } ], "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "responses": { "200": { "description": "Already enabled; forceReauth renews human session verification without requiring fresh consent for an unchanged destination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailStatus" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalLink" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "400": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "401": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "403": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "404": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "409": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "410": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "422": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "429": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "503": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailApprovalRequest" } } } } } }, "/v1/approvals/{approvalId}/owner-challenge": { "post": { "operationId": "createOwnerChallenge", "summary": "Create owner-wallet challenge bound to this browser and approval", "security": [ { "humanSession": [], "csrfToken": [] } ], "parameters": [ { "name": "approvalId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Challenge" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "400": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "401": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "403": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "404": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "409": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "410": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "422": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "429": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "503": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "description": "An anonymous session is issued by GET /approve/{approvalId}. It is not authorization to view private data." } }, "/v1/approvals/{approvalId}/owner-proof": { "post": { "operationId": "proveOwnerWallet", "summary": "Verify the owning wallet and consume challenge", "security": [ { "humanSession": [], "csrfToken": [] } ], "parameters": [ { "name": "approvalId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerProofResult" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "400": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "401": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "403": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "404": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "409": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "410": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "422": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "429": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "503": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureProof" } } } } } }, "/v1/approvals/{approvalId}": { "get": { "operationId": "getApproval", "summary": "Read approval after proof of owning wallet", "security": [ { "humanSession": [] } ], "parameters": [ { "name": "approvalId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "400": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "401": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "403": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "404": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "409": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "410": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "422": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "429": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "503": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } } } }, "/v1/approvals/{approvalId}/authenticate": { "post": { "operationId": "authenticateHuman", "summary": "Start fresh World OIDC after owner proof", "security": [ { "humanSession": [], "csrfToken": [] } ], "parameters": [ { "name": "approvalId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthUrl" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "400": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "401": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "403": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "404": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "409": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "410": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "422": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "429": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "503": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } } } }, "/auth/world/callback": { "get": { "operationId": "worldCallback", "summary": "Validate state, code and ID token; return to a fixed same-origin page", "security": [], "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "schema": { "type": "string" } }, { "name": "error", "in": "query", "schema": { "type": "string" } } ], "description": "Require matching browser session and exactly one of code or error. Unknown state is rejected. Authentication alone must not enable mail.", "responses": { "303": { "description": "Verified authentication or handled cancellation; does not imply consent.", "headers": { "Location": { "required": true, "schema": { "type": "string" }, "description": "Fixed allowlisted same-origin approval page" } } }, "400": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/approvals/{approvalId}/decision": { "post": { "operationId": "decideMailApproval", "summary": "Record explicit approve/deny after fresh World verification", "security": [ { "humanSession": [], "csrfToken": [] } ], "parameters": [ { "name": "approvalId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionResult" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "400": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "401": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "403": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "404": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "409": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "410": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "422": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "429": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "503": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Decision" } } } }, "description": "Require owner proof, matching World binding/candidate, fresh auth_time, action hash, active lease/version and unexpired approval. Bind and apply atomically. The pending request expires after 10 minutes and binds the current leaseVersion, target profile version and target destinationVersion; this expiry does not limit applied consent. Applied consent persists for the same lease and destination until destination change or human disable, subject to security suspension. For a destination change, approval creates a one-time write authorization bound to targetProfileVersion and targetDestinationVersion; existing consent is replaced only by successful atomic destination PUT." } }, "/v1/subscriptions/{subscriptionId}/mail-profile": { "get": { "operationId": "getHumanMailProfile", "summary": "Read own mail settings and decrypted address", "security": [ { "humanSession": [] } ], "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HumanMailProfile" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "400": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "401": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "403": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "404": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "409": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "410": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "422": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "429": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "503": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } }, "description": "Requires owning-wallet proof and matching World human binding. Agent bearer is not accepted. Address read requires effective enabled consent and an active lease. Same-destination consent persists without a time limit across login and same-lease renewal or revival. Lease expiry suspends effective availability; human disable and security suspension still block access. These human endpoints remain unavailable until approval verification is integrated." } }, "/v1/subscriptions/{subscriptionId}/mail-destination": { "put": { "operationId": "saveMailDestination", "summary": "Save human-entered destination; does not dispatch mail", "security": [ { "humanSession": [], "csrfToken": [] } ], "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HumanMailProfile" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "400": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "401": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "403": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "404": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "409": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "410": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "422": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "429": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "503": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationSave" } } } }, "description": "Require owning wallet and matching World binding, active paid lease, verified one-time write approval, CSRF and expectedVersion CAS. First save atomically binds approved first-save authorization to the first destinationVersion. Changing a destination requires fresh write approval bound to targetProfileVersion and targetDestinationVersion; atomic PUT saves the destination, consumes authorization and switches consent binding. Do not require effective enabled consent for the unsaved new destination. Keep existing consent until save succeeds, and do not bypass human disable or security suspension. Unchanged destinations do not require reapproval on login, renewal or revival. Prefecture must match a Japanese prefecture allowlist." } }, "/v1/subscriptions/{subscriptionId}/mail-disable": { "post": { "operationId": "disableMail", "summary": "Revoke mail setting grant", "security": [ { "humanSession": [], "csrfToken": [] } ], "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HumanMailProfile" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "400": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "401": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "403": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "404": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "409": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "410": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "422": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "429": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } }, "503": { "description": "Request rejected. See error and traceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" }, "description": "Redacted diagnostic correlation ID" } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableRequest" } } } }, "description": "Require owning wallet and matching World human binding, CSRF and expectedVersion. Return destination=null after revocation." } }, "/v1/ens/resolve": { "get": { "operationId": "resolveEnsLease", "summary": "Verify ENSv2 name and active lease binding without disclosing address or human data", "security": [], "parameters": [ { "name": "name", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "ENSIP-15 normalized before lookup; testnet namespace only." } ], "responses": { "200": { "description": "verified, pending or invalid. No physical address or internal lease UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnsResolution" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "400": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "401": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "403": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "404": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "409": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "410": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "422": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "429": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "503": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } } } } }, "/v1/subscriptions/by-ens": { "get": { "operationId": "getLeaseByEns", "summary": "Resolve ENSv2 and return the authenticated owner agent lease", "security": [ { "agentBearer": [] } ], "parameters": [ { "name": "name", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "ENSIP-15 normalized before lookup; testnet namespace only." } ], "responses": { "200": { "description": "Own verified lease; contains contracted office address, never forwarding destination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lease" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "400": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "401": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "403": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "404": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "409": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "410": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "422": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "429": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "503": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } } } } }, "/v1/subscriptions/{subscriptionId}/ens": { "get": { "operationId": "getLeaseEnsStatus", "summary": "Read optional ENS add-on purchase and publishing status for an owned subscription", "security": [ { "agentBearer": [] } ], "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "ENS name state independent of lease activation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnsStatus" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "400": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "401": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "403": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "404": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "409": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "410": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "422": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "429": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "503": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } } } } }, "/v1/subscriptions/{subscriptionId}/ens-description-transaction": { "post": { "operationId": "prepareEnsDescriptionTransaction", "summary": "Prepare a constrained unsigned transaction; does not submit or confirm changes", "security": [ { "agentBearer": [] } ], "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnsDescriptionRequest" } } } }, "responses": { "200": { "description": "The client validates destination, calldata, chain, zero value and gas cap before signing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnsUnsignedTransaction" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "400": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "401": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "403": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "404": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "409": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "410": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "422": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "429": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } }, "503": { "description": "Rejected or unavailable; inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Trace-Id": { "schema": { "type": "string" } } } } } } } }, "components": { "securitySchemes": { "agentBearer": { "type": "http", "scheme": "bearer", "description": "Application agent token, not World OAuth token." }, "humanSession": { "type": "apiKey", "in": "cookie", "name": "realaddr_session", "description": "Server-side browser session. Each endpoint also enforces required wallet and World verification state." }, "csrfToken": { "type": "apiKey", "in": "header", "name": "X-CSRF-Token", "description": "Session-bound CSRF token; also verify Origin." } }, "schemas": { "Error": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$", "description": "Stable machine-readable error code." }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "traceId": { "type": "string" }, "resourceId": { "type": "string", "format": "uuid" } }, "required": [ "error", "message", "retryable", "traceId" ] }, "Empty": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] }, "AuthChallengeRequest": { "type": "object", "additionalProperties": false, "properties": { "walletAddress": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "network": { "type": "string", "pattern": "^eip155:[0-9]+$" }, "termsVersion": { "type": "string", "description": "署名前に確認・同意する規約version。eventの正式versionはrealaddr-v1。local開発用認証を正式規約への同意へ読み替えない。", "minLength": 1, "maxLength": 64 } }, "required": [ "walletAddress", "network", "termsVersion" ] }, "Challenge": { "type": "object", "additionalProperties": false, "properties": { "challengeId": { "type": "string", "format": "uuid" }, "message": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "challengeId", "message", "expiresAt" ] }, "SignatureProof": { "type": "object", "additionalProperties": false, "properties": { "challengeId": { "type": "string", "format": "uuid" }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]+$" } }, "required": [ "challengeId", "signature" ] }, "AgentSession": { "type": "object", "additionalProperties": false, "properties": { "agentId": { "type": "string", "format": "uuid" }, "token": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "agentId", "token", "expiresAt" ] }, "Plan": { "type": "object", "additionalProperties": false, "properties": { "periodDays": { "type": "integer", "const": 30 }, "amountAtomic": { "type": "string", "enum": [ "550000", "55000000" ], "description": "30-day address price in 6-decimal USDC units: event test/dev 550000; future mainnet profile 55000000 is not currently on sale. The server validates the active environment and verified asset. ENS add-on is priced separately." }, "network": { "type": "string" }, "asset": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "decimals": { "type": "integer", "const": 6 } }, "required": [ "periodDays", "amountAtomic", "network", "asset", "decimals" ] }, "Building": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "availableSlots": { "type": "integer", "minimum": 0, "maximum": 65535 }, "plan": { "$ref": "#/components/schemas/Plan" }, "id": { "type": "string", "format": "uuid" } }, "required": [ "id", "label", "availableSlots", "plan" ] }, "Buildings": { "type": "object", "additionalProperties": false, "properties": { "nextCursor": { "type": [ "string", "null" ] }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/Building" } } }, "required": [ "locations", "nextCursor" ] }, "PurchaseOrder": { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "purchase", "type": "string", "default": "purchase" }, "locationId": { "type": "string", "format": "uuid" }, "floor": { "type": "integer", "minimum": 1, "maximum": 65535, "description": "Optional virtual slot. Omission requests atomic server allocation." } }, "required": [ "locationId" ] }, "RenewalOrder": { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "renew", "type": "string" }, "subscriptionId": { "type": "string", "format": "uuid" } }, "required": [ "kind", "subscriptionId" ] }, "EnsAddonOrder": { "type": "object", "additionalProperties": false, "description": "One-time ENSv2 add-on for an active subscription. Omitting nameType selects the standard f00042-style floor label; custom names use the same location namespace. It does not reserve a new slot or consume the daily new-lease quota. A paid add-on is never sold again for the same subscription; address renewals include ENS maintenance without another add-on charge.", "properties": { "kind": { "const": "ens_addon", "type": "string" }, "subscriptionId": { "type": "string", "format": "uuid" }, "nameType": { "type": "string", "enum": [ "floor", "custom" ], "default": "floor" }, "customLabel": { "type": "string", "minLength": 3, "maxLength": 32, "pattern": "^[a-z0-9][a-z0-9-]{1,30}[a-z0-9]$", "not": { "anyOf": [ { "pattern": "^f[0-9]+$" }, { "enum": [ "admin", "www", "api" ] } ] }, "description": "Lowercase ASCII DNS label. All f followed only by digits is reserved for standard floor names. In namePolicyVersion=1, the exact service-label reservation set is admin, api and www; the server and NameController apply the same fixed policy. The server also applies ENSIP-15 canonical validation and a global normalized FQDN uniqueness guard." } }, "required": [ "kind", "subscriptionId" ], "allOf": [ { "if": { "properties": { "nameType": { "const": "custom" } }, "required": [ "nameType" ] }, "then": { "required": [ "customLabel" ] }, "else": { "not": { "required": [ "customLabel" ] } } } ] }, "LeaseOrderRequest": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseOrder" }, { "$ref": "#/components/schemas/RenewalOrder" }, { "$ref": "#/components/schemas/EnsAddonOrder" } ] }, "Risk": { "type": "object", "additionalProperties": false, "properties": { "decision": { "type": "string", "enum": [ "allow", "deny", "hold" ] }, "reasonCodes": { "type": "array", "items": { "type": "string" } }, "checkedAt": { "type": "string", "format": "date-time" }, "paymentNetwork": { "type": "string" }, "riskNetwork": { "type": "string" }, "subjectAddress": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "side": { "type": "string", "enum": [ "buyer", "seller" ] }, "responseHash": { "type": "string" } }, "required": [ "decision", "reasonCodes", "checkedAt", "paymentNetwork", "riskNetwork", "subjectAddress", "side" ] }, "PaymentReceipt": { "type": "object", "additionalProperties": false, "properties": { "paymentId": { "type": "string", "format": "uuid" }, "network": { "type": "string" }, "asset": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amountAtomic": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "payer": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "payTo": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "txHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "confirmedAt": { "type": "string", "format": "date-time" } }, "required": [ "paymentId", "network", "asset", "amountAtomic", "payer", "payTo", "txHash", "confirmedAt" ] }, "Order": { "type": "object", "additionalProperties": false, "description": "For kind ens_addon, fulfilled means one paid ENS entitlement and its publishing outbox are durably recorded for the existing subscription; it does not mean ENS is ready. A confirmed unrecoverable ENS issuance failure may later move the same order through refund_pending to refunded while the address lease remains intact. Reconciliation of an unknown payment uses the same intent and must not request a new add-on charge.", "properties": { "kind": { "type": "string", "enum": [ "purchase", "renew", "ens_addon" ] }, "status": { "type": "string", "enum": [ "awaiting_payment", "settling", "reconciling", "fulfilled", "failed_unpaid", "manual_review", "refund_pending", "refunded", "expired", "cancelled", "blocked" ] }, "subscriptionId": { "type": "string", "format": "uuid", "description": "Required for renew and ens_addon; for ens_addon this is the existing subscription receiving the one-time paid entitlement." }, "amountAtomic": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "For ens_addon this is the fixed one-time fee in 6-decimal USDC units: event test/dev floor 100000 or custom 300000; future mainnet floor 10000000 or custom 30000000, with mainnet sales currently disabled." }, "network": { "type": "string" }, "asset": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "payTo": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "expiresAt": { "type": "string", "format": "date-time", "description": "For ens_addon, at most 10 minutes after quote and no later than the current subscription expiry." }, "riskAssessments": { "type": "array", "items": { "$ref": "#/components/schemas/Risk" } }, "receipt": { "$ref": "#/components/schemas/PaymentReceipt" }, "locationId": { "type": "string", "format": "uuid", "description": "For ens_addon, derived server-side from subscriptionId." }, "floor": { "type": "integer", "minimum": 1, "maximum": 65535, "description": "Virtual service slot, never a physical building floor. For ens_addon, derived server-side from subscriptionId without a new hold." }, "payPath": { "type": "string", "pattern": "^/v1/payment-intents/[0-9a-fA-F-]+/pay$" }, "id": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "nameType": { "type": "string", "enum": [ "floor", "custom" ], "description": "Present for ens_addon; fixed when the quote is created." }, "label": { "type": "string", "description": "Present for ens_addon; standard floor label or validated custom label." }, "fqdn": { "type": "string", "description": "Present for ens_addon; canonical ENSIP-15 name under the location namespace and configured parent." }, "pricingVersion": { "type": "string", "description": "Present for ens_addon; identifies the fixed fee policy used for this quote." } }, "required": [ "id", "kind", "status", "amountAtomic", "network", "asset", "payTo", "expiresAt", "riskAssessments", "locationId", "floor", "payPath", "createdAt" ], "allOf": [ { "if": { "properties": { "kind": { "const": "ens_addon" } }, "required": [ "kind" ] }, "then": { "required": [ "subscriptionId", "nameType", "label", "fqdn", "pricingVersion" ] } } ] }, "Pending": { "type": "object", "additionalProperties": false, "properties": { "intentId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "settling", "reconciling", "manual_review", "refund_pending" ] }, "pollUrl": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 } }, "required": [ "intentId", "status", "pollUrl", "retryAfterSeconds" ] }, "Refunded": { "type": "object", "additionalProperties": false, "description": "A confirmed issuance-failure refund of the full original order amount to the verified original payer. Replaying pay returns this result without a new settlement.", "properties": { "intentId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "const": "refunded" }, "refundId": { "type": "string", "format": "uuid" }, "amountAtomic": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "network": { "type": "string" }, "asset": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "payer": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "sender": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "txHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "confirmedAt": { "type": "string", "format": "date-time" } }, "required": [ "intentId", "status", "refundId", "amountAtomic", "network", "asset", "payer", "sender", "txHash", "confirmedAt" ] }, "Fulfilled": { "type": "object", "additionalProperties": false, "description": "For ens_addon, this confirms a durable one-time paid entitlement and publishing outbox for subscriptionId, not completed ENS registration or resolution. A later confirmed unrecoverable issuance failure can lead to an automatic refund of that add-on order only.", "properties": { "intentId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "const": "fulfilled" }, "subscriptionId": { "type": "string", "format": "uuid" }, "receipt": { "$ref": "#/components/schemas/PaymentReceipt" } }, "required": [ "intentId", "status", "subscriptionId", "receipt" ] }, "MailStatus": { "description": "Effective mail setting status. Applied human consent has no time limit for the same lease and destination; lease expiry suspends availability, and same-lease renewal or revival resumes it unless human disable or security suspension blocks it. Physical forwarding is outside scope.", "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "disabled", "enabled", "suspended" ] }, "destinationConfigured": { "type": "boolean" }, "physicalForwardingAvailable": { "type": "boolean", "const": false } }, "required": [ "status", "destinationConfigured", "physicalForwardingAvailable" ] }, "ChainStatus": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "pending", "synced", "error" ] }, "network": { "type": "string" }, "registryAddress": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "leaseKey": { "type": "string" }, "txHash": { "type": "string" }, "version": { "type": "integer", "minimum": 0 } }, "required": [ "status" ] }, "Lease": { "type": "object", "additionalProperties": false, "properties": { "locationId": { "type": "string", "format": "uuid" }, "floor": { "type": "integer", "minimum": 1, "maximum": 65535 }, "displayAddress": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "expired", "suspended", "revoked" ] }, "startsAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "minimum": 0 }, "chain": { "$ref": "#/components/schemas/ChainStatus" }, "mail": { "$ref": "#/components/schemas/MailStatus" }, "ens": { "$ref": "#/components/schemas/EnsStatus" }, "id": { "type": "string", "format": "uuid" } }, "required": [ "id", "locationId", "floor", "displayAddress", "status", "startsAt", "expiresAt", "version", "chain", "mail", "ens" ] }, "Leases": { "type": "object", "additionalProperties": false, "properties": { "nextCursor": { "type": [ "string", "null" ] }, "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/Lease" } } }, "required": [ "subscriptions", "nextCursor" ] }, "MailApprovalRequest": { "type": "object", "additionalProperties": false, "properties": { "forceReauth": { "type": "boolean", "default": false } }, "required": [] }, "ApprovalLink": { "type": "object", "additionalProperties": false, "properties": { "approvalId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "authenticated" ] }, "approvalUrl": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Short-lived approval request deadline, at most 10 minutes after creation; not an expiry of applied same-destination consent." } }, "required": [ "approvalId", "status", "approvalUrl", "expiresAt" ] }, "Approval": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "subscriptionId": { "type": "string", "format": "uuid" }, "agentId": { "type": "string", "format": "uuid" }, "action": { "type": "string", "const": "mail.enable" }, "actionHash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "status": { "type": "string", "enum": [ "pending", "authenticated", "applied", "denied", "expired", "cancelled" ] }, "ownerWallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Short-lived approval request deadline, at most 10 minutes after creation; not an expiry of applied same-destination consent." }, "worldAuthenticated": { "type": "boolean" } }, "required": [ "id", "subscriptionId", "agentId", "action", "actionHash", "status", "ownerWallet", "expiresAt", "worldAuthenticated" ] }, "OwnerProofResult": { "type": "object", "additionalProperties": false, "properties": { "walletVerified": { "type": "boolean", "const": true } }, "required": [ "walletVerified" ] }, "AuthUrl": { "type": "object", "additionalProperties": false, "properties": { "authorizationUrl": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "authorizationUrl", "expiresAt" ] }, "Decision": { "type": "object", "additionalProperties": false, "properties": { "decision": { "type": "string", "enum": [ "approve", "deny" ] }, "actionHash": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "decision", "actionHash" ] }, "DecisionResult": { "type": "object", "additionalProperties": false, "properties": { "approvalId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "applied", "denied" ] }, "mail": { "$ref": "#/components/schemas/MailStatus" } }, "required": [ "approvalId", "status", "mail" ] }, "Destination": { "type": "object", "additionalProperties": false, "properties": { "country": { "type": "string", "const": "JP" }, "recipient": { "type": "string", "minLength": 1, "maxLength": 100 }, "postalCode": { "type": "string", "pattern": "^[0-9]{7}$" }, "prefecture": { "type": "string", "minLength": 1, "maxLength": 20 }, "city": { "type": "string", "minLength": 1, "maxLength": 100 }, "addressLine1": { "type": "string", "minLength": 1, "maxLength": 200 }, "addressLine2": { "type": "string", "maxLength": 200 } }, "required": [ "country", "recipient", "postalCode", "prefecture", "city", "addressLine1" ] }, "DestinationSave": { "type": "object", "additionalProperties": false, "properties": { "expectedVersion": { "type": "integer", "minimum": 0 }, "destination": { "$ref": "#/components/schemas/Destination" } }, "required": [ "expectedVersion", "destination" ] }, "DisableRequest": { "type": "object", "additionalProperties": false, "properties": { "expectedVersion": { "type": "integer", "minimum": 0 } }, "required": [ "expectedVersion" ] }, "HumanMailProfile": { "type": "object", "additionalProperties": false, "properties": { "subscriptionId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 0 }, "mail": { "$ref": "#/components/schemas/MailStatus" }, "destination": { "anyOf": [ { "$ref": "#/components/schemas/Destination" }, { "type": "null" } ] } }, "required": [ "subscriptionId", "version", "mail", "destination" ] }, "EnsStatus": { "type": "object", "additionalProperties": false, "description": "not_purchased means no paid ENS entitlement; an in-progress payment is tracked by its payment intent. An entitlement refunded after confirmed issuance failure is disabled with lastErrorCode ens_refunded and cannot be repurchased automatically in v1. A ready name requires a real registered name and resolver, never placeholders.", "properties": { "status": { "type": "string", "enum": [ "not_purchased", "pending", "ready", "error", "expired", "disabled" ] }, "network": { "type": "string", "const": "eip155:11155111", "description": "Network for an optional ENS add-on. With status not_purchased, only status and network are returned; no placeholder name, resolver or transaction is invented. The add-on fee is quoted by POST /v1/payment-intents and cannot be purchased while pricing is unavailable." }, "name": { "type": "string" }, "resolverAddress": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "registryAddress": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "controllerAddress": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "expiresAt": { "type": "string", "format": "date-time" }, "targetLeaseVersion": { "type": "integer", "minimum": 0 }, "syncedLeaseVersion": { "type": "integer", "minimum": 0 }, "txHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "lastErrorCode": { "type": "string" } }, "required": [ "status", "network" ] }, "EnsReference": { "type": "object", "additionalProperties": false, "properties": { "network": { "type": "string", "const": "eip155:11155111" }, "leaseRegistry": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "leaseKey": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "controller": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "resolver": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "ownerWallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "required": [ "network", "leaseRegistry", "leaseKey", "controller", "resolver", "ownerWallet" ] }, "EnsResolution": { "type": "object", "additionalProperties": false, "properties": { "normalizedName": { "type": "string" }, "status": { "type": "string", "enum": [ "verified", "pending", "invalid" ] }, "reasonCode": { "type": "string" }, "checkedAt": { "type": "string", "format": "date-time" }, "reference": { "$ref": "#/components/schemas/EnsReference" }, "expiresAt": { "type": "string", "format": "date-time" }, "verifiedBlock": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "normalizedName", "status", "reasonCode", "checkedAt" ] }, "EnsDescriptionRequest": { "type": "object", "additionalProperties": false, "properties": { "description": { "type": "string", "maxLength": 280 }, "expectedLeaseVersion": { "type": "integer", "minimum": 0 } }, "required": [ "description", "expectedLeaseVersion" ] }, "EnsUnsignedTransaction": { "type": "object", "additionalProperties": false, "properties": { "network": { "type": "string", "const": "eip155:11155111" }, "chainId": { "type": "integer", "const": 11155111 }, "from": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "to": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "data": { "type": "string", "pattern": "^0x[0-9a-fA-F]+$" }, "value": { "type": "string", "const": "0" }, "name": { "type": "string" }, "key": { "type": "string", "const": "description" }, "expiresAt": { "type": "string", "format": "date-time" }, "maxGasAtomic": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "network", "chainId", "from", "to", "data", "value", "name", "key", "expiresAt", "maxGasAtomic" ] }, "Health": { "type": "object", "additionalProperties": false, "properties": { "status": { "const": "ok", "type": "string" }, "mode": { "const": "api", "type": "string" } }, "required": [ "status", "mode" ] }, "OpenApiDocument": { "type": "object", "additionalProperties": true, "description": "Published OpenAPI 3.1 document." }, "FloorAvailability": { "type": "object", "additionalProperties": false, "properties": { "locationId": { "type": "string", "format": "uuid" }, "floor": { "type": "integer", "minimum": 1, "maximum": 65535, "description": "Virtual service slot, not a physical floor." }, "available": { "type": "boolean", "description": "Current bitmap snapshot; payment intent reservation remains authoritative." } }, "required": [ "locationId", "floor", "available" ] }, "PaymentIntents": { "type": "object", "additionalProperties": false, "properties": { "paymentIntents": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "paymentIntents", "nextCursor" ] } } } }