{ "openapi": "3.1.0", "info": { "title": "Cryptanio Public REST API", "version": "v1", "description": "Stable public v1 contract. Describes the current candidate, not a guarantee of production deployment. Check the target environment's /v1/health before use. Projects, plans, API keys, and address sources are configured in Account. IDs and exact monetary amounts are strings. Ignore unknown additional response fields.", "x-product-version": "1.0.0 62", "x-documentation-updated": "2026-10-10" }, "servers": [ { "url": "https://api.cryptanio.com", "description": "Production: check health and feature availability first; this file does not prove candidate promotion." } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "watches", "description": "Monitoring watches" }, { "name": "events", "description": "Events" }, { "name": "payments", "description": "Payments events" }, { "name": "invoices", "description": "Payments invoices" }, { "name": "endpoints", "description": "Webhook recipients" }, { "name": "stream", "description": "SSE" }, { "name": "health", "description": "API readiness" }, { "name": "chains", "description": "Network catalog" } ], "paths": { "/v1/watches": { "post": { "operationId": "createWatch", "summary": "Create a Monitoring watch", "description": "Attach an address to an existing Monitoring project with independent rules. Projects are created in Account. One address can be used in different projects. Repeating an exact attachment is not a general rule-update API; use Account to change rules.", "tags": [ "watches" ], "x-access": "write", "responses": { "201": { "description": "Successful response.", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Watch" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scope": "watches", "x-service": "monitoring", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchRequest" } } } } }, "get": { "operationId": "listWatches", "summary": "List Monitoring watches", "description": "Watches of an accessible Monitoring project; project is required unless the key is project-scoped. Continue using next_before.", "tags": [ "watches" ], "x-access": "read", "responses": { "200": { "description": "Successful response.", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchList" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scope": "watches", "x-service": "monitoring", "parameters": [ { "name": "project", "in": "query", "required": false, "description": "Project ID. Required for listing or creating watches unless the key is project-scoped. For other operations omission uses the operation's account/project context; set it explicitly.", "schema": { "type": "string" } }, { "name": "chain", "in": "query", "required": false, "description": "Network code filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size: at most 200. Invalid values use the default; values above 200 are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "before", "in": "query", "required": false, "description": "Cursor from next_before or the last item's ID on the previous page; newest first.", "schema": { "$ref": "#/components/schemas/ID" } } ] } }, "/v1/watches/{id}": { "get": { "operationId": "getWatch", "summary": "Get a Monitoring watch", "description": "Read a watch attachment, not its payment history; query /events for events.", "tags": [ "watches" ], "x-access": "read", "responses": { "200": { "description": "Successful response.", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Watch" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scope": "watches", "x-service": "monitoring", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Opaque resource ID.", "schema": { "$ref": "#/components/schemas/ID" } } ] }, "delete": { "operationId": "deleteWatch", "summary": "Delete a Monitoring watch", "description": "Remove this project's watch, not other projects or the address book. A synchronized list/source can return 409; edit the source in Account. Repeating a successful removal returns 404.", "tags": [ "watches" ], "x-access": "write", "responses": { "200": { "description": "Successful response.", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scope": "watches", "x-service": "monitoring", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Opaque resource ID.", "schema": { "$ref": "#/components/schemas/ID" } } ] } }, "/v1/events": { "get": { "operationId": "listEvents", "summary": "List events", "description": "Event history within the key's scope, retained for 30 days. No date filter; paginate with before. Service-scoped keys restrict their service. Non-payment events have payment:null; no additional contract/notice body is returned.", "tags": [ "events" ], "x-access": "read", "responses": { "200": { "description": "Successful response.", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scope": "events", "parameters": [ { "name": "project", "in": "query", "required": false, "description": "Project ID. Required for listing or creating watches unless the key is project-scoped. For other operations omission uses the operation's account/project context; set it explicitly.", "schema": { "type": "string" } }, { "name": "watch_id", "in": "query", "required": false, "description": "Project watch ID.", "schema": { "type": "string" } }, { "name": "chain", "in": "query", "required": false, "description": "Network code filter.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Event type, such as payment.confirmed.", "schema": { "type": "string" } }, { "name": "address", "in": "query", "required": false, "description": "Address.", "schema": { "type": "string" } }, { "name": "tx_id", "in": "query", "required": false, "description": "Transaction ID.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size: at most 200. Invalid values use the default; values above 200 are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 25 } }, { "name": "before", "in": "query", "required": false, "description": "Cursor from next_before or the last item's ID on the previous page; newest first.", "schema": { "$ref": "#/components/schemas/ID" } } ] } }, "/v1/payments": { "get": { "operationId": "listPayments", "summary": "List Payments events", "description": "Same shape and cursor as /events, restricted to Payments service events; not an account-wide alias.", "tags": [ "payments" ], "x-access": "read", "responses": { "200": { "description": "Successful response.", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scope": "events", "x-service": "payments", "parameters": [ { "name": "project", "in": "query", "required": false, "description": "Project ID. Required for listing or creating watches unless the key is project-scoped. For other operations omission uses the operation's account/project context; set it explicitly.", "schema": { "type": "string" } }, { "name": "watch_id", "in": "query", "required": false, "description": "Project watch ID.", "schema": { "type": "string" } }, { "name": "chain", "in": "query", "required": false, "description": "Network code filter.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Event type, such as payment.confirmed.", "schema": { "type": "string" } }, { "name": "address", "in": "query", "required": false, "description": "Address.", "schema": { "type": "string" } }, { "name": "tx_id", "in": "query", "required": false, "description": "Transaction ID.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size: at most 200. Invalid values use the default; values above 200 are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 25 } }, { "name": "before", "in": "query", "required": false, "description": "Cursor from next_before or the last item's ID on the previous page; newest first.", "schema": { "$ref": "#/components/schemas/ID" } } ] } }, "/v1/invoices": { "post": { "operationId": "createInvoice", "summary": "Create an invoice", "description": "Create a Payments invoice. Supply chain and amount for fixed payment details, or omit chain, asset, amount, address and tolerance and supply invoice_currency plus invoice_amount for a payer-selected method. The latter requires a live write key and Idempotency-Key; creation and an identical retry return the interactive checkout URL. GET/list retain read-only links. After a timeout, retry the same body with the same Idempotency-Key; different parameters return 409. A keyed retry returns 201 with the same ID. Without a key, a fixed-method retry can create another invoice. Does not create a blockchain payment.", "tags": [ "invoices" ], "x-access": "write", "responses": { "201": { "description": "Successful response.", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scope": "invoices", "x-service": "payments", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "16–80 ASCII letters, digits, dashes, or underscores. Unique logical order ID within the account. Required for a payer-selected payment method.", "schema": { "type": "string", "minLength": 16, "maxLength": 80, "pattern": "^[A-Za-z0-9_-]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRequest" } } } } }, "get": { "operationId": "listInvoices", "summary": "List invoices", "description": "Invoices only, not donations. Newest ID first. The response contains data without next_before; pass the last item ID as before to continue. Stop at an empty page.", "tags": [ "invoices" ], "x-access": "read", "responses": { "200": { "description": "Successful response.", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceList" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scope": "invoices", "x-service": "payments", "parameters": [ { "name": "project", "in": "query", "required": false, "description": "Project ID. Required for listing or creating watches unless the key is project-scoped. For other operations omission uses the operation's account/project context; set it explicitly.", "schema": { "type": "string" } }, { "name": "chain", "in": "query", "required": false, "description": "Network code filter.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Invoice status.", "schema": { "$ref": "#/components/schemas/InvoiceStatus" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size: at most 200. Invalid values use the default; values above 200 are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "before", "in": "query", "required": false, "description": "Cursor from next_before or the last item's ID on the previous page; newest first.", "schema": { "$ref": "#/components/schemas/ID" } } ] } }, "/v1/invoices/{id}": { "get": { "operationId": "getInvoice", "summary": "Get an invoice", "description": "Read an invoice in a project allowed by the API key.", "tags": [ "invoices" ], "x-access": "read", "responses": { "200": { "description": "Successful response.", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scope": "invoices", "x-service": "payments", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Opaque resource ID.", "schema": { "$ref": "#/components/schemas/ID" } } ] } }, "/v1/invoices/{id}/cancel": { "post": { "operationId": "cancelInvoice", "summary": "Cancel an invoice", "description": "Cancel an open invoice without deleting it. It remains available for reconciliation. An incompatible closed status returns 409.", "tags": [ "invoices" ], "x-access": "write", "responses": { "200": { "description": "Successful response.", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scope": "invoices", "x-service": "payments", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Opaque resource ID.", "schema": { "$ref": "#/components/schemas/ID" } } ] } }, "/v1/endpoints": { "post": { "operationId": "createEndpoint", "summary": "Create a webhook endpoint", "description": "Add a project HTTPS receiver. Maximum 20 active endpoints per account. Re-registering the same URL for the same project with the same API key does not duplicate deliveries: 200 with the existing ID and no secret. Store the secret after 201. At capacity, even a repeat can return 402.", "tags": [ "endpoints" ], "x-access": "write", "responses": { "200": { "description": "Endpoint already registered; secret is omitted.", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Endpoint" } } } }, "201": { "description": "Successful response.", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Endpoint" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scope": "webhooks", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointRequest" } } } } }, "get": { "operationId": "listEndpoints", "summary": "List webhook endpoints", "description": "Active endpoints in projects allowed by the API key. No secrets returned; no pagination (at most 20).", "tags": [ "endpoints" ], "x-access": "read", "responses": { "200": { "description": "Successful response.", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointList" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scope": "webhooks" } }, "/v1/endpoints/{id}": { "delete": { "operationId": "deleteEndpoint", "summary": "Delete a webhook endpoint", "description": "Idempotent removal: 200 with deleted:true even if already removed or inaccessible to this key. Does not delete another scope's object.", "tags": [ "endpoints" ], "x-access": "write", "responses": { "200": { "description": "Successful response.", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scope": "webhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Opaque resource ID.", "schema": { "$ref": "#/components/schemas/ID" } } ] } }, "/v1/stream": { "get": { "operationId": "streamEvents", "summary": "Stream events", "description": "SSE with event:payment, JSON data, and heartbeat comments. Its shape differs from webhook v1. Recover missing events through /events; Last-Event-ID replay is not implemented. Native browser EventSource cannot set Bearer headers: use a server client or fetch streaming, never a key in the query.", "tags": [ "stream" ], "x-access": "read", "responses": { "200": { "description": "Server-Sent Events stream.", "content": { "text/event-stream": { "schema": { "type": "string" }, "example": ": connected\n\nretry: 5000\n\n: ping\n\n" } }, "x-event-schema": { "$ref": "#/components/schemas/StreamEvent" } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scope": "stream" } }, "/v1/health": { "get": { "operationId": "getHealth", "summary": "Get API health", "description": "Check public API readiness and product version. Verify new capabilities on https://api.cryptanio.com.", "tags": [ "health" ], "x-access": "public", "responses": { "200": { "description": "Successful response.", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "503": { "description": "API temporarily not ready.", "headers": { "Retry-After": { "schema": { "type": "string" }, "example": "5" }, "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } } }, "security": [] } }, "/v1/chains": { "get": { "operationId": "listChains", "summary": "List networks", "description": "Network and confirmation catalog. live indicates public API monitoring availability, not merely address-format support. Check the current catalog before attaching an address.", "tags": [ "chains" ], "x-access": "public", "responses": { "200": { "description": "Successful response.", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChainList" } } } } }, "security": [] } } }, "webhooks": { "event": { "post": { "summary": "Receive a Cryptanio webhook", "description": "HTTPS POST to the receiver URL. Verify HMAC-SHA256 of timestamp + '.' + unchanged raw body, signature format, allowed timestamp, and constant-time comparison. Use signed event_id/event_type after verification. Return 2xx after durable storage; deduplicate retries by event_id.", "parameters": [ { "name": "X-Event-Id", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/ID" }, "description": "ID hint; trust the signed-body value." }, { "name": "X-Event-Type", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Type hint; trust the signed-body value." }, { "name": "X-Attempt", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Attempt number, not a deduplication key." }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Unix seconds for this delivery attempt." }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "description": "64 lowercase hexadecimal HMAC-SHA256 characters." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "responses": { "200": { "description": "Event accepted; any 2xx is successful." }, "410": { "description": "Receiver removed; further deliveries stop." } }, "security": [] } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "ck_live_…", "description": "Keep the API secret server-side. Create a key at https://account.cryptanio.com/api-keys. Expiry, revocation, scopes, read-only mode, project, service, and IP restrictions constrain access." } }, "headers": { "ProductVersion": { "schema": { "type": "string" }, "description": "Environment's technical product version." }, "ContractVersion": { "schema": { "type": "string", "const": "v1" }, "description": "Public contract version." } }, "responses": { "Error400": { "description": "Invalid request (bad_request, unsupported_asset).", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error401": { "description": "No valid active API key (unauthorized).", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error402": { "description": "Resource limit reached (limit_reached).", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error403": { "description": "Key disallows the operation, project, service or IP; email unconfirmed.", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error409": { "description": "State conflict, conflicting retry parameters, or payment resource limit (conflict, limit_reached, service_inactive).", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error429": { "description": "Too many requests (rate_limited); retry after Retry-After.", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Minimum delay in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error500": { "description": "Internal error (internal).", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error503": { "description": "Temporary unavailability (unavailable); retry with backoff.", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error404": { "description": "Object not found within the key's scope (not_found).", "headers": { "X-Server-Version": { "$ref": "#/components/headers/ProductVersion" }, "X-API-Version": { "$ref": "#/components/headers/ContractVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "ID": { "type": "string", "minLength": 1, "description": "Opaque identifier. Its format is not guaranteed; do not convert to a number.", "examples": [ "1002" ] }, "Decimal": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "examples": [ "12.50" ] }, "RawAmount": { "type": "string", "pattern": "^[0-9]+$", "examples": [ "12500000" ] }, "StringMap": { "type": "object", "additionalProperties": { "type": "string" } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable message; do not use it as an error code." } } } }, "examples": [ { "error": { "code": "forbidden", "message": "this API key is read-only" } } ] }, "WatchRequest": { "type": "object", "required": [ "chain", "address" ], "properties": { "project": { "type": "string", "description": "Project ID. Required for listing or creating watches unless the key is project-scoped. For other operations omission uses the operation's account/project context; set it explicitly." }, "chain": { "type": "string", "description": "Network code from GET /v1/chains.", "minLength": 1 }, "address": { "type": "string", "description": "Address in the selected network; validated and normalized.", "minLength": 1 }, "asset": { "type": "string", "description": "Default asset for exact: native, supported symbol, or token identifier.", "default": "native" }, "label": { "type": "string", "description": "Address-book label.", "maxLength": 60 }, "note": { "type": "string", "description": "Optional address-book note.", "maxLength": 280 }, "watch_outgoing": { "type": "boolean", "description": "Also receive outgoing operations; the network must support them.", "default": false }, "asset_policy": { "type": "string", "description": "exact selects one asset; allow uses asset_ids; all selects every network asset. Tokenless networks only support native/exact.", "enum": [ "exact", "allow", "all" ], "default": "exact" }, "asset_ids": { "type": "array", "items": { "type": "string", "maxLength": 256 }, "maxItems": 100, "description": "Exactly one for exact, at least one for allow, empty for all. With exact and an empty list, asset is used." }, "excluded_asset_ids": { "type": "array", "items": { "type": "string", "maxLength": 256 }, "maxItems": 100, "description": "Assets to exclude." }, "min_confirmations": { "type": "integer", "description": "Minimum confirmations.", "minimum": 0, "default": 0 }, "min_amount": { "$ref": "#/components/schemas/RawAmount", "description": "Non-negative threshold in smallest units, not a decimal amount." }, "watch_contracts": { "type": "boolean", "description": "Receive supported contract events.", "default": false }, "watch_unexpected_assets": { "type": "boolean", "description": "Receive unexpected-asset events.", "default": false } }, "examples": [ { "project": "1002", "chain": "ethereum", "address": "0x52908400098527886E0F7030069857D2E4169EE7", "asset": "native", "label": "Treasury" } ] }, "Watch": { "type": "object", "required": [ "id", "project_id", "service", "book_address_id", "status", "chain", "address", "asset", "watch_outgoing", "origin_kinds", "created_at" ], "properties": { "id": { "$ref": "#/components/schemas/ID", "description": "Opaque identifier; keep it as a string." }, "project_id": { "$ref": "#/components/schemas/ID", "description": "Opaque identifier; keep it as a string." }, "service": { "type": "string", "description": "Project service.", "const": "monitoring" }, "book_address_id": { "$ref": "#/components/schemas/ID", "description": "Matching address-book address ID." }, "status": { "type": "string", "description": "Project-address attachment state.", "enum": [ "active", "paused", "deleted" ] }, "chain": { "type": "string", "description": "Network code." }, "address": { "type": "string", "description": "Normalized address." }, "asset": { "type": "string", "description": "Assets in the response string; multiple assets are comma-separated." }, "meta": { "$ref": "#/components/schemas/StringMap", "description": "Address label and note, if configured." }, "watched_as": { "type": "string", "description": "Additional address identifier when used by the network." }, "sandbox": { "type": "boolean", "description": "true for a test watch; omission means false." }, "watch_outgoing": { "type": "boolean", "description": "Whether outgoing operations are monitored." }, "origin_kinds": { "type": "array", "items": { "type": "string" }, "description": "Ways the address was added to the project." }, "created_at": { "type": "string", "format": "date-time", "description": "UTC date and time in RFC 3339." } }, "examples": [ { "id": "1008", "project_id": "1002", "service": "monitoring", "book_address_id": "1007", "status": "active", "chain": "ethereum", "address": "0x52908400098527886E0F7030069857D2E4169EE7", "asset": "native", "sandbox": true, "watch_outgoing": false, "origin_kinds": [ "manual" ], "created_at": "2026-10-06T10:00:00Z" } ] }, "Customer": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Customer identifier in your system.", "maxLength": 120 } } }, "Product": { "type": "object", "properties": { "id": { "type": "string", "description": "Product identifier in your system.", "maxLength": 120 }, "name": { "type": "string", "description": "Product name.", "maxLength": 200 }, "quantity": { "type": "integer", "description": "Quantity.", "minimum": 1, "maximum": 1000000 } } }, "Payer": { "type": "object", "required": [ "comment" ], "properties": { "comment": { "type": "string", "description": "Payer comment.", "maxLength": 500 } } }, "InvoiceMetadata": { "type": "object", "maxProperties": 20, "propertyNames": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9_.-]+$" }, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Up to 20 pairs, at most 8192 JSON bytes. Do not include secrets." }, "InvoiceRequest": { "type": "object", "anyOf": [ { "required": [ "chain", "amount" ] }, { "required": [ "invoice_currency", "invoice_amount" ], "not": { "anyOf": [ { "required": [ "chain" ] }, { "required": [ "asset" ] }, { "required": [ "amount" ] }, { "required": [ "address" ] }, { "required": [ "tolerance" ] } ] } } ], "properties": { "project": { "type": "string", "description": "Payments project ID; explicit selection is recommended. A project-scoped key uses its project." }, "chain": { "type": "string", "description": "Network code.", "minLength": 1 }, "asset": { "type": "string", "description": "Supported payment asset: native, symbol, or known identifier. Accepted assets depend on the network; omission selects native.", "default": "native" }, "amount": { "$ref": "#/components/schemas/Decimal", "description": "Positive crypto amount in asset units; precision must not exceed the asset's decimals." }, "reference": { "type": "string", "description": "Your order reference; not a substitute for Idempotency-Key.", "maxLength": 120 }, "address": { "type": "string", "description": "Optional address from the project's payment pool. Otherwise the service selects one." }, "tolerance": { "$ref": "#/components/schemas/Decimal", "description": "Allowed underpayment in asset units, strictly less than amount. Omit for zero tolerance." }, "customer": { "$ref": "#/components/schemas/Customer" }, "product": { "$ref": "#/components/schemas/Product" }, "payer": { "$ref": "#/components/schemas/Payer" }, "metadata": { "$ref": "#/components/schemas/InvoiceMetadata" }, "invoice_currency": { "type": "string", "description": "Three-letter order quote currency; only together with invoice_amount.", "pattern": "^[A-Za-z]{3}$" }, "invoice_amount": { "$ref": "#/components/schemas/Decimal", "description": "Positive order quote in invoice_currency. With chain and amount this is the merchant snapshot. Without payment details it is the fixed invoice value used to quote the payer's selected asset.", "maxLength": 80 }, "expires_in": { "type": "integer", "maximum": 10080, "default": 60, "description": "Payment window in minutes, starting at successful issuance of details. Omission or 0 uses the project policy (60 by default); maximum 10080. Fixed-method legacy requests also treat negative values as omitted; payer-selected checkout rejects negative values." } }, "additionalProperties": false, "dependentRequired": { "invoice_currency": [ "invoice_amount" ], "invoice_amount": [ "invoice_currency" ] }, "examples": [ { "project": "2002", "invoice_currency": "USD", "invoice_amount": "12.50", "reference": "order-42" }, { "project": "2002", "chain": "ethereum", "asset": "USDC", "amount": "12.50", "reference": "order-42", "expires_in": 60, "customer": { "id": "customer-42" }, "metadata": { "order": "42" } } ] }, "InvoiceStatus": { "type": "string", "enum": [ "pending", "seen", "paid", "underpaid", "partial", "overpaid", "expired", "late", "canceled" ], "description": "pending awaits payment; seen detected; partial partially paid; paid settled; underpaid/overpaid/late need a decision; expired deadline passed; canceled voided." }, "Invoice": { "type": "object", "required": [ "id", "status", "project_id", "chain", "asset", "address", "amount", "amount_raw", "asked", "decimals", "sandbox", "expires_at", "created_at" ], "properties": { "checkout_url": { "type": "string", "format": "uri", "description": "Hosted Cryptanio payment page. Creation/retry of a payer-selected invoice returns an interactive capability that permits method selection until payment is detected. Fixed-method creation and every GET/list return a separate read-only link. Share either link only with the intended payer; neither grants account or API-key access. Confirm payment using the invoice API or a verified webhook, not a browser redirect." }, "id": { "$ref": "#/components/schemas/ID", "description": "Opaque identifier; keep it as a string." }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "project_id": { "$ref": "#/components/schemas/ID", "description": "Opaque identifier; keep it as a string." }, "reference": { "type": "string", "description": "Order reference." }, "customer": { "$ref": "#/components/schemas/Customer" }, "product": { "$ref": "#/components/schemas/Product" }, "payer": { "$ref": "#/components/schemas/Payer" }, "metadata": { "$ref": "#/components/schemas/InvoiceMetadata" }, "invoice_currency": { "type": "string", "description": "Order quote currency." }, "invoice_amount": { "$ref": "#/components/schemas/Decimal", "description": "Exact decimal amount as a string; do not use floating point." }, "chain": { "type": "string", "description": "Network code." }, "asset": { "type": "string", "description": "Payment asset." }, "address": { "type": "string", "description": "Payment address." }, "payment_route": { "type": "object", "description": "Required on-chain discriminator when an automatic source issues a tag, memo, TON comment or Solana Pay reference. Keep it with the receiving address; the merchant order reference is a separate field.", "required": [ "kind", "value" ], "properties": { "kind": { "type": "string", "enum": [ "destination_tag", "memo", "comment", "reference" ] }, "value": { "type": "string", "description": "Exact case-sensitive value. For Solana use payment_uri or the hosted checkout; a wallet memo is not a Solana Pay reference." } } }, "payment_uri": { "type": "string", "format": "uri", "description": "Solana Pay transfer request with the recipient, exact amount, supported token mint and mandatory reference. Encode this URI in the payment QR instead of the plain receiving address." }, "amount": { "anyOf": [ { "$ref": "#/components/schemas/Decimal" }, { "type": "string", "const": "" } ], "description": "Actual amount the buyer must send; may differ from asked to distinguish invoices. Empty until a method is selected." }, "amount_raw": { "anyOf": [ { "$ref": "#/components/schemas/RawAmount" }, { "type": "string", "const": "" } ], "description": "Integer smallest-unit amount as a string. Empty until a method is selected." }, "asked": { "anyOf": [ { "$ref": "#/components/schemas/Decimal" }, { "type": "string", "const": "" } ], "description": "Originally requested crypto amount. Empty until a method is selected." }, "decimals": { "type": "integer", "description": "Asset decimal places.", "minimum": 0 }, "tolerance": { "$ref": "#/components/schemas/RawAmount", "description": "Tolerance in smallest units; unlike request.tolerance." }, "sandbox": { "type": "boolean", "description": "A test invoice does not prove a real blockchain payment." }, "needs_decision": { "type": "boolean", "description": "A decision is required for underpaid, overpaid, or late." }, "paid": { "$ref": "#/components/schemas/RawAmount", "description": "Received amount in smallest units." }, "tx_id": { "type": "string", "description": "Payment transaction identifier." }, "paid_at": { "type": "string", "format": "date-time", "description": "UTC date and time in RFC 3339." }, "expires_at": { "type": "string", "format": "date-time", "description": "UTC date and time in RFC 3339." }, "created_at": { "type": "string", "format": "date-time", "description": "UTC date and time in RFC 3339." } }, "examples": [ { "id": "2100", "status": "pending", "project_id": "2002", "reference": "order-42", "chain": "ethereum", "asset": "USDC", "address": "0x52908400098527886E0F7030069857D2E4169EE7", "amount": "12.5", "amount_raw": "12500000", "asked": "12.5", "decimals": 6, "sandbox": true, "expires_at": "2026-10-06T11:00:00Z", "created_at": "2026-10-06T10:00:00Z" } ] }, "EndpointRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Public HTTPS webhook receiver URL; local and private addresses are rejected.", "format": "uri", "pattern": "^https://" }, "label": { "type": "string", "description": "Optional destination label." }, "project": { "type": "string", "description": "Project ID. Omission uses the key's project or the account's default project." } }, "examples": [ { "project": "1002", "url": "https://merchant.example/webhooks/cryptanio", "label": "Orders" } ] }, "Endpoint": { "type": "object", "required": [ "id", "project_id", "sandbox", "url", "source", "created_at" ], "properties": { "id": { "$ref": "#/components/schemas/ID", "description": "Opaque identifier; keep it as a string." }, "project_id": { "$ref": "#/components/schemas/ID", "description": "Opaque identifier; keep it as a string." }, "sandbox": { "type": "boolean", "description": "Test destination flag; does not imply a public customer sandbox is available." }, "url": { "type": "string", "description": "Destination HTTPS URL.", "format": "uri" }, "label": { "type": "string", "description": "Label." }, "secret": { "type": "string", "description": "Signing secret; returned only for a new creation, not for a list or repeated registration." }, "source": { "type": "string", "description": "Destination creation method, such as api, dashboard, or browser. New values may be added." }, "created_at": { "type": "string", "format": "date-time", "description": "UTC date and time in RFC 3339." } }, "examples": [ { "id": "2200", "project_id": "1002", "sandbox": true, "url": "https://merchant.example/webhooks/cryptanio", "source": "api", "created_at": "2026-10-06T10:00:00Z" } ] }, "Deleted": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "$ref": "#/components/schemas/ID", "description": "Opaque identifier; keep it as a string." }, "deleted": { "type": "boolean", "description": "Record removed from this API scope.", "const": true } }, "examples": [ { "id": "1008", "deleted": true } ] }, "EventPayment": { "type": "object", "properties": { "tx_id": { "type": "string", "description": "Transaction identifier." }, "index": { "type": "integer", "description": "Transfer index within the transaction.", "minimum": 0 }, "height": { "type": "integer", "description": "Block height, when known.", "minimum": 0 }, "address": { "type": "string", "description": "Observed address." }, "asset": { "type": "string", "description": "REST/SSE asset: string identifier, not the webhook asset object." }, "amount_raw": { "$ref": "#/components/schemas/RawAmount", "description": "Integer smallest-unit amount as a string." }, "amount": { "$ref": "#/components/schemas/Decimal", "description": "Exact decimal amount as a string; do not use floating point." }, "decimals": { "type": "integer", "description": "Decimal places.", "minimum": 0 }, "confirmations": { "type": "integer", "description": "Confirmations.", "minimum": 0 }, "revision": { "type": "integer", "description": "Transfer state revision.", "minimum": 0 }, "direction": { "type": "string", "description": "Direction relative to the observed address.", "enum": [ "in", "out" ] }, "simulated": { "type": "boolean", "description": "Simulated event." }, "late": { "type": "boolean", "description": "Late detected transfer." }, "block_hash": { "type": "string", "description": "Block hash." }, "match_key": { "type": "string", "description": "Match identifier when used by the network." }, "meta": { "$ref": "#/components/schemas/StringMap" }, "invoice": { "type": "object", "additionalProperties": true }, "customer": { "$ref": "#/components/schemas/Customer" }, "product": { "$ref": "#/components/schemas/Product" }, "payer": { "$ref": "#/components/schemas/Payer" }, "metadata": { "$ref": "#/components/schemas/StringMap" } }, "description": "REST/SSE payment document. Fields depend on the event and network; not the normalized webhook v1 shape.", "additionalProperties": true }, "Event": { "type": "object", "required": [ "event_id", "event_type", "chain", "occurred_at", "payment" ], "properties": { "event_id": { "$ref": "#/components/schemas/ID", "description": "Opaque identifier; keep it as a string." }, "event_type": { "type": "string", "description": "Event type; new types may be added." }, "chain": { "type": "string", "description": "Network code." }, "service": { "type": "string", "description": "Service, when known." }, "watch_id": { "$ref": "#/components/schemas/ID", "description": "Project watch ID, when linked to a watch." }, "occurred_at": { "type": "string", "format": "date-time", "description": "UTC date and time in RFC 3339." }, "payment": { "anyOf": [ { "$ref": "#/components/schemas/EventPayment" }, { "type": "null" } ], "description": "Payment document, or null for a non-payment event. GET /events does not return contract/notice payloads." }, "sandbox": { "type": "boolean", "description": "Test event; omission means false." } }, "examples": [ { "event_id": "2300", "event_type": "payment.confirmed", "chain": "ethereum", "service": "monitoring", "watch_id": "1008", "occurred_at": "2026-10-06T10:00:00Z", "payment": { "tx_id": "simulated_2300", "index": 0, "address": "0x52908400098527886E0F7030069857D2E4169EE7", "asset": "native", "amount_raw": "1000000000000000000", "amount": "1.000000000000000000", "decimals": 18, "confirmations": 0, "revision": 1, "direction": "in", "simulated": true }, "sandbox": true } ] }, "StreamEvent": { "type": "object", "required": [ "event_id", "event_type", "chain", "occurred_at" ], "properties": { "event_id": { "$ref": "#/components/schemas/ID", "description": "Opaque identifier; keep it as a string." }, "event_type": { "type": "string", "description": "Event type; new types may be added." }, "chain": { "type": "string", "description": "Network code." }, "service": { "type": "string", "description": "Service, when known." }, "watch_id": { "$ref": "#/components/schemas/ID", "description": "Project watch ID, when linked to a watch." }, "occurred_at": { "type": "string", "format": "date-time", "description": "UTC date and time in RFC 3339." }, "payment": { "anyOf": [ { "$ref": "#/components/schemas/EventPayment" }, { "type": "null" } ], "description": "Payment document, or null for a non-payment event. GET /events does not return contract/notice payloads." }, "sandbox": { "type": "boolean", "description": "Test event; omission means false." }, "project_id": { "$ref": "#/components/schemas/ID", "description": "Opaque identifier; keep it as a string." }, "project_name": { "type": "string", "description": "Project name." }, "url": { "type": "string", "description": "Link to the Account event.", "format": "uri" }, "contract": { "type": "object", "additionalProperties": true }, "mode": { "type": "string", "description": "live or test.", "enum": [ "live", "test" ] } }, "description": "JSON in SSE data; differs from webhook v1. Non-payment events omit payment and may include contract." }, "Health": { "type": "object", "required": [ "status", "version" ], "properties": { "status": { "type": "string", "description": "ok means ready; not_ready temporarily unavailable.", "enum": [ "ok", "not_ready" ] }, "version": { "type": "string", "description": "Product version of this environment, not the API contract version." }, "reason": { "type": "string", "description": "Optional diagnostic code; do not use it for business logic." } }, "examples": [ { "status": "ok", "version": "1.0.0 62" } ] }, "Chain": { "type": "object", "required": [ "chain", "title", "native_coin", "decimals", "pending_in", "confirmed_in", "live" ], "properties": { "chain": { "type": "string", "description": "Network code for requests." }, "title": { "type": "string", "description": "Network title." }, "native_coin": { "type": "string", "description": "Native coin." }, "decimals": { "type": "integer", "description": "Native coin decimals.", "minimum": 0 }, "token_standard": { "type": "string", "description": "Supported token standard." }, "stablecoins": { "type": "array", "items": { "type": "string" }, "description": "Known payment stablecoin symbols." }, "pending_in": { "type": "string", "description": "Expected pending detection." }, "confirmed_in": { "type": "string", "description": "Expected confirmation." }, "caveat": { "type": "string", "description": "Network-specific caveat." }, "live": { "type": "boolean", "description": "Real blockchain transaction monitoring is available in the public API. Address-format support alone does not guarantee it." } } }, "WebhookAsset": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Symbol if known; not sufficient to establish token identity." }, "standard": { "type": "string", "description": "Token standard if known." }, "contract": { "type": "string", "description": "Token contract in its network, where applicable." }, "identifier": { "type": "string", "description": "Other network-specific token identifier." } } }, "Valuation": { "type": "object", "required": [ "currency", "amount", "rate", "rate_at" ], "properties": { "currency": { "type": "string", "description": "Valuation currency, such as USD." }, "amount": { "$ref": "#/components/schemas/Decimal", "description": "Exact decimal amount as a string; do not use floating point." }, "rate": { "$ref": "#/components/schemas/Decimal", "description": "Asset exchange rate as a decimal string." }, "rate_at": { "type": "string", "format": "date-time", "description": "UTC date and time in RFC 3339." }, "provider": { "type": "string", "description": "Quote source name, if known." } } }, "WebhookPayment": { "type": "object", "required": [ "chain", "direction", "asset", "address", "tx_id", "index", "amount", "amount_raw", "decimals", "confirmations", "revision" ], "properties": { "chain": { "type": "string", "description": "Network code." }, "direction": { "type": "string", "description": "Incoming payment: in; outgoing debit: out.", "enum": [ "in", "out" ] }, "asset": { "$ref": "#/components/schemas/WebhookAsset" }, "address": { "type": "string", "description": "Observed address." }, "tx_id": { "type": "string", "description": "Transaction ID." }, "index": { "type": "integer", "description": "Transfer index; do not assume 0 for any network.", "minimum": 0 }, "height": { "type": "integer", "description": "Block height if known.", "minimum": 0 }, "block_hash": { "type": "string", "description": "Block hash if known." }, "match_key": { "type": "string", "description": "Network match identifier, when applicable." }, "amount": { "$ref": "#/components/schemas/Decimal", "description": "Exact decimal amount as a string; do not use floating point." }, "amount_raw": { "$ref": "#/components/schemas/RawAmount", "description": "Integer smallest-unit amount as a string." }, "decimals": { "type": "integer", "description": "Decimal places.", "minimum": 0 }, "confirmations": { "type": "integer", "description": "Confirmations.", "minimum": 0 }, "revision": { "type": "integer", "description": "Transfer state revision. Do not collapse distinct event_id values by transaction identity.", "minimum": 0 }, "late": { "type": "boolean", "description": "Late detected transfer; not the same as invoice status late." }, "simulated": { "type": "boolean", "description": "Simulated transfer." }, "valuation": { "$ref": "#/components/schemas/Valuation" } } }, "WebhookContract": { "type": "object", "required": [ "chain", "address", "tx_id", "index" ], "properties": { "chain": { "type": "string", "description": "Network code." }, "address": { "type": "string", "description": "Observed address or contract." }, "tx_id": { "type": "string", "description": "Transaction ID." }, "index": { "type": "integer", "description": "Event index.", "minimum": 0 }, "height": { "type": "integer", "description": "Block height.", "minimum": 0 }, "block_hash": { "type": "string", "description": "Block hash." }, "kind": { "type": "string", "description": "Change kind." }, "asset": { "type": "string", "description": "Affected asset identifier, if known." }, "detail": { "$ref": "#/components/schemas/StringMap" }, "simulated": { "type": "boolean", "description": "Simulated event." } } }, "WebhookInvoice": { "type": "object", "required": [ "id" ], "properties": { "id": { "$ref": "#/components/schemas/ID", "description": "Opaque identifier; keep it as a string." }, "reference": { "type": "string", "description": "Order reference." }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "currency": { "type": "string", "description": "Order quote currency." }, "amount": { "$ref": "#/components/schemas/Decimal", "description": "Exact decimal amount as a string; do not use floating point." } } }, "Notice": { "type": "object", "required": [ "subject", "text" ], "properties": { "subject": { "type": "string", "description": "Notice subject." }, "text": { "type": "string", "description": "Notice text." } } }, "Webhook": { "type": "object", "required": [ "schema_version", "event_id", "event_type", "occurred_at", "project_id", "mode", "sandbox" ], "properties": { "schema_version": { "type": "string", "description": "Webhook payload version.", "const": "v1" }, "event_id": { "$ref": "#/components/schemas/ID", "description": "Event ID: unchanged for delivery retries. Different states can have different event_id values." }, "event_type": { "type": "string", "description": "Type in the signed body; use it after verifying the signature. New types may be added." }, "occurred_at": { "type": "string", "format": "date-time", "description": "UTC date and time in RFC 3339." }, "project_id": { "$ref": "#/components/schemas/ID", "description": "Opaque identifier; keep it as a string." }, "service": { "type": "string", "description": "Project service, where applicable." }, "mode": { "type": "string", "description": "Event mode.", "enum": [ "live", "test" ] }, "sandbox": { "type": "boolean", "description": "Explicit simulation flag." }, "payment": { "$ref": "#/components/schemas/WebhookPayment" }, "contract": { "$ref": "#/components/schemas/WebhookContract" }, "invoice": { "$ref": "#/components/schemas/WebhookInvoice" }, "customer": { "$ref": "#/components/schemas/Customer" }, "product": { "$ref": "#/components/schemas/Product" }, "payer": { "$ref": "#/components/schemas/Payer" }, "metadata": { "$ref": "#/components/schemas/StringMap" }, "notice": { "$ref": "#/components/schemas/Notice" } }, "description": "Public signed webhook v1 body. payment.* and debit.* contain payment; contract.* and asset.unexpected contain contract; webhook.test has no business payload; account.notice, account.notification, treasury.alarm, and subscription.notice contain notice. Deduplicate delivery retries by event_id.", "allOf": [ { "if": { "properties": { "event_type": { "pattern": "^(payment|debit)\\." } } }, "then": { "required": [ "payment" ], "not": { "anyOf": [ { "required": [ "contract" ] }, { "required": [ "notice" ] } ] } } }, { "if": { "properties": { "event_type": { "pattern": "^(contract\\.|asset\\.unexpected$)" } } }, "then": { "required": [ "contract" ], "not": { "anyOf": [ { "required": [ "payment" ] }, { "required": [ "notice" ] } ] } } }, { "if": { "properties": { "event_type": { "const": "webhook.test" } } }, "then": { "not": { "anyOf": [ { "required": [ "payment" ] }, { "required": [ "contract" ] }, { "required": [ "notice" ] } ] } } }, { "if": { "properties": { "event_type": { "enum": [ "account.notice", "account.notification", "treasury.alarm", "subscription.notice" ] } } }, "then": { "required": [ "notice" ], "not": { "anyOf": [ { "required": [ "payment" ] }, { "required": [ "contract" ] } ] } } } ], "x-event-types": [ "payment.pending", "payment.confirmed", "payment.rolled_back", "debit.pending", "debit.confirmed", "debit.rolled_back", "contract.approval", "contract.owner_added", "contract.owner_removed", "contract.threshold_changed", "contract.permissions_changed", "asset.unexpected", "webhook.test", "account.notice", "account.notification", "treasury.alarm", "subscription.notice" ], "examples": [ { "schema_version": "v1", "event_id": "2300", "event_type": "payment.confirmed", "occurred_at": "2026-10-06T10:00:00Z", "project_id": "1002", "service": "monitoring", "mode": "test", "sandbox": true, "payment": { "chain": "ethereum", "direction": "in", "asset": { "symbol": "ETH" }, "address": "0x52908400098527886E0F7030069857D2E4169EE7", "tx_id": "simulated_2300", "index": 0, "amount": "1.000000000000000000", "amount_raw": "1000000000000000000", "decimals": 18, "confirmations": 0, "revision": 1, "simulated": true } }, { "schema_version": "v1", "event_id": "2301", "event_type": "webhook.test", "occurred_at": "2026-10-06T10:00:00Z", "project_id": "1002", "mode": "test", "sandbox": true }, { "schema_version": "v1", "event_id": "2302", "event_type": "account.notice", "occurred_at": "2026-10-06T10:00:00Z", "project_id": "1002", "mode": "live", "sandbox": false, "notice": { "subject": "Service paused", "text": "Review your service settings." } } ] }, "WatchList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Watch" } }, "next_before": { "$ref": "#/components/schemas/ID", "description": "Next-page cursor; only present when more pages exist." } } }, "InvoiceList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } } } }, "EventList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "next_before": { "$ref": "#/components/schemas/ID", "description": "Next-page cursor; only present when more pages exist." } } }, "EndpointList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Endpoint" } } } }, "ChainList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Chain" } } } } } } }