{ "openapi": "3.1.0", "info": { "title": "MegTrust Client API", "version": "1.0.0", "description": "Signed server-to-server API. Read README.md for canonical signing, retries, webhooks and MCP. 120 requests/key/minute; 64 KiB maximum request body. Keys reach exactly one workspace. Use separate credentials per environment." }, "servers": [ { "url": "https://stagingvault.megtrust.com", "description": "Sandbox" }, { "url": "https://vault.megtrust.com", "description": "Production" } ], "externalDocs": { "description": "Client integration guide", "url": "/integrations/megtrust/README.md" }, "security": [ { "KeyId": [], "Timestamp": [], "Signature": [] } ], "paths": { "/api/v1/wallets": { "get": { "operationId": "list_wallets", "summary": "List workspace wallets", "responses": { "200": { "description": "List workspace wallets", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletListResponse" } } } }, "400": { "description": "validation_failed, idempotency_key_required", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized, invalid_timestamp", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "wallet_not_found, withdrawal_not_found", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_conflict", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "request_too_large", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "asset_not_held, destination_not_whitelisted, no_approver_available, withdrawal_failed", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "description": "Seconds to wait before a freshly signed retry.", "schema": { "type": "string", "pattern": "^\\d+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_unavailable", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "description": "Seconds to wait before a freshly signed retry.", "schema": { "type": "string", "pattern": "^\\d+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Balances are decimal strings and identify the network. Unreadable balances return an error instead of zero." }, "parameters": [ { "name": "_request_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Fresh random UUID per attempt, included in the signed path. Avoids duplicate signatures for identical requests in the same second." } ] }, "/api/v1/wallets/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "_request_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Fresh random UUID per attempt, included in the signed path. Avoids duplicate signatures for identical requests in the same second." } ], "get": { "operationId": "get_wallet", "summary": "Read one workspace wallet", "responses": { "200": { "description": "Read one workspace wallet", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" } } } }, "400": { "description": "validation_failed, idempotency_key_required", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized, invalid_timestamp", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "wallet_not_found, withdrawal_not_found", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_conflict", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "request_too_large", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "asset_not_held, destination_not_whitelisted, no_approver_available, withdrawal_failed", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "description": "Seconds to wait before a freshly signed retry.", "schema": { "type": "string", "pattern": "^\\d+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_unavailable", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "description": "Seconds to wait before a freshly signed retry.", "schema": { "type": "string", "pattern": "^\\d+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/transactions": { "get": { "operationId": "list_transactions", "summary": "Read recent movements", "responses": { "200": { "description": "Read recent movements", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionListResponse" } } } }, "400": { "description": "validation_failed, idempotency_key_required", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized, invalid_timestamp", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "wallet_not_found, withdrawal_not_found", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_conflict", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "request_too_large", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "asset_not_held, destination_not_whitelisted, no_approver_available, withdrawal_failed", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "description": "Seconds to wait before a freshly signed retry.", "schema": { "type": "string", "pattern": "^\\d+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_unavailable", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "description": "Seconds to wait before a freshly signed retry.", "schema": { "type": "string", "pattern": "^\\d+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "wallet_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "meta.next_cursor from the previous page. Page with this only." }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only movements recorded after this time. A range filter, not a paging mechanism." }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only movements recorded before this time. A range filter, not a paging mechanism." } ], "description": "On-chain movements, newest first, cursor-paged: follow meta.next_cursor until it is null. A page can hold slightly fewer rows than limit (network fees fold into their payout row) or more (a move between two of your own wallets is two rows). Payouts waiting for approval are not listed here; follow them in /api/v1/withdrawals." }, "parameters": [ { "name": "_request_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Fresh random UUID per attempt, included in the signed path. Avoids duplicate signatures for identical requests in the same second." } ] }, "/api/v1/transactions/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "_request_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Fresh random UUID per attempt, included in the signed path. Avoids duplicate signatures for identical requests in the same second." } ], "get": { "operationId": "get_transaction", "summary": "Read one movement", "description": "Every leg of one movement, as an array: one for a deposit or payout, two for a move between two of your own wallets (list rows already share the id). 404 transaction_not_found for anything outside your workspace.", "responses": { "200": { "description": "Read one movement", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionListResponse" } } } }, "401": { "description": "unauthorized, invalid_timestamp", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "transaction_not_found", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "description": "Seconds to wait before a freshly signed retry.", "schema": { "type": "string", "pattern": "^\\d+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_unavailable", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "description": "Seconds to wait before a freshly signed retry.", "schema": { "type": "string", "pattern": "^\\d+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/counterparties": { "get": { "operationId": "list_counterparties", "summary": "List destinations", "responses": { "200": { "description": "List destinations", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterpartyListResponse" } } } }, "400": { "description": "validation_failed, idempotency_key_required", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized, invalid_timestamp", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "wallet_not_found, withdrawal_not_found", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_conflict", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "request_too_large", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "asset_not_held, destination_not_whitelisted, no_approver_available, withdrawal_failed", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "description": "Seconds to wait before a freshly signed retry.", "schema": { "type": "string", "pattern": "^\\d+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_unavailable", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "description": "Seconds to wait before a freshly signed retry.", "schema": { "type": "string", "pattern": "^\\d+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create_counterparty", "summary": "Register a pending destination", "responses": { "200": { "description": "Existing destination; meta.already_exists=true. Does not edit it.", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterpartyResponse" } } } }, "201": { "description": "Register a pending destination", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterpartyResponse" } } } }, "400": { "description": "validation_failed, idempotency_key_required", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized, invalid_timestamp", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "wallet_not_found, withdrawal_not_found", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_conflict", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "request_too_large", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "asset_not_held, destination_not_whitelisted, no_approver_available, withdrawal_failed", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "description": "Seconds to wait before a freshly signed retry.", "schema": { "type": "string", "pattern": "^\\d+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_unavailable", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "description": "Seconds to wait before a freshly signed retry.", "schema": { "type": "string", "pattern": "^\\d+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterpartyRequest" } } } } }, "parameters": [ { "name": "_request_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Fresh random UUID per attempt, included in the signed path. Avoids duplicate signatures for identical requests in the same second." } ] }, "/api/v1/withdrawals": { "get": { "operationId": "list_withdrawals", "summary": "List recorded withdrawals", "responses": { "200": { "description": "List recorded withdrawals", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalListResponse" } } } }, "400": { "description": "validation_failed, idempotency_key_required", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized, invalid_timestamp", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "wallet_not_found, withdrawal_not_found", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_conflict", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "request_too_large", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "asset_not_held, destination_not_whitelisted, no_approver_available, withdrawal_failed", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "description": "Seconds to wait before a freshly signed retry.", "schema": { "type": "string", "pattern": "^\\d+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_unavailable", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "description": "Seconds to wait before a freshly signed retry.", "schema": { "type": "string", "pattern": "^\\d+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } }, { "name": "wallet_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "idempotency_key", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "description": "Scoped to this key's workspace. Follow meta.next_offset (null at the end); new rows may shift offsets, so deduplicate by id. Use the detail endpoint to refresh status." }, "post": { "operationId": "request_withdrawal", "summary": "Request a withdrawal under organisation policy", "responses": { "200": { "description": "Original withdrawal; meta.idempotent_replay=true.", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalResponse" } } } }, "202": { "description": "Request a withdrawal under organisation policy", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalResponse" } } } }, "400": { "description": "validation_failed, idempotency_key_required", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized, invalid_timestamp", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "wallet_not_found, withdrawal_not_found", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_conflict", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "request_too_large", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "asset_not_held, destination_not_whitelisted, no_approver_available, withdrawal_failed", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "description": "Seconds to wait before a freshly signed retry.", "schema": { "type": "string", "pattern": "^\\d+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_unavailable", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "description": "Seconds to wait before a freshly signed retry.", "schema": { "type": "string", "pattern": "^\\d+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalRequest" } } } }, "description": "202 is accepted for processing, never proof of settlement. One persisted idempotency key per payment, unique within the organisation. Same key and validated body return the original row (200); a conflicting body returns 409. Replays do not reissue failed or received rows. No approval endpoint is exposed." }, "parameters": [ { "name": "_request_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Fresh random UUID per attempt, included in the signed path. Avoids duplicate signatures for identical requests in the same second." } ] }, "/api/v1/withdrawals/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "_request_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Fresh random UUID per attempt, included in the signed path. Avoids duplicate signatures for identical requests in the same second." } ], "get": { "operationId": "get_withdrawal", "summary": "Refresh withdrawal status", "responses": { "200": { "description": "Refresh withdrawal status", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalResponse" } } } }, "400": { "description": "validation_failed, idempotency_key_required", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized, invalid_timestamp", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "wallet_not_found, withdrawal_not_found", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_conflict", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "request_too_large", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "asset_not_held, destination_not_whitelisted, no_approver_available, withdrawal_failed", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "description": "Seconds to wait before a freshly signed retry.", "schema": { "type": "string", "pattern": "^\\d+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_unavailable", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "description": "Seconds to wait before a freshly signed retry.", "schema": { "type": "string", "pattern": "^\\d+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Returns last recorded state with meta.stale=true if a live refresh fails. Final rows use recorded state. Polling never approves or retries a payment." } }, "/api/v1/withdrawals/{id}/cancel": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "_request_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Fresh random UUID per attempt, included in the signed path. Avoids duplicate signatures for identical requests in the same second." } ], "post": { "operationId": "cancel_withdrawal", "summary": "Cancel a pending withdrawal", "description": "Withdraws a payout that is still pending_approval. No body and no Idempotency-Key; repeating it is safe and returns the cancelled withdrawal. 409 withdrawal_not_cancellable once an approver has acted or the payout has moved past pending_approval.", "responses": { "200": { "description": "Cancel a pending withdrawal", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalResponse" } } } }, "401": { "description": "unauthorized, invalid_timestamp", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "withdrawal_not_found", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "withdrawal_not_cancellable", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "description": "Seconds to wait before a freshly signed retry.", "schema": { "type": "string", "pattern": "^\\d+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_unavailable", "headers": { "X-Request-Id": { "description": "Server-generated support correlation ID.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "description": "Seconds to wait before a freshly signed retry.", "schema": { "type": "string", "pattern": "^\\d+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "KeyId": { "type": "apiKey", "in": "header", "name": "x-api-key-id", "description": "Key ID registered by your organisation administrator." }, "Timestamp": { "type": "apiKey", "in": "header", "name": "x-api-timestamp", "description": "Unix seconds within ±300 seconds of the server clock." }, "Signature": { "type": "apiKey", "in": "header", "name": "x-api-signature", "description": "Padded base64 Ed25519 signature over timestamp, METHOD, exact path+query, lowercase SHA256(raw body), Idempotency-Key or empty string, joined with LF. Legacy HMAC uses lowercase hex HMAC-SHA256. Signing is required; entering a static value is insufficient." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_timestamp", "validation_failed", "idempotency_key_required", "idempotency_conflict", "request_too_large", "wallet_not_found", "withdrawal_not_found", "transaction_not_found", "withdrawal_not_cancellable", "asset_not_held", "destination_not_whitelisted", "no_approver_available", "withdrawal_failed", "rate_limited", "service_unavailable", "internal_error" ] }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Wallet": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "locked", "closed" ] }, "address": { "type": [ "string", "null" ], "deprecated": true, "description": "Display-only. For deposits select deposit_addresses by network." }, "deposit_addresses": { "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string" }, "network_name": { "type": "string" }, "address": { "type": "string" } }, "required": [ "network", "network_name", "address" ] } }, "networks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "balances": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string" }, "network": { "type": [ "string", "null" ] }, "amount": { "type": "string" }, "available": { "type": "string" }, "usd_value": { "type": "number" } }, "required": [ "asset", "network", "amount", "available", "usd_value" ] } }, "total_usd": { "type": "number" } }, "required": [ "id", "name", "status", "address", "deposit_addresses", "networks", "balances", "total_usd" ] }, "Transaction": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "direction": { "type": "string", "enum": [ "in", "out", "internal" ] }, "from": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } }, "required": [ "name", "address" ] }, "to": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } }, "required": [ "name", "address" ] }, "amount": { "type": "string" }, "asset": { "type": "string" }, "fee": { "type": [ "string", "null" ] }, "fee_asset": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "tx_hash": { "type": [ "string", "null" ] }, "network": { "type": [ "string", "null" ] }, "network_name": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] } }, "required": [ "id", "created_at", "direction", "from", "to", "amount", "asset", "fee", "fee_asset", "status", "tx_hash", "network", "network_name", "wallet_id" ] }, "Withdrawal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "received", "pending_approval", "approved", "processing", "completed", "rejected", "failed", "expired", "cancelled" ] }, "wallet_id": { "type": "string" }, "asset": { "type": [ "string", "null" ] }, "amount": { "type": [ "string", "null" ] }, "destination": { "type": [ "string", "null" ] }, "network": { "type": [ "string", "null" ] }, "tx_hash": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "wallet_id", "asset", "amount", "destination", "network", "tx_hash", "created_at", "updated_at" ] }, "WithdrawalRequest": { "type": "object", "properties": { "wallet_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "asset": { "type": "string", "minLength": 1, "maxLength": 24 }, "amount": { "type": "string", "maxLength": 100, "pattern": "^(?=.*[1-9])\\d+(\\.\\d+)?$", "description": "Positive decimal string in whole asset units, within the asset's decimal precision. Never a JSON number." }, "destination": { "type": "string", "minLength": 8, "maxLength": 128 }, "network": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Use the exact balance network. Required when asset is ambiguous; omission only resolves a single known-network balance." }, "fee_priority": { "type": "string", "enum": [ "low", "medium", "high" ] } }, "required": [ "wallet_id", "asset", "amount", "destination" ], "additionalProperties": false }, "Counterparty": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "network": { "type": "string" }, "network_name": { "type": "string" }, "address": { "type": "string" }, "direction": { "type": "string" }, "status": { "type": "string" }, "can_send": { "type": "boolean" }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "counterparty_type": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "wallet_type": { "type": "string" }, "vasp_name": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "label", "network", "network_name", "address", "direction", "status", "can_send", "verified_at", "counterparty_type", "first_name", "last_name", "company_name", "wallet_type", "vasp_name", "country", "created_at" ] }, "CounterpartyRequest": { "type": "object", "properties": { "network": { "type": "string", "minLength": 1, "maxLength": 128 }, "address": { "type": "string", "minLength": 1, "maxLength": 128 }, "counterparty_type": { "type": "string", "enum": [ "individual", "company" ] }, "first_name": { "type": "string", "maxLength": 120 }, "last_name": { "type": "string", "maxLength": 120 }, "company_name": { "type": "string", "maxLength": 120 }, "wallet_type": { "type": "string", "enum": [ "vasp", "unhosted" ] }, "vasp_name": { "type": "string", "maxLength": 120 }, "country": { "type": "string", "minLength": 2, "maxLength": 2 }, "label": { "type": "string", "maxLength": 120 }, "direction": { "type": "string", "enum": [ "send", "both" ], "default": "send" } }, "required": [ "network", "address", "counterparty_type", "wallet_type", "country" ], "additionalProperties": false, "description": "Individual: first_name and last_name required. Company: company_name required. Hosted wallet: vasp_name required. Country must be a supported two-letter code. New entries are pending and require console verification." }, "Deposit": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed" ] }, "wallet_id": { "type": "string" }, "asset": { "type": [ "string", "null" ] }, "amount": { "type": "string" }, "from_address": { "type": [ "string", "null" ] }, "tx_hash": { "type": [ "string", "null" ] }, "received_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "status", "wallet_id", "asset", "amount", "from_address", "tx_hash", "received_at" ] }, "WalletResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Wallet" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "next_offset": { "type": [ "integer", "null" ] }, "idempotent_replay": { "type": "boolean" }, "already_exists": { "type": "boolean" }, "stale": { "type": "boolean" } }, "required": [], "additionalProperties": true } }, "required": [ "data", "meta" ] }, "WalletListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Wallet" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "next_offset": { "type": [ "integer", "null" ] }, "idempotent_replay": { "type": "boolean" }, "already_exists": { "type": "boolean" }, "stale": { "type": "boolean" } }, "required": [], "additionalProperties": true } }, "required": [ "data", "meta" ] }, "TransactionResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Transaction" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "next_offset": { "type": [ "integer", "null" ] }, "idempotent_replay": { "type": "boolean" }, "already_exists": { "type": "boolean" }, "stale": { "type": "boolean" } }, "required": [], "additionalProperties": true } }, "required": [ "data", "meta" ] }, "TransactionListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "limit": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass back as cursor for the next, older page. null on the last page." }, "offset": { "type": "integer" }, "next_offset": { "type": [ "integer", "null" ] }, "idempotent_replay": { "type": "boolean" }, "already_exists": { "type": "boolean" }, "stale": { "type": "boolean" } }, "required": [], "additionalProperties": true } }, "required": [ "data", "meta" ] }, "WithdrawalResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Withdrawal" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "next_offset": { "type": [ "integer", "null" ] }, "idempotent_replay": { "type": "boolean" }, "already_exists": { "type": "boolean" }, "stale": { "type": "boolean" } }, "required": [], "additionalProperties": true } }, "required": [ "data", "meta" ] }, "WithdrawalListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Withdrawal" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "next_offset": { "type": [ "integer", "null" ] }, "idempotent_replay": { "type": "boolean" }, "already_exists": { "type": "boolean" }, "stale": { "type": "boolean" } }, "required": [], "additionalProperties": true } }, "required": [ "data", "meta" ] }, "CounterpartyResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Counterparty" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "next_offset": { "type": [ "integer", "null" ] }, "idempotent_replay": { "type": "boolean" }, "already_exists": { "type": "boolean" }, "stale": { "type": "boolean" } }, "required": [], "additionalProperties": true } }, "required": [ "data", "meta" ] }, "CounterpartyListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Counterparty" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "next_offset": { "type": [ "integer", "null" ] }, "idempotent_replay": { "type": "boolean" }, "already_exists": { "type": "boolean" }, "stale": { "type": "boolean" } }, "required": [], "additionalProperties": true } }, "required": [ "data", "meta" ] }, "WithdrawalEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event ID; durably deduplicate before applying effects." }, "type": { "type": "string", "enum": [ "withdrawal.status_changed" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Withdrawal" } }, "required": [ "id", "type", "created_at", "data" ] }, "DepositReceivedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event ID; durably deduplicate before applying effects." }, "type": { "type": "string", "enum": [ "deposit.received" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Deposit" } }, "required": [ "id", "type", "created_at", "data" ] }, "DepositCompletedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event ID; durably deduplicate before applying effects." }, "type": { "type": "string", "enum": [ "deposit.completed" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Deposit" } }, "required": [ "id", "type", "created_at", "data" ] } } }, "webhooks": { "clientEvent": { "post": { "summary": "Delivery to your registered HTTPS receiver", "security": [], "parameters": [ { "name": "x-webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "x-webhook-signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } ], "description": "Verify raw bytes with the endpoint secret: HMAC-SHA256(timestamp + '.' + raw body), ±5 minutes. Durably deduplicate event.id. Deliveries may be delayed, duplicated and out of order; up to eight attempts. Respond within 10 seconds after durably accepting the event.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WithdrawalEvent" }, { "$ref": "#/components/schemas/DepositReceivedEvent" }, { "$ref": "#/components/schemas/DepositCompletedEvent" } ] } } } }, "responses": { "200": { "description": "Event durably accepted" }, "204": { "description": "Event durably accepted" } } } } } }