{ "openapi": "3.1.0", "info": { "title": "Lumetrade API", "description": "Lumetrade API documentation.\n\nThe Lumetrade API gives third-party partners secure server-to-server access to Lumetrade\naccounts, wallets, currencies, beneficiaries, deposits, withdrawals, and trade data. Use this API\nto build operational dashboards, initiate supported money movement workflows, reconcile\ntransactions, and surface account or wallet information in your own internal systems.\n\nThis documentation describes the external `v1` API contract and the conventions your integration\nshould follow from its first request through production use.\n\n## Authentication and access\n\nAPI requests must include both `X-API-KEY` and `X-API-SECRET` headers. API keys are created\nthrough the authenticated user's API key management flow. The same user can revoke or rotate those\ncredentials when needed. Treat the API secret as a server-side credential only; never expose it in\nbrowser, mobile, or other client-side code.\n\nAuthentication and access failures are handled consistently across the external API:\n\n- `401` means the request could not be authenticated because API key headers are missing, invalid,\n revoked, or expired.\n- `403` means the request was authenticated, but the API key owner is not allowed to perform the\n action because of permissions, account state, or access rules.\n\nIndividual endpoint documentation does not repeat these responses unless an endpoint has\nauthentication or access behavior that differs from the standard API key flow.\n\n## Currency and assets\n\nSupported currencies, assets, networks, and withdrawal rails are configuration-driven. When building\nforms or validation rules, use the relevant external, public, or user currency and payment route\nendpoints instead of hard-coding an asset list from this document. External account and currency\nendpoints are scoped to the API key owner's effective jurisdiction.\n\n## Security\n\nProduction and staging integrations must use HTTPS. Rotate API keys immediately if you suspect a\nsecret has been exposed. Store secrets in a vault or server-side secret manager, and do not log full\nAPI secrets.\n\n## Error model\n\nError responses use Lumetrade's standard error envelope:\n\n```json\n{\n \"code\": 1133,\n \"message\": \"Validation error: amount is required\",\n \"httpStatus\": 400,\n \"requestId\": \"req_01HY...\",\n \"timestamp\": \"2026-01-01T00:00:00Z\",\n \"errors\": [\n {\n \"field\": \"amount\",\n \"message\": \"must be greater than 0\"\n }\n ]\n}\n```\n\nCommon non-authentication error classes include `400` validation failures, `404` resources not found\nfor the authenticated owner, `409` insufficient funds or conflicting money movement state, and `500`\nunexpected server errors.\n\n## Pagination and filtering\n\nCurrent list endpoints may expose reserved query parameters for page, size, sort, date range, and\nstatus filters. Unless an endpoint explicitly says otherwise, current responses are unpaginated arrays\nand your integration should not depend on server-side pagination behavior yet.\n\n## Transaction lifecycle\n\nDeposits, withdrawals, trades, and fills move through domain statuses such as pending, processing,\ncompleted, failed, cancelled, or reversed depending on the resource type. A status is final only when\nthe specific endpoint and business flow represent it as terminal. Your integration should poll the\nread endpoints for status changes because webhooks are not currently documented for this API.\n", "contact": { "name": "Lume Forge" }, "version": "v1" }, "servers": [ { "url": "https://api.lumetrade.com" } ], "tags": [ { "name": "Beneficiaries", "description": "Beneficiary endpoints for the authenticated API key owner." }, { "name": "Withdrawals", "description": "Withdrawal history endpoints for the authenticated API key owner." }, { "name": "Trades", "description": "Trade history endpoints for the authenticated API key owner." }, { "name": "Accounts", "description": "Account endpoints for the authenticated API key owner." }, { "name": "Deposits", "description": "Deposit history endpoints for the authenticated API key owner." }, { "name": "Wallets", "description": "Wallet endpoints for the authenticated API key owner." }, { "name": "Currencies", "description": "Currency catalog endpoints for the authenticated API key owner." } ], "paths": { "/api/v1/trades/quote": { "post": { "tags": [ "Trades" ], "summary": "Get trade quote", "description": "Requests an RFQ quote for the authenticated API key owner.", "operationId": "getQuote", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumetrade API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalRequestRFQQuoteRequest" }, "examples": { "Quote by send amount": { "summary": "Request a quote using fromAmount", "description": "Quote by send amount", "value": { "fromAmount": 100, "fromCurrency": "USDT", "toCurrency": "ZAR", "quoteIntent": "client_linked" } }, "Quote by receive amount": { "summary": "Request a quote using toAmount", "description": "Quote by receive amount", "value": { "toAmount": 1840, "fromCurrency": "USDT", "toCurrency": "ZAR", "quoteIntent": "client_linked" } } } } }, "required": true }, "responses": { "200": { "description": "Quote returned successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Quote request validation failed", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/trades/quote/confirm": { "post": { "tags": [ "Trades" ], "summary": "Confirm trade quote", "description": "Confirms a previously issued RFQ quote for the authenticated API key owner.", "operationId": "confirmQuote", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumetrade API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAcceptRFQQuoteRequest" }, "examples": { "Confirm by send amount": { "summary": "Confirm using fromAmount", "description": "Confirm by send amount", "value": { "fromAmount": 100, "fromCurrency": "USDT", "toCurrency": "ZAR", "quoteStr": "rfq_quote_7K9Q2M" } }, "Confirm by receive amount": { "summary": "Confirm using toAmount", "description": "Confirm by receive amount", "value": { "toAmount": 1840, "fromCurrency": "USDT", "toCurrency": "ZAR", "quoteStr": "rfq_quote_7K9Q2M" } } } } }, "required": true }, "responses": { "200": { "description": "Quote confirmed successfully", "content": { "application/json": { "examples": { "Confirmed trade by send amount": { "summary": "Trade response returned after confirming a fromAmount quote", "description": "Confirmed trade by send amount", "value": { "fromCurrency": "USDT", "toCurrency": "ZAR", "fromAmount": 100, "toAmount": 1840, "rate": 18.4, "isRateInverted": false, "isRfq": true, "status": "COMPLETED", "transactionId": "TID4J7K2N", "createdAt": "2026-05-11T10:15:30Z", "completedAt": "2026-05-11T10:15:35" } }, "Confirmed trade by receive amount": { "summary": "Trade response returned after confirming a toAmount quote", "description": "Confirmed trade by receive amount", "value": { "fromCurrency": "USDT", "toCurrency": "ZAR", "fromAmount": 100, "toAmount": 1840, "rate": 18.4, "isRateInverted": false, "isRfq": true, "status": "COMPLETED", "transactionId": "TID4J7K2N", "createdAt": "2026-05-11T10:15:30Z", "completedAt": "2026-05-11T10:15:35" } } } } } }, "400": { "description": "Quote confirmation validation failed", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/beneficiaries/withdrawals": { "post": { "tags": [ "Beneficiaries" ], "summary": "Create beneficiary withdrawal", "description": "Creates a withdrawal using only the saved details from an existing confirmed beneficiary.", "operationId": "createWithdrawal", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumetrade API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBeneficiaryWithdrawalRequest" } } }, "required": true }, "responses": { "201": { "description": "Withdrawal created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWithdrawalResponse" } } } }, "400": { "description": "Withdrawal request is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWithdrawalResponse" } } } }, "404": { "description": "Beneficiary was not found for the authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWithdrawalResponse" } } } } } } }, "/api/v1/accounts": { "get": { "tags": [ "Accounts" ], "summary": "List accounts", "description": "Returns accounts belonging to the authenticated API key owner for currencies enabled in the owner's effective jurisdiction.", "operationId": "getAccounts", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumetrade API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accounts returned successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalAccountResponse" } } } } } } }, "post": { "tags": [ "Accounts" ], "summary": "Create account", "description": "Creates an account for the authenticated API key owner only when the requested currency is enabled in the owner's effective jurisdiction.", "operationId": "createAccount", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumetrade API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalCreateAccountRequest" } } }, "required": true }, "responses": { "201": { "description": "Account created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAccountResponse" } } } }, "400": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAccountResponse" } } } }, "404": { "description": "Currency is not supported for this user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAccountResponse" } } } }, "409": { "description": "Account already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAccountResponse" } } } } } } }, "/api/v1/withdrawals": { "get": { "tags": [ "Withdrawals" ], "summary": "List withdrawals", "description": "Returns the authenticated user's withdrawal history. Pagination, sorting, date filtering, and status filtering parameters are reserved for this list endpoint; current responses remain unpaginated until server-side pagination is enabled.", "operationId": "getWithdrawHistory", "parameters": [ { "name": "page", "in": "query", "description": "Page number, zero-based.", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 0 }, { "name": "size", "in": "query", "description": "Page size. Planned maximum: 100.", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 50 }, { "name": "sort", "in": "query", "description": "Sort expression: field,direction.", "required": false, "schema": { "type": "string" }, "example": "completedAt,desc" }, { "name": "dateFrom", "in": "query", "description": "Reserved inclusive lower timestamp bound.", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-01-01T00:00:00Z" }, { "name": "dateTo", "in": "query", "description": "Reserved inclusive upper timestamp bound.", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-01-31T23:59:59Z" }, { "name": "status", "in": "query", "description": "Reserved withdrawal status filter.", "required": false, "schema": { "type": "string" }, "example": "COMPLETED" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumetrade API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Withdrawals returned successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WithdrawResponse" } } } } } } } }, "/api/v1/withdrawals/{transactionId}": { "get": { "tags": [ "Withdrawals" ], "summary": "Get withdrawal", "description": "Returns a single withdrawal belonging to the authenticated API key owner.", "operationId": "getWithdraw", "parameters": [ { "name": "transactionId", "in": "path", "description": "Withdrawal transaction id returned by the withdrawal list endpoint.", "required": true, "schema": { "type": "string" }, "example": "wd_5M8Q1P" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumetrade API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Withdrawal returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawResponse" } } } }, "404": { "description": "Withdrawal was not found for the authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawResponse" } } } } } } }, "/api/v1/wallets": { "get": { "tags": [ "Wallets" ], "summary": "List wallets", "description": "Returns wallets belonging to the authenticated API key owner.", "operationId": "getWallets", "parameters": [ { "name": "paymentMethodType", "in": "query", "description": "Optional payment method type filter for fiat wallets.", "required": false, "schema": { "type": "string" }, "example": "EFT" }, { "name": "networkName", "in": "query", "description": "Optional network name filter for crypto wallets.", "required": false, "schema": { "type": "string" }, "example": "Ethereum (ETH)" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumetrade API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Wallets returned successfully", "content": { "application/json": { "examples": { "Fiat virtual EFT wallet": { "summary": "Fiat wallet with user-specific EFT bank account details", "description": "Fiat virtual EFT wallet", "value": [ { "id": "wal_3Q8M1K", "currency": "ZAR", "depositDetails": { "bankName": "Nedbank", "accountName": "Example Customer", "accountNumber": "9876543210", "accountType": "Current", "branchCode": "198765" }, "networkName": null, "paymentMethodType": "EFT" } ] }, "Crypto wallet": { "summary": "Crypto wallet with blockchain address deposit details", "description": "Crypto wallet", "value": [ { "id": "wal_7K9Q2M", "currency": "BTC", "depositDetails": { "address": "bc1qexample...", "address_tag": "123456" }, "networkName": "Bitcoin", "paymentMethodType": null } ] } } } } } } } }, "/api/v1/wallets/{walletId}": { "get": { "tags": [ "Wallets" ], "summary": "Get wallet", "description": "Returns one wallet belonging to the authenticated API key owner.", "operationId": "getWallet", "parameters": [ { "name": "walletId", "in": "path", "description": "Wallet id returned by the wallet list endpoint.", "required": true, "schema": { "type": "string" }, "example": "wal_3Q8M1K" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumetrade API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Wallet returned successfully", "content": { "application/json": { "examples": { "Fiat virtual EFT wallet": { "summary": "Fiat wallet with user-specific EFT bank account details", "description": "Fiat virtual EFT wallet", "value": { "id": "wal_3Q8M1K", "currency": "ZAR", "depositDetails": { "bankName": "Nedbank", "accountName": "Example Customer", "accountNumber": "9876543210", "accountType": "Current", "branchCode": "198765" }, "networkName": null, "paymentMethodType": "EFT" } }, "Crypto wallet": { "summary": "Crypto wallet with blockchain address deposit details", "description": "Crypto wallet", "value": { "id": "wal_7K9Q2M", "currency": "BTC", "depositDetails": { "address": "bc1qexample...", "address_tag": "123456" }, "networkName": "Bitcoin", "paymentMethodType": null } } } } } }, "404": { "description": "Wallet was not found for the authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" } } } } } } }, "/api/v1/trades": { "get": { "tags": [ "Trades" ], "summary": "List trades", "description": "Returns the authenticated user's trade history, including any fills linked to each trade. Pagination, sorting, date filtering, and status filtering parameters are reserved for this list endpoint; current responses remain unpaginated until server-side pagination is enabled.", "operationId": "tradeHistory", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 0 }, { "name": "size", "in": "query", "description": "Page size", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 50 }, { "name": "sort", "in": "query", "description": "Sort expression: field,direction.", "required": false, "schema": { "type": "string" }, "example": "completedAt,desc" }, { "name": "dateFrom", "in": "query", "description": "Lower timestamp bound.", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-01-01T00:00:00Z" }, { "name": "dateTo", "in": "query", "description": "Upper timestamp bound.", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-01-31T23:59:59Z" }, { "name": "status", "in": "query", "description": "Trade status filter.", "required": false, "schema": { "type": "string" }, "example": "COMPLETED" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumetrade API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trades returned successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TradeResponse" } } } } } } } }, "/api/v1/trades/{transactionId}": { "get": { "tags": [ "Trades" ], "summary": "Get trade", "description": "Returns a single trade belonging to the authenticated API key owner.", "operationId": "getTrade", "parameters": [ { "name": "transactionId", "in": "path", "description": "Trade transaction id returned by the trade list endpoint.", "required": true, "schema": { "type": "string" }, "example": "TID4J7K2N" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumetrade API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trade returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TradeResponse" } } } }, "404": { "description": "Trade was not found for the authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TradeResponse" } } } } } } }, "/api/v1/deposits": { "get": { "tags": [ "Deposits" ], "summary": "List deposits", "description": "Returns the authenticated user's deposit history. Pagination, sorting, date filtering, and status filtering parameters are reserved for this list endpoint; current responses remain unpaginated until server-side pagination is enabled.", "operationId": "depositHistory", "parameters": [ { "name": "page", "in": "query", "description": "Page number, zero-based.", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 0 }, { "name": "size", "in": "query", "description": "Page size. Planned maximum: 100.", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 50 }, { "name": "sort", "in": "query", "description": "Sort expression: field,direction.", "required": false, "schema": { "type": "string" }, "example": "completedAt,desc" }, { "name": "dateFrom", "in": "query", "description": "Lower timestamp bound.", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-01-01T00:00:00Z" }, { "name": "dateTo", "in": "query", "description": "Upper timestamp bound.", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-01-31T23:59:59Z" }, { "name": "status", "in": "query", "description": "Deposit status filter.", "required": false, "schema": { "type": "string" }, "example": "COMPLETED" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumetrade API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deposits returned successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DepositResponse" } } } } } } } }, "/api/v1/deposits/{transactionId}": { "get": { "tags": [ "Deposits" ], "summary": "Get deposit", "description": "Returns a single deposit belonging to the authenticated API key owner.", "operationId": "getDeposit", "parameters": [ { "name": "transactionId", "in": "path", "description": "Deposit Transaction id returned by the deposit list endpoint.", "required": true, "schema": { "type": "string" }, "example": "dep_9H2K7P" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumetrade API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deposit returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositResponse" } } } }, "404": { "description": "Deposit was not found for the authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositResponse" } } } } } } }, "/api/v1/currencies": { "get": { "tags": [ "Currencies" ], "summary": "List currencies", "description": "Returns enabled currencies for the authenticated API key owner's effective jurisdiction.", "operationId": "getCurrencies", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumetrade API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Currencies returned successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalCurrencyResponse" } } } } } } } }, "/api/v1/beneficiaries": { "get": { "tags": [ "Beneficiaries" ], "summary": "List beneficiaries", "description": "Returns confirmed beneficiaries belonging to the authenticated API key owner.", "operationId": "getBeneficiaries", "parameters": [ { "name": "currency", "in": "query", "description": "Optional beneficiary currency code filter.", "required": false, "schema": { "type": "string" }, "example": "ZAR" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumetrade API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Beneficiaries returned successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BeneficiaryResponse" } } } } } } } }, "/api/v1/beneficiaries/{beneficiaryId}": { "get": { "tags": [ "Beneficiaries" ], "summary": "Get beneficiary", "description": "Returns a confirmed beneficiary belonging to the authenticated API key owner.", "operationId": "getBeneficiary", "parameters": [ { "name": "beneficiaryId", "in": "path", "description": "Beneficiary id returned by the beneficiary list endpoint.", "required": true, "schema": { "type": "string" }, "example": "ben_7K9Q2M" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumetrade API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Beneficiary returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeneficiaryResponse" } } } }, "404": { "description": "Beneficiary was not found for the authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeneficiaryResponse" } } } } } } }, "/api/v1/accounts/{accountId}": { "get": { "tags": [ "Accounts" ], "summary": "Get account", "description": "Returns one account belonging to the authenticated API key owner when its currency is enabled in the owner's effective jurisdiction.", "operationId": "getAccount", "parameters": [ { "name": "accountId", "in": "path", "description": "Account id returned by the account list endpoint.", "required": true, "schema": { "type": "string" }, "example": "acc_8F4J2N" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumetrade API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAccountResponse" } } } }, "404": { "description": "Account was not found for the authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAccountResponse" } } } } } } }, "/api/v1/accounts/currency/{currency}": { "get": { "tags": [ "Accounts" ], "summary": "Get account by currency", "description": "Returns one account belonging to the authenticated API key owner for the requested currency when that currency is enabled in the owner's effective jurisdiction.", "operationId": "getAccountByCurrency", "parameters": [ { "name": "currency", "in": "path", "description": "Currency for the account lookup.", "required": true, "schema": { "type": "string" }, "example": "ZAR" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumetrade API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAccountResponse" } } } }, "404": { "description": "Account or currency was not found for the authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAccountResponse" } } } } } } } }, "components": { "schemas": { "ExternalRequestRFQQuoteRequest": { "type": "object", "properties": { "fromAmount": { "type": "number", "description": "How much the customer wants to send or pay. Provide either fromAmount or toAmount, not both.", "example": 100 }, "toAmount": { "type": "number", "description": "How much the customer wants to receive. Provide either toAmount or fromAmount, not both.", "example": 1840 }, "fromCurrency": { "type": "string", "description": "Currency the customer is sending or paying with.", "example": "USDT" }, "toCurrency": { "type": "string", "description": "Currency the customer wants to receive.", "example": "ZAR" }, "quoteIntent": { "type": "string", "description": "Use client_linked when the customer may confirm this quote. Use indicative when the customer only needs a preview price.", "enum": [ "indicative", "client_linked" ], "example": "client_linked", "pattern": "(?i)indicative|client_linked" } } }, "ExternalAcceptRFQQuoteRequest": { "type": "object", "properties": { "fromAmount": { "type": "number", "description": "Amount the customer sends or pays from the quote response. Provide either fromAmount or toAmount, not both.", "example": 100 }, "toAmount": { "type": "number", "description": "Amount the customer receives from the quote response. Provide either toAmount or fromAmount, not both.", "example": 1840 }, "fromCurrency": { "type": "string", "description": "Currency the customer sends or pays with.", "example": "USDT" }, "quoteStr": { "type": "string", "description": "Quote reference returned by /api/v1/trades/quote.", "example": "rfq_quote_7K9Q2M" }, "toCurrency": { "type": "string", "description": "Currency the customer receives.", "example": "ZAR" } } }, "CreateBeneficiaryWithdrawalRequest": { "type": "object", "description": "Request to create a withdrawal from a beneficiary.", "properties": { "beneficiaryId": { "type": "string", "description": "Beneficiary id returned by the beneficiary endpoints.", "example": "ben_7K9Q2M" }, "amount": { "type": "number", "description": "Withdrawal amount in the beneficiary currency.", "example": 101 } }, "required": [ "amount" ] }, "CreateWithdrawalResponse": { "type": "object", "description": "Withdrawal creation response returned by the API.", "properties": { "transactionId": { "type": "string", "description": "Created withdrawal transaction id.", "example": "WD5M8Q1P" }, "status": { "type": "string", "description": "Created withdrawal status.", "enum": [ "PENDING", "ACCEPTED", "AWAITING_CONFIRMATION", "PROCESSING", "COMPLIANCE_PENDING", "COMPLETED", "FAILED", "CANCELLED", "REVERSED" ], "example": "PENDING" } } }, "ExternalCreateAccountRequest": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency code for the account to create.", "example": "ZAR" } } }, "ExternalAccountResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Account id used by external account endpoints.", "example": "acc_8F4J2N" }, "currency": { "type": "string", "description": "Account currency.", "example": "ZAR" }, "balance": { "type": "number", "description": "Available account balance.", "example": 2500 }, "lockedBalance": { "type": "number", "description": "Locked account balance.", "example": 0 } } }, "JsonNode": { "type": "object", "additionalProperties": true, "description": "Raw withdrawal details stored as JSON object.", "example": { "bankName": "FNB", "accountNumber": "1234567890" }, "properties": { "pojo": { "type": "boolean" }, "int": { "type": "boolean" }, "double": { "type": "boolean" }, "bigDecimal": { "type": "boolean" }, "bigInteger": { "type": "boolean" }, "nodeType": { "type": "string", "enum": [ "ARRAY", "BINARY", "BOOLEAN", "MISSING", "NULL", "NUMBER", "OBJECT", "POJO", "STRING" ] }, "container": { "type": "boolean" }, "short": { "type": "boolean" }, "long": { "type": "boolean" }, "valueNode": { "type": "boolean" }, "missingNode": { "type": "boolean" }, "floatingPointNumber": { "type": "boolean" }, "integralNumber": { "type": "boolean" }, "string": { "type": "boolean" }, "boolean": { "type": "boolean" }, "object": { "type": "boolean" }, "textual": { "type": "boolean", "deprecated": true }, "binary": { "type": "boolean" }, "number": { "type": "boolean" }, "array": { "type": "boolean" }, "empty": { "type": "boolean" }, "null": { "type": "boolean" }, "float": { "type": "boolean" }, "embeddedValue": { "type": "boolean" } } }, "WithdrawResponse": { "type": "object", "description": "Withdrawal transaction returned by the API.", "properties": { "amount": { "type": "number", "description": "Withdrawal amount.", "example": 101 }, "fee": { "type": "number", "description": "Withdrawal fee.", "example": 1 }, "currency": { "type": "string", "description": "Withdrawal currency code.", "example": "ZAR" }, "withdrawDetails": { "$ref": "#/components/schemas/JsonNode", "additionalProperties": true, "description": "Raw withdrawal details stored as JSON object.", "example": { "bankName": "FNB", "accountNumber": "1234567890" } }, "status": { "type": "string", "description": "Withdrawal status.", "enum": [ "PENDING", "ACCEPTED", "AWAITING_CONFIRMATION", "PROCESSING", "COMPLIANCE_PENDING", "COMPLETED", "FAILED", "CANCELLED", "REVERSED" ], "example": "COMPLETED" }, "transactionId": { "type": "string", "description": "Transaction id for withdrawal lookups.", "example": "wd_5M8Q1P" }, "createdAt": { "type": "string", "format": "date-time", "description": "Withdrawal creation timestamp.", "example": "2026-05-11T10:15:30Z" }, "completedAt": { "type": "string", "format": "date-time", "description": "Completion timestamp.", "example": "2026-05-11T10:20:30" }, "isFiat": { "type": "boolean", "description": "Whether this withdrawal used a fiat route.", "example": true } } }, "WalletResponse": { "type": "object", "description": "Wallet owned by the authenticated API key user.", "properties": { "id": { "type": "string", "description": "Stable wallet id used by external wallet endpoints.", "example": "wal_3Q8M1K" }, "currency": { "type": "string", "description": "Wallet currency code.", "example": "BTC" }, "depositDetails": { "$ref": "#/components/schemas/JsonNode", "additionalProperties": true, "description": "Raw wallet deposit details stored as JSON object.", "example": { "address": "bc1qexample...", "address_tag": "123456" } }, "networkName": { "type": "string", "description": "Crypto network name when available.", "example": "Bitcoin" }, "paymentMethodType": { "type": "string", "description": "Fiat payment method type when available.", "example": "EFT" } } }, "FillResponse": { "type": "object", "description": "Trade fill returned by the API.", "properties": { "fromCurrency": { "type": "string", "description": "Currency sent for this fill.", "example": "USDT" }, "fromCurrencyAmount": { "type": "number", "description": "Amount sent for this fill.", "example": 100 }, "toCurrency": { "type": "string", "description": "Currency received for this fill.", "example": "ZAR" }, "toCurrencyAmount": { "type": "number", "description": "Amount received for this fill.", "example": 1840 }, "status": { "type": "string", "description": "Fill status.", "enum": [ "COMPLETED", "REVERSED" ], "example": "COMPLETED" }, "transactionId": { "type": "string", "description": "Transaction id for this fill.", "example": "fil_2N8K4Q" }, "modifiedAt": { "type": "string", "format": "date-time", "description": "Last modified timestamp.", "example": "2026-05-11T10:15:35Z" }, "createdAt": { "type": "string", "format": "date-time", "description": "Fill creation timestamp.", "example": "2026-05-11T10:15:30Z" } } }, "TradeResponse": { "type": "object", "description": "Trade transaction returned by the API.", "properties": { "fromCurrency": { "type": "string", "description": "Currency sold/sent.", "example": "USDT" }, "toCurrency": { "type": "string", "description": "Currency bought/received.", "example": "ZAR" }, "fromAmount": { "type": "number", "description": "Amount sold/sent.", "example": 100 }, "toAmount": { "type": "number", "description": "Amount bought/received.", "example": 1840 }, "rate": { "type": "number", "description": "Executed trade rate.", "example": 18.4 }, "isRateInverted": { "type": "boolean", "description": "Whether the displayed rate is inverted.", "example": false }, "isRfq": { "type": "boolean", "description": "Whether this trade was created from RFQ.", "example": true }, "status": { "type": "string", "description": "Trade status.", "enum": [ "PENDING", "COMPLETED", "CANCELLED", "REVERSED" ], "example": "COMPLETED" }, "transactionId": { "type": "string", "description": "Transaction id for trade lookups.", "example": "trd_4J7K2N" }, "createdAt": { "type": "string", "format": "date-time", "description": "Trade creation timestamp.", "example": "2026-05-11T10:15:30Z" }, "completedAt": { "type": "string", "format": "date-time", "description": "Completion timestamp.", "example": "2026-05-11T10:15:35" }, "fills": { "type": "array", "description": "Trade fills. Omitted from RFQ quote confirmation responses.", "items": { "$ref": "#/components/schemas/FillResponse" } } } }, "DepositResponse": { "type": "object", "description": "Deposit transaction returned by the API.", "properties": { "currency": { "type": "string", "description": "Deposit currency code.", "example": "USDT" }, "transactionId": { "type": "string", "description": "Transaction id for deposit lookups.", "example": "DP9H2K7P" }, "amount": { "type": "number", "description": "Deposit amount.", "example": 100 }, "fee": { "type": "number", "description": "Deposit fee.", "example": 0 }, "status": { "type": "string", "description": "Deposit status.", "enum": [ "SUBMITTED", "PENDING", "PROCESSING", "COMPLIANCE_PENDING", "COMPLETED", "FAILED", "CANCELLED", "REVERSED" ], "example": "COMPLETED" }, "completedAt": { "type": "string", "format": "date-time", "description": "Completion timestamp.", "example": "2026-05-11T10:15:30" } } }, "ExternalCurrencyResponse": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency code.", "example": "ZAR" }, "name": { "type": "string", "description": "Currency display name.", "example": "South African Rand" } } }, "BeneficiaryResponse": { "type": "object", "description": "Beneficiary available to the authenticated API key user.", "properties": { "id": { "type": "string", "description": "Beneficiary id used by external beneficiary endpoints.", "example": "ben_7K9Q2M" }, "currency": { "type": "string", "description": "Saved beneficiary currency.", "example": "ZAR" }, "nickname": { "type": "string", "description": "Beneficiary nickname.", "example": "FNB Savings" }, "withdrawFormDetails": { "$ref": "#/components/schemas/JsonNode", "additionalProperties": true, "description": "Saved withdrawal form details for the beneficiary.", "example": { "bankName": "FNB", "accountNumber": "1234567890", "accountHolderName": "Jane Example" } }, "createdAt": { "type": "string", "format": "date-time", "description": "Beneficiary creation timestamp.", "example": "2026-05-11T10:15:30Z" } } } } } }