{ "openapi": "3.1.0", "info": { "version": "1.1.0", "title": "Third Party API", "description": "Deriv API provides programmatic access to trading services, account management, and market data across multiple trading platforms including CFDs, options, and peer-to-peer exchange. This REST API enables developers to integrate Deriv's trading infrastructure into their applications with comprehensive endpoints for account operations, trading activities, and real-time market information." }, "tags": [ { "name": "Options Trading", "description": "Options trading API: account management, OTP issuance for WebSocket auth, and WebSocket endpoints for trading and public market data." }, { "name": "Options Trading - Legacy", "description": "Read-only access to a user's pre-upgrade options trading data (statement, accounts, upgrade status). These endpoints expose data sourced from the legacy platform and will be removed once the platform upgrade is complete for all users." }, { "name": "Reporting", "description": "Aggregated business reporting endpoints (e.g. per-application markup statistics)." }, { "name": "System", "description": "Operational endpoints for service health and infrastructure checks." }, { "name": "Partners", "description": "Partner reporting and client attribution endpoints." }, { "name": "Payment Agent", "description": "Endpoints for discovering payment agent profiles and executing payment-agent-facilitated deposits and withdrawals." }, { "name": "Identity", "description": "Endpoints for accessing identity data for the authenticated user." }, { "name": "Wallets", "description": "Endpoints for accessing wallet balances and transactions for the authenticated client." } ], "paths": { "/trading/v1/options/accounts": { "get": { "tags": [ "Options Trading" ], "summary": "List options trading accounts", "description": "Returns every options trading account the authenticated user owns, including both real and demo accounts. Use this to discover the account IDs needed for placing trades, opening WebSocket connections, or resetting demo balances.", "operationId": "3855391d-78e9-438b-b2db-b9aa41527add", "security": [ { "oauth2": [ "trade" ] } ], "parameters": [ { "name": "Deriv-App-ID", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Application identifier" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OptionsAccount" } }, "meta": { "$ref": "#/components/schemas/Metadata" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Gateway timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Options Trading" ], "summary": "Create an options trading account", "description": "Opens a new options trading account for the authenticated user. The account type (real or demo) and currency are taken from the request body. The newly created account is returned in the response.", "operationId": "800f51ec-2b2c-4493-9213-2f36a2c91cc0", "security": [ { "oauth2": [ "account_manage" ] } ], "parameters": [ { "name": "Deriv-App-ID", "in": "header", "required": true, "description": "Application identifier used for Personal Access Token (PAT) authentication.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "description": "Account currency", "enum": [ "USD" ] }, "group": { "type": "string", "description": "Account group", "enum": [ "row" ] }, "account_type": { "type": "string", "description": "Account type", "enum": [ "demo", "real" ] } }, "required": [ "currency", "group", "account_type" ] } } } }, "responses": { "200": { "description": "OK - returned when the account already exists (if the same parameters are provided)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OptionsAccount" }, "meta": { "$ref": "#/components/schemas/Metadata" } } } } } }, "201": { "description": "Created - returned when a new account is created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OptionsAccount" } }, "meta": { "$ref": "#/components/schemas/Metadata" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Gateway timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trading/v1/options/accounts/{account_id}/reset-demo-balance": { "post": { "tags": [ "Options Trading" ], "summary": "Reset a demo account's balance", "description": "Resets the balance of the specified demo account back to its default starting amount. Only demo accounts owned by the authenticated user can be reset; calling this on a real account will be rejected.", "operationId": "8e112353-992d-41ce-a91c-26f6d02db73c", "security": [ { "oauth2": [ "trade" ] } ], "parameters": [ { "name": "Deriv-App-ID", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Application identifier" }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Options Trading account ID" } ], "responses": { "200": { "description": "OK - Demo balance reset successfully" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Gateway timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trading/v1/options/accounts/{accountId}/otp": { "post": { "tags": [ "Options Trading" ], "summary": "Issue a one-time password for WebSocket authentication", "description": "Issues a short-lived one-time password (OTP) that authenticates a subsequent WebSocket connection for the specified account. The response includes the OTP and a ready-to-use WebSocket URL with the OTP attached as a query parameter. The OTP is valid for 120 seconds and can be used only once — open the WebSocket connection promptly after calling this endpoint.", "operationId": "d3b5f8e2-3c4a-4f7e-9f1e-2b6c8f9e4d2a", "security": [ { "oauth2": [ "trade" ] } ], "parameters": [ { "name": "Deriv-App-ID", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Application identifier" }, { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Options Trading account ID that OTP is requested for" } ], "responses": { "200": { "description": "OTP generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "description": "OTP URL for websocket authentication" } }, "required": [ "url" ] }, "meta": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "data", "meta" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trading/v1/options/contracts/bulk-purchase/real": { "post": { "tags": [ "Options Trading" ], "summary": "Buy a contract across multiple real accounts", "description": "Buys the same options contract for multiple real-money accounts in a single call. Authentication is by your application's `Deriv-App-ID` header together with the per-account Personal Access Tokens (PATs) supplied in the request body; no OAuth access token is required for this endpoint. Each entry in the request pairs an end-user PAT — which must carry the `trade` scope and own the paired account — with the real account to buy for, and the same contract parameters are applied to every account. Up to 100 entries are accepted per request. An entry whose token is invalid, or whose token does not own the paired account, is reported individually in the response without affecting the others; if no entry is valid the request is rejected with 400. This endpoint is for real-money accounts only — demo accounts are reported as per-account failures.", "operationId": "a1c2e3f4-5b6d-4e8a-9c1f-2d3b4a5c6e7f", "parameters": [ { "name": "Deriv-App-ID", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Application identifier used for Personal Access Token (PAT) authentication." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contract_parameters": { "type": "object", "description": "Options contract parameters applied to every account in the request (e.g. contract_type, symbol, amount, duration).", "additionalProperties": true }, "accounts": { "type": "array", "description": "List of end-user token / account pairs to buy the contract for. Duplicate pairs are honoured and result in repeated purchases.", "minItems": 1, "maxItems": 100, "items": { "type": "object", "properties": { "token": { "type": "string", "description": "End-user Personal Access Token (PAT) authorizing the purchase on the paired account.", "minLength": 1, "maxLength": 512 }, "account_id": { "type": "string", "description": "Options trading account the contract should be bought for. Must belong to the token's owner.", "minLength": 1, "maxLength": 64 } }, "required": [ "token", "account_id" ], "additionalProperties": false } } }, "required": [ "contract_parameters", "accounts" ] } } } }, "responses": { "200": { "description": "The request was processed. The transactions array contains one entry per account with either the purchased contract details or a per-account error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "transactions": { "type": "array", "description": "Per-account purchase results. Each entry reports success (contract/transaction details) or an error for that account.", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "transactions" ] }, "meta": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "data", "meta" ] } } } }, "400": { "description": "Invalid request body, or no token/account pair passed validation (each failing account is reported in errors[].field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "An upstream service was temporarily unavailable. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trading/v1/options/contracts/bulk-purchase/demo": { "post": { "tags": [ "Options Trading" ], "summary": "Buy a contract across multiple demo accounts", "description": "Buys the same options contract for multiple demo accounts in a single call. Authentication is by your application's `Deriv-App-ID` header together with the per-account Personal Access Tokens (PATs) supplied in the request body; no OAuth access token is required for this endpoint. Each entry in the request pairs an end-user PAT — which must carry the `trade` scope and own the paired account — with the demo account to buy for, and the same contract parameters are applied to every account. Up to 100 entries are accepted per request. An entry whose token is invalid, or whose token does not own the paired account, is reported individually in the response without affecting the others; if no entry is valid the request is rejected with 400. This endpoint is for demo accounts only — real-money accounts are reported as per-account failures.", "operationId": "b2d3f4a5-6c7e-4f9b-8a2d-3e4c5b6a7d8e", "parameters": [ { "name": "Deriv-App-ID", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Application identifier used for Personal Access Token (PAT) authentication." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contract_parameters": { "type": "object", "description": "Options contract parameters applied to every account in the request (e.g. contract_type, symbol, amount, duration).", "additionalProperties": true }, "accounts": { "type": "array", "description": "List of end-user token / account pairs to buy the contract for. Duplicate pairs are honoured and result in repeated purchases.", "minItems": 1, "maxItems": 100, "items": { "type": "object", "properties": { "token": { "type": "string", "description": "End-user Personal Access Token (PAT) authorizing the purchase on the paired account.", "minLength": 1, "maxLength": 512 }, "account_id": { "type": "string", "description": "Options trading account the contract should be bought for. Must belong to the token's owner.", "minLength": 1, "maxLength": 64 } }, "required": [ "token", "account_id" ], "additionalProperties": false } } }, "required": [ "contract_parameters", "accounts" ] } } } }, "responses": { "200": { "description": "The request was processed. The transactions array contains one entry per account with either the purchased contract details or a per-account error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "transactions": { "type": "array", "description": "Per-account purchase results. Each entry reports success (contract/transaction details) or an error for that account.", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "transactions" ] }, "meta": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "data", "meta" ] } } } }, "400": { "description": "Invalid request body, or no token/account pair passed validation (each failing account is reported in errors[].field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "An upstream service was temporarily unavailable. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trading/v1/options/ws/demo": { "get": { "tags": [ "Options Trading" ], "summary": "Open a WebSocket connection for a demo account", "description": "Upgrades the HTTP request to a WebSocket connection scoped to a demo options trading account. Authentication requires a valid OTP obtained from the OTP endpoint, passed as the `otp` query parameter. Use this channel to subscribe to real-time market data, send trading instructions, and receive order and position updates for the demo account.", "operationId": "56761c01-95d7-4201-80cb-2836d1b8c518", "parameters": [ { "name": "otp", "in": "query", "required": true, "schema": { "type": "string" }, "description": "One time password to authorize websocket connection. Token should be generated by endpoint /trading/v1/options/accounts/{accountId}/otp" } ], "responses": { "101": { "description": "Switching Protocols - WebSocket connection established" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid or missing OTP", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trading/v1/options/ws/real": { "get": { "tags": [ "Options Trading" ], "summary": "Open a WebSocket connection for a real account", "description": "Upgrades the HTTP request to a WebSocket connection scoped to a real-money options trading account. Authentication requires a valid OTP obtained from the OTP endpoint, passed as the `otp` query parameter. Use this channel to subscribe to real-time market data, send trading instructions, and receive order and position updates. Trades placed over this channel settle against the account's real balance.", "operationId": "5d2450ad-eb86-459b-a61f-74594a21f884", "parameters": [ { "name": "otp", "in": "query", "required": true, "schema": { "type": "string" }, "description": "One time password to authorize websocket connection. Token should be generated by endpoint /trading/v1/options/accounts/{accountId}/otp" } ], "responses": { "101": { "description": "Switching Protocols - WebSocket connection established" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid or missing OTP", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trading/v1/options/ws/public": { "get": { "tags": [ "Options Trading" ], "summary": "Open a public WebSocket connection (no authentication)", "description": "Upgrades the HTTP request to a WebSocket connection for public options trading data. No authentication or OTP is required. Use this channel to stream real-time market data — for example quotes, ticks, and contract metadata — without needing a user account. Account-scoped actions such as placing trades or reading balances are not available on this channel.", "operationId": "56761c01-95d7-4201-80cb-2836d1b8c519", "responses": { "101": { "description": "Switching Protocols - WebSocket connection established" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trading/v1/options/legacy/statement": { "get": { "tags": [ "Options Trading - Legacy" ], "summary": "Get the legacy transaction statement for a loginid", "description": "Returns the historical transaction statement from the legacy options platform for the authenticated user, scoped to the default account of the loginid supplied in the `loginid` query parameter. Results can be filtered by transaction type and by a date range, expressed as a half-open interval `[date_from, date_to)` using epoch seconds. Pagination uses `limit` (default 100, maximum 999) and `offset`. Transactions are returned newest first, with the most recent `transaction_time` at the top and ties broken by `id` in descending order. Legacy endpoint — will be removed once the platform upgrade is complete for all users.", "operationId": "otp-history-statement", "security": [ { "oauth2": [ "trade" ] } ], "parameters": [ { "name": "Deriv-App-ID", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Application identifier" }, { "name": "loginid", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]+[0-9]+$", "examples": [ "CR12345" ] }, "description": "Legacy loginid whose default-account statement to return. Must match `^[A-Z]+[0-9]+$`." }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 2147483647 }, "description": "Inclusive lower bound as epoch seconds. A row is included iff its true `transaction_time` is `>= date_from`. Defaults to 0 (all history). Values above 2147483647 (the year-2038 epoch limit) are rejected with HTTP 422." }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 2147483647 }, "description": "Exclusive upper bound as epoch seconds. A row is included iff its true `transaction_time` is `< date_to`. Defaults to current time. Values above 2147483647 (the year-2038 epoch limit) are rejected with HTTP 422." }, { "name": "action_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "buy", "sell", "deposit", "withdrawal", "transfer", "hold", "release", "adjustment", "escrow" ] }, "description": "Filter by transaction type. Defaults to all types." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 999, "default": 100 }, "description": "Maximum number of transactions to return. Defaults to 100, maximum 999." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of transactions to skip before returning results. Use with `limit` for pagination." } ], "responses": { "200": { "description": "Statement payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyStatementResponse" }, "example": { "transactions": [ { "transaction_id": 22859, "account_id": 202201, "loginid": "CR90000109", "action_type": "sell", "amount": "0.00", "balance_after": "9558.62", "transaction_time": 1779169387, "contract_id": 13039, "currency": "USD", "shortcode": "PUT_1HZ100V_19.12_1779162186_1779169386_S0P_0", "bet_class": "higher_lower_bet", "bet_type": "PUT", "symbol": "1HZ100V", "app_id": 2 } ], "count": 100 } } } }, "400": { "description": "Bad input (e.g. malformed loginid)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "User or default account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "User migration is pending or has failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trading/v1/options/legacy/accounts": { "get": { "tags": [ "Options Trading - Legacy" ], "summary": "List the authenticated user's legacy accounts", "description": "Returns the authenticated user's accounts on the legacy options platform, grouped by loginid. Each account includes its `account_id` and `currency`. Loginids that have no accounts are omitted. When the user has no resolvable legacy accounts, the response is `{\"loginids\": {}}`. Use the returned loginids with the legacy statement endpoint to fetch historical transactions. Legacy endpoint — will be removed once the platform upgrade is complete for all users.", "operationId": "otp-history-accounts", "security": [ { "oauth2": [ "trade" ] } ], "parameters": [ { "name": "Deriv-App-ID", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Application identifier" } ], "responses": { "200": { "description": "Accounts grouped by loginid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyAccountsResponse" }, "example": { "loginids": { "CR90000123": [ { "account_id": 123, "currency": "USD" } ] } } } } }, "404": { "description": "User has no legacy account mapping", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "User migration is pending or has failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trading/v1/options/legacy/migration-status": { "get": { "tags": [ "Options Trading - Legacy" ], "summary": "Get the user's platform upgrade status", "description": "Returns the authenticated user's current platform upgrade status. The response always has HTTP 200 and the shape `{\"status\": }`, where `` is one of `complete`, `pending`, `failed`, or `not_applicable`. These states are normal answers, not error conditions — for example, `pending` means the upgrade is still in progress, and `not_applicable` means the user never had a legacy account in the first place. Responses are returned with `Cache-Control: no-store`, so polling clients always see fresh state. Legacy endpoint — will be removed once the platform upgrade is complete for all users.", "operationId": "otp-history-migration-status", "security": [ { "oauth2": [ "trade" ] } ], "parameters": [ { "name": "Deriv-App-ID", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Application identifier" } ], "responses": { "200": { "description": "Current migration status", "headers": { "Cache-Control": { "description": "Always set to `no-store` so polling clients are not served stale state.", "schema": { "type": "string", "examples": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyMigrationStatusResponse" }, "example": { "status": "complete" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/applications/v1/markup-statistics": { "get": { "tags": [ "Reporting" ], "summary": "Get markup statistics per application", "description": "Returns aggregated markup statistics over a date range, broken down per application registered by the authenticated user. Use this to track how much markup revenue each of your registered applications has generated. The date range is specified via query parameters.", "operationId": "026b23c5-dcd8-4dbf-8248-c6b057f9fa2a", "security": [ { "oauth2": [ "application_read" ] } ], "parameters": [ { "name": "Deriv-App-ID", "in": "header", "required": true, "description": "Application identifier used for Personal Access Token (PAT) authentication.", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "examples": [ "2026-05-01" ] }, "description": "Interval start date (YYYY-MM-DD), inclusive, UTC." }, { "name": "date_to", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "examples": [ "2026-05-06" ] }, "description": "Interval end date (YYYY-MM-DD), inclusive, UTC." } ], "responses": { "200": { "description": "Markup statistics payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AppMarkupStatistics" }, "meta": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "data", "meta" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Gateway timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/health": { "get": { "tags": [ "System" ], "summary": "Service health check", "description": "Returns HTTP 200 when the gateway is up and able to serve traffic. Intended for use by load balancers, uptime monitors, and infrastructure probes. The endpoint requires no authentication and returns no body payload of interest — the HTTP status alone is the signal.", "operationId": "604a39f2-81db-4ca5-ba34-3f9b67694d1a", "responses": { "200": { "description": "OK - Service is healthy", "content": { "text/plain": { "schema": { "type": "string", "examples": [ "OK" ] } } } } } } }, "/partners/analytics/v1/overview": { "get": { "tags": [ "Partners" ], "summary": "Get partner analytics overview", "description": "Returns signup, master-partner, and activity summary cards for the authenticated partner over an inclusive reporting period.", "operationId": "partners-analytics-v1-overview", "security": [ { "oauth2": [ "application_read" ] } ], "parameters": [ { "name": "Deriv-App-ID", "in": "header", "required": true, "description": "Application identifier used for Personal Access Token (PAT) authentication.", "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "required": true, "description": "Inclusive reporting-period start date. The date range must not exceed 730 days.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "examples": [ "2026-07-01" ] } }, { "name": "end_date", "in": "query", "required": true, "description": "Inclusive reporting-period end date. Must be on or after `start_date` and no more than 730 days later.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "examples": [ "2026-07-21" ] } } ], "responses": { "200": { "description": "Partner analytics overview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAnalyticsOverviewResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Partner not found" }, "422": { "description": "Validation error" }, "500": { "description": "Internal server error" }, "504": { "description": "Gateway timeout" } } } }, "/partners/client-tags/check": { "post": { "tags": [ "Partners" ], "summary": "Check partner client tags", "description": "Checks whether the supplied client IDs are directly tagged to the authenticated partner.", "operationId": "partners-client-tags-check", "security": [ { "oauth2": [ "application_read" ] } ], "parameters": [ { "name": "Deriv-App-ID", "in": "header", "required": true, "description": "Application identifier used for Personal Access Token (PAT) authentication.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerClientTagCheckRequest" }, "example": { "client_ids": [ "12345", "CU52765" ] } } } }, "responses": { "200": { "description": "Client tag check results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerClientTagCheckResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Partner not found" }, "422": { "description": "Validation error" }, "500": { "description": "Internal server error" }, "502": { "description": "Unable to check client tags through Tagging Service" }, "504": { "description": "Gateway timeout" } } } }, "/payment-agents/v1/agents": { "get": { "tags": [ "Payment Agent" ], "summary": "List available payment agents", "description": "Returns a paginated list of active payment agents that support the requested `currency`. Results include publicly listed agents, plus any agent you've previously received a transfer from even if that agent isn't publicly listed. An optional `country` filter further restricts to agents that serve that country. Each result includes the agent's profile and its commission rates for the requested currency.", "operationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "security": [ { "oauth2": [ "payment" ] } ], "parameters": [ { "name": "currency", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Z_]{1,18}$", "examples": [ "USD" ] }, "description": "Currency code. Only agents that support this currency are returned." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-z]{2}$", "examples": [ "id" ] }, "description": "ISO 3166-1 alpha-2 country code in lowercase (e.g. `id`). When supplied, only agents whose `countries` list includes this value are returned." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number for pagination. Defaults to 1." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 25 }, "description": "Number of results per page. Defaults to 25." } ], "responses": { "200": { "description": "OK — paginated list of payment agents matching the supplied filters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Payment agent list items sorted by agent ID ascending.", "items": { "$ref": "#/components/schemas/PaymentAgentListItem" } }, "errors": { "type": "array", "items": {}, "description": "Empty on success." }, "metadata": { "$ref": "#/components/schemas/PAMetadata" } }, "required": [ "data", "errors", "metadata" ] } } } }, "400": { "description": "Bad request — missing or invalid query parameters. `errors[0].code` will be one of:\n\n- `InvalidCurrency` — `currency` does not match the required format (1-18 characters, uppercase letters and underscores)\n- `InvalidCountry` — `country` does not match the required format (lowercase 2-letter ISO 3166-1 alpha-2)\n- `InputError` — a required query parameter is missing or another input failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "401": { "description": "Unauthorized — missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "403": { "description": "Forbidden — valid token but insufficient scope (`payment` scope required).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "500": { "description": "Internal server error — `errors[0].code` will be `InternalError`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "504": { "description": "Gateway timeout — the service did not respond in time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } } } } }, "/payment-agents/v1/agents/{id}": { "get": { "tags": [ "Payment Agent" ], "summary": "Get a payment agent by ID", "description": "Returns the full profile of a single payment agent, including agents not publicly listed in the directory. Use this when you already have an agent's `id` and need their full details. The response always includes a `currencies` array with the agent's commission rates and withdrawal limits for each supported currency, and a `urls` array with the agent's associated websites. Pass `me` as the `id` to return the authenticated client's own agent profile.", "operationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "security": [ { "oauth2": [ "payment" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^(?:[1-9]\\d*|me)$" }, "description": "Numeric ID of the payment agent (as returned by `GET /payment-agents/v1/agents`) or the literal string `\"me\"` to return the authenticated client's own agent profile. Any other non-numeric value returns `InvalidAgentID`." } ], "responses": { "200": { "description": "OK — full payment agent profile.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PaymentAgentDetail" }, "errors": { "type": "array", "items": {}, "description": "Empty on success." }, "metadata": { "$ref": "#/components/schemas/PAMetadata" } }, "required": [ "data", "errors", "metadata" ] } } } }, "400": { "description": "Bad request — `errors[0].code` will be one of:\n\n- `InvalidAgentID` — the `id` path parameter is not a valid numeric ID or `me`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" }, "examples": { "InvalidAgentID": { "value": { "data": {}, "errors": [ { "status": 400, "code": "InvalidAgentID" } ], "metadata": { "endpoint": "/payment-agents/v1/agents/abc", "method": "GET", "timing": 0.005 } } } } } } }, "401": { "description": "Unauthorized — missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "403": { "description": "Forbidden — valid token but insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "404": { "description": "Not found — `AgentNotFound`: no payment agent exists with the given `id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" }, "examples": { "AgentNotFound": { "value": { "data": {}, "errors": [ { "status": 404, "code": "AgentNotFound" } ], "metadata": { "endpoint": "/payment-agents/v1/agents/999999", "method": "GET", "timing": 0.012 } } } } } } }, "500": { "description": "Internal server error — `errors[0].code` will be `InternalError`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "504": { "description": "Gateway timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } } } } }, "/payment-agents/v1/agent-statistics": { "get": { "tags": [ "Payment Agent" ], "summary": "Get payment agent statistics", "description": "Returns the aggregate set of countries and currencies covered by at least one active, publicly listed payment agent. Use this to determine which `currency` and `country` filter values are meaningful before calling the agent list — results may lag newly onboarded agents by a short period.", "operationId": "c3d4e5f6-a7b8-9012-cdef-012345678902", "security": [ { "oauth2": [ "payment" ] } ], "responses": { "200": { "description": "OK — aggregated statistics.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentStatistics" }, "errors": { "type": "array", "items": {}, "description": "Empty on success." }, "metadata": { "$ref": "#/components/schemas/PAMetadata" } }, "required": [ "data", "errors", "metadata" ] } } } }, "401": { "description": "Unauthorized — missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "403": { "description": "Forbidden — valid token but insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "504": { "description": "Gateway timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } } } } }, "/payment-agents/v1/clients/me": { "get": { "tags": [ "Payment Agent" ], "summary": "Get the caller's client settings", "description": "Returns the authenticated client's current settings for using payment agents: whether they can receive deposits from payment agents, whether they can withdraw funds through a payment agent, and whether their real name is shared with agents on transactions. Clients that have never used a payment agent see defaults: `deposit_enabled: true`, `withdraw_enabled: true`, `show_real_name: false`.", "operationId": "b5c6d7e8-f9a0-1234-5678-9abcdef01234", "security": [ { "oauth2": [ "payment" ] } ], "responses": { "200": { "description": "OK — current client settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ClientSettings" }, "errors": { "type": "array", "items": {}, "description": "Empty on success." }, "metadata": { "$ref": "#/components/schemas/PAMetadata" } }, "required": [ "data", "errors", "metadata" ], "examples": [ { "data": { "deposit_enabled": true, "withdraw_enabled": true, "show_real_name": false }, "errors": [], "metadata": { "endpoint": "/payment-agents/v1/clients/me", "method": "GET", "timing": 0.018 } } ] } } } }, "401": { "description": "Unauthorized — missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "403": { "description": "Forbidden — valid token but insufficient scope (`payment` scope required).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "500": { "description": "Internal server error — `errors[0].code` will be `InternalError`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "504": { "description": "Gateway timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } } } }, "patch": { "tags": [ "Payment Agent" ], "summary": "Update the caller's client settings", "description": "Updates the authenticated client's preference for whether payment agents can see their real name on transactions. Set `show_real_name: true` to reveal it, `false` to withhold it. Returns the updated `ClientSettings`.\n\nA client's first-ever payment-agent interaction registers their account — see the 400/500 responses for errors that only apply on that first call.", "operationId": "c6d7e8f9-a0b1-2345-6789-abcdef012345", "security": [ { "oauth2": [ "payment" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Settings to update.", "properties": { "show_real_name": { "type": "boolean", "description": "New value for the privacy preference. `true` reveals the client's real name to payment agents on future transactions. `false` withholds it.", "examples": [ true ] } }, "required": [ "show_real_name" ] } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "OK — updated client settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ClientSettings" }, "errors": { "type": "array", "items": {}, "description": "Empty on success." }, "metadata": { "$ref": "#/components/schemas/PAMetadata" } }, "required": [ "data", "errors", "metadata" ], "examples": [ { "data": { "deposit_enabled": true, "withdraw_enabled": true, "show_real_name": true }, "errors": [], "metadata": { "endpoint": "/payment-agents/v1/clients/me", "method": "PATCH", "timing": 0.032 } } ] } } } }, "400": { "description": "Bad request — `errors[0].code` will be one of:\n\n- `NoClientWallet` — the client has no wallet available for payment-agent transactions (only reachable on the client's first-ever payment-agent call)\n- `InputError` — `show_real_name` is missing, or another input failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "401": { "description": "Unauthorized — missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "403": { "description": "Forbidden — valid token but insufficient scope (`payment` scope required).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "500": { "description": "Internal server error — `errors[0].code` will be one of:\n\n- `ClientIdentityLookupFailed` — the client's account details could not be retrieved (only reachable on the client's first-ever payment-agent call)\n- `WalletLookupFailed` — the client's wallet details could not be retrieved (only reachable on the client's first-ever payment-agent call)\n- `InternalError` — an unexpected error occurred\n\nThese errors are transient. Retrying the request is reasonable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "504": { "description": "Gateway timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } } } } }, "/payment-agents/v1/transfer": { "post": { "tags": [ "Payment Agent" ], "summary": "Transfer funds to a client (payment agent deposit)", "description": "Lets an authenticated payment agent deposit funds directly into a client's Deriv wallet, identified by their account nickname (`to_nickname`).\n\nOn success returns a `TransferResult` — `status: \"complete\"` with a `transaction_id` for a real transfer, `status: \"pending\"` with `transaction_id: null` when the transfer was accepted but is still being processed, or `status: \"dry_run_ok\"` with `transaction_id: null` when `dry_run: true` is set on the request. Supply a `request_id` on the request to poll a `\"pending\"` transfer via `GET /payment-agents/v1/transfer/{request_id}` — strongly recommended, since a `\"pending\"` transfer without a `request_id` cannot be tracked afterwards (`transaction_id` is `null` in that case). `client_real_name` and `client_is_agent` describe the recipient.\n\nSee the 400 response for the full list of validation and business-rule error codes.", "operationId": "d4e5f6a7-b8c9-0123-def0-123456789003", "security": [ { "oauth2": [ "payment" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Transfer parameters.", "properties": { "to_nickname": { "type": "string", "description": "Deriv account nickname of the client to receive the funds.", "examples": [ "client_nickname" ] }, "amount": { "type": "string", "pattern": "^(?:0|[1-9]\\d{0,13})(?:\\.\\d{1,18})?$", "description": "Amount to transfer expressed as a decimal string.", "examples": [ "100.00" ] }, "currency": { "type": "string", "pattern": "^[A-Z_]{1,18}$", "description": "Currency code for the transfer. Must be supported by the authenticated payment agent.", "examples": [ "USD" ] }, "notes": { "type": "string", "description": "Optional free-text notes for this transaction.", "examples": [ "Payment for services" ] }, "request_id": { "type": "string", "pattern": "^[\\w\\-]{1,128}$", "description": "Idempotency key, 1-128 characters (letters, digits, underscore, hyphen). Optional but strongly recommended: without it, a `status: \"pending\"` response cannot be tracked to a final state (`transaction_id` is `null` in that case). If provided, the transfer status can be retrieved via `GET /payment-agents/v1/transfer/{request_id}`. Reusing a previous `request_id` returns `RequestIDUsed` instead of creating a duplicate transfer.", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "dry_run": { "type": "boolean", "description": "When `true`, the request runs validation and returns success without creating a transaction. Use to preflight a transfer before committing. Response `status` will be `\"dry_run_ok\"` and `transaction_id` will be `null`. Note: `request_id` uniqueness is checked only on the real call — a `dry_run` will not fail with `RequestIDUsed` even if the `request_id` has been used before.", "examples": [ false ] } }, "required": [ "to_nickname", "amount", "currency" ] } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "OK — the transfer completed, is still being processed (pending), or was validated in dry-run mode. See `TransferResult`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TransferResult" }, "errors": { "type": "array", "items": {}, "description": "Empty on success." }, "metadata": { "$ref": "#/components/schemas/PAMetadata" } }, "required": [ "data", "errors", "metadata" ], "examples": [ { "data": { "status": "complete", "transaction_id": 123, "client_real_name": "Jane Doe", "client_is_agent": false }, "errors": [], "metadata": { "endpoint": "/payment-agents/v1/transfer", "method": "POST", "timing": 0.21 } } ] } } } }, "400": { "description": "Bad request — `errors[0].code` will be one of:\n\n- `AgentIDNotFound` — the authenticated client is not a registered payment agent\n- `AgentInactive` — the authenticated payment agent account is currently inactive\n- `AgentSelfTransfer` — the `to_nickname` provided belongs to the calling payment agent. An agent cannot transfer funds to their own account\n- `TransferToAgentNotAllowed` — the recipient is another payment agent and the calling agent is not permitted to transfer to other payment agents\n- `TransferAgentCurrencyUnsupported` — the recipient is another payment agent that does not support the transfer currency\n- `AgentCurrencyUnsupported` — the agent does not support the requested `currency`\n- `NicknameNotFound` — `to_nickname` does not match any Deriv account\n- `NoClientWallet` — the recipient account cannot receive the funds\n- `WalletDisabled` — the recipient's wallet is currently disabled\n- `DepositDisabled` — deposits to the recipient's wallet are currently disabled\n- `ClientCountryUnsupported` — the recipient's country of residence is not covered by this agent\n- `WithdrawalAmountMinimum` — `amount` is below the agent's configured minimum for this currency\n- `WithdrawalAmountMaximum` — `amount` exceeds the agent's configured maximum for this currency\n- `WalletFundsInsufficient` — the agent's wallet does not hold enough funds for this transfer\n- `DailyTransferCountLimit` — the agent has reached the maximum number of transfers allowed in 24 hours\n- `DailyTransferAmountLimit` — this transfer would exceed the maximum transfer amount allowed in 24 hours\n- `InvalidCurrency` — `currency` does not match the required format (1-18 characters, uppercase letters and underscores)\n- `InvalidAmount` — `amount` is not a valid decimal string\n- `InvalidRequestIDFormat` — `request_id` does not match the required format (1-128 characters: letters, digits, underscore, hyphen)\n- `RequestIDUsed` — the `request_id` has already been used. It must be unique per transfer\n- `InputError` — a required field is missing or another input failed validation\n- `ClientDepositDisabled` — the recipient client is not allowed to receive deposits from payment agents\n- `AgentWithdrawDisabled` — the calling agent is not allowed to withdraw from their own wallet, which is required to fund a `POST /transfer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" }, "examples": { "AgentCurrencyUnsupported": { "value": { "data": {}, "errors": [ { "status": 400, "code": "AgentCurrencyUnsupported" } ], "metadata": { "endpoint": "/payment-agents/v1/transfer", "method": "POST", "timing": 0.032 } } } } } } }, "401": { "description": "Unauthorized — missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "403": { "description": "Forbidden — valid token but insufficient scope (`payment` scope required).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "500": { "description": "Internal server error — `errors[0].code` will be one of:\n\n- `NicknameLookupFailed` — the recipient account could not be resolved from `to_nickname`\n- `WalletLookupFailed` — the recipient's wallet details could not be retrieved\n- `TransferFailed` — the transfer could not be completed\n- `InternalError` — an unexpected error occurred\n\nThese errors are transient. Retrying the request is reasonable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" }, "examples": { "InternalError": { "value": { "data": {}, "errors": [ { "status": 500, "code": "InternalError" } ], "metadata": { "endpoint": "/payment-agents/v1/transfer", "method": "POST", "timing": 0.120 } } } } } } }, "504": { "description": "Gateway timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } } } } }, "/payment-agents/v1/transfer/{request_id}": { "get": { "tags": [ "Payment Agent" ], "summary": "Get the status of a transfer", "description": "Returns the current status of a transfer previously initiated via `POST /payment-agents/v1/transfer` with a `request_id`. Both the payment agent who initiated the transfer and the receiving client can query this endpoint. Most transfers return `\"complete\"` in the initial `POST` response and don't need to be polled; when the initial response is `\"pending\"`, the status will progress to `\"complete\"`, `\"rejected\"`, or `\"failed\"`.", "operationId": "b0c1d2e3-f4a5-6789-b0c1-d2e3f4a56789", "security": [ { "oauth2": [ "payment" ] } ], "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[\\w\\-]{1,128}$" }, "description": "The `request_id` previously passed to `POST /payment-agents/v1/transfer` (1-128 characters: letters, digits, underscore, hyphen). A value that doesn't match the required format returns `InvalidRequestIDFormat`. A well-formed value that doesn't match any of your transfers returns `RequestIDNotFound`." } ], "responses": { "200": { "description": "OK — current transfer status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TransactionStatus" }, "errors": { "type": "array", "items": {}, "description": "Empty on success." }, "metadata": { "$ref": "#/components/schemas/PAMetadata" } }, "required": [ "data", "errors", "metadata" ] } } } }, "400": { "description": "Bad request — `errors[0].code` will be one of:\n\n- `InvalidRequestIDFormat` — `request_id` does not match the required format (1-128 characters: letters, digits, underscore, hyphen)\n- `RequestIDNotFound` — no transfer with this `request_id` is accessible to the authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" }, "examples": { "RequestIDNotFound": { "value": { "data": {}, "errors": [ { "status": 400, "code": "RequestIDNotFound" } ], "metadata": { "endpoint": "/payment-agents/v1/transfer/my-request-id", "method": "GET", "timing": 0.019 } } } } } } }, "401": { "description": "Unauthorized — missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "403": { "description": "Forbidden — valid token but insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "500": { "description": "Internal server error — `errors[0].code` will be `InternalError`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "504": { "description": "Gateway timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } } } } }, "/payment-agents/v1/withdraw/verification_code": { "post": { "tags": [ "Payment Agent" ], "summary": "Request a withdrawal verification code", "description": "Requests a one-time verification code be sent to the client's registered contact (email or phone). Call this before submitting a withdrawal via `POST /payment-agents/v1/withdraw` — the code must be included as `verification_code` in that request. The code is valid until `expires_at` (epoch seconds). A new code cannot be requested before `next_request_at` (epoch seconds).\n\nThe same agent-eligibility and business-rule checks that guard `POST /payment-agents/v1/withdraw` also run here — if this request succeeds, the subsequent withdrawal will not fail those checks. See the 400 response for the full list of error codes.", "operationId": "f6a7b8c9-d0e1-2345-f012-345678901005", "security": [ { "oauth2": [ "payment" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Verification code request parameters. Must match the intended withdrawal.", "properties": { "agent_id": { "type": "integer", "minimum": 1, "description": "Unique identifier of the payment agent to withdraw through, as returned by `GET /payment-agents/v1/agents`. Values below `1` are rejected with `InvalidAgentID`.", "examples": [ 42 ] }, "amount": { "type": "string", "pattern": "^(?:0|[1-9]\\d{0,13})(?:\\.\\d{1,18})?$", "description": "Intended withdrawal amount as a decimal string.", "examples": [ "50.00" ] }, "currency": { "type": "string", "pattern": "^[A-Z_]{1,18}$", "description": "Currency code for the intended withdrawal.", "examples": [ "USD" ] } }, "required": [ "agent_id", "amount", "currency" ] } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "OK — the verification code has been sent to the client's registered contact.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VerificationCodeResponse" }, "errors": { "type": "array", "items": {}, "description": "Empty on success." }, "metadata": { "$ref": "#/components/schemas/PAMetadata" } }, "required": [ "data", "errors", "metadata" ], "examples": [ { "data": { "message": "Please check your email or phone for the verification code.", "next_request_at": 1781548267, "expires_at": 1781548567 }, "errors": [], "metadata": { "endpoint": "/payment-agents/v1/withdraw/verification_code", "method": "POST", "timing": 1.049 } } ] } } } }, "400": { "description": "Bad request — `errors[0].code` will be one of:\n\n- `InvalidAgentID` — `agent_id` is less than 1\n- `AgentIDNotFound` — no payment agent exists with the given `agent_id`\n- `AgentInactive` — the target payment agent is not currently active\n- `AgentSelfWithdraw` — the authenticated client is the registered owner of the selected payment agent. A client cannot withdraw through a payment agent account they own\n- `AgentCurrencyUnsupported` — the agent does not support the requested `currency`\n- `ClientCountryUnsupported` — the client's country of residence is not covered by this agent\n- `WithdrawalAmountMinimum` — `amount` is below the agent's minimum withdrawal limit for this currency\n- `WithdrawalAmountMaximum` — `amount` exceeds the agent's maximum withdrawal limit for this currency\n- `DailyWithdrawalCountLimit` — the client has reached the maximum number of withdrawals allowed in 24 hours\n- `DailyWithdrawalAmountLimit` — this withdrawal would exceed the maximum withdrawal amount allowed in 24 hours\n- `InvalidCurrency` — `currency` does not match the required format\n- `InvalidAmount` — `amount` is not a valid decimal string\n- `OtpRateLimitExceeded` — too many verification code requests in a short period. `errors[0].detail.next_request_at` indicates when a new request can be made\n- `InputError` — a required field is missing or another input failed validation\n- `ClientWithdrawDisabled` — the calling client is not allowed to withdraw funds through a payment agent\n- `AgentDepositDisabled` — the target agent is not allowed to receive deposits into their own wallet, which is required to complete a withdrawal through them", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" }, "examples": { "OtpRateLimitExceeded": { "value": { "data": {}, "errors": [ { "status": 400, "code": "OtpRateLimitExceeded", "detail": { "message": "Too many OTP requests. Please try again later.", "next_request_at": 1781547816 } } ], "metadata": { "endpoint": "/payment-agents/v1/withdraw/verification_code", "method": "POST", "timing": 0.801 } } } } } } }, "401": { "description": "Unauthorized — missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "403": { "description": "Forbidden — valid token but insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "500": { "description": "Internal server error — `errors[0].code` will be one of:\n\n- `VerificationCodeRequestFailed` — the verification code could not be dispatched\n- `InternalError` — an unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "504": { "description": "Gateway timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } } } } }, "/payment-agents/v1/withdraw": { "post": { "tags": [ "Payment Agent" ], "summary": "Withdraw funds via a payment agent", "description": "Lets an authenticated client withdraw funds from their Deriv wallet via a payment agent. The agent is identified by `agent_id`. The withdrawal moves the requested amount out of the client's wallet and into the agent's wallet. The agent then settles the equivalent value with the client outside of Deriv.\n\nBefore calling this endpoint, request a one-time verification code via `POST /payment-agents/v1/withdraw/verification_code` and supply it as `verification_code`. The code must be 6 digits and within its validity window.\n\nSee the 400 response for the full list of validation and business-rule error codes.", "operationId": "e5f6a7b8-c9d0-1234-ef01-234567890004", "security": [ { "oauth2": [ "payment" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Withdrawal parameters.", "properties": { "agent_id": { "type": "integer", "minimum": 1, "description": "Unique identifier of the payment agent to withdraw through, as returned by `GET /payment-agents/v1/agents`. Values below `1` are rejected with `InvalidAgentID`.", "examples": [ 42 ] }, "amount": { "type": "string", "pattern": "^(?:0|[1-9]\\d{0,13})(?:\\.\\d{1,18})?$", "description": "Amount to withdraw as a decimal string. Must satisfy the agent's `withdrawal_minimum` and `withdrawal_maximum` limits for the currency.", "examples": [ "50.00" ] }, "currency": { "type": "string", "pattern": "^[A-Z_]{1,18}$", "description": "Currency code for the withdrawal. Must be supported by the target payment agent.", "examples": [ "USD" ] }, "verification_code": { "type": "string", "pattern": "^[0-9]{6}$", "description": "6-digit one-time verification code obtained from `POST /payment-agents/v1/withdraw/verification_code`.", "examples": [ "123456" ] }, "request_id": { "type": "string", "pattern": "^[\\w\\-]{1,128}$", "description": "Optional, 1-128 characters (letters, digits, underscore, hyphen). If provided, the withdrawal status can be retrieved via `GET /payment-agents/v1/withdraw/{request_id}`. Without it, status tracking is unavailable for this withdrawal. Must be unique — reusing a previous `request_id` returns `RequestIDUsed`.", "examples": [ "7842b85d-6979-4f9f-a0c7-cf2e8d122739" ] }, "notes": { "type": "string", "description": "Optional free-text notes for this transaction.", "examples": [ "Withdrawal request" ] } }, "required": [ "agent_id", "amount", "currency", "verification_code" ] } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "OK — the withdrawal was accepted. `data.status` is `\"pending\"` while the transaction processes. `data.transaction_id` identifies the transaction. Use `GET /payment-agents/v1/withdraw/{request_id}` to poll for the final status if you provided a `request_id`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TransactionStatus" }, "errors": { "type": "array", "items": {}, "description": "Empty on success." }, "metadata": { "$ref": "#/components/schemas/PAMetadata" } }, "required": [ "data", "errors", "metadata" ], "examples": [ { "data": { "status": "pending", "transaction_id": 456 }, "errors": [], "metadata": { "endpoint": "/payment-agents/v1/withdraw", "method": "POST", "timing": 0.447 } } ] } } } }, "400": { "description": "Bad request — `errors[0].code` will be one of:\n\n- `InvalidAgentID` — `agent_id` is less than 1\n- `AgentIDNotFound` — no payment agent exists with the given `agent_id`\n- `AgentInactive` — the target payment agent is currently inactive\n- `AgentSelfWithdraw` — the authenticated client is the registered owner of the selected payment agent. A client cannot withdraw through a payment agent account they own\n- `AgentCurrencyUnsupported` — the agent does not support the requested `currency`\n- `VerificationCodeFormatInvalid` — `verification_code` is not a 6-digit numeric string\n- `NoClientWallet` — the authenticated client's account has no wallet to withdraw from\n- `ClientCountryUnsupported` — the client's country of residence is not covered by this agent\n- `WithdrawalAmountMinimum` — `amount` is below the agent's minimum withdrawal limit for this currency\n- `WithdrawalAmountMaximum` — `amount` exceeds the agent's maximum withdrawal limit for this currency\n- `DailyWithdrawalCountLimit` — the client has reached the maximum number of withdrawals allowed in 24 hours\n- `DailyWithdrawalAmountLimit` — this withdrawal would exceed the maximum withdrawal amount allowed in 24 hours\n- `WalletFundsInsufficient` — the client's wallet does not hold enough funds for this withdrawal\n- `InvalidCurrency` — `currency` does not match the required format\n- `InvalidAmount` — `amount` is not a valid decimal string\n- `InvalidRequestIDFormat` — `request_id` does not match the required format (1-128 characters: letters, digits, underscore, hyphen)\n- `RequestIDUsed` — the `request_id` has already been used. It must be unique per withdrawal\n- `InvalidOTP` — the `verification_code` is incorrect. `errors[0].detail.message` contains the error message\n- `OtpValidationRateLimitExceeded` — too many incorrect verification code attempts. `errors[0].detail.message` contains the error message\n- `InputError` — a required field is missing or another input failed validation\n- `ClientWithdrawDisabled` — the calling client is not allowed to withdraw funds through a payment agent\n- `AgentDepositDisabled` — the target agent is not allowed to receive deposits into their own wallet, which is required to complete a withdrawal through them", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" }, "examples": { "AgentCurrencyUnsupported": { "value": { "data": {}, "errors": [ { "status": 400, "code": "AgentCurrencyUnsupported" } ], "metadata": { "endpoint": "/payment-agents/v1/withdraw", "method": "POST", "timing": 0.030 } } }, "InvalidOTP": { "value": { "data": {}, "errors": [ { "status": 400, "code": "InvalidOTP", "detail": { "message": "Invalid OTP" } } ], "metadata": { "endpoint": "/payment-agents/v1/withdraw", "method": "POST", "timing": 0.447 } } }, "OtpValidationRateLimitExceeded": { "value": { "data": {}, "errors": [ { "status": 400, "code": "OtpValidationRateLimitExceeded", "detail": { "message": "Too many failed OTP validation attempts. Please try after some time." } } ], "metadata": { "endpoint": "/payment-agents/v1/withdraw", "method": "POST", "timing": 0.16 } } } } } } }, "401": { "description": "Unauthorized — missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "403": { "description": "Forbidden — valid token but insufficient scope (`payment` scope required).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "500": { "description": "Internal server error — `errors[0].code` will be one of:\n\n- `ClientIdentityLookupFailed` — the authenticated client's account details could not be retrieved\n- `WalletLookupFailed` — the client's wallet details could not be retrieved\n- `WithdrawalFailed` — the withdrawal could not be completed\n- `OTPValidationFailed` — verification code validation failed unexpectedly\n- `InternalError` — an unexpected error occurred\n\nThese errors are transient. Retrying the request is reasonable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" }, "examples": { "InternalError": { "value": { "data": {}, "errors": [ { "status": 500, "code": "InternalError" } ], "metadata": { "endpoint": "/payment-agents/v1/withdraw", "method": "POST", "timing": 0.150 } } } } } } }, "504": { "description": "Gateway timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } } } } }, "/payment-agents/v1/withdraw/{request_id}": { "get": { "tags": [ "Payment Agent" ], "summary": "Get the status of a withdrawal", "description": "Returns the current status of a withdrawal previously initiated via `POST /payment-agents/v1/withdraw` with a `request_id`. Both the client who initiated the withdrawal and the payment agent can query this endpoint. The status progresses from `\"pending\"` to `\"complete\"`, `\"rejected\"`, or `\"failed\"`.", "operationId": "a9b0c1d2-e3f4-5678-a9b0-c1d2e3f45678", "security": [ { "oauth2": [ "payment" ] } ], "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[\\w\\-]{1,128}$" }, "description": "The `request_id` previously passed to `POST /payment-agents/v1/withdraw` (1-128 characters: letters, digits, underscore, hyphen). A value that doesn't match the required format returns `InvalidRequestIDFormat`. A well-formed value that doesn't match any of your withdrawals returns `RequestIDNotFound`." } ], "responses": { "200": { "description": "OK — current withdrawal status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TransactionStatus" }, "errors": { "type": "array", "items": {}, "description": "Empty on success." }, "metadata": { "$ref": "#/components/schemas/PAMetadata" } }, "required": [ "data", "errors", "metadata" ] } } } }, "400": { "description": "Bad request — `errors[0].code` will be one of:\n\n- `InvalidRequestIDFormat` — `request_id` does not match the required format (1-128 characters: letters, digits, underscore, hyphen)\n- `RequestIDNotFound` — no withdrawal with this `request_id` is accessible to the authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" }, "examples": { "RequestIDNotFound": { "value": { "data": {}, "errors": [ { "status": 400, "code": "RequestIDNotFound" } ], "metadata": { "endpoint": "/payment-agents/v1/withdraw/my-request-id", "method": "GET", "timing": 0.021 } } } } } } }, "401": { "description": "Unauthorized — missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "403": { "description": "Forbidden — valid token but insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "500": { "description": "Internal server error — `errors[0].code` will be `InternalError`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } }, "504": { "description": "Gateway timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PAErrorResponse" } } } } } } }, "/account/v1/nickname": { "get": { "tags": [ "Identity" ], "summary": "Get the nickname for the authenticated user", "description": "Returns the nickname associated with the authenticated user's identity. The brand is resolved from the `X-Brand` request header and the caller's identity is resolved from the `X-Client-ID` request header — both are set by the gateway and cannot be spoofed by the client.", "operationId": "get-pii-nickname", "security": [ { "oauth2": [ "account_manage" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NicknameResponse" }, "errors": { "type": "array", "items": {}, "description": "Empty on success." }, "metadata": { "$ref": "#/components/schemas/ResponseMetadata" } }, "required": [ "data", "errors", "metadata" ] } } } }, "400": { "description": "Bad request — missing `X-Brand` or `X-Client-Id` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized — missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — valid token but insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found — the brand could not be resolved (`BrandNotFound`) or no identity exists for the given client and brand (`IdentityNotFound`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway timeout — the service did not respond in time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/wallet/v1/wallets": { "get": { "tags": [ "Wallets" ], "summary": "List wallets for the authenticated client", "description": "Returns the list of wallets for the authenticated client, with balances in each wallet's native currency. When `conversion_currency` is supplied, each balance is additionally returned converted to that currency. `start_date_time` / `end_date_time` bound the \"balance as of\" window.", "operationId": "get-wallets", "security": [ { "oauth2": [ "payment" ] } ], "parameters": [ { "name": "conversion_currency", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{3}$", "examples": [ "USD" ] }, "description": "3-letter ISO currency code. When supplied, balance amounts are additionally returned converted to this currency." }, { "name": "start_date_time", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "integer", "minimum": 0 } ] }, "description": "ISO 8601 timestamp or epoch seconds. Lower bound of the \"balance as of\" window." }, { "name": "end_date_time", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "integer", "minimum": 0 } ] }, "description": "ISO 8601 timestamp or epoch seconds. Upper bound of the \"balance as of\" window." } ], "responses": { "200": { "description": "OK — wallets for the authenticated client, with balances in native currencies and optional conversion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletListResponse" } } } }, "400": { "description": "Bad request — `errors[0].code` will be `BadRequest`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletErrorResponse" } } } }, "401": { "description": "Unauthorized — missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletErrorResponse" } } } }, "403": { "description": "Forbidden — valid token but insufficient scope (`payment` scope required).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletErrorResponse" } } } }, "404": { "description": "Not found — `errors[0].code` will be `NotFound`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletErrorResponse" } } } }, "500": { "description": "Internal server error — `errors[0].code` will be `InternalServerError`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletErrorResponse" } } } }, "503": { "description": "Service unavailable — request rejected by the gateway circuit breaker.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletErrorResponse" } } } }, "504": { "description": "Gateway timeout — the service did not respond in time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletErrorResponse" } } } } } } }, "/wallet/v1/exchange-rate": { "get": { "tags": [ "Wallets" ], "summary": "Get an exchange-rate quote between two currencies", "description": "Returns a quote for converting between two currencies. The quote carries the exchange rate and a `rate_token`; pass both to `POST /wallet/v1/transfers/exchange` (or a cross-currency `POST /wallet/v1/transfers/platforms` request) to execute a transfer at the quoted rate.", "operationId": "get-exchange-rate", "security": [ { "oauth2": [ "payment" ] } ], "parameters": [ { "name": "source_currency", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Z0-9_]{1,18}$", "examples": [ "USD" ] }, "description": "Currency to convert from." }, { "name": "destination_currency", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Z0-9_]{1,18}$", "examples": [ "BTC" ] }, "description": "Currency to convert to." } ], "responses": { "200": { "description": "OK — quote for the requested currency pair.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeRateResponse" } } } }, "400": { "description": "Bad request — `errors[0].code` will be `ValidationError` (missing or invalid `source_currency` / `destination_currency`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "401": { "description": "Unauthorized — missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "403": { "description": "Forbidden — valid token but insufficient scope (`payment` scope required).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "429": { "description": "Too many requests — rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "500": { "description": "Internal server error — e.g. no rate available for the requested pair.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "503": { "description": "Service unavailable — request rejected by the gateway circuit breaker.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "504": { "description": "Gateway timeout — the service did not respond in time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } } } } }, "/wallet/v1/transactions/{wallet_type}": { "get": { "tags": [ "Wallets" ], "summary": "List transactions for one of the authenticated client's wallets", "description": "Returns a cursor-paginated list of transactions for the wallet identified by `wallet_type` (resolved server-side against `X-Client-ID`). Filterable by `request_id`, `transaction_currency`, and date range.\n\nEach row carries a `channel` (`cashier` or `payment_agent`) indicating how the money moved and a `category` (`deposit` or `withdrawal`) computed relative to the caller.", "operationId": "get-wallet-transactions", "security": [ { "oauth2": [ "payment" ] } ], "parameters": [ { "name": "wallet_type", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WalletType" }, "description": "Wallet type to return transactions for. Resolved server-side against the caller's `X-Client-ID`." }, { "name": "request_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by the transaction's `request_id`." }, { "name": "transaction_currency", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{3}$", "examples": [ "USD" ] }, "description": "3-letter ISO currency code. Restricts the response to transactions in this currency." }, { "name": "start_date_time", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "integer", "minimum": 0 } ] }, "description": "ISO 8601 timestamp or epoch seconds. Lower bound of the transaction window." }, { "name": "end_date_time", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "integer", "minimum": 0 } ] }, "description": "ISO 8601 timestamp or epoch seconds. Upper bound of the transaction window." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 100, "maximum": 1000, "default": 100 }, "description": "Page size. Between 100 and 1000. Defaults to 100." }, { "name": "page_cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned in `links.next` / `links.prev`. When present, other filters are ignored — the cursor encodes them." } ], "responses": { "200": { "description": "OK — cursor-paginated transactions for the requested wallet type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTransactionsResponse" } } } }, "400": { "description": "Bad request — `errors[0].code` will be `BadRequest`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletErrorResponse" } } } }, "401": { "description": "Unauthorized — missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletErrorResponse" } } } }, "403": { "description": "Forbidden — valid token but insufficient scope (`payment` scope required).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletErrorResponse" } } } }, "404": { "description": "Not found — `errors[0].code` will be `NotFound`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletErrorResponse" } } } }, "500": { "description": "Internal server error — `errors[0].code` will be `InternalServerError`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletErrorResponse" } } } }, "503": { "description": "Service unavailable — request rejected by the gateway circuit breaker.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletErrorResponse" } } } }, "504": { "description": "Gateway timeout — the service did not respond in time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletErrorResponse" } } } } } } }, "/wallet/v1/transfers": { "post": { "tags": [ "Wallets" ], "summary": "Transfer funds between two of the authenticated client's wallets", "description": "Executes a same-currency transfer between two wallets owned by the authenticated client. The transfer is validated against all business rules (transfer restrictions, amount and balance limits, minimum transfer value) and any applicable fee is deducted before execution — validate first with `POST /wallet/v1/transfers/validate` to preview the fee and net amount.\n\n`request_id` is the idempotency key: reusing a previously submitted `request_id` does not create a duplicate transfer. For cross-currency transfers use `POST /wallet/v1/transfers/exchange`; for transfers to or from trading platforms use `POST /wallet/v1/transfers/platforms`.", "operationId": "create-transfer", "security": [ { "oauth2": [ "payment" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferRequest" }, "examples": { "same_currency": { "summary": "Same-currency wallet transfer", "value": { "currency": "USD", "amount": "100.00", "source_wallet_id": "942a2f2d-1f33-4559-994e-42b403033bc6", "destination_wallet_id": "ef4b3abd-c05e-42ea-a3f2-021ec69e1580", "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "description": "Move funds to P2P wallet" } } } } } }, "responses": { "200": { "description": "OK — transfer executed. `data` carries the executed transfer details and echoes the request's `request_id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferExecuteResponse" } } } }, "400": { "description": "Bad request — `errors[0].code` is `ValidationError` for malformed input (the offending field is named in `field`) or `BadRequest` for a business-rule rejection (e.g. transfer restricted for the client, insufficient balance, amount below the minimum).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "401": { "description": "Unauthorized — missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "403": { "description": "Forbidden — valid token but insufficient scope (`payment` scope required), one of the wallets does not belong to the authenticated client, or transfers are restricted for the client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "429": { "description": "Too many requests — rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "500": { "description": "Internal server error — the transfer could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "503": { "description": "Service unavailable — request rejected by the gateway circuit breaker.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "504": { "description": "Gateway timeout — the service did not respond in time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } } } } }, "/wallet/v1/transfers/exchange": { "post": { "tags": [ "Wallets" ], "summary": "Transfer funds between wallets in different currencies", "description": "Executes a cross-currency transfer between two wallets owned by the authenticated client, converting `amount` from `source_currency` to `destination_currency` at the quoted `exchange_rate`. The transfer is validated against all business rules and any applicable currency-exchange fee is deducted before execution — validate first with `POST /wallet/v1/transfers/validate` to preview the fee and estimated destination amount.\n\n`exchange_rate` and `rate_token` come from an exchange-rate quote obtained beforehand; `rate_token` attests that the rate being executed is the one that was quoted. `request_id` is the idempotency key: reusing a previously submitted `request_id` does not create a duplicate transfer.", "operationId": "create-exchange-transfer", "security": [ { "oauth2": [ "payment" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeTransferRequest" }, "examples": { "cross_currency": { "summary": "USD to BTC transfer", "value": { "source_wallet_id": "942a2f2d-1f33-4559-994e-42b403033bc6", "source_currency": "USD", "amount": "100.00", "destination_wallet_id": "ef4b3abd-c05e-42ea-a3f2-021ec69e1580", "destination_currency": "BTC", "exchange_rate": "0.0000095238", "rate_token": "eyJhbGciOi...", "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "description": "Convert USD to BTC" } } } } } }, "responses": { "200": { "description": "OK — transfer executed. `data` carries the executed transfer details and echoes the request's `request_id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferExecuteResponse" } } } }, "400": { "description": "Bad request — `errors[0].code` is `ValidationError` for malformed input, `BadRequest` for a business-rule rejection, or `DailyLimitError` / `MinimumAmountError` / `TransactionLimitError` when a transfer limit is breached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "401": { "description": "Unauthorized — missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "403": { "description": "Forbidden — valid token but insufficient scope (`payment` scope required), one of the wallets does not belong to the authenticated client, or transfers are restricted for the client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "429": { "description": "Too many requests — rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "500": { "description": "Internal server error — the transfer could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "503": { "description": "Service unavailable — request rejected by the gateway circuit breaker.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "504": { "description": "Gateway timeout — the service did not respond in time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } } } } }, "/wallet/v1/transfers/platforms": { "post": { "tags": [ "Wallets" ], "summary": "Transfer funds between a wallet and a trading platform account", "description": "Executes a transfer between one of the authenticated client's wallets and one of their trading platform accounts. `direction` controls the flow: `from_wallet` debits the wallet to fund the platform account, `to_wallet` debits the platform account to fund the wallet. `currency` is the platform account's currency and must match it.\n\nThe transfer is validated against all business rules and any applicable fee is deducted before execution — validate first with `POST /wallet/v1/transfers/validate` to preview the fee and net amount.\n\nCross-currency platform transfers are supported by additionally sending `wallet_currency` (the wallet's currency) together with `exchange_rate` and `rate_token` from an exchange-rate quote. `request_id` is the idempotency key: reusing a previously submitted `request_id` is rejected with `DuplicateRequestID`.", "operationId": "create-platform-transfer", "security": [ { "oauth2": [ "payment" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformTransferRequest" }, "examples": { "from_wallet": { "summary": "Fund an MT5 account from a wallet", "value": { "wallet_id": "942a2f2d-1f33-4559-994e-42b403033bc6", "amount": "100.00", "currency": "USD", "direction": "from_wallet", "platform_name": "mt5", "platform_account_id": "MTR9000001", "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "description": "Fund MT5 account" } }, "to_wallet": { "summary": "Withdraw from a platform account to a wallet", "value": { "wallet_id": "942a2f2d-1f33-4559-994e-42b403033bc6", "amount": "50.00", "currency": "USD", "direction": "to_wallet", "platform_name": "ctrader", "platform_account_id": "CTR9000002", "request_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901" } } } } } }, "responses": { "200": { "description": "OK — transfer executed. `data.status` carries the transfer status details and `data.request_id` echoes the request's `request_id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformTransferExecuteResponse" } } } }, "400": { "description": "Bad request — `errors[0].code` is `ValidationError` for malformed input, `BadRequest` for a business-rule rejection, `WalletFundsInsufficient` when the wallet balance cannot cover the transfer, or `DuplicateRequestID` when `request_id` has already been used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "401": { "description": "Unauthorized — missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "403": { "description": "Forbidden — valid token but insufficient scope (`payment` scope required), the wallet or platform account does not belong to the authenticated client, the platform account currency does not match `currency`, or transfers are restricted for the client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "429": { "description": "Too many requests — rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "500": { "description": "Internal server error — the transfer could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "503": { "description": "Service unavailable — request rejected by the gateway circuit breaker.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "504": { "description": "Gateway timeout — the service did not respond in time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } } } } }, "/wallet/v1/transfers/validate": { "post": { "tags": [ "Wallets" ], "summary": "Validate a transfer between the authenticated client's accounts", "description": "Performs a dry-run validation of a transfer between two of the authenticated client's accounts without moving any funds. The transfer is checked against all business rules — transfer-type compatibility, client and country restrictions, amount and balance limits, and the minimum transfer value — and, when valid, the response carries the fee that would be charged and the estimated amount the destination would receive.\n\nFor cross-currency transfers (`source_currency` differs from `destination_currency`), `rate` is required. A `200` response means the transfer is valid as of now; executing it is a separate operation.", "operationId": "validate-transfer", "security": [ { "oauth2": [ "payment" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationRequest" }, "examples": { "same_currency": { "summary": "Same-currency transfer", "value": { "source_type": "main", "destination_type": "p2p", "source_id": "942a2f2d-1f33-4559-994e-42b403033bc6", "destination_id": "ef4b3abd-c05e-42ea-a3f2-021ec69e1580", "amount": "100.00", "balance": "250.00", "source_currency": "USD", "destination_currency": "USD" } }, "cross_currency": { "summary": "Cross-currency transfer", "value": { "source_type": "main", "destination_type": "main", "source_id": "942a2f2d-1f33-4559-994e-42b403033bc6", "destination_id": "ef4b3abd-c05e-42ea-a3f2-021ec69e1580", "amount": "100.00", "balance": "250.00", "source_currency": "USD", "destination_currency": "BTC", "rate": "0.0000095238" } } } } } }, "responses": { "200": { "description": "OK — the transfer is valid. `data.details` carries the fee and amount breakdown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationResponse" } } } }, "400": { "description": "Bad request — `errors[0].code` is `ValidationError` for malformed input (the offending field is named in `field`), `BadRequest` for a business-rule rejection (e.g. transfer type not allowed, transfer restricted for the client or their country of residence, cross-currency not allowed, amount below the minimum), or `CurrencyNotAllowed` when the destination payment agent does not accept the currency.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "401": { "description": "Unauthorized — missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "403": { "description": "Forbidden — valid token but insufficient scope (`payment` scope required), or transfers are restricted for the client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "429": { "description": "Too many requests — rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "500": { "description": "Internal server error — e.g. exchange rate unavailable for the requested currencies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "503": { "description": "Service unavailable — request rejected by the gateway circuit breaker.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } }, "504": { "description": "Gateway timeout — the service did not respond in time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferValidationErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://oauth.deriv.com/oauth2/authorize", "tokenUrl": "https://oauth.deriv.com/oauth2/token", "scopes": { "trade": "Access to trading operations", "account_manage": "Write access for account creation and management", "application_read": "Read-only access to your registered applications", "payment": "Access to payment agent deposit and withdrawal operations" } } } } }, "schemas": { "AppMarkupBreakdownRow": { "type": "object", "description": "Per-application aggregates included in the statistics window.", "properties": { "app_id": { "type": "string", "description": "Third-party application identifier" }, "app_markup_usd": { "type": "number", "format": "double", "description": "Sum of application markup attributed to this app in USD over the requested interval." }, "volume_usd": { "type": "number", "format": "double", "description": "Sum of contract volume (buy price in USD terms) for this app over the requested interval." }, "payout_usd": { "type": "number", "format": "double", "description": "Sum of all potential payouts in USD terms for this app over the requested interval." }, "contract_count": { "type": "integer", "format": "uint64", "description": "Number of contracts included in the aggregates for this app." }, "client_count": { "type": "integer", "format": "uint64", "description": "Number of distinct client accounts that traded under this app in the interval." } }, "required": [ "app_id", "app_markup_usd", "volume_usd", "payout_usd", "contract_count", "client_count" ] }, "AppMarkupStatistics": { "type": "object", "description": "Markup and trading aggregates for the caller's applications over the requested date range. Root fields sum across all included apps; `breakdown` lists the same metrics per application.", "properties": { "total_app_markup_usd": { "type": "number", "format": "double", "description": "Sum of application markup attributed to all included apps in the interval." }, "total_volume_usd": { "type": "number", "format": "double", "description": "Sum of contract volume (buy price in USD terms) across all included apps in the interval." }, "total_payout_usd": { "type": "number", "format": "double", "description": "Sum of all potential payouts (in USD terms) across all included apps in the interval." }, "total_contract_count": { "type": "integer", "format": "uint64", "description": "Total number of contracts counted toward the aggregates across all included apps." }, "total_client_count": { "type": "integer", "format": "uint64", "description": "Number of distinct client accounts that traded under any included app in the interval." }, "breakdown": { "type": "array", "description": "Per-application rows; each entry corresponds to one `app_id` with metrics for that app only.", "items": { "$ref": "#/components/schemas/AppMarkupBreakdownRow" } } }, "required": [ "total_app_markup_usd", "total_volume_usd", "total_payout_usd", "total_contract_count", "total_client_count", "breakdown" ] }, "LegacyAccountItem": { "type": "object", "description": "A single account from the legacy platform.", "properties": { "account_id": { "type": "integer", "format": "int64", "description": "Legacy account identifier." }, "currency": { "type": "string", "description": "Account currency code (e.g. USD, BTC)." } }, "required": [ "account_id", "currency" ] }, "LegacyAccountsResponse": { "type": "object", "description": "Legacy accounts grouped by loginid. Loginids with no resolvable accounts are omitted.", "properties": { "loginids": { "type": "object", "description": "Map of loginid (e.g. CR0001) to its accounts.", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/LegacyAccountItem" } } } }, "required": [ "loginids" ] }, "LegacyMigrationStatusResponse": { "type": "object", "description": "Current state of the user's platform upgrade. All known states (including pending, failed, and not_applicable) are returned with HTTP 200.", "properties": { "status": { "type": "string", "enum": [ "complete", "pending", "failed", "not_applicable" ], "description": "Migration lifecycle state." } }, "required": [ "status" ] }, "LegacyTransactionItem": { "type": "object", "description": "A single historical transaction from the legacy platform for the requested loginid's default account.", "properties": { "transaction_id": { "type": "integer", "format": "int64", "description": "Unique transaction identifier." }, "account_id": { "type": "integer", "format": "int64", "description": "Legacy account identifier (the default account of the requested loginid)." }, "loginid": { "type": "string", "description": "Legacy client loginid as requested (e.g. CR12345)." }, "action_type": { "type": "string", "enum": [ "buy", "sell", "deposit", "withdrawal", "transfer", "hold", "release", "adjustment", "escrow" ], "description": "Transaction type." }, "amount": { "type": [ "string", "null" ], "description": "Signed transaction amount as a decimal string." }, "balance_after": { "type": [ "string", "null" ], "description": "Account balance after the transaction as a decimal string." }, "transaction_time": { "type": [ "integer", "null" ], "format": "int64", "description": "Transaction timestamp as epoch seconds, computed as the floor of the underlying high-precision database timestamp. Supplying this value as `date_from` on a subsequent request always re-includes the originating row." }, "contract_id": { "type": [ "integer", "null" ], "format": "int64", "description": "Financial market bet ID; null for non-trading transactions." }, "currency": { "type": [ "string", "null" ], "description": "Account currency code (the default account's currency)." }, "shortcode": { "type": [ "string", "null" ], "description": "Legacy contract shortcode; null for non-trading transactions." }, "bet_class": { "type": [ "string", "null" ], "description": "Bet class (e.g. higher_lower_bet, digit_bet, multiplier); null for non-trading transactions." }, "bet_type": { "type": [ "string", "null" ], "description": "Bet type (e.g. CALL, PUT, DIGITOVER); null for non-trading transactions." }, "symbol": { "type": [ "string", "null" ], "description": "Underlying market symbol (e.g. R_100, frxEURUSD); null for non-trading transactions." }, "app_id": { "type": [ "integer", "null" ], "format": "int64", "description": "Identifier of the third-party application that originated the transaction; null if not recorded." } }, "required": [ "transaction_id", "account_id", "loginid", "action_type" ] }, "LegacyStatementResponse": { "type": "object", "description": "Statement of historical transactions from the legacy platform for the requested loginid's default account, ordered by `transaction_time` descending (ties broken by `id` descending).", "properties": { "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/LegacyTransactionItem" } }, "count": { "type": "integer", "description": "Number of items in `transactions` (equals `transactions.length`). Not a total across pages." } }, "required": [ "transactions", "count" ] }, "Metadata": { "type": "object", "properties": { "endpoint": { "type": "string", "description": "The current endpoint", "examples": [ "/trading/v1/options/accounts" ] }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "DELETE" ], "description": "The current HTTP request method", "examples": [ "GET" ] }, "timing": { "type": "integer", "format": "uint64", "description": "Time for the API to serve the request in milliseconds.", "examples": [ 222 ] } }, "required": [ "endpoint", "method", "timing" ] }, "Error": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "integer", "format": "int32", "default": 400, "description": "HTTP-equivalent status code for this error entry." }, "code": { "type": "string", "enum": [ "ValidationError", "FieldIsRequired", "Unauthorized", "RateLimit", "BadInputRequest", "InternalServerError", "AccountNotFound", "AccessDenied", "UnauthorizedAccess" ], "description": "One of the predefined error codes.", "examples": [ "ValidationError" ] }, "message": { "type": "string", "description": "Human-readable description of the error. Intended for logs and developer-facing surfaces; not guaranteed stable across versions." }, "field": { "type": "string", "description": "Request element that caused the error (query param name, path param name, header name, or dot-joined body path). Omitted when not attributable to a single field." } }, "required": [ "status", "code", "message" ] }, "description": "List of Errors from the request" }, "meta": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "meta", "errors" ] }, "OptionsAccount": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID", "examples": [ "DOT90004580" ] }, "balance": { "type": "number", "description": "Account balance", "examples": [ 10000 ] }, "currency": { "type": "string", "description": "Account currency", "examples": [ "USD" ] }, "group": { "type": "string", "description": "Account group", "examples": [ "row" ] }, "status": { "type": "string", "description": "Account status", "enum": [ "active", "inactive" ], "examples": [ "active" ] }, "account_type": { "type": "string", "description": "Account type", "enum": [ "demo", "real" ], "examples": [ "demo" ] } }, "required": [ "account_id", "balance", "currency", "group", "status", "account_type" ] }, "PartnerAnalyticsPeriod": { "type": "object", "properties": { "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" } }, "required": [ "start_date", "end_date" ] }, "PartnerAnalyticsSignupCard": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0 }, "real_accounts": { "type": "integer", "minimum": 0 }, "first_time_depositors": { "type": "integer", "minimum": 0 }, "first_time_traders": { "type": "integer", "minimum": 0 } }, "required": [ "total", "real_accounts", "first_time_depositors", "first_time_traders" ] }, "PartnerAnalyticsMasterPartnerCard": { "type": "object", "properties": { "earnings_occurred": { "type": "number", "format": "double", "description": "Master-partner earnings attributed to the reporting period, in USD." }, "active_subpartners": { "type": "integer", "minimum": 0 } }, "required": [ "earnings_occurred", "active_subpartners" ] }, "PartnerAnalyticsActivityCard": { "type": "object", "properties": { "paid": { "type": "number", "format": "double", "description": "Paid partner commission for the reporting period, in USD." }, "pending": { "type": "number", "format": "double", "description": "Pending partner commission for the reporting period, in USD." }, "active_traders": { "type": "integer", "minimum": 0 } }, "required": [ "paid", "pending", "active_traders" ] }, "PartnerAnalyticsOverviewResponse": { "type": "object", "properties": { "period": { "$ref": "#/components/schemas/PartnerAnalyticsPeriod" }, "currency": { "type": "string", "const": "USD", "default": "USD" }, "has_lifetime_referred_client": { "type": "boolean" }, "signups": { "$ref": "#/components/schemas/PartnerAnalyticsSignupCard" }, "master_partner": { "$ref": "#/components/schemas/PartnerAnalyticsMasterPartnerCard" }, "activity": { "$ref": "#/components/schemas/PartnerAnalyticsActivityCard" } }, "required": [ "period", "currency", "has_lifetime_referred_client", "signups", "master_partner", "activity" ] }, "PartnerClientTagCheckRequest": { "type": "object", "properties": { "client_ids": { "type": "array", "description": "Client IDs to check. Numeric, UUID, and alphanumeric external ID values are supported.", "minItems": 1, "maxItems": 100, "items": { "type": "string" } } }, "required": [ "client_ids" ] }, "PartnerClientTagCheckItem": { "type": "object", "properties": { "client_id": { "type": "string", "description": "Sanitized client ID from the request." }, "is_tagged": { "type": "boolean", "description": "Whether the client is directly tagged to the authenticated partner." } }, "required": [ "client_id", "is_tagged" ] }, "PartnerClientTagCheckResponse": { "type": "object", "properties": { "partner_id": { "type": "integer", "description": "Resolved partner member ID." }, "total_checked": { "type": "integer", "minimum": 0 }, "tagged_count": { "type": "integer", "minimum": 0 }, "clients": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerClientTagCheckItem" } } }, "required": [ "partner_id", "total_checked", "tagged_count", "clients" ] }, "PAMetadata": { "type": "object", "description": "Request metadata included in every response.", "properties": { "endpoint": { "type": "string", "description": "The request URI." }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH" ], "description": "The HTTP method used for the request." }, "timing": { "type": "number", "description": "Time in seconds for the service to process the request." } }, "required": [ "endpoint", "method", "timing" ] }, "PAErrorDetail": { "type": "object", "description": "Additional context for specific error codes. `message` is always present. `next_request_at` is included for rate-limit errors to indicate when the operation can be retried.", "properties": { "message": { "type": "string", "description": "Human-readable description of the error condition.", "examples": [ "Invalid OTP" ] }, "next_request_at": { "type": "integer", "description": "Epoch timestamp (seconds) after which the operation may be retried. Present only on rate-limit errors.", "examples": [ 1781547816 ] } }, "required": [ "message" ] }, "PAErrorItem": { "type": "object", "description": "A single error entry. Every entry carries an HTTP-equivalent `status` and a machine-readable `code`. Some errors include a `detail` object with additional context — see individual endpoint documentation.", "properties": { "status": { "type": "integer", "description": "HTTP-equivalent status code for this error." }, "code": { "type": "string", "description": "Machine-readable error code identifying what went wrong.", "enum": [ "AgentIDNotFound", "AgentNotFound", "AgentInactive", "AgentSelfTransfer", "AgentSelfWithdraw", "AgentCurrencyUnsupported", "TransferAgentCurrencyUnsupported", "TransferToAgentNotAllowed", "InvalidAgentID", "InvalidCurrency", "InvalidCountry", "InvalidAmount", "NicknameNotFound", "NicknameLookupFailed", "NoClientWallet", "WalletLookupFailed", "WalletDisabled", "DepositDisabled", "ClientCountryUnsupported", "ClientIdentityLookupFailed", "WithdrawalAmountMinimum", "WithdrawalAmountMaximum", "DailyTransferCountLimit", "DailyTransferAmountLimit", "DailyWithdrawalCountLimit", "DailyWithdrawalAmountLimit", "WalletFundsInsufficient", "TransferFailed", "WithdrawalFailed", "VerificationCodeFormatInvalid", "OtpRateLimitExceeded", "InvalidOTP", "OtpValidationRateLimitExceeded", "OTPValidationFailed", "VerificationCodeRequestFailed", "RequestIDUsed", "RequestIDNotFound", "InvalidRequestIDFormat", "InputError", "InternalError", "ClientWithdrawDisabled", "ClientDepositDisabled", "AgentWithdrawDisabled", "AgentDepositDisabled" ] }, "detail": { "$ref": "#/components/schemas/PAErrorDetail" } }, "required": [ "status", "code" ] }, "PAErrorResponse": { "type": "object", "description": "Standard error envelope. `data` is empty. `errors` contains one entry describing what went wrong.", "properties": { "data": { "type": "object", "description": "Always an empty object on error.", "examples": [ {} ] }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/PAErrorItem" }, "description": "One or more error entries." }, "metadata": { "$ref": "#/components/schemas/PAMetadata" } }, "required": [ "data", "errors", "metadata" ] }, "VerificationCodeResponse": { "type": "object", "description": "Confirmation that a one-time verification code has been dispatched to the client's registered contact.", "properties": { "message": { "type": "string", "description": "Confirmation message indicating where to look for the code.", "examples": [ "Please check your email or phone for the verification code." ] }, "next_request_at": { "type": "integer", "description": "Epoch timestamp (seconds) before which a new verification code cannot be requested.", "examples": [ 1781548267 ] }, "expires_at": { "type": "integer", "description": "Epoch timestamp (seconds) after which the verification code is no longer valid.", "examples": [ 1781548567 ] } }, "required": [ "message", "next_request_at", "expires_at" ] }, "ClientSettings": { "type": "object", "description": "The client's current settings for using payment agents. Returned by `GET /clients/me` and `PATCH /clients/me`.", "properties": { "deposit_enabled": { "type": "boolean", "description": "Whether the client can currently receive deposits from payment agents (i.e. be the recipient of a `POST /transfer` call)." }, "withdraw_enabled": { "type": "boolean", "description": "Whether the client can currently withdraw funds through a payment agent (`POST /withdraw`)." }, "show_real_name": { "type": "boolean", "description": "Whether payment agents see the client's real name on transactions with them. `false` withholds the real name." } }, "required": [ "deposit_enabled", "withdraw_enabled", "show_real_name" ] }, "AgentCurrencyItem": { "type": "object", "description": "Commission rates and withdrawal limits for a single currency supported by a payment agent.", "properties": { "currency": { "type": "string", "description": "Currency code.", "examples": [ "USD" ] }, "deposit_commission": { "type": [ "number", "null" ], "description": "Commission percentage charged by the agent on deposits. Null if no deposit commission applies.", "examples": [ 1.5 ] }, "withdrawal_commission": { "type": [ "number", "null" ], "description": "Commission percentage charged by the agent on withdrawals. Null if no withdrawal commission applies.", "examples": [ 2.0 ] }, "withdrawal_minimum": { "type": [ "string", "null" ], "description": "Minimum withdrawal amount as a decimal string. Null if no minimum is enforced.", "examples": [ "10.00" ] }, "withdrawal_maximum": { "type": [ "string", "null" ], "description": "Maximum withdrawal amount as a decimal string. Null if no maximum is enforced.", "examples": [ "1000.00" ] } }, "required": [ "currency" ] }, "PaymentAgentListItem": { "type": "object", "description": "Payment agent summary as returned by the list endpoint. Commission fields reflect the rates for the `currency` used in the query.", "properties": { "id": { "type": "integer", "description": "Unique identifier of the payment agent. Pass this as `agent_id` to `POST /payment-agents/v1/withdraw`.", "examples": [ 42 ] }, "created_at": { "type": "integer", "description": "Epoch timestamp (milliseconds) when the agent was registered.", "examples": [ 1717000000000 ] }, "is_listed": { "type": "boolean", "description": "Whether the agent appears in the public agent directory. `false` indicates this agent was included because you've previously received a transfer from them, not because they're publicly listed." }, "name": { "type": [ "string", "null" ], "description": "Display name of the payment agent.", "examples": [ "Agent One" ] }, "nickname": { "type": [ "string", "null" ], "description": "Short display handle for the payment agent." }, "information": { "type": [ "string", "null" ], "description": "Free-text description of the agent's services and operating details." }, "email": { "type": [ "string", "null" ], "description": "Contact email address of the payment agent." }, "phone_numbers": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Contact phone numbers." }, "payment_methods": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Payment methods accepted by this agent (e.g. `\"bank_transfer\"`, `\"mobile_money\"`)." }, "countries": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "ISO 3166-1 alpha-2 country codes in lowercase in which this agent operates." }, "urls": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Website links for the agent." }, "deposit_commission": { "type": [ "number", "null" ], "description": "Commission rate for deposits in the queried currency." }, "withdrawal_commission": { "type": [ "number", "null" ], "description": "Commission rate for withdrawals in the queried currency." }, "withdrawal_minimum": { "type": [ "string", "null" ], "description": "Minimum withdrawal amount as a decimal string for the queried currency." }, "withdrawal_maximum": { "type": [ "string", "null" ], "description": "Maximum withdrawal amount as a decimal string for the queried currency." } }, "required": [ "id" ] }, "PaymentAgentDetail": { "type": "object", "description": "Full payment agent profile returned by `GET /payment-agents/v1/agents/{id}`. Always includes a `currencies` array (one entry per supported currency with commission and limit settings) and a `urls` array. Unlike the list endpoint, this may include agents not publicly listed in the directory.", "properties": { "id": { "type": "integer", "description": "Unique identifier of the payment agent.", "examples": [ 42 ] }, "cashier_withdraw": { "type": "boolean", "description": "Whether the agent is allowed to withdraw from the payment agent wallet (only returned when viewing own profile)." }, "transfer_to_pa": { "type": "boolean", "description": "Whether the agent is permitted to transfer funds to other payment agents (only returned when viewing own profile)." }, "created_at": { "type": "integer", "description": "Epoch timestamp (milliseconds) when the agent was registered.", "examples": [ 1717000000000 ] }, "is_listed": { "type": "boolean", "description": "Whether the agent appears in the public agent directory." }, "name": { "type": [ "string", "null" ], "description": "Display name of the payment agent.", "examples": [ "Agent One" ] }, "nickname": { "type": [ "string", "null" ], "description": "Short display handle for the payment agent." }, "information": { "type": [ "string", "null" ], "description": "Free-text description of the agent's services and operating details." }, "email": { "type": [ "string", "null" ], "description": "Contact email address." }, "phone_numbers": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Contact phone numbers." }, "payment_methods": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Payment methods accepted by this agent." }, "countries": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "ISO 3166-1 alpha-2 country codes in lowercase in which this agent operates." }, "urls": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Website URLs associated with the agent. May be null when the agent has no registered URLs." }, "currencies": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCurrencyItem" }, "description": "Commission and limit settings for each currency the agent supports." }, "deposit_enabled": { "type": "boolean", "description": "Whether the agent is allowed to perform deposits to their own wallet (only returned when viewing own profile)." }, "withdraw_enabled": { "type": "boolean", "description": "Whether the agent is allowed to perform withdrawals from their own wallet (only returned when viewing own profile)." } }, "required": [ "id", "urls", "currencies" ] }, "AgentStatistics": { "type": "object", "description": "Lists all countries and currencies currently covered by at least one active payment agent. Use these values to discover valid options for the `currency` and `country` parameters when listing agents. Results may not immediately reflect newly added agents.", "properties": { "available_countries": { "type": "array", "items": { "type": "string" }, "description": "ISO 3166-1 alpha-2 country codes in lowercase covered by at least one active payment agent.", "examples": [ [ "au", "id", "ng", "pk" ] ] }, "available_currencies": { "type": "array", "items": { "type": "string" }, "description": "Sorted, deduplicated list of currency codes supported by at least one active payment agent.", "examples": [ [ "EUR", "IDR", "NGN", "USD" ] ] } }, "required": [ "available_countries", "available_currencies" ] }, "TransactionStatus": { "type": "object", "description": "Transaction status returned by the withdrawal endpoint and by the transfer/withdrawal status endpoints.", "properties": { "status": { "type": "string", "enum": [ "requested", "pending", "complete", "rejected", "failed" ], "description": "Current status of the transaction. Withdrawals start as `\"pending\"` and eventually move to `\"complete\"`, `\"rejected\"`, or `\"failed\"` if it could not be processed. Transfers may also return `\"pending\"` when they cannot complete immediately. `\"requested\"` is a transient state that callers are unlikely to see.", "examples": [ "pending" ] }, "transaction_id": { "type": [ "integer", "null" ], "description": "Identifier of the transaction. May be null while the transaction is still being processed or if it did not complete successfully. If you supplied a `request_id`, use `GET /payment-agents/v1/withdraw/{request_id}` or `GET /payment-agents/v1/transfer/{request_id}` to track status independently of `transaction_id`.", "examples": [ 123 ] } }, "required": [ "status", "transaction_id" ] }, "TransferResult": { "type": "object", "description": "Result of a `POST /payment-agents/v1/transfer` call.", "properties": { "status": { "type": "string", "enum": [ "complete", "pending", "dry_run_ok" ], "description": "`\"complete\"` when a real transfer was executed. `\"pending\"` when the transfer was accepted but is still being processed — use `GET /payment-agents/v1/transfer/{request_id}` with the supplied `request_id` to poll for the final status. `\"dry_run_ok\"` when `dry_run: true` was set on the request and only validation was performed.", "examples": [ "complete" ] }, "transaction_id": { "type": [ "integer", "null" ], "description": "Identifier of the created transaction. `null` when `status` is `\"dry_run_ok\"` or `\"pending\"`.", "examples": [ 123 ] }, "client_real_name": { "type": [ "string", "null" ], "description": "Recipient's real name. Returned when the recipient has chosen to share it by setting `show_real_name: true` via `PATCH /payment-agents/v1/clients/me`. `null` if they've kept their name private, or if their name cannot be resolved.", "examples": [ "Jane Doe" ] }, "client_is_agent": { "type": "boolean", "description": "Whether the recipient is itself another payment agent. `true` for transfers between two payment agents, `false` for a transfer to a regular client.", "examples": [ false ] } }, "required": [ "status", "transaction_id", "client_real_name", "client_is_agent" ] }, "ResponseMetadata": { "type": "object", "description": "Request metadata included in every response.", "properties": { "endpoint": { "type": "string", "description": "The request URI." }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH" ], "description": "The HTTP method used for the request." }, "timing": { "type": "number", "description": "Time in seconds for the service to process the request." } }, "required": [ "endpoint", "method", "timing" ] }, "ErrorItem": { "type": "object", "description": "A single error entry.", "properties": { "status": { "type": "integer", "description": "HTTP-equivalent status code for this error." }, "code": { "type": "string", "description": "Machine-readable error code identifying what went wrong.", "enum": [ "BrandNotFound", "IdentityNotFound", "InputError", "InternalError" ] }, "message": { "type": "string", "description": "Human-readable description of the error condition." } }, "required": [ "status", "code" ] }, "ErrorResponse": { "type": "object", "description": "Standard error envelope. `data` is empty. `errors` contains one entry describing what went wrong.", "properties": { "data": { "type": "object", "description": "Always an empty object on error.", "examples": [ {} ] }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorItem" }, "description": "One or more error entries." }, "metadata": { "$ref": "#/components/schemas/ResponseMetadata" } }, "required": [ "data", "errors", "metadata" ] }, "NicknameResponse": { "type": "object", "description": "Nickname data for the authenticated user's identity.", "properties": { "external_reference_id": { "type": "string", "format": "uuid", "description": "The external reference ID for this Identity." }, "nickname": { "type": "string", "description": "The nickname associated with this Identity." } }, "required": [ "external_reference_id", "nickname" ] }, "WalletCurrencyBalance": { "type": "object", "description": "Balance figures for a single currency within a wallet. All amounts are decimal strings to preserve precision.", "properties": { "balance": { "type": "string", "description": "Current balance in this currency.", "examples": [ "1993.2" ] }, "input": { "type": "string", "description": "Cumulative amount credited to the wallet in this currency.", "examples": [ "2283.2" ] }, "output": { "type": "string", "description": "Cumulative amount debited from the wallet in this currency.", "examples": [ "290" ] } }, "required": [ "balance", "input", "output" ] }, "Wallet": { "type": "object", "description": "A single wallet belonging to the authenticated client.", "properties": { "wallet_id": { "type": "string", "format": "uuid", "description": "Wallet identifier.", "examples": [ "942a2f2d-1f33-4559-994e-42b403033bc6" ] }, "type": { "type": "string", "description": "Wallet type.", "examples": [ "main" ] }, "balances": { "type": "object", "description": "Balances keyed by 3-letter ISO currency code.", "additionalProperties": { "$ref": "#/components/schemas/WalletCurrencyBalance" } }, "total_balance": { "$ref": "#/components/schemas/WalletTotalBalance", "description": "Only present when `conversion_currency` is set on the request. Shows the wallet's balances summed and converted into the requested currency." } }, "required": [ "wallet_id", "type", "balances" ] }, "WalletTotalBalance": { "type": "object", "description": "Aggregate balances for a single wallet converted into the currency requested via `conversion_currency`. Amounts are approximate because FX rates fluctuate.", "properties": { "converted_to": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency the totals were converted into — echoes the request's `conversion_currency`.", "examples": [ "USD" ] }, "approximate_total_balance": { "type": "string", "description": "Sum of all currency balances converted into `converted_to`.", "examples": [ "345.57598013272" ] }, "approximate_total_input": { "type": "string", "description": "Sum of all currency inputs converted into `converted_to`.", "examples": [ "382.57598013272" ] }, "approximate_total_output": { "type": "string", "description": "Sum of all currency outputs converted into `converted_to`.", "examples": [ "37" ] } }, "required": [ "converted_to", "approximate_total_balance", "approximate_total_input", "approximate_total_output" ] }, "WalletErrorItem": { "type": "object", "description": "A single error entry.", "properties": { "status": { "type": "integer", "description": "HTTP-equivalent status code for this error." }, "code": { "type": "string", "description": "Machine-readable error code identifying what went wrong.", "enum": [ "BadRequest", "Unauthorized", "NotFound", "InternalServerError" ] }, "message": { "type": "string", "description": "Human-readable description of the error condition." } }, "required": [ "status", "code" ] }, "WalletErrorResponse": { "type": "object", "description": "Standard error envelope. `errors` contains one or more entries describing what went wrong.", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/WalletErrorItem" }, "description": "One or more error entries." } }, "required": [ "errors" ] }, "WalletListResponse": { "type": "object", "description": "Successful wallet list response for the authenticated client.", "properties": { "data": { "type": "array", "description": "One entry per wallet owned by the authenticated client.", "items": { "$ref": "#/components/schemas/Wallet" } } }, "required": [ "data" ] }, "WalletType": { "type": "string", "description": "Wallet type identifier.", "enum": [ "main", "p2p", "partner", "payment_agent" ] }, "WalletTransactionMetadata": { "type": "object", "description": "Transaction metadata. `source_*` and `destination_*` fields are populated per the channel/category matrix — see endpoint documentation. Any metadata field whose value would reference internal cashier plumbing is dropped from the response entirely (the field is absent rather than empty).", "properties": { "transaction_status": { "type": "string", "description": "Transaction settlement status.", "examples": [ "complete", "pending" ] }, "transaction_gross_amount": { "type": "string", "description": "Gross amount as a decimal string.", "examples": [ "10" ] }, "transaction_net_amount": { "type": "string", "description": "Net amount as a decimal string.", "examples": [ "10" ] }, "transaction_currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "3-letter ISO currency code the amounts are denominated in.", "examples": [ "USD" ] }, "source_client_id": { "type": "string", "format": "uuid", "description": "Owning client of the source wallet. Absent for cashier deposits (the source is the system)." }, "source_wallet_type": { "allOf": [ { "$ref": "#/components/schemas/WalletType" } ], "description": "Wallet type on the source side. Absent for cashier deposits." }, "destination_client_id": { "type": "string", "format": "uuid", "description": "Owning client of the destination wallet. Absent for cashier withdrawals." }, "destination_wallet_type": { "allOf": [ { "$ref": "#/components/schemas/WalletType" } ], "description": "Wallet type on the destination side. Absent for cashier withdrawals." } }, "required": [ "transaction_status", "transaction_gross_amount", "transaction_net_amount", "transaction_currency" ] }, "WalletTransaction": { "type": "object", "description": "A single wallet transaction. `category` is computed relative to the caller (deposit / withdrawal), and `channel` indicates how the money moved (cashier / payment agent).", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "Idempotency / correlation ID.", "examples": [ "ef4b3abd-c05e-42ea-a3f2-021ec69e1580" ] }, "transaction_id": { "type": "integer", "description": "Wallet-service assigned identifier.", "examples": [ 277121 ] }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 UTC timestamp with microseconds.", "examples": [ "2026-07-10T07:34:29.688372Z" ] }, "category": { "type": "string", "description": "Direction of the transaction relative to the caller.", "enum": [ "deposit", "withdrawal" ] }, "channel": { "type": "string", "description": "How the money moved.", "enum": [ "cashier", "payment_agent" ] }, "metadata": { "$ref": "#/components/schemas/WalletTransactionMetadata" } }, "required": [ "request_id", "transaction_id", "timestamp", "category", "channel", "metadata" ] }, "WalletTransactionsLinks": { "type": "object", "description": "Cursor-based pagination links. Each link contains only `page_cursor` — follow it verbatim to fetch the next / previous page. `null` when the corresponding page does not exist (e.g. `next` on the last page).", "properties": { "self": { "type": [ "string", "null" ], "description": "URL of the current page.", "examples": [ "/wallet/v1/transactions/main?page_cursor=…" ] }, "next": { "type": [ "string", "null" ], "description": "URL of the next page, or `null` when there is no next page." }, "prev": { "type": [ "string", "null" ], "description": "URL of the previous page, or `null` when there is no previous page." }, "first": { "type": [ "string", "null" ], "description": "URL of the first page." } }, "required": [ "self", "next", "prev", "first" ] }, "WalletTransactionsData": { "type": "object", "description": "Envelope for the transactions list plus the resolved date range for the current page.", "properties": { "start_date_time": { "type": [ "string", "null" ], "format": "date-time", "description": "Lower bound of the returned range. `null` when unbounded." }, "end_date_time": { "type": [ "string", "null" ], "format": "date-time", "description": "Upper bound of the returned range. `null` when unbounded." }, "transactions": { "type": "array", "description": "Transactions on this page, newest first.", "items": { "$ref": "#/components/schemas/WalletTransaction" } } }, "required": [ "start_date_time", "end_date_time", "transactions" ] }, "WalletTransactionsResponse": { "type": "object", "description": "Successful transactions response for the requested wallet type.", "properties": { "data": { "$ref": "#/components/schemas/WalletTransactionsData" }, "links": { "$ref": "#/components/schemas/WalletTransactionsLinks" } }, "required": [ "data", "links" ] }, "TransferAccountType": { "type": "string", "description": "Account type that can take part in a transfer.", "enum": [ "main", "p2p", "platform", "payment_agent" ] }, "ExchangeRateResponse": { "type": "object", "description": "Successful exchange-rate quote response.", "properties": { "data": { "type": "object", "description": "The quote for the requested currency pair.", "additionalProperties": true, "properties": { "exchange_rate": { "type": "string", "description": "Quoted exchange rate as a decimal string.", "examples": [ "0.0000095238" ] }, "rate_token": { "type": "string", "description": "Token attesting to this quote. Pass it to `POST /wallet/v1/transfers/exchange` (or a cross-currency platform transfer) to execute at the quoted rate." } } } }, "required": [ "data" ] }, "TransferValidationRequest": { "type": "object", "description": "Transfer to validate. This is a strict whitelist — fields not listed here are rejected with `400`.", "additionalProperties": false, "properties": { "source_type": { "allOf": [ { "$ref": "#/components/schemas/TransferAccountType" } ], "description": "Type of the source account." }, "destination_type": { "allOf": [ { "$ref": "#/components/schemas/TransferAccountType" } ], "description": "Type of the destination account." }, "source_id": { "type": "string", "description": "Identifier of the source account: the wallet UUID, or the platform account ID (e.g. `MTR5312343`) when `source_type` is `platform`.", "examples": [ "942a2f2d-1f33-4559-994e-42b403033bc6" ] }, "destination_id": { "type": "string", "description": "Identifier of the destination account: the wallet UUID, or the platform account ID (e.g. `MTR5312343`) when `destination_type` is `platform`.", "examples": [ "ef4b3abd-c05e-42ea-a3f2-021ec69e1580" ] }, "amount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Transfer amount as a decimal string (`>= 0`).", "examples": [ "100.00" ] }, "balance": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Current spendable balance of the source account, in `source_currency`. Same format as `amount`. Used to validate sufficient funds.", "examples": [ "250.00" ] }, "source_currency": { "type": "string", "pattern": "^[A-Z0-9_]{1,18}$", "description": "Currency code of the source account.", "examples": [ "USD" ] }, "destination_currency": { "type": "string", "pattern": "^[A-Z0-9_]{1,18}$", "description": "Currency code of the destination account.", "examples": [ "BTC" ] }, "rate": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Exchange rate as a positive decimal string. Required for cross-currency transfers (`source_currency` differs from `destination_currency`); omit otherwise.", "examples": [ "0.92" ] }, "source_platform_name": { "type": "string", "description": "Platform name. Provide when `source_type` is `platform`.", "enum": [ "mt5", "ctrader", "options", "crypto-exchange", "tradingview" ] }, "destination_platform_name": { "type": "string", "description": "Platform name. Provide when `destination_type` is `platform`.", "enum": [ "mt5", "ctrader", "options", "crypto-exchange", "tradingview" ] } }, "required": [ "source_type", "destination_type", "source_id", "destination_id", "amount", "balance", "source_currency", "destination_currency" ] }, "TransferValidationTransfer": { "type": "object", "description": "Classification of the validated transfer.", "properties": { "is_cross_currency": { "type": "boolean", "description": "Whether the source and destination currencies differ." }, "type": { "type": "string", "description": "Kind of transfer.", "enum": [ "wallet_to_wallet", "wallet_to_platform" ] } }, "required": [ "is_cross_currency", "type" ] }, "TransferValidationSource": { "type": "object", "description": "Source side of the validated transfer. All amounts are decimal strings.", "properties": { "id": { "type": "string", "description": "Source account identifier, echoed from the request (wallet UUID or platform account ID).", "examples": [ "942a2f2d-1f33-4559-994e-42b403033bc6" ] }, "type": { "$ref": "#/components/schemas/TransferAccountType" }, "currency": { "type": "string", "description": "Currency of the source account.", "examples": [ "USD" ] }, "amount": { "type": "string", "description": "Requested amount.", "examples": [ "100.00" ] }, "net_amount": { "type": "string", "description": "Amount minus the fee, in the source currency.", "examples": [ "99.50" ] } }, "required": [ "id", "type", "currency", "amount", "net_amount" ] }, "TransferValidationDestination": { "type": "object", "description": "Destination side of the validated transfer. All amounts are decimal strings.", "properties": { "id": { "type": "string", "description": "Destination account identifier, echoed from the request (wallet UUID or platform account ID).", "examples": [ "ef4b3abd-c05e-42ea-a3f2-021ec69e1580" ] }, "type": { "$ref": "#/components/schemas/TransferAccountType" }, "currency": { "type": "string", "description": "Currency of the destination account.", "examples": [ "USD" ] }, "amount": { "type": "string", "description": "Estimated amount the destination receives, floored to the destination currency's precision. For cross-currency transfers this is an estimate, not the settled value.", "examples": [ "99.50" ] }, "estimated": { "type": "boolean", "description": "Always `true` — `amount` is an estimate." } }, "required": [ "id", "type", "currency", "amount", "estimated" ] }, "TransferValidationFee": { "type": "object", "description": "Fee that would be charged on the transfer.", "properties": { "amount": { "type": "string", "description": "Fee amount, in `currency`.", "examples": [ "0.50" ] }, "percentage": { "type": "number", "description": "Nominal fee percentage.", "examples": [ 0.5 ] }, "applied_percentage": { "type": "string", "description": "Effective fee percentage actually charged. Exceeds `percentage` when `min_fee_applied` is `true`.", "examples": [ "0.50" ] }, "min_fee_applied": { "type": "boolean", "description": "`true` when the percentage-based fee was below the currency's smallest ledger unit and was raised to it." }, "reason_code": { "type": [ "string", "null" ], "description": "Why the fee is charged. `null` (or absent) when no fee applies.", "enum": [ "convenience_fee", "currency_exchange", null ] }, "currency": { "type": "string", "description": "Currency the fee is charged in — the wallet side of the transfer.", "examples": [ "USD" ] }, "source": { "type": "string", "description": "Account the fee is charged from (wallet UUID or platform account ID).", "examples": [ "942a2f2d-1f33-4559-994e-42b403033bc6" ] } }, "required": [ "amount", "percentage", "applied_percentage", "min_fee_applied", "currency", "source" ] }, "TransferValidationDetails": { "type": "object", "description": "Breakdown of the validated transfer.", "properties": { "transfer": { "$ref": "#/components/schemas/TransferValidationTransfer" }, "source": { "$ref": "#/components/schemas/TransferValidationSource" }, "destination": { "$ref": "#/components/schemas/TransferValidationDestination" }, "fee": { "$ref": "#/components/schemas/TransferValidationFee" } }, "required": [ "transfer", "source", "destination", "fee" ] }, "TransferValidationResponse": { "type": "object", "description": "Successful transfer validation response.", "properties": { "data": { "type": "object", "properties": { "is_valid": { "type": "boolean", "description": "Always `true` — an invalid transfer produces an error response, not `false`." }, "details": { "$ref": "#/components/schemas/TransferValidationDetails" } }, "required": [ "is_valid", "details" ] } }, "required": [ "data" ] }, "TransferValidationErrorItem": { "type": "object", "description": "A single error entry.", "properties": { "status": { "type": "integer", "description": "HTTP-equivalent status code for this error." }, "code": { "type": "string", "description": "Machine-readable error code identifying what went wrong. Common values: `ValidationError`, `BadRequest`, `CurrencyNotAllowed`, `Unauthorized`, `Forbidden`, `InternalServerError`." }, "message": { "type": "string", "description": "Human-readable description of the error condition." }, "field": { "type": "string", "description": "Name of the offending request field. Present only for `ValidationError`." }, "i18n_key": { "type": "string", "description": "Localization key for the message." }, "details": { "type": "object", "description": "Additional structured context for the error.", "additionalProperties": true } }, "required": [ "status", "code", "message" ] }, "TransferValidationErrorResponse": { "type": "object", "description": "Standard error envelope. `errors` contains one or more entries describing what went wrong.", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/TransferValidationErrorItem" }, "description": "One or more error entries." } }, "required": [ "errors" ] }, "TransferRequest": { "type": "object", "description": "Same-currency transfer between two wallets owned by the authenticated client. This is a strict whitelist — fields not listed here are rejected with `400`.", "additionalProperties": false, "properties": { "currency": { "type": "string", "pattern": "^[A-Z0-9_]{1,18}$", "description": "Currency of the transfer. Both wallets must hold a balance in this currency.", "examples": [ "USD" ] }, "amount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Transfer amount as a decimal string. Any applicable fee is deducted from this amount.", "examples": [ "100.00" ] }, "source_wallet_id": { "type": "string", "format": "uuid", "description": "Wallet to debit. Must belong to the authenticated client.", "examples": [ "942a2f2d-1f33-4559-994e-42b403033bc6" ] }, "destination_wallet_id": { "type": "string", "format": "uuid", "description": "Wallet to credit. Must belong to the authenticated client.", "examples": [ "ef4b3abd-c05e-42ea-a3f2-021ec69e1580" ] }, "request_id": { "type": "string", "format": "uuid", "description": "Idempotency key. Reusing a previously submitted `request_id` does not create a duplicate transfer.", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "description": { "type": "string", "description": "Optional free-text note attached to the transfer.", "examples": [ "Move funds to P2P wallet" ] } }, "required": [ "currency", "amount", "source_wallet_id", "destination_wallet_id", "request_id" ] }, "ExchangeTransferRequest": { "type": "object", "description": "Cross-currency transfer between two wallets owned by the authenticated client. This is a strict whitelist — fields not listed here are rejected with `400`.", "additionalProperties": false, "properties": { "source_wallet_id": { "type": "string", "format": "uuid", "description": "Wallet to debit, in `source_currency`. Must belong to the authenticated client.", "examples": [ "942a2f2d-1f33-4559-994e-42b403033bc6" ] }, "source_currency": { "type": "string", "pattern": "^[A-Z0-9_]{1,18}$", "description": "Currency debited from the source wallet.", "examples": [ "USD" ] }, "amount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Amount to convert, in `source_currency`, as a decimal string. Any applicable currency-exchange fee is deducted from this amount.", "examples": [ "100.00" ] }, "destination_wallet_id": { "type": "string", "format": "uuid", "description": "Wallet to credit, in `destination_currency`. Must belong to the authenticated client.", "examples": [ "ef4b3abd-c05e-42ea-a3f2-021ec69e1580" ] }, "destination_currency": { "type": "string", "pattern": "^[A-Z0-9_]{1,18}$", "description": "Currency credited to the destination wallet.", "examples": [ "BTC" ] }, "exchange_rate": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Quoted exchange rate as a positive decimal string, from an exchange-rate quote obtained beforehand.", "examples": [ "0.0000095238" ] }, "rate_token": { "type": "string", "description": "Token attesting to the quoted exchange rate, issued together with the quote.", "examples": [ "eyJhbGciOi..." ] }, "request_id": { "type": "string", "format": "uuid", "description": "Idempotency key. Reusing a previously submitted `request_id` does not create a duplicate transfer.", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "description": { "type": "string", "description": "Optional free-text note attached to the transfer.", "examples": [ "Convert USD to BTC" ] } }, "required": [ "source_wallet_id", "source_currency", "amount", "destination_wallet_id", "destination_currency", "exchange_rate", "rate_token", "request_id" ] }, "PlatformTransferRequest": { "type": "object", "description": "Transfer between a wallet and a trading platform account owned by the authenticated client. This is a strict whitelist — fields not listed here are rejected with `400`.", "additionalProperties": false, "properties": { "wallet_id": { "type": "string", "format": "uuid", "description": "Wallet on the wallet side of the transfer. Must belong to the authenticated client.", "examples": [ "942a2f2d-1f33-4559-994e-42b403033bc6" ] }, "amount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Transfer amount as a decimal string, in `currency`. Any applicable fee is deducted from this amount.", "examples": [ "100.00" ] }, "currency": { "type": "string", "pattern": "^[A-Z0-9_]{1,18}$", "description": "Currency of the platform account. Must match the account's actual currency.", "examples": [ "USD" ] }, "direction": { "type": "string", "description": "`from_wallet` debits the wallet to fund the platform account; `to_wallet` debits the platform account to fund the wallet.", "enum": [ "to_wallet", "from_wallet" ] }, "platform_name": { "type": "string", "description": "Trading platform of the account.", "enum": [ "mt5", "ctrader", "options", "crypto-exchange", "tradingview" ] }, "platform_account_id": { "type": "string", "description": "Login/account identifier on the platform. Must belong to the authenticated client and be a real (not demo) account.", "examples": [ "MTR9000001" ] }, "request_id": { "type": "string", "format": "uuid", "description": "Idempotency key. Reusing a previously submitted `request_id` is rejected with `DuplicateRequestID`.", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "description": { "type": "string", "description": "Optional free-text note attached to the transfer.", "examples": [ "Fund MT5 account" ] }, "wallet_currency": { "type": "string", "pattern": "^[A-Z0-9_]{1,18}$", "description": "The wallet's currency. Send only for cross-currency platform transfers, when it differs from `currency`; then `exchange_rate` and `rate_token` are also required.", "examples": [ "EUR" ] }, "exchange_rate": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Quoted exchange rate as a positive decimal string. Required together with `rate_token` when `wallet_currency` differs from `currency`.", "examples": [ "0.92" ] }, "rate_token": { "type": "string", "description": "Token attesting to the quoted exchange rate. Required together with `exchange_rate` when `wallet_currency` differs from `currency`.", "examples": [ "eyJhbGciOi..." ] } }, "required": [ "wallet_id", "amount", "currency", "direction", "platform_name", "platform_account_id", "request_id" ], "dependentRequired": { "wallet_currency": [ "exchange_rate", "rate_token" ], "exchange_rate": [ "wallet_currency", "rate_token" ], "rate_token": [ "wallet_currency", "exchange_rate" ] } }, "TransferExecuteResponse": { "type": "object", "description": "Successful transfer execution response.", "properties": { "data": { "type": "object", "description": "Details of the executed transfer. Always echoes the request's `request_id`; the remaining fields describe the recorded transfer.", "additionalProperties": true, "properties": { "request_id": { "type": "string", "format": "uuid", "description": "The `request_id` supplied in the request, echoed back as the idempotency reference of the executed transfer.", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] } }, "required": [ "request_id" ] } }, "required": [ "data" ] }, "PlatformTransferExecuteResponse": { "type": "object", "description": "Successful platform transfer execution response.", "properties": { "data": { "type": "object", "properties": { "status": { "type": "object", "description": "Status details of the executed transfer.", "additionalProperties": true }, "request_id": { "type": "string", "format": "uuid", "description": "The `request_id` supplied in the request, echoed back as the idempotency reference of the executed transfer.", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] } }, "required": [ "status", "request_id" ] } }, "required": [ "data" ] } } } }