{ "openapi": "3.0.3", "info": { "title": "Bitnob API v2", "version": "2.0.0", "description": "# Bitnob API v2\n\nA single, ready-to-use collection for the Bitnob Core API v2 — balances, payouts, cards, trading, lightning, bulk transfers and more.\n\n## Quick start\n\n1. Set the collection variables:\n - `base_url` — e.g. `https://api.bitnob.com`\n - `client_id` — your workspace client id\n - `client_secret` — your workspace client secret\n2. Run any request. The **collection-level pre-request script** automatically:\n - generates a fresh `timestamp` + `nonce`,\n - canonicalises the JSON body (compact form),\n - computes `HmacSHA256(client_id:timestamp:nonce:body, client_secret)`, and\n - injects `X-Auth-Client`, `X-Auth-Timestamp`, `X-Auth-Nonce`, `X-Auth-Signature`.\n\nYou never modify headers manually — just edit the body and hit send.\n\n## Conventions\n\n- **Amounts** are in *base units* (whole integers, no decimals). For USDT that's `1 USDT = 1_000_000` units. For BTC that's sats.\n- **`memo`** is only meaningful for chains that require a destination tag (e.g. Stellar). Omit it for Tron/Ethereum.\n- **`reference`** is caller-supplied and should be unique per action for safe retries / idempotency.\n- Most error responses follow RFC 7807 (`type`, `title`, `status`, `detail`, `correlation_id`, `timestamp`).\n\n## Folders\n\nEvery resource lives in its own folder. Happy-path requests come first, followed by list/filter endpoints, then action endpoints (`confirm`, `retry`, `cancel`, etc.).", "contact": { "name": "Bitnob", "url": "https://bitnob.com" }, "license": { "name": "Proprietary", "url": "https://bitnob.com/terms" } }, "servers": [ { "url": "https://api.bitnob.com", "description": "Production" } ], "security": [ { "BitnobHmacAuth": [] } ], "tags": [ { "name": "Identity", "description": "Authentication probe for verifying workspace credentials." }, { "name": "Balances", "description": "Wallet balances per currency for the authenticated workspace." }, { "name": "Addresses", "description": "On-chain deposit addresses for receiving crypto." }, { "name": "Withdrawals", "description": "On-chain withdrawals from workspace balance to an external wallet address." }, { "name": "Transactions", "description": "Unified transaction history across all movement types." }, { "name": "Exchange rates", "description": "Point-in-time conversion rates between supported currencies." }, { "name": "Trading", "description": "Spot trading: quotes, orders, scheduled DCA, and target (limit-style) orders." }, { "name": "Bulk transfers", "description": "Batched disbursements from CSV or inline items, with optional recurring schedules." }, { "name": "Cards", "description": "Virtual and physical card issuance, funding, controls, and transactions. Amounts are in base units of `currency` (e.g. USD cents × 100 for `USD` cards)." }, { "name": "Lightning", "description": "Bitcoin Lightning invoices and payments." }, { "name": "Customers", "description": "Customer lifecycle + KYC geography helpers." }, { "name": "Beneficiaries", "description": "Saved crypto and fiat payout recipients." }, { "name": "Payouts", "description": "Fiat payouts to bank accounts and mobile money across supported countries. Flow: **quote → initialize → finalize**." } ], "paths": { "/api/whoami": { "get": { "tags": [ "Identity" ], "summary": "Who am I", "description": "Returns the workspace identity associated with the presented HMAC credentials. Useful as a first call to confirm keys, clock skew, and signature formula are all correct.", "operationId": "get_api_whoami", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/balances": { "get": { "tags": [ "Balances" ], "summary": "List balances", "description": "Returns a paginated balance snapshot per currency. Use it to display wallet balances or reconcile holdings.", "operationId": "get_api_balances", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/balances/{currency}": { "get": { "tags": [ "Balances" ], "summary": "Get balance by currency", "description": "Single-currency balance (e.g. `USDT`, `BTC`, `USDC`). 404 if the workspace holds no wallet for that currency.", "operationId": "get_api_balances_currency", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "currency identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/addresses": { "post": { "tags": [ "Addresses" ], "summary": "Generate address", "description": "Provisions a deposit address for the given `chain`. Labels / references are caller metadata — they don't affect the wallet.", "operationId": "post_api_addresses", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "example": "ethereum" }, "customer_id": { "type": "string", "example": "cust_abc123" }, "customer_email": { "type": "string", "example": "john@example.com" }, "label": { "type": "string", "example": "USDT deposit address" }, "reference": { "type": "string", "example": "ref-addr-001" } }, "required": [ "chain", "customer_id", "customer_email", "label", "reference" ] }, "example": { "chain": "ethereum", "customer_id": "cust_abc123", "customer_email": "john@example.com", "label": "USDT deposit address", "reference": "ref-addr-001" } } } } }, "get": { "tags": [ "Addresses" ], "summary": "List addresses", "description": "Paginated list of all provisioned addresses across the workspace.", "operationId": "get_api_addresses", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/addresses/{id}": { "get": { "tags": [ "Addresses" ], "summary": "Get address by id", "description": "Single address by internal id. Useful when reconciling deposits back to a specific address record.", "operationId": "get_api_addresses_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/addresses/validate": { "post": { "tags": [ "Addresses" ], "summary": "Validate address", "description": "Structural validation for an external address + chain pair. Returns `{valid: true|false}`; does not verify on-chain existence.", "operationId": "post_api_addresses_validate", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "example": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b" }, "chain": { "type": "string", "example": "ethereum" } }, "required": [ "address", "chain" ] }, "example": { "address": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b", "chain": "ethereum" } } } } } }, "/api/addresses/supported-chains": { "get": { "tags": [ "Addresses" ], "summary": "Supported chains", "description": "Chains accepted by the address endpoints, including display names and precision.", "operationId": "get_api_addresses_supported_chains", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/withdrawals": { "post": { "tags": [ "Withdrawals" ], "summary": "Initiate withdrawal", "description": "Debits the workspace balance and broadcasts a transfer. `amount` is in base units (whole integer). `memo` only applies to chains requiring a destination tag (e.g. Stellar).", "operationId": "post_api_withdrawals", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to_address": { "type": "string", "example": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b" }, "amount": { "type": "string", "example": "150500000" }, "currency": { "type": "string", "example": "USDT" }, "chain": { "type": "string", "example": "ethereum" }, "reference": { "type": "string", "example": "withdraw-ref-001" }, "description": { "type": "string", "example": "Vendor payment" } }, "required": [ "to_address", "amount", "currency", "chain", "reference", "description" ] }, "example": { "to_address": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b", "amount": "150500000", "currency": "USDT", "chain": "ethereum", "reference": "withdraw-ref-001", "description": "Vendor payment" } } } } } }, "/api/transactions": { "get": { "tags": [ "Transactions" ], "summary": "List transactions", "description": "Retrieves a paginated list of transactions, with support for filtering via query parameters. Commonly used to list transaction histories, audit flows, or search for specific transactions across various dimensions.", "operationId": "get_api_transactions", "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "example": "completed" }, "description": "" }, { "name": "ascending", "in": "query", "required": false, "schema": { "type": "string", "example": "true" }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string", "example": "50" }, "description": "" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/transactions/{id}": { "get": { "tags": [ "Transactions" ], "summary": "Get transaction by id", "description": "Single transaction envelope with full lifecycle metadata.", "operationId": "get_api_transactions_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/exchange-rates": { "get": { "tags": [ "Exchange rates" ], "summary": "Get single-pair rate", "description": "Mid-market rate for `from`→`to`.", "operationId": "get_api_exchange_rates", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "example": "USDT" }, "description": "" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "example": "NGN" }, "description": "" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/exchange-rates/convert": { "get": { "tags": [ "Exchange rates" ], "summary": "Convert amount", "description": "Applies the current rate to `amount` (in `from` display units) and returns the converted value + effective rate.", "operationId": "get_api_exchange_rates_convert", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "example": "USDT" }, "description": "" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "example": "NGN" }, "description": "" }, { "name": "amount", "in": "query", "required": true, "schema": { "type": "string", "example": "100" }, "description": "" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/trading/prices": { "get": { "tags": [ "Trading" ], "summary": "List all prices", "description": "Returns every available pair with its current mid-price.", "operationId": "get_api_trading_prices", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/trading/prices/{pair}": { "get": { "tags": [ "Trading" ], "summary": "Get price by pair", "description": "Spot price for a single pair (e.g. `BTCUSD`, `ETHUSD`).", "operationId": "get_api_trading_prices_pair", "parameters": [ { "name": "pair", "in": "path", "required": true, "schema": { "type": "string" }, "description": "pair identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/trading/quotes": { "post": { "tags": [ "Trading" ], "summary": "Create quote", "description": "Requests a locked quote for a BUY or SELL. The returned `quote_id` must be submitted with a matching order before it expires.", "operationId": "post_api_trading_quotes", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "base_currency": { "type": "string", "example": "BTC" }, "quote_currency": { "type": "string", "example": "USDT" }, "side": { "type": "string", "example": "BUY" }, "quantity": { "type": "string", "example": "0.05" }, "quantity_in_base_units": { "type": "boolean" } }, "required": [ "base_currency", "quote_currency", "side", "quantity" ] }, "example": { "base_currency": "BTC", "quote_currency": "USDT", "side": "BUY", "quantity": "0.05", "quantity_in_base_units": false } } } } } }, "/api/trading/quotes/{id}": { "get": { "tags": [ "Trading" ], "summary": "Get quote status", "description": "Check remaining TTL and fulfilment state for an outstanding quote.", "operationId": "get_api_trading_quotes_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/trading/orders": { "post": { "tags": [ "Trading" ], "summary": "Submit order", "description": "Execute a BUY or SELL. Supply the `quote_id` from a fresh quote for best pricing.", "operationId": "post_api_trading_orders", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "base_currency": { "type": "string", "example": "BTC" }, "quote_currency": { "type": "string", "example": "USDT" }, "side": { "type": "string", "example": "BUY" }, "quantity": { "type": "string", "example": "0.05" }, "quote_id": { "type": "string", "example": "{{quote_id}}" }, "reference": { "type": "string", "example": "order-ref-001" } }, "required": [ "base_currency", "quote_currency", "side", "quantity", "quote_id", "reference" ] }, "example": { "base_currency": "BTC", "quote_currency": "USDT", "side": "BUY", "quantity": "0.05", "quote_id": "{{quote_id}}", "reference": "order-ref-001" } } } } }, "get": { "tags": [ "Trading" ], "summary": "List orders", "description": "Paginated order history with optional filters.", "operationId": "get_api_trading_orders", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "example": "filled" }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string", "example": "50" }, "description": "" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/trading/orders/{id}": { "get": { "tags": [ "Trading" ], "summary": "Get order by id or reference", "description": "Fetch an individual order by its id or your supplied reference.", "operationId": "get_api_trading_orders_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/trading/scheduled-orders": { "post": { "tags": [ "Trading" ], "summary": "Create scheduled order", "description": "Creates a recurring buy/sell on a `daily`, `weekly`, or `monthly` cadence.", "operationId": "post_api_trading_scheduled_orders", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "example": "BTC" }, "quote_currency": { "type": "string", "example": "USDT" }, "amount": { "type": "string", "example": "50000000" }, "frequency": { "type": "string", "example": "weekly" }, "day_of_week": { "type": "integer" }, "execution_time": { "type": "string", "example": "09:00" }, "reference": { "type": "string", "example": "dca-ref-001" } }, "required": [ "currency", "quote_currency", "amount", "frequency", "day_of_week", "execution_time", "reference" ] }, "example": { "currency": "BTC", "quote_currency": "USDT", "amount": "50000000", "frequency": "weekly", "day_of_week": 1, "execution_time": "09:00", "reference": "dca-ref-001" } } } } }, "get": { "tags": [ "Trading" ], "summary": "List scheduled orders", "description": "All scheduled orders for the workspace.", "operationId": "get_api_trading_scheduled_orders", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/trading/scheduled-orders/{id}": { "get": { "tags": [ "Trading" ], "summary": "Get scheduled order", "description": "Details for a single recurring order.", "operationId": "get_api_trading_scheduled_orders_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Trading" ], "summary": "Update scheduled order", "description": "Mutate amount, cadence, or status. Pass `status: paused` to halt future executions without cancelling.", "operationId": "put_api_trading_scheduled_orders_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "example": "200000000" }, "status": { "type": "string", "example": "paused" }, "execution_time": { "type": "string", "example": "10:00" } }, "required": [ "amount", "status", "execution_time" ] }, "example": { "amount": "200000000", "status": "paused", "execution_time": "10:00" } } } } } }, "/api/trading/scheduled-orders/{id}/executions": { "get": { "tags": [ "Trading" ], "summary": "List scheduled-order executions", "description": "Execution log for a scheduled order.", "operationId": "get_api_trading_scheduled_orders_id_executions", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/trading/target-orders": { "post": { "tags": [ "Trading" ], "summary": "Create target order", "description": "Creates a target order that fires when `target_price` is met. Optionally set `expires_at` to auto-cancel.", "operationId": "post_api_trading_target_orders", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "base_currency": { "type": "string", "example": "BTC" }, "quote_currency": { "type": "string", "example": "USDT" }, "side": { "type": "string", "example": "BUY" }, "quantity": { "type": "string", "example": "0.10" }, "target_price": { "type": "string", "example": "60000.00" }, "expires_at": { "type": "string", "example": "" }, "reference": { "type": "string", "example": "target-ref-001" } }, "required": [ "base_currency", "quote_currency", "side", "quantity", "target_price", "reference" ] }, "example": { "base_currency": "BTC", "quote_currency": "USDT", "side": "BUY", "quantity": "0.10", "target_price": "60000.00", "expires_at": "", "reference": "target-ref-001" } } } } }, "get": { "tags": [ "Trading" ], "summary": "List target orders", "description": "All target orders, filterable by status.", "operationId": "get_api_trading_target_orders", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/trading/target-orders/{id}": { "get": { "tags": [ "Trading" ], "summary": "Get target order", "description": "Details for a single target order.", "operationId": "get_api_trading_target_orders_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/bulk-transfers": { "post": { "tags": [ "Bulk transfers" ], "summary": "Create draft batch", "description": "Creates a draft with inline items. Amounts are in base units.", "operationId": "post_api_bulk_transfers", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "example": "March payroll batch" }, "items": { "type": "array", "items": { "type": "object", "properties": { "row_index": { "type": "integer" }, "chain": { "type": "string", "example": "ethereum" }, "currency": { "type": "string", "example": "USDT" }, "address": { "type": "string", "example": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b" }, "amount": { "type": "string", "example": "100000000" }, "reference": { "type": "string", "example": "bulk-item-1" } }, "required": [ "row_index", "chain", "currency", "address", "amount", "reference" ] } } }, "required": [ "description", "items" ] }, "example": { "description": "March payroll batch", "items": [ { "row_index": 1, "chain": "ethereum", "currency": "USDT", "address": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b", "amount": "100000000", "reference": "bulk-item-1" } ] } } } } }, "get": { "tags": [ "Bulk transfers" ], "summary": "List batches", "description": "Paginated batch history.", "operationId": "get_api_bulk_transfers", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/bulk-transfers/upload-urls": { "post": { "tags": [ "Bulk transfers" ], "summary": "Get upload URL (S3 presigned)", "description": "Returns a presigned PUT URL for uploading a CSV. Upload directly to S3, then call **Preview uploaded file** with the returned `upload_id`.", "operationId": "post_api_bulk_transfers_upload_urls", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "example": "payroll.csv" } }, "required": [ "filename" ] }, "example": { "filename": "payroll.csv" } } } } } }, "/api/bulk-transfers/previews": { "post": { "tags": [ "Bulk transfers" ], "summary": "Preview uploaded file", "description": "Parses and validates the uploaded CSV, returning row-level status before confirmation.", "operationId": "post_api_bulk_transfers_previews", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "upload_id": { "type": "string", "example": "{{upload_id}}" } }, "required": [ "upload_id" ] }, "example": { "upload_id": "{{upload_id}}" } } } } } }, "/api/bulk-transfers/{batchId}": { "get": { "tags": [ "Bulk transfers" ], "summary": "Get batch", "description": "Single batch with per-item status.", "operationId": "get_api_bulk_transfers_batchId", "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "batchId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/bulk-transfers/{batchId}/confirm": { "post": { "tags": [ "Bulk transfers" ], "summary": "Confirm batch", "description": "Promotes a draft batch to execution. Irreversible — funds are debited.", "operationId": "post_api_bulk_transfers_batchId_confirm", "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "batchId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } } } }, "/api/bulk-transfers/{batchId}/retry": { "post": { "tags": [ "Bulk transfers" ], "summary": "Retry failed items", "description": "Retries only the listed item ids within a partially-failed batch.", "operationId": "post_api_bulk_transfers_batchId_retry", "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "batchId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "item_ids": { "type": "array", "items": { "type": "string", "example": "item-uuid-1" } } }, "required": [ "item_ids" ] }, "example": { "item_ids": [ "item-uuid-1", "item-uuid-2" ] } } } } } }, "/api/bulk-transfers/schedules": { "post": { "tags": [ "Bulk transfers" ], "summary": "Create schedule", "description": "Clones `template_batch_id` on the given cadence. Leave `end_date` empty for open-ended.", "operationId": "post_api_bulk_transfers_schedules", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "template_batch_id": { "type": "string", "example": "batch_template_1" }, "frequency": { "type": "string", "example": "weekly" }, "execution_time": { "type": "string", "example": "09:00" }, "day_of_week": { "type": "integer" }, "day_of_month": { "type": "integer" }, "start_date": { "type": "string", "format": "date", "example": "2026-05-01" }, "end_date": { "type": "string", "example": "" } }, "required": [ "template_batch_id", "frequency", "execution_time", "day_of_week", "start_date" ] }, "example": { "template_batch_id": "batch_template_1", "frequency": "weekly", "execution_time": "09:00", "day_of_week": 1, "day_of_month": 0, "start_date": "2026-05-01", "end_date": "" } } } } }, "get": { "tags": [ "Bulk transfers" ], "summary": "List schedules", "description": "All active and paused schedules.", "operationId": "get_api_bulk_transfers_schedules", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/bulk-transfers/schedules/{scheduleId}": { "put": { "tags": [ "Bulk transfers" ], "summary": "Update schedule", "description": "Mutate cadence, execution window, or pause/resume via `status`.", "operationId": "put_api_bulk_transfers_schedules_scheduleId", "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "scheduleId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "paused" }, "execution_time": { "type": "string", "example": "10:00" }, "day_of_week": { "type": "integer" }, "day_of_month": { "type": "integer" }, "end_date": { "type": "string", "example": "" } }, "required": [ "status", "execution_time", "day_of_week" ] }, "example": { "status": "paused", "execution_time": "10:00", "day_of_week": 1, "day_of_month": 0, "end_date": "" } } } } } }, "/api/bulk-transfers/schedules/{scheduleId}/executions": { "get": { "tags": [ "Bulk transfers" ], "summary": "List schedule executions", "description": "Execution history for a schedule. Each execution resolves to a concrete batch id.", "operationId": "get_api_bulk_transfers_schedules_scheduleId_executions", "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "scheduleId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/bulk-transfers/executions/{executionId}/retry": { "post": { "tags": [ "Bulk transfers" ], "summary": "Retry failed execution", "description": "Retries an execution that failed partway. No-op if already completed.", "operationId": "post_api_bulk_transfers_executions_executionId_retry", "parameters": [ { "name": "executionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "executionId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } } } }, "/api/cards": { "post": { "tags": [ "Cards" ], "summary": "Create card (embedded customer)", "description": "Issues a new card and creates the customer in the same call. For existing customers, pass `customer_id` instead of the nested `customer` block.", "operationId": "post_api_cards", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "card_type": { "type": "string", "example": "virtual" }, "name": { "type": "string", "example": "Ifeoma Okafor" }, "currency": { "type": "string", "example": "USD" }, "amount": { "type": "integer" }, "webhook_url": { "type": "string", "format": "uri", "example": "https://example.com/webhooks/cards" }, "created_by": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "contactless_payment": { "type": "boolean" }, "customer": { "type": "object", "properties": { "customer_type": { "type": "string", "example": "individual" }, "first_name": { "type": "string", "example": "Ifeoma" }, "last_name": { "type": "string", "example": "Okafor" }, "date_of_birth": { "type": "string", "format": "date", "example": "1993-07-08" }, "id_type": { "type": "string", "example": "national_id" }, "id_number": { "type": "string", "example": "NIN12345678901" }, "email": { "type": "string", "example": "ifeoma.okafor@example.com" }, "phone_number": { "type": "string", "example": "8034567890" }, "dial_code": { "type": "string", "example": "+234" }, "line1": { "type": "string", "example": "18 Wuse Zone 4" }, "city": { "type": "string", "example": "Abuja" }, "state": { "type": "string", "example": "FCT" }, "postal_code": { "type": "string", "example": "900271" }, "country": { "type": "string", "example": "NGA" } }, "required": [ "customer_type", "first_name", "last_name", "date_of_birth", "id_type", "id_number", "email", "phone_number", "dial_code", "line1", "city", "state", "postal_code", "country" ] }, "card_limits": { "type": "object", "properties": { "single_transaction": { "type": "string", "example": "1000.00" }, "daily": { "type": "string", "example": "5000.00" }, "weekly": { "type": "string", "example": "20000.00" }, "monthly": { "type": "string", "example": "50000.00" } }, "required": [ "single_transaction", "daily", "weekly", "monthly" ] } }, "required": [ "card_type", "name", "currency", "amount", "webhook_url", "created_by", "contactless_payment", "customer", "card_limits" ] }, "example": { "card_type": "virtual", "name": "Ifeoma Okafor", "currency": "USD", "amount": 5000000, "webhook_url": "https://example.com/webhooks/cards", "created_by": "550e8400-e29b-41d4-a716-446655440000", "contactless_payment": true, "customer": { "customer_type": "individual", "first_name": "Ifeoma", "last_name": "Okafor", "date_of_birth": "1993-07-08", "id_type": "national_id", "id_number": "NIN12345678901", "email": "ifeoma.okafor@example.com", "phone_number": "8034567890", "dial_code": "+234", "line1": "18 Wuse Zone 4", "city": "Abuja", "state": "FCT", "postal_code": "900271", "country": "NGA" }, "card_limits": { "single_transaction": "1000.00", "daily": "5000.00", "weekly": "20000.00", "monthly": "50000.00" } } } } } }, "get": { "tags": [ "Cards" ], "summary": "List cards", "description": "Paginated card inventory for the workspace.", "operationId": "get_api_cards", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cards/encryption-key": { "post": { "tags": [ "Cards" ], "summary": "Register encryption key", "description": "Registers a workspace-wide public key. Secure-details endpoints return card PAN/CVV encrypted with this key.", "operationId": "post_api_cards_encryption_key", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "public_key_pem": { "type": "string", "example": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----" } }, "required": [ "public_key_pem" ] }, "example": { "public_key_pem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----" } } } } } }, "/api/cards/team-members": { "get": { "tags": [ "Cards" ], "summary": "List team-member cards", "description": "Cards owned by workspace team members (distinct from customer-issued cards).", "operationId": "get_api_cards_team_members", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cards/transactions": { "get": { "tags": [ "Cards" ], "summary": "List all card transactions", "description": "Workspace-wide card transaction feed across every card.", "operationId": "get_api_cards_transactions", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cards/{cardId}": { "get": { "tags": [ "Cards" ], "summary": "Get card", "description": "Card metadata (masked PAN, status, balances, limits).", "operationId": "get_api_cards_cardId", "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "cardId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Cards" ], "summary": "Terminate card", "description": "Permanently terminates the card. Remaining balance sweeps back to the workspace wallet.", "operationId": "delete_api_cards_cardId", "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "cardId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "example": "Card no longer needed" } }, "required": [ "reason" ] }, "example": { "reason": "Card no longer needed" } } } } } }, "/api/cards/{cardId}/secure": { "get": { "tags": [ "Cards" ], "summary": "Get secure card details", "description": "Full PAN/CVV/expiry encrypted with the workspace public key registered via **Register encryption key**.", "operationId": "get_api_cards_cardId_secure", "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "cardId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cards/{cardId}/transactions": { "get": { "tags": [ "Cards" ], "summary": "List card transactions (by card)", "description": "Transactions scoped to one card.", "operationId": "get_api_cards_cardId_transactions", "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "cardId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cards/{cardId}/transactions/{transactionId}": { "get": { "tags": [ "Cards" ], "summary": "Get single card transaction", "description": "Single transaction with clearing, settlement, and dispute metadata.", "operationId": "get_api_cards_cardId_transactions_transactionId", "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "cardId identifier" }, { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "transactionId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cards/{cardId}/balance": { "post": { "tags": [ "Cards" ], "summary": "Fund or withdraw balance", "description": "`type: fund` debits the workspace balance and credits the card. `type: withdraw` reverses it. `amount` is in base units of the card currency.", "operationId": "post_api_cards_cardId_balance", "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "cardId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "fund" }, "amount": { "type": "integer" }, "reference": { "type": "string", "example": "fund-ref-001" } }, "required": [ "type", "amount", "reference" ] }, "example": { "type": "fund", "amount": 5000000, "reference": "fund-ref-001" } } } } } }, "/api/cards/{cardId}/status": { "post": { "tags": [ "Cards" ], "summary": "Freeze or unfreeze", "description": "Set `status: frozen` to block authorisations, `status: active` to resume.", "operationId": "post_api_cards_cardId_status", "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "cardId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "frozen" } }, "required": [ "status" ] }, "example": { "status": "frozen" } } } } } }, "/api/cards/{cardId}/spend-limits": { "put": { "tags": [ "Cards" ], "summary": "Update spend limits", "description": "Mutate transaction/daily/weekly/monthly/yearly/all-time limits. Values in base units.", "operationId": "put_api_cards_cardId_spend_limits", "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "cardId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spending_limits": { "type": "object", "properties": { "transaction_limit": { "type": "integer" }, "daily_limit": { "type": "integer" }, "weekly_limit": { "type": "integer" }, "monthly_limit": { "type": "integer" }, "yearly_limit": { "type": "integer" }, "all_time_limit": { "type": "integer" } }, "required": [ "transaction_limit", "daily_limit", "weekly_limit", "monthly_limit", "yearly_limit" ] } }, "required": [ "spending_limits" ] }, "example": { "spending_limits": { "transaction_limit": 10000000, "daily_limit": 50000000, "weekly_limit": 200000000, "monthly_limit": 500000000, "yearly_limit": 6000000000, "all_time_limit": 0 } } } } } } }, "/api/lightning/invoices": { "post": { "tags": [ "Lightning" ], "summary": "Create invoice", "description": "Issues a BOLT11 invoice for the given customer. Amount is in satoshis.", "operationId": "post_api_lightning_invoices", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "example": "cust_abc123" }, "amount": { "type": "integer" }, "description": { "type": "string", "example": "Payment for invoice #1234" }, "expiry": { "type": "integer" }, "reference": { "type": "string", "example": "ln-inv-001" } }, "required": [ "customer_id", "amount", "description", "expiry", "reference" ] }, "example": { "customer_id": "cust_abc123", "amount": 50000, "description": "Payment for invoice #1234", "expiry": 3600, "reference": "ln-inv-001" } } } } }, "get": { "tags": [ "Lightning" ], "summary": "List invoices", "description": "Invoice history with filters.", "operationId": "get_api_lightning_invoices", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/lightning/invoices/{id}": { "get": { "tags": [ "Lightning" ], "summary": "Get invoice", "description": "Invoice by id, including payment status.", "operationId": "get_api_lightning_invoices_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/lightning/decode": { "post": { "tags": [ "Lightning" ], "summary": "Decode BOLT11", "description": "Structurally decodes a BOLT11 string into amount, expiry, description, routing hints, etc. Does not initiate payment.", "operationId": "post_api_lightning_decode", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "string", "example": "lnbc500u1pj9qk7pp5..." } }, "required": [ "request" ] }, "example": { "request": "lnbc500u1pj9qk7pp5..." } } } } } }, "/api/lightning/preview": { "post": { "tags": [ "Lightning" ], "summary": "Preview payment", "description": "Simulates routing and fee discovery for a BOLT11 without actually paying. Returns estimated fees + path.", "operationId": "post_api_lightning_preview", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "string", "example": "lnbc500u1pj9qk7pp5..." } }, "required": [ "request" ] }, "example": { "request": "lnbc500u1pj9qk7pp5..." } } } } } }, "/api/lightning/pay": { "post": { "tags": [ "Lightning" ], "summary": "Send payment", "description": "Pays a BOLT11. Bounded by `max_fee` (sats). Idempotent on `reference`.", "operationId": "post_api_lightning_pay", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "example": "cust_abc123" }, "request": { "type": "string", "example": "lnbc500u1pj9qk7pp5..." }, "reference": { "type": "string", "example": "ln-pay-001" }, "max_fee": { "type": "integer" } }, "required": [ "customer_id", "request", "reference", "max_fee" ] }, "example": { "customer_id": "cust_abc123", "request": "lnbc500u1pj9qk7pp5...", "reference": "ln-pay-001", "max_fee": 1000 } } } } } }, "/api/customers/countries": { "get": { "tags": [ "Customers" ], "summary": "List countries", "description": "Countries accepted for customer registration.", "operationId": "get_api_customers_countries", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/customers/countries/{countryCode}/states": { "get": { "tags": [ "Customers" ], "summary": "List states for country", "description": "State / province list for a country. Used to populate KYC address forms.", "operationId": "get_api_customers_countries_countryCode_states", "parameters": [ { "name": "countryCode", "in": "path", "required": true, "schema": { "type": "string" }, "description": "countryCode identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/customers": { "post": { "tags": [ "Customers" ], "summary": "Create customer", "description": "Create a customer record. KYC fields (`id_type`, `id_number`) are required for card issuance in most regions.", "operationId": "post_api_customers", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "example": "alice@example.com" }, "customer_type": { "type": "string", "example": "individual" }, "first_name": { "type": "string", "example": "Alice" }, "last_name": { "type": "string", "example": "Johnson" }, "date_of_birth": { "type": "string", "format": "date", "example": "1990-05-15" }, "id_type": { "type": "string", "example": "passport" }, "id_number": { "type": "string", "example": "A12345678" }, "country": { "type": "string", "example": "USA" } }, "required": [ "email", "customer_type", "first_name", "last_name", "date_of_birth", "id_type", "id_number", "country" ] }, "example": { "email": "alice@example.com", "customer_type": "individual", "first_name": "Alice", "last_name": "Johnson", "date_of_birth": "1990-05-15", "id_type": "passport", "id_number": "A12345678", "country": "USA" } } } } }, "get": { "tags": [ "Customers" ], "summary": "List customers", "description": "Paginated customers.", "operationId": "get_api_customers", "parameters": [ { "name": "first_name", "in": "query", "required": false, "schema": { "type": "string", "example": "alice" }, "description": "" }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/customers/{customerId}": { "get": { "tags": [ "Customers" ], "summary": "Get customer", "description": "Single customer with KYC status.", "operationId": "get_api_customers_customerId", "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "customerId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Customers" ], "summary": "Update customer", "description": "Mutate customer fields or toggle active status.", "operationId": "put_api_customers_customerId", "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "customerId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "example": "Alice" }, "last_name": { "type": "string", "example": "Smith" }, "is_active": { "type": "boolean" } }, "required": [ "first_name", "last_name", "is_active" ] }, "example": { "first_name": "Alice", "last_name": "Smith", "is_active": true } } } } } }, "/api/beneficiaries": { "post": { "tags": [ "Beneficiaries" ], "summary": "Create beneficiary", "description": "Save a recipient for reuse. Crypto beneficiaries require `wallet_address`, `currency`, and `network`.", "operationId": "post_api_beneficiaries", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Alice Ethereum Wallet" }, "type": { "type": "string", "example": "CRYPTO" }, "wallet_address": { "type": "string", "example": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b" }, "currency": { "type": "string", "example": "USDT" }, "network": { "type": "string", "example": "ethereum" } }, "required": [ "name", "type", "wallet_address", "currency", "network" ] }, "example": { "name": "Alice Ethereum Wallet", "type": "CRYPTO", "wallet_address": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b", "currency": "USDT", "network": "ethereum" } } } } }, "get": { "tags": [ "Beneficiaries" ], "summary": "List beneficiaries", "description": "Paginated list of saved recipients.", "operationId": "get_api_beneficiaries", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/beneficiaries/{beneficiaryId}": { "get": { "tags": [ "Beneficiaries" ], "summary": "Get beneficiary", "description": "Single beneficiary.", "operationId": "get_api_beneficiaries_beneficiaryId", "parameters": [ { "name": "beneficiaryId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "beneficiaryId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Beneficiaries" ], "summary": "Update beneficiary", "description": "Mutate name or active status.", "operationId": "put_api_beneficiaries_beneficiaryId", "parameters": [ { "name": "beneficiaryId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "beneficiaryId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Updated Wallet" }, "is_active": { "type": "boolean" } }, "required": [ "name", "is_active" ] }, "example": { "name": "Updated Wallet", "is_active": true } } } } } }, "/api/payouts/quotes": { "post": { "tags": [ "Payouts" ], "summary": "Create quote", "description": "Requests a rate + fee quote. Returns `quoteId` required by Initialize. Quotes expire quickly (seconds to minutes).", "operationId": "post_api_payouts_quotes", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_asset": { "type": "string", "example": "USDT" }, "to_currency": { "type": "string", "example": "NGN" }, "source": { "type": "string", "example": "offchain" }, "chain": { "type": "string", "example": "" }, "amount": { "type": "string", "example": "100000000" }, "payment_reason": { "type": "string", "example": "vendor_payment" }, "reference": { "type": "string", "example": "payout-ref-001" }, "country": { "type": "string", "example": "NG" } }, "required": [ "from_asset", "to_currency", "source", "amount", "payment_reason", "reference", "country" ] }, "example": { "from_asset": "USDT", "to_currency": "NGN", "source": "offchain", "chain": "", "amount": "100000000", "payment_reason": "vendor_payment", "reference": "payout-ref-001", "country": "NG" } } } } } }, "/api/payouts/{quoteId}/initialize": { "post": { "tags": [ "Payouts" ], "summary": "Initialize payout", "description": "Locks the quote and creates the payout intent with the beneficiary. The response includes an id used by Finalize.", "operationId": "post_api_payouts_quoteId_initialize", "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "quoteId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "example": "" }, "beneficiary": { "type": "object", "properties": { "type": { "type": "string", "example": "BANK" }, "accountNumber": { "type": "string", "example": "1421795566" }, "accountName": { "type": "string", "example": "CHIAMAKA JENNIFER EZEOBI" }, "bankCode": { "type": "string", "example": "000014" } }, "required": [ "type", "accountNumber", "accountName", "bankCode" ] }, "reference": { "type": "string", "example": "init-ref-001" }, "callback_url": { "type": "string", "format": "uri", "example": "https://example.com/webhooks/payouts" } }, "required": [ "beneficiary", "reference", "callback_url" ] }, "example": { "customer_id": "", "beneficiary": { "type": "BANK", "accountNumber": "1421795566", "accountName": "CHIAMAKA JENNIFER EZEOBI", "bankCode": "000014" }, "reference": "init-ref-001", "callback_url": "https://example.com/webhooks/payouts" } } } } } }, "/api/payouts/{quoteId}/finalize": { "post": { "tags": [ "Payouts" ], "summary": "Finalize payout", "description": "Commits the debit and releases the payout to the rails. Irreversible.", "operationId": "post_api_payouts_quoteId_finalize", "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "quoteId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } } } }, "/api/payouts/account-lookup": { "get": { "tags": [ "Payouts" ], "summary": "Account lookup", "description": "Name-resolves a bank account so the UI can show the account holder before the user confirms.", "operationId": "get_api_payouts_account_lookup", "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "example": "NG" }, "description": "" }, { "name": "bank_code", "in": "query", "required": true, "schema": { "type": "string", "example": "000014" }, "description": "" }, { "name": "account_number", "in": "query", "required": true, "schema": { "type": "string", "example": "1421795566" }, "description": "" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/payouts/supported-countries": { "get": { "tags": [ "Payouts" ], "summary": "Supported countries", "description": "Countries with live payout rails, including display metadata.", "operationId": "get_api_payouts_supported_countries", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/payouts/supported-countries/{country}": { "get": { "tags": [ "Payouts" ], "summary": "Country requirements", "description": "Per-country beneficiary-field requirements (which fields are required, their validation rules, etc.).", "operationId": "get_api_payouts_supported_countries_country", "parameters": [ { "name": "country", "in": "path", "required": true, "schema": { "type": "string" }, "description": "country identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/payouts/limits": { "get": { "tags": [ "Payouts" ], "summary": "Payout limits", "description": "Workspace-level min/max payout amounts per currency and per rail.", "operationId": "get_api_payouts_limits", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/payouts/banks/{countryCode}": { "get": { "tags": [ "Payouts" ], "summary": "Banks by country", "description": "Bank / mobile-money directory for a country. Use the returned `code` in Initialize's `bankCode`.", "operationId": "get_api_payouts_banks_countryCode", "parameters": [ { "name": "countryCode", "in": "path", "required": true, "schema": { "type": "string" }, "description": "countryCode identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/payouts": { "get": { "tags": [ "Payouts" ], "summary": "List payouts", "description": "Payout history with filters.", "operationId": "get_api_payouts", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string", "example": "50" }, "description": "" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/payouts/{id}": { "get": { "tags": [ "Payouts" ], "summary": "Get payout", "description": "Single payout, including lifecycle events and rail-specific metadata.", "operationId": "get_api_payouts_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "BitnobHmacAuth": { "type": "apiKey", "in": "header", "name": "X-Auth-Signature", "description": "HMAC-SHA256 authentication. All calls must include four headers:\n- `X-Auth-Client` — your workspace client id\n- `X-Auth-Timestamp` — Unix seconds\n- `X-Auth-Nonce` — 16-byte random hex\n- `X-Auth-Signature` — hex(HMAC-SHA256(\n `{client_id}:{timestamp}:{nonce}:{compact_json_body}`,\n client_secret))\n" } }, "schemas": { "Error": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "correlation_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } }, "example": { "type": "https://api.bitnob.com/errors/UNAUTHORIZED", "title": "Unauthorized", "status": 401, "detail": "Invalid HMAC signature", "code": "UNAUTHORIZED", "correlation_id": "req_019d9b7e-9e76-711e-afbe-aba9b9455412", "timestamp": "2026-04-17T12:50:59.850532036Z" } } } } }