{ "openapi": "3.1.0", "info": { "title": "PPOps merchant API", "version": "0.1.0-beta.3", "description": "One merchant receiver, network and token per instance. Amounts are integer atomic-unit strings; timestamps are Unix seconds. Webhooks are at-least-once. See docs/PAYMENT-STATES.md for expiry and settlement semantics." }, "servers": [ { "url": "http://127.0.0.1:8787", "description": "Local merchant daemon" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/live": { "get": { "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Live" } } } }, "400": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/ready": { "get": { "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ready" } } } }, "503": { "description": "A complete recent scan is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ready" } } } } } } }, "/v1/health": { "get": { "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "400": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/pay/{id}": { "get": { "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payer checkout", "content": { "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pay/{id}/request.json": { "get": { "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutRequest" } } } }, "400": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "description": "Minimal signed request. The wallet must verify the signer through an independent trusted channel." } }, "/v1/intents": { "post": { "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIntent" } } } }, "responses": { "200": { "description": "Exact request replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Intent" } } }, "headers": { "Idempotent-Replayed": { "schema": { "type": "string", "enum": [ "true" ] } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Intent" } } }, "headers": { "Idempotent-Replayed": { "schema": { "type": "string", "enum": [ "false" ] } } } }, "400": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Intent" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } }, "400": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "description": "Newest creation first. No total or filters. Continue with offset + items.length until a short page; offset pagination is not a consistent snapshot." } }, "/v1/intents/{id}": { "get": { "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Intent" } } } }, "400": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/intents/{id}/status": { "get": { "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntentStatus" } } } }, "400": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/runtime": { "get": { "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Runtime" } } } }, "401": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/settlements": { "get": { "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Settlement" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } }, "400": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ] } }, "/v1/events": { "get": { "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } }, "400": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ] } }, "/v1/outbox": { "get": { "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Outbox" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } }, "400": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ] } }, "/v1/outbox/{eventId}/replay": { "post": { "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Replay" } } } }, "401": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Replay a dead-lettered event after repairing its receiver. Already delivered and pending events cannot be replayed here." } }, "/v1/descriptors/verify": { "post": { "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Descriptor" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } } }, "400": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Verify against this daemon's configured merchant signer. Does not prove settlement or replace expiry/amount checks." } }, "/v1/metrics": { "get": { "responses": { "200": { "description": "Metadata-free Prometheus text", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/openapi.json": { "get": { "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request could not be completed; inspect the stable code and optional hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "paymentEvent": { "post": { "description": "Outbound event to the configured merchant URL. HMAC-SHA256 covers timestamp.keyId.eventId.rawBody. Verify freshness and raw bytes, validate schema and durably deduplicate eventId before returning 2xx.", "security": [], "parameters": [ { "name": "PPOps-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "PPOps-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "PPOps-Key-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "PPOps-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Accepted or valid duplicate. Other non-2xx responses trigger bounded retries." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "CreateIntent": { "type": "object", "properties": { "externalReference": { "type": "string", "minLength": 1, "maxLength": 512 }, "amountAtomic": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "expiresAt": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "externalReference", "amountAtomic", "expiresAt" ], "additionalProperties": false }, "Intent": { "type": "object", "properties": { "id": { "type": "string" }, "externalReference": { "type": "string" }, "chainId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "tokenAddress": { "type": "string" }, "tokenSymbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "expectedAmountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "receivedAmountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "pendingAmountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "overpaymentAmountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "status": { "type": "string", "enum": [ "OPEN", "PARTIAL", "PAID", "EXPIRED", "PAID_LATE" ] }, "expiresAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "checkoutPath": { "type": "string" }, "payment": { "type": "object", "properties": { "rail": { "type": "string", "const": "railgun" }, "recipient": { "type": "string" }, "memo": { "type": "string" }, "descriptor": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "chainId": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "rail": { "type": "string", "const": "railgun" }, "tokenAddress": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255 }, "amountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "recipient0zk": { "type": "string" }, "reference": { "type": "string" }, "expiresAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "nonce": { "type": "string" }, "merchantSigner": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "version", "chainId", "rail", "tokenAddress", "decimals", "amountAtomic", "recipient0zk", "reference", "expiresAt", "nonce", "merchantSigner", "signature" ], "additionalProperties": false } }, "required": [ "rail", "recipient", "memo", "descriptor" ], "additionalProperties": false } }, "required": [ "id", "externalReference", "chainId", "tokenAddress", "tokenSymbol", "decimals", "expectedAmountAtomic", "receivedAmountAtomic", "pendingAmountAtomic", "overpaymentAmountAtomic", "status", "expiresAt", "createdAt", "revision", "checkoutPath", "payment" ], "additionalProperties": false }, "IntentStatus": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "OPEN", "PARTIAL", "PAID", "EXPIRED", "PAID_LATE" ] }, "expectedAmountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "receivedAmountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "pendingAmountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "overpaymentAmountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "expiresAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "status", "expectedAmountAtomic", "receivedAmountAtomic", "pendingAmountAtomic", "overpaymentAmountAtomic", "expiresAt", "revision" ], "additionalProperties": false }, "CheckoutRequest": { "type": "object", "properties": { "id": { "type": "string" }, "chainId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "tokenAddress": { "type": "string" }, "tokenSymbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "amountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "amountFormatted": { "type": "string" }, "receivedAmountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "pendingAmountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "status": { "type": "string", "enum": [ "OPEN", "PARTIAL", "PAID", "EXPIRED", "PAID_LATE" ] }, "expiresAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rail": { "type": "string", "const": "railgun" }, "recipient": { "type": "string" }, "memo": { "type": "string" }, "descriptor": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "chainId": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "rail": { "type": "string", "const": "railgun" }, "tokenAddress": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255 }, "amountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "recipient0zk": { "type": "string" }, "reference": { "type": "string" }, "expiresAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "nonce": { "type": "string" }, "merchantSigner": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "version", "chainId", "rail", "tokenAddress", "decimals", "amountAtomic", "recipient0zk", "reference", "expiresAt", "nonce", "merchantSigner", "signature" ], "additionalProperties": false }, "expectedMerchantSigner": { "type": "string" }, "reconciliationReady": { "type": "boolean" }, "paymentStage": { "type": "string", "enum": [ "AWAITING_PAYMENT", "PAYMENT_DETECTED", "PRIVACY_CHECKS_PENDING", "PAYMENT_COMPLETE", "PAYMENT_REVERTED" ] }, "overpaymentAmountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "simulated": { "type": "boolean", "const": true } }, "required": [ "id", "chainId", "tokenAddress", "tokenSymbol", "decimals", "amountAtomic", "amountFormatted", "receivedAmountAtomic", "pendingAmountAtomic", "status", "expiresAt", "rail", "recipient", "memo", "descriptor", "expectedMerchantSigner", "reconciliationReady", "paymentStage", "overpaymentAmountAtomic" ], "additionalProperties": false }, "Descriptor": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "chainId": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "rail": { "type": "string", "const": "railgun" }, "tokenAddress": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255 }, "amountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "recipient0zk": { "type": "string" }, "reference": { "type": "string" }, "expiresAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "nonce": { "type": "string" }, "merchantSigner": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "version", "chainId", "rail", "tokenAddress", "decimals", "amountAtomic", "recipient0zk", "reference", "expiresAt", "nonce", "merchantSigner", "signature" ], "additionalProperties": false }, "Event": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1 }, "eventId": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "type": { "type": "string", "enum": [ "settlement.observed", "payment.partial", "payment.confirmed", "payment.expired", "payment.reverted" ] }, "occurredAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "intentId": { "type": "string", "pattern": "^pi_[0-9a-f]{32}$" }, "settlementId": { "type": "string", "minLength": 1, "maxLength": 512 }, "intentStatus": { "type": "string", "enum": [ "OPEN", "PARTIAL", "PAID", "EXPIRED", "PAID_LATE" ] }, "receivedAmountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "expectedAmountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "overpaymentAmountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" } }, "required": [ "schemaVersion", "eventId", "type", "occurredAt", "intentId", "intentStatus", "receivedAmountAtomic", "expectedAmountAtomic", "overpaymentAmountAtomic" ], "additionalProperties": false }, "Settlement": { "type": "object", "properties": { "uniqueSettlementId": { "type": "string" }, "chainId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "txidVersion": { "type": "string" }, "tree": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "transactionHash": { "type": "string" }, "railgunTxid": { "type": "string" }, "tokenAddress": { "type": "string" }, "amountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "blockNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "blockTimestamp": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "balanceBucket": { "type": "string" }, "rawPPOIStatuses": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "chainStatus": { "type": "string", "enum": [ "OBSERVED", "CONFIRMED", "FINALIZED", "REVERTED" ] }, "poiStatus": { "type": "string", "enum": [ "UNKNOWN", "PENDING", "SPENDABLE", "BLOCKED" ] }, "matchStatus": { "type": "string", "enum": [ "UNMATCHED", "MATCHED", "CONFLICT" ] }, "reference": { "type": "string" }, "intentId": { "type": "string" }, "firstSeenAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastSeenAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "eligibleAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "uniqueSettlementId", "chainId", "txidVersion", "tree", "position", "transactionHash", "tokenAddress", "amountAtomic", "blockNumber", "blockTimestamp", "balanceBucket", "rawPPOIStatuses", "chainStatus", "poiStatus", "matchStatus", "firstSeenAt", "lastSeenAt" ], "additionalProperties": false }, "Outbox": { "type": "object", "properties": { "eventId": { "type": "string" }, "eventType": { "type": "string" }, "attempts": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "nextAttemptAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "deliveredAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "deadLetteredAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastError": { "type": "string" } }, "required": [ "eventId", "eventType", "attempts", "nextAttemptAt" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "hint": { "type": "string" }, "field": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "hint": { "type": "string" } }, "required": [ "field", "hint" ], "additionalProperties": false } } }, "required": [ "code" ], "additionalProperties": false }, "valid": { "type": "boolean", "const": false } }, "required": [ "error" ], "additionalProperties": false }, "Runtime": { "type": "object", "properties": { "instanceId": { "type": "string" }, "chainId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "tokenAddress": { "type": "string" }, "tokenSymbol": { "type": "string" }, "tokenDecimals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "finalityMode": { "type": "string", "enum": [ "finalized", "confirmations" ] }, "rpcProviderCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ppoiConfiguredNodeCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "startedAt": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "instanceId", "chainId", "tokenAddress", "tokenSymbol", "tokenDecimals", "finalityMode", "rpcProviderCount", "ppoiConfiguredNodeCount", "startedAt" ], "additionalProperties": false }, "Health": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready", "starting", "degraded" ] }, "version": { "type": "string" }, "railgunReady": { "type": "boolean" }, "scanInProgress": { "type": "boolean" }, "consecutiveFailures": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "scanStalled": { "type": "boolean" }, "lastScanAt": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "lastScanError": { "type": "string" }, "syncProgress": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "degraded": { "type": "boolean" } }, "required": [ "status", "version", "railgunReady", "scanInProgress", "consecutiveFailures", "scanStalled" ], "additionalProperties": false }, "Ready": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready", "not_ready" ] }, "version": { "type": "string" }, "scanInProgress": { "type": "boolean" }, "scanStalled": { "type": "boolean" }, "lastScanAt": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "syncProgress": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "status", "version", "scanInProgress", "scanStalled" ], "additionalProperties": false }, "Live": { "type": "object", "properties": { "status": { "type": "string", "const": "alive" }, "version": { "type": "string" } }, "required": [ "status", "version" ], "additionalProperties": false }, "Replay": { "type": "object", "properties": { "eventId": { "type": "string" }, "replayScheduled": { "type": "boolean", "const": true } }, "required": [ "eventId", "replayScheduled" ], "additionalProperties": false }, "Verification": { "type": "object", "properties": { "valid": { "type": "boolean", "const": true }, "recoveredSigner": { "type": "string" }, "expectedSigner": { "type": "string" } }, "required": [ "valid", "recoveredSigner", "expectedSigner" ], "additionalProperties": false }, "AtomicAmount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" } } } }