{ "openapi": "3.1.0", "info": { "title": "xAPG shared payment API", "version": "0.3.0" }, "paths": { "/supported": { "get": { "summary": "Discover enabled schemes, networks, assets and signers", "security": [ { "institutionKey": [] } ], "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "description": "Optional correlation ID; the response returns a request ID", "schema": { "type": "string" } } ], "x-required-scope": "supported", "x-browser-csrf-required": false, "responses": { "200": { "description": "Declared endpoint result; payment clients must inspect isValid/success and failure.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportedResponse" } } } }, "400": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "429": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } } } }, "/verify": { "post": { "summary": "Validate a signed payment without transferring funds", "description": "Exact EIP-3009 verifies authorization locally without RPC balance, nonce or simulation checks. Settlement revalidates authorization and current onchain state. Batch verification retains its existing behavior; Permit2 is unchanged.", "security": [ { "institutionKey": [] }, { "browserSession": [], "browserCsrf": [] } ], "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "description": "Optional correlation ID; the response returns a request ID", "schema": { "type": "string" } } ], "x-required-scope": "verify", "x-browser-csrf-required": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilitatorRequest" } } } }, "responses": { "200": { "description": "Declared endpoint result; payment clients must inspect isValid/success and failure.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicVerifyResponse" } } } }, "400": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PublicVerifyResponse" }, { "$ref": "#/components/schemas/APIError" } ] } } } }, "401": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PublicVerifyResponse" }, { "$ref": "#/components/schemas/APIError" } ] } } } }, "403": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PublicVerifyResponse" }, { "$ref": "#/components/schemas/APIError" } ] } } } }, "409": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PublicVerifyResponse" }, { "$ref": "#/components/schemas/APIError" } ] } } } }, "429": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PublicVerifyResponse" }, { "$ref": "#/components/schemas/APIError" } ] } } } }, "503": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PublicVerifyResponse" }, { "$ref": "#/components/schemas/APIError" } ] } } } } } } }, "/settle": { "post": { "summary": "Submit an approved payment operation and return its result", "security": [ { "institutionKey": [] }, { "browserSession": [], "browserCsrf": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Batch onchain operations only; reuse with the identical body. Exact does not use this header", "schema": { "type": "string" } }, { "name": "X-Request-ID", "in": "header", "required": false, "description": "Optional correlation ID; the response returns a request ID", "schema": { "type": "string" } }, { "name": "X-Payment-Operation-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Stable business operation UUID reused across devices and signatures." }, { "name": "X-Payment-Recovery", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "same-operation" ] }, "description": "Optional /settle header: same-operation. Requires the original X-Request-ID, X-Payment-Operation-ID and unchanged payment body. Claims only an expired execution lease; replays an existing signed transaction, never creates a replacement payment. Legacy operations without recovery metadata fail closed" } ], "x-required-scope": "settle", "x-browser-csrf-required": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilitatorRequest" } } } }, "responses": { "200": { "description": "Declared endpoint result; payment clients must inspect isValid/success and failure.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSettleResponse" } } } }, "400": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PublicSettleResponse" }, { "$ref": "#/components/schemas/APIError" } ] } } } }, "401": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PublicSettleResponse" }, { "$ref": "#/components/schemas/APIError" } ] } } } }, "403": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PublicSettleResponse" }, { "$ref": "#/components/schemas/APIError" } ] } } } }, "409": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PublicSettleResponse" }, { "$ref": "#/components/schemas/APIError" } ] } } } }, "429": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PublicSettleResponse" }, { "$ref": "#/components/schemas/APIError" } ] } } } }, "503": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PublicSettleResponse" }, { "$ref": "#/components/schemas/APIError" } ] } } } } } } }, "/settlements/pending": { "get": { "summary": "Find one unresolved operation across devices; reconcile each request before retrying", "security": [ { "institutionKey": [] }, { "browserSession": [] } ], "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "description": "Optional correlation ID; the response returns a request ID", "schema": { "type": "string" } } ], "x-required-scope": "settle", "x-browser-csrf-required": false, "responses": { "200": { "description": "Declared endpoint result; payment clients must inspect isValid/success and failure.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingSettlement" } } } }, "400": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "429": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } } } }, "/settlements/{requestId}": { "get": { "summary": "Read owned settlement evidence by request ID; no resubmission", "security": [ { "institutionKey": [] }, { "browserSession": [] } ], "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "description": "Optional correlation ID; the response returns a request ID", "schema": { "type": "string" } }, { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Request ID owned by the authenticated account." } ], "x-required-scope": "settle", "x-browser-csrf-required": false, "responses": { "200": { "description": "Declared endpoint result; payment clients must inspect isValid/success and failure.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementReceipt" } } } }, "400": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "404": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "429": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } } } }, "/payment-environment-config": { "get": { "summary": "Read deployment environment, network, asset and limits", "security": [], "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "description": "Optional correlation ID; the response returns a request ID", "schema": { "type": "string" } } ], "x-required-scope": null, "x-browser-csrf-required": false, "responses": { "200": { "description": "Declared endpoint result; payment clients must inspect isValid/success and failure.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentConfig" } } } }, "400": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } } } }, "/demo/payment-config": { "get": { "summary": "Read payment configuration for the authenticated wallet demo", "security": [ { "browserSession": [] } ], "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "description": "Optional correlation ID; the response returns a request ID", "schema": { "type": "string" } } ], "x-required-scope": null, "x-browser-csrf-required": false, "responses": { "200": { "description": "Declared endpoint result; payment clients must inspect isValid/success and failure.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrimaryCapability" } } } }, "400": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "429": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } } } }, "/version": { "get": { "summary": "Identify the deployed release", "security": [], "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "description": "Optional correlation ID; the response returns a request ID", "schema": { "type": "string" } } ], "x-required-scope": null, "x-browser-csrf-required": false, "responses": { "200": { "description": "Declared endpoint result; payment clients must inspect isValid/success and failure.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionResponse" } } } }, "400": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "API or payment failure. HTTP status alone does not prove settlement outcome.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } } } } }, "components": { "schemas": { "PendingSettlement": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "operationId": { "type": "string" }, "requestId": { "type": "string" }, "network": { "type": "string" }, "state": { "type": "string" } }, "required": [ "operationId", "requestId", "network", "state" ], "additionalProperties": true }, "receipt": { "type": "object", "properties": { "requestId": { "type": "string" }, "environment": { "type": "string" }, "network": { "type": "string" }, "scheme": { "type": "string" }, "status": { "type": "string", "enum": [ "processing", "completed", "unknown" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "httpStatus": { "type": "number" }, "response": { "type": "object", "properties": { "success": { "type": "boolean" }, "payer": { "type": "string" }, "transaction": { "type": "string" }, "network": { "type": "string" }, "errorReason": { "type": "string" }, "failure": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable failure code. cloud_journal_lane_blocked means an expired unsigned transaction blocks the sender nonce lane; cloud_journal_lane_untracked means a legacy nonce gap cannot be safely tracked. New requests rejected by these admission checks have settlementStatus=not_submitted and retryable=false; operator reconciliation is required. Previously signed or uncertain operations must use same-operation recovery and reconciliation." }, "stage": { "type": "string", "enum": [ "request_validation", "authorization_validation", "chain_read", "simulation", "settlement_submission", "confirmation" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "settlementStatus": { "type": "string", "enum": [ "not_submitted", "failed", "unknown" ] }, "requestId": { "type": "string" } }, "required": [ "code", "stage", "message", "retryable", "settlementStatus", "requestId" ], "additionalProperties": true }, "gasUsed": { "type": "string" }, "effectiveGasPrice": { "type": "string" }, "gasCostWei": { "type": "string" }, "amount": { "type": "string" }, "asset": { "type": "string" }, "extra": { "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "error": {}, "requestId": { "type": "string" } }, "required": [], "additionalProperties": true } }, "required": [ "requestId", "environment", "network", "scheme", "status", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [], "additionalProperties": true }, "FacilitatorRequest": { "type": "object", "properties": { "x402Version": { "const": 2 }, "paymentPayload": { "type": "object", "properties": { "x402Version": { "type": "number" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" } }, "required": [], "additionalProperties": true }, "accepted": { "type": "object", "properties": { "scheme": { "type": "string", "enum": [ "exact", "batch-settlement" ] }, "network": { "type": "string" }, "amount": { "type": "string" }, "asset": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "number" }, "extra": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "protocol": { "type": "string" }, "recipientId": { "type": "string" }, "recipientLabel": { "type": "string" }, "reason": { "type": "string" }, "reference": { "type": "string" }, "receiverAuthorizer": { "type": "string" }, "withdrawDelay": { "type": "number" }, "minDeposit": { "type": "string" }, "assetTransferMethod": { "type": "string", "enum": [ "eip3009", "permit2" ] } }, "required": [], "additionalProperties": true } }, "required": [ "scheme", "network", "amount", "asset", "payTo", "maxTimeoutSeconds" ], "additionalProperties": true }, "payload": {} }, "required": [ "x402Version", "accepted", "payload" ], "additionalProperties": true }, "paymentRequirements": { "type": "object", "properties": { "scheme": { "type": "string", "enum": [ "exact", "batch-settlement" ] }, "network": { "type": "string" }, "amount": { "type": "string" }, "asset": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "number" }, "extra": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "protocol": { "type": "string" }, "recipientId": { "type": "string" }, "recipientLabel": { "type": "string" }, "reason": { "type": "string" }, "reference": { "type": "string" }, "receiverAuthorizer": { "type": "string" }, "withdrawDelay": { "type": "number" }, "minDeposit": { "type": "string" }, "assetTransferMethod": { "type": "string", "enum": [ "eip3009", "permit2" ] } }, "required": [], "additionalProperties": true } }, "required": [ "scheme", "network", "amount", "asset", "payTo", "maxTimeoutSeconds" ], "additionalProperties": true }, "clientContext": { "type": "object", "properties": { "walletName": { "type": "string" } }, "required": [], "additionalProperties": true } }, "required": [ "x402Version", "paymentPayload", "paymentRequirements" ], "additionalProperties": true }, "PaymentRequirements": { "type": "object", "properties": { "scheme": { "type": "string", "enum": [ "exact", "batch-settlement" ] }, "network": { "type": "string" }, "amount": { "type": "string" }, "asset": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "number" }, "extra": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "protocol": { "type": "string" }, "recipientId": { "type": "string" }, "recipientLabel": { "type": "string" }, "reason": { "type": "string" }, "reference": { "type": "string" }, "receiverAuthorizer": { "type": "string" }, "withdrawDelay": { "type": "number" }, "minDeposit": { "type": "string" }, "assetTransferMethod": { "type": "string", "enum": [ "eip3009", "permit2" ] } }, "required": [], "additionalProperties": true } }, "required": [ "scheme", "network", "amount", "asset", "payTo", "maxTimeoutSeconds" ], "additionalProperties": true }, "PaymentEnvelope": { "type": "object", "properties": { "x402Version": { "type": "number" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" } }, "required": [], "additionalProperties": true }, "accepted": { "type": "object", "properties": { "scheme": { "type": "string", "enum": [ "exact", "batch-settlement" ] }, "network": { "type": "string" }, "amount": { "type": "string" }, "asset": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "number" }, "extra": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "protocol": { "type": "string" }, "recipientId": { "type": "string" }, "recipientLabel": { "type": "string" }, "reason": { "type": "string" }, "reference": { "type": "string" }, "receiverAuthorizer": { "type": "string" }, "withdrawDelay": { "type": "number" }, "minDeposit": { "type": "string" }, "assetTransferMethod": { "type": "string", "enum": [ "eip3009", "permit2" ] } }, "required": [], "additionalProperties": true } }, "required": [ "scheme", "network", "amount", "asset", "payTo", "maxTimeoutSeconds" ], "additionalProperties": true }, "payload": {} }, "required": [ "x402Version", "accepted", "payload" ], "additionalProperties": true }, "PaymentFailure": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable failure code. cloud_journal_lane_blocked means an expired unsigned transaction blocks the sender nonce lane; cloud_journal_lane_untracked means a legacy nonce gap cannot be safely tracked. New requests rejected by these admission checks have settlementStatus=not_submitted and retryable=false; operator reconciliation is required. Previously signed or uncertain operations must use same-operation recovery and reconciliation." }, "stage": { "type": "string", "enum": [ "request_validation", "authorization_validation", "chain_read", "simulation", "settlement_submission", "confirmation" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "settlementStatus": { "type": "string", "enum": [ "not_submitted", "failed", "unknown" ] }, "requestId": { "type": "string" } }, "required": [ "code", "stage", "message", "retryable", "settlementStatus", "requestId" ], "additionalProperties": true }, "PublicVerifyResponse": { "type": "object", "properties": { "isValid": { "type": "boolean" }, "payer": { "type": "string" }, "invalidReason": { "type": "string" }, "failure": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable failure code. cloud_journal_lane_blocked means an expired unsigned transaction blocks the sender nonce lane; cloud_journal_lane_untracked means a legacy nonce gap cannot be safely tracked. New requests rejected by these admission checks have settlementStatus=not_submitted and retryable=false; operator reconciliation is required. Previously signed or uncertain operations must use same-operation recovery and reconciliation." }, "stage": { "type": "string", "enum": [ "request_validation", "authorization_validation", "chain_read", "simulation", "settlement_submission", "confirmation" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "settlementStatus": { "type": "string", "enum": [ "not_submitted", "failed", "unknown" ] }, "requestId": { "type": "string" } }, "required": [ "code", "stage", "message", "retryable", "settlementStatus", "requestId" ], "additionalProperties": true }, "extra": { "type": "object", "properties": {}, "required": [], "additionalProperties": true } }, "required": [ "isValid" ], "additionalProperties": true }, "PublicSettleResponse": { "oneOf": [ { "type": "object", "properties": { "success": { "const": true }, "payer": { "type": "string" }, "transaction": { "type": "string" }, "network": { "type": "string" }, "errorReason": { "type": "string" }, "failure": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable failure code. cloud_journal_lane_blocked means an expired unsigned transaction blocks the sender nonce lane; cloud_journal_lane_untracked means a legacy nonce gap cannot be safely tracked. New requests rejected by these admission checks have settlementStatus=not_submitted and retryable=false; operator reconciliation is required. Previously signed or uncertain operations must use same-operation recovery and reconciliation." }, "stage": { "type": "string", "enum": [ "request_validation", "authorization_validation", "chain_read", "simulation", "settlement_submission", "confirmation" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "settlementStatus": { "type": "string", "enum": [ "not_submitted", "failed", "unknown" ] }, "requestId": { "type": "string" } }, "required": [ "code", "stage", "message", "retryable", "settlementStatus", "requestId" ], "additionalProperties": true }, "gasUsed": { "type": "string" }, "effectiveGasPrice": { "type": "string" }, "gasCostWei": { "type": "string" }, "amount": { "type": "string" }, "asset": { "type": "string" }, "extra": { "type": "object", "properties": {}, "required": [], "additionalProperties": true } }, "required": [ "success", "network" ], "additionalProperties": true }, { "type": "object", "properties": { "success": { "const": false }, "payer": { "type": "string" }, "transaction": { "type": "string" }, "network": { "type": "string" }, "errorReason": { "type": "string" }, "failure": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable failure code. cloud_journal_lane_blocked means an expired unsigned transaction blocks the sender nonce lane; cloud_journal_lane_untracked means a legacy nonce gap cannot be safely tracked. New requests rejected by these admission checks have settlementStatus=not_submitted and retryable=false; operator reconciliation is required. Previously signed or uncertain operations must use same-operation recovery and reconciliation." }, "stage": { "type": "string", "enum": [ "request_validation", "authorization_validation", "chain_read", "simulation", "settlement_submission", "confirmation" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "settlementStatus": { "type": "string", "enum": [ "not_submitted", "failed", "unknown" ] }, "requestId": { "type": "string" } }, "required": [ "code", "stage", "message", "retryable", "settlementStatus", "requestId" ], "additionalProperties": true }, "gasUsed": { "type": "string" }, "effectiveGasPrice": { "type": "string" }, "gasCostWei": { "type": "string" }, "amount": { "type": "string" }, "asset": { "type": "string" }, "extra": { "type": "object", "properties": {}, "required": [], "additionalProperties": true } }, "required": [ "success", "errorReason", "failure" ], "additionalProperties": true } ] }, "APIError": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string" }, "errorDetail": { "type": "object", "properties": { "code": { "type": "string" } }, "required": [ "code" ], "additionalProperties": true }, "requestId": { "type": "string" } }, "required": [ "error" ], "additionalProperties": true }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "const": "local_mainnet_payment_execution_disabled" } }, "required": [ "code" ], "additionalProperties": true }, "requestId": { "type": "string" } }, "required": [ "error" ], "additionalProperties": true } ] }, "SupportedResponse": { "type": "object", "properties": { "environment": { "type": "string", "enum": [ "testnet", "mainnet" ] }, "realFunds": { "type": "boolean" }, "kinds": { "type": "array", "items": { "type": "object", "properties": { "x402Version": { "const": 2 }, "scheme": { "type": "string" }, "network": { "type": "string" }, "extra": { "type": "object", "properties": { "contractAddress": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "chainId": { "type": "number" } }, "required": [ "contractAddress", "name", "version", "chainId" ], "additionalProperties": true } }, "required": [ "x402Version", "scheme", "network" ], "additionalProperties": true } }, "extensions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "adapters": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "assets": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "number" }, "testOnly": { "type": "boolean" } }, "required": [ "address", "symbol", "decimals" ], "additionalProperties": true } }, "permit2": { "type": "string" }, "settlementSpenders": { "type": "array", "items": { "type": "string" } }, "model": { "type": "string" }, "contractAddress": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "chainId": { "type": "number" } }, "required": [ "id", "network", "settlementSpenders" ], "additionalProperties": true } } }, "required": [ "name", "version", "adapters" ], "additionalProperties": true } }, "signers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "assets": { "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string" }, "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "number" }, "protocols": { "type": "array", "items": { "type": "string" } }, "testOnly": { "type": "boolean" } }, "required": [ "network", "address", "symbol", "decimals", "protocols" ], "additionalProperties": true } } }, "required": [ "environment", "realFunds", "kinds", "extensions", "signers", "assets" ], "additionalProperties": true }, "PrimaryCapability": { "type": "object", "properties": { "service": { "const": "XAPG" }, "environment": { "type": "string", "enum": [ "testnet", "mainnet" ] }, "realFunds": { "type": "boolean" }, "authorizationMode": { "const": "wallet_approval" }, "network": { "type": "string" }, "chainId": { "type": "number" }, "chain": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "chainName": { "type": "string" }, "nativeCurrency": { "type": "object", "properties": { "name": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "number" } }, "required": [ "name", "symbol", "decimals" ], "additionalProperties": true }, "rpcUrls": { "type": "array", "items": { "type": "string" } }, "blockExplorerUrls": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "chainName", "nativeCurrency", "rpcUrls", "blockExplorerUrls" ], "additionalProperties": true }, "asset": { "type": "object", "properties": { "symbol": { "type": "string" }, "address": { "type": "string" }, "decimals": { "type": "number" }, "eip712": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" } }, "required": [ "name", "version" ], "additionalProperties": true } }, "required": [ "symbol", "address", "decimals", "eip712" ], "additionalProperties": true }, "walletDemo": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "resource": { "type": "object", "properties": { "path": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" } }, "required": [ "path", "description", "mimeType" ], "additionalProperties": true } }, "required": [ "enabled", "resource" ], "additionalProperties": true }, "recipient": { "type": "string" }, "protocols": { "type": "array", "items": { "type": "string" } }, "payment": { "type": "object", "properties": { "x402Version": { "const": 2 }, "scheme": { "const": "exact" }, "adapter": { "const": "eip-3009" }, "defaultAmountAtomic": { "type": "string" }, "maxTimeoutSeconds": { "type": "number" }, "resource": { "type": "object", "properties": { "external": { "type": "boolean" }, "path": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" } }, "required": [ "description" ], "additionalProperties": true } }, "required": [ "x402Version", "scheme", "adapter", "defaultAmountAtomic", "maxTimeoutSeconds", "resource" ], "additionalProperties": true }, "policy": { "type": "object", "properties": { "allowedOrigins": { "type": "array", "items": { "type": "string" } }, "maxAmountAtomic": { "type": "string" }, "authorizationAllowanceAtomic": { "type": "string" }, "allowanceScope": { "type": "string" }, "allowanceEnforcement": { "type": "string" }, "sessionLimitAtomic": { "type": "string" } }, "required": [ "allowedOrigins", "maxAmountAtomic" ], "additionalProperties": true } }, "required": [ "service", "environment", "realFunds", "authorizationMode", "network", "chainId", "chain", "asset", "walletDemo", "protocols", "payment", "policy" ], "additionalProperties": true }, "EnvironmentConfig": { "type": "object", "properties": { "service": { "const": "XAPG" }, "environment": { "type": "string", "enum": [ "testnet", "mainnet" ] }, "realFunds": { "type": "boolean" }, "authorizationMode": { "const": "wallet_approval" }, "network": { "type": "string" }, "chainId": { "type": "number" }, "chain": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "chainName": { "type": "string" }, "nativeCurrency": { "type": "object", "properties": { "name": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "number" } }, "required": [ "name", "symbol", "decimals" ], "additionalProperties": true }, "rpcUrls": { "type": "array", "items": { "type": "string" } }, "blockExplorerUrls": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "chainName", "nativeCurrency", "rpcUrls", "blockExplorerUrls" ], "additionalProperties": true }, "asset": { "type": "object", "properties": { "symbol": { "type": "string" }, "address": { "type": "string" }, "decimals": { "type": "number" }, "eip712": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" } }, "required": [ "name", "version" ], "additionalProperties": true } }, "required": [ "symbol", "address", "decimals", "eip712" ], "additionalProperties": true }, "walletDemo": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "resource": { "type": "object", "properties": { "path": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" } }, "required": [ "path", "description", "mimeType" ], "additionalProperties": true } }, "required": [ "enabled", "resource" ], "additionalProperties": true }, "recipient": { "type": "string" }, "protocols": { "type": "array", "items": { "type": "string" } }, "payment": { "type": "object", "properties": { "x402Version": { "const": 2 }, "scheme": { "const": "exact" }, "adapter": { "const": "eip-3009" }, "defaultAmountAtomic": { "type": "string" }, "maxTimeoutSeconds": { "type": "number" }, "resource": { "type": "object", "properties": { "external": { "type": "boolean" }, "path": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" } }, "required": [ "description" ], "additionalProperties": true } }, "required": [ "x402Version", "scheme", "adapter", "defaultAmountAtomic", "maxTimeoutSeconds", "resource" ], "additionalProperties": true }, "policy": { "type": "object", "properties": { "allowedOrigins": { "type": "array", "items": { "type": "string" } }, "maxAmountAtomic": { "type": "string" }, "authorizationAllowanceAtomic": { "type": "string" }, "allowanceScope": { "type": "string" }, "allowanceEnforcement": { "type": "string" }, "sessionLimitAtomic": { "type": "string" } }, "required": [ "allowedOrigins", "maxAmountAtomic" ], "additionalProperties": true }, "apiBaseUrl": { "type": "string" }, "testnetAppUrl": { "type": "string" }, "apiVersion": { "type": "string" }, "batchContract": { "type": "object", "properties": { "contractAddress": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "chainId": { "type": "number" } }, "required": [ "contractAddress", "name", "version", "chainId" ], "additionalProperties": true }, "limits": { "type": "object", "properties": { "batchMaxDepositAtomic": { "type": "string" }, "rateLimits": { "type": "object", "properties": { "general": { "type": "object", "properties": { "max": { "type": "number" }, "windowMs": { "type": "number" }, "scope": { "type": "string" } }, "required": [ "max", "windowMs", "scope" ], "additionalProperties": true }, "institution": { "oneOf": [ { "type": "object", "properties": { "max": { "type": "number" }, "windowMs": { "type": "number" }, "scope": { "type": "string" } }, "required": [ "max", "windowMs", "scope" ], "additionalProperties": true }, { "type": "object", "properties": { "scope": { "const": "institution_owner" }, "endpoints": { "type": "array", "items": { "type": "string" } }, "configurableByAdmin": { "const": true }, "policy": { "const": "settle" }, "defaultEnabled": { "const": false }, "independentQueryQuota": { "const": true } }, "required": [ "scope", "endpoints", "configurableByAdmin", "policy", "defaultEnabled", "independentQueryQuota" ], "additionalProperties": true } ] } }, "required": [ "general", "institution" ], "additionalProperties": true } }, "required": [ "batchMaxDepositAtomic", "rateLimits" ], "additionalProperties": true } }, "required": [ "service", "environment", "realFunds", "authorizationMode", "network", "chainId", "chain", "asset", "walletDemo", "protocols", "payment", "policy", "apiBaseUrl", "apiVersion", "batchContract", "limits" ], "additionalProperties": true }, "SettlementReceipt": { "type": "object", "properties": { "requestId": { "type": "string" }, "environment": { "type": "string" }, "network": { "type": "string" }, "scheme": { "type": "string" }, "status": { "type": "string", "enum": [ "processing", "completed", "unknown" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "httpStatus": { "type": "number" }, "response": { "type": "object", "properties": { "success": { "type": "boolean" }, "payer": { "type": "string" }, "transaction": { "type": "string" }, "network": { "type": "string" }, "errorReason": { "type": "string" }, "failure": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable failure code. cloud_journal_lane_blocked means an expired unsigned transaction blocks the sender nonce lane; cloud_journal_lane_untracked means a legacy nonce gap cannot be safely tracked. New requests rejected by these admission checks have settlementStatus=not_submitted and retryable=false; operator reconciliation is required. Previously signed or uncertain operations must use same-operation recovery and reconciliation." }, "stage": { "type": "string", "enum": [ "request_validation", "authorization_validation", "chain_read", "simulation", "settlement_submission", "confirmation" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "settlementStatus": { "type": "string", "enum": [ "not_submitted", "failed", "unknown" ] }, "requestId": { "type": "string" } }, "required": [ "code", "stage", "message", "retryable", "settlementStatus", "requestId" ], "additionalProperties": true }, "gasUsed": { "type": "string" }, "effectiveGasPrice": { "type": "string" }, "gasCostWei": { "type": "string" }, "amount": { "type": "string" }, "asset": { "type": "string" }, "extra": { "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "error": {}, "requestId": { "type": "string" } }, "required": [], "additionalProperties": true } }, "required": [ "requestId", "environment", "network", "scheme", "status", "createdAt", "updatedAt" ], "additionalProperties": true }, "VersionResponse": { "type": "object", "properties": { "version": { "type": "string" }, "gitSha": { "type": "string" }, "buildId": { "type": "string" }, "revision": { "type": "string" } }, "required": [ "version", "gitSha", "buildId", "revision" ], "additionalProperties": true } }, "securitySchemes": { "browserCsrf": { "type": "apiKey", "in": "header", "name": "X-CSRF-Token", "description": "Required together with a browser session for POST requests." }, "institutionKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "browserSession": { "type": "apiKey", "in": "cookie", "name": "__Host-apg_session", "description": "Production secure browser session. Development uses apg_session or apg_mainnet_session; POST also requires X-CSRF-Token." } } }, "x-settlement-policy": "not_submitted means no submission was attempted; failed means a known failure; unknown means the outcome must be reconciled by request ID before any resubmission. Retryability alone does not authorize resubmission." }