{ "openapi": "3.0.3", "info": { "title": "Octolit Trading API", "version": "1.0.0", "description": "REST API of the trading platform for the client's own programs. Create a key in the trader (Pro mode > API\naccess); it is shown once. Send it as header `X-API-Key: ` (or `Authorization: Bearer `), never in a URL.\nKeys are read-only unless created with the \"trade\" scope, may be limited to some trading accounts and to IP\naddresses, and the broker can revoke them or stop API trading at any time.\n\nLimits: requests per minute per key and per client, order actions per second per key and per trading account\n(see GET /account). Every answer carries X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset; a 429\ncarries Retry-After.\n\nIdempotency: every order action (open, close, cancel) needs a client_order_id (1-64 characters: letters, digits,\n_ - : .), in the body or the Idempotency-Key header. Sending the same client_order_id again answers the FIRST\norder (code \"replayed\") and never places a second one. After a timeout or a 500 \"unknown_outcome\", look the\norder up (GET /orders/lookup?client_order_id=) before sending anything new.\n\nQuotes are the trading quotes - the prices orders fill at - not chart prices. Every error answers\n{ \"error\": { \"code\", \"message\", \"details\"? } }; the codes are listed in x-error-codes and in the Error schema." }, "servers": [ { "url": "https://api.your-brand.com/api/open/v1", "description": "Your broker's API host + /api/open/v1" } ], "security": [ { "ApiKey": [] }, { "Bearer": [] } ], "tags": [ { "name": "account", "description": "The key, its client and trading accounts" }, { "name": "market", "description": "Symbols and the trading quotes orders fill at" }, { "name": "trading", "description": "Orders, positions and history (trade scope for writes)" }, { "name": "stream", "description": "WebSocket tickets (quotes + account / execution events)" }, { "name": "meta", "description": "This document and the reference page" } ], "paths": { "/openapi.json": { "get": { "tags": [ "meta" ], "operationId": "getSpec", "summary": "This OpenAPI document (no key needed)", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/docs": { "get": { "tags": [ "meta" ], "operationId": "getDocs", "summary": "This reference as an HTML page (no key needed)", "security": [], "responses": { "200": { "description": "OK", "content": { "text/html": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/account": { "get": { "tags": [ "account" ], "operationId": "getAccount", "summary": "The key, its client, limits and switches", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/accounts": { "get": { "tags": [ "account" ], "operationId": "listAccounts", "summary": "Trading accounts this key may use, with balance figures", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/accounts/{id}": { "get": { "tags": [ "account" ], "operationId": "getTradingAccount", "summary": "One trading account", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/Account" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/symbols": { "get": { "tags": [ "market" ], "operationId": "listSymbols", "summary": "Symbols of a trading account (spread, leverage, contract size)", "parameters": [ { "$ref": "#/components/parameters/TradingAccountId" }, { "name": "market", "in": "query", "required": false, "schema": { "type": "string" }, "description": "fx | crypto | stocks | indices | commodities ..." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "part of the symbol or name" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "from 1" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "1..1000, default 200" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "trading_account_id": { "type": "integer" }, "symbols": { "type": "array", "items": { "$ref": "#/components/schemas/Symbol" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/symbols/{id}": { "get": { "tags": [ "market" ], "operationId": "getSymbol", "summary": "One symbol", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/TradingAccountId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "trading_account_id": { "type": "integer" }, "symbol": { "$ref": "#/components/schemas/Symbol" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/quotes": { "get": { "tags": [ "market" ], "operationId": "getQuotes", "summary": "Trading quotes snapshot (the prices orders fill at)", "parameters": [ { "name": "symbol_ids", "in": "query", "required": false, "schema": { "type": "string" }, "description": "comma list of symbol ids (max 100)" }, { "name": "symbols", "in": "query", "required": false, "schema": { "type": "string" }, "description": "comma list of symbols (max 100)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "quotes": { "type": "array", "items": { "$ref": "#/components/schemas/Quote" } }, "source": { "type": "string", "enum": [ "trading" ] }, "mirror_at": { "type": "integer", "description": "epoch ms of the quote snapshot" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/bars": { "get": { "tags": [ "market" ], "operationId": "getBars", "summary": "Chart history: the newest OHLCV bars of one symbol up to `to` (any chart timeframe)", "parameters": [ { "name": "symbol_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "or symbol" }, { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string" }, "description": "or symbol_id" }, { "name": "resolution", "in": "query", "required": false, "schema": { "type": "string" }, "description": "1m, 5m, 15m, 30m, 1h, 4h, 1D, 1W, 1M (default 1h; aliases 60, H1, D, W1, MN ...)" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "newest bar open time: epoch seconds, epoch ms or ISO 8601 (default now)" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "oldest bar open time (optional, before to)" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "1..5000, default 500; the newest count bars" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol_id": { "type": "integer" }, "symbol": { "type": "string" }, "pair": { "type": "string" }, "resolution": { "type": "string", "enum": [ "1m", "5m", "15m", "30m", "1h", "4h", "1D", "1W", "1M" ] }, "from": { "type": "integer", "description": "epoch seconds", "nullable": true }, "to": { "type": "integer", "description": "epoch seconds" }, "count": { "type": "integer", "description": "bars returned" }, "bars": { "type": "array", "items": { "$ref": "#/components/schemas/Bar" } }, "complete": { "type": "boolean" }, "next_to": { "type": "integer", "description": "send as `to` for the next older page; null when complete", "nullable": true } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/trending": { "get": { "tags": [ "market" ], "operationId": "getTrending", "summary": "Trending instruments: the symbols this brand's clients traded the most (live, prop / bot / demo trades not counted; 403 trending_disabled unless the brand offers it)", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string" }, "description": "1h, 24h, 7d (default 24h)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "1..50, default 10" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trending" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/positions": { "get": { "tags": [ "trading" ], "operationId": "listPositions", "summary": "Open positions", "parameters": [ { "$ref": "#/components/parameters/TradingAccountId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "positions": { "type": "array", "items": { "$ref": "#/components/schemas/Position" } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/positions/{id}": { "get": { "tags": [ "trading" ], "operationId": "getPosition", "summary": "A position, order or closed trade of this key's accounts", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "position": { "$ref": "#/components/schemas/Position" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } }, "patch": { "tags": [ "trading" ], "operationId": "modifyPosition", "summary": "Set / remove stop loss and take profit of an open position", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModifyPosition" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PositionResult" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/positions/{id}/close": { "post": { "tags": [ "trading" ], "operationId": "closePosition", "summary": "Close an open position (the whole of it)", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientOrderId" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PositionResult" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/history": { "get": { "tags": [ "trading" ], "operationId": "listHistory", "summary": "Closed trades, newest id first (cursor: next_before_id)", "parameters": [ { "$ref": "#/components/parameters/TradingAccountId" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601, closed at or after" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601, closed before" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "1..500, default 100" }, { "name": "before_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "next_before_id of the previous page" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "trades": { "type": "array", "items": { "$ref": "#/components/schemas/Position" } }, "next_before_id": { "type": "integer", "nullable": true } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/orders": { "get": { "tags": [ "trading" ], "operationId": "listOrders", "summary": "Pending orders", "parameters": [ { "$ref": "#/components/parameters/TradingAccountId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/Position" } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } }, "post": { "tags": [ "trading" ], "operationId": "placeOrder", "summary": "Place a market, limit or stop order", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRequest" } } } }, "responses": { "200": { "description": "Replayed (same client_order_id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResult" } } } }, "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResult" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/orders/lookup": { "get": { "tags": [ "trading" ], "operationId": "lookupOrder", "summary": "The order this key placed with a client_order_id", "parameters": [ { "name": "client_order_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "the id the order was sent with" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "client_order_id": { "type": "string" }, "order": { "$ref": "#/components/schemas/Position" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/stream_ticket": { "post": { "tags": [ "stream" ], "operationId": "createStreamTicket", "summary": "A 60-second single-use ticket for the WebSocket: wss://api.your-brand.com/rt/v1/ws?ticket=... (a read-only key is enough; 403 websocket_disabled unless OPEN_API_WS)", "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ticket": { "type": "string" }, "exp": { "type": "integer", "description": "unix seconds" }, "expires_in": { "type": "integer", "description": "seconds" }, "url": { "type": "string", "description": "the WebSocket path" }, "single_use": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/orders/{id}": { "get": { "tags": [ "trading" ], "operationId": "getOrder", "summary": "An order, position or closed trade of this key's accounts", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/Position" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } }, "patch": { "tags": [ "trading" ], "operationId": "modifyOrder", "summary": "Move a pending order / set its stop loss and take profit", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModifyOrder" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResult" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } }, "delete": { "tags": [ "trading" ], "operationId": "cancelOrder", "summary": "Cancel a pending order", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientOrderId" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelResult" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "qk_ + 48 characters" }, "Bearer": { "type": "http", "scheme": "bearer", "description": "the same key as a Bearer token" } }, "parameters": { "Id": { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, "TradingAccountId": { "name": "trading_account_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "one trading account of this key (symbols: default the first)" }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_\\-:.]{1,64}$" }, "description": "the client_order_id when the body has none" } }, "responses": { "E400": { "description": "Bad request (invalid_json)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E401": { "description": "No / invalid / revoked / expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E403": { "description": "Refused (IP, scope, brand switch, kill switch, account, inactive client)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E404": { "description": "Not found (also every path while the Open API is off on this server)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E409": { "description": "Wrong state (pending vs open, MT rows, an order in flight)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E422": { "description": "Invalid request or refused by the order checks (margin, levels, size, market closed ...)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E429": { "description": "Rate limited (Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E500": { "description": "Internal error; unknown_outcome = look the order up before sending it again", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E503": { "description": "Temporarily unavailable (prices, balance, quotes, rate-limit store)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "account_invalid", "account_not_allowed", "account_not_found", "api_key_expired", "api_key_required", "api_key_revoked", "api_trading_stopped", "balance_unavailable", "brand_inactive", "client_inactive", "client_order_id_required", "company_inactive", "history_unavailable", "insufficient_margin", "internal_error", "invalid_api_key", "invalid_client_order_id", "invalid_json", "invalid_levels", "invalid_leverage", "invalid_price", "invalid_request", "invalid_size", "ip_not_allowed", "ip_unverifiable", "market_closed", "mt_account", "mt_position", "no_conversion_rate", "no_price", "not_found", "not_open", "not_pending", "not_placed", "not_ready", "open_api_disabled", "order_in_flight", "order_rate_limited", "order_refused", "pending_order", "position_state", "quotes_unavailable", "rate_limit_unavailable", "rate_limited", "still_open", "stream_unavailable", "symbol_invalid", "symbol_not_allowed", "symbol_not_found", "too_many_invalid_keys", "too_many_orders", "trade_scope_required", "trading_denied", "trading_inactive", "trending_disabled", "trending_unavailable", "unknown_outcome", "websocket_disabled" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Me": { "type": "object", "properties": { "client_id": { "type": "integer" }, "key": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "trade", "fix" ] } }, "trading_account_ids": { "type": "array", "items": { "type": "integer" }, "nullable": true }, "ip_allowlist": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "trading_account_ids": { "type": "array", "items": { "type": "integer" } }, "limits": { "type": "object", "properties": { "requests_per_min": { "type": "integer" }, "client_requests_per_min": { "type": "integer" }, "orders_per_sec": { "type": "integer" }, "account_orders_per_sec": { "type": "integer" }, "max_keys": { "type": "integer" } } }, "websocket": { "type": "boolean" }, "trading_stopped": { "type": "boolean" }, "server_time": { "type": "string", "format": "date-time" } } }, "Account": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "nullable": true }, "currency": { "type": "string", "nullable": true }, "account_type": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "nullable": true } }, "nullable": true }, "demo": { "type": "boolean" }, "active": { "type": "boolean" }, "hidden": { "type": "boolean" }, "platform": { "type": "string", "enum": [ "internal", "mt" ] }, "tradable": { "type": "boolean" }, "balance_available": { "type": "boolean" }, "balance": { "type": "number", "nullable": true }, "equity": { "type": "number", "nullable": true }, "profit": { "type": "number", "nullable": true }, "margin": { "type": "number", "nullable": true }, "free_margin": { "type": "number", "nullable": true }, "margin_level": { "type": "number", "nullable": true }, "closed_profit": { "type": "number", "nullable": true } } }, "Symbol": { "type": "object", "properties": { "id": { "type": "integer" }, "symbol": { "type": "string" }, "name": { "type": "string", "nullable": true }, "market": { "type": "string", "nullable": true }, "base": { "type": "string", "nullable": true }, "quote": { "type": "string", "nullable": true }, "pair": { "type": "string" }, "contract_size": { "type": "number", "description": "units per lot" }, "spread": { "type": "number" }, "spread_on": { "type": "integer" }, "leverage": { "type": "number", "description": "the most an order may use; the default of an order without leverage" }, "leverage_type": { "type": "string", "enum": [ "fixed", "up_to" ] }, "tradable": { "type": "boolean" } } }, "Quote": { "type": "object", "properties": { "symbol_id": { "type": "integer" }, "symbol": { "type": "string" }, "pair": { "type": "string" }, "bid": { "type": "number", "nullable": true }, "ask": { "type": "number", "nullable": true }, "mid": { "type": "number", "nullable": true }, "ts": { "type": "integer", "description": "epoch ms of the price", "nullable": true } } }, "Bar": { "type": "object", "properties": { "t": { "type": "integer", "description": "epoch seconds, bar open time (UTC)" }, "o": { "type": "number", "description": "open" }, "h": { "type": "number", "description": "high" }, "l": { "type": "number", "description": "low" }, "c": { "type": "number", "description": "close" }, "v": { "type": "number", "description": "volume (tick count); null when unknown", "nullable": true } } }, "TrendingSymbol": { "type": "object", "properties": { "rank": { "type": "integer" }, "symbol": { "type": "string", "description": "BASE-QUOTE pair" }, "ticker": { "type": "string", "nullable": true }, "ticker_id": { "type": "integer", "nullable": true }, "name": { "type": "string", "nullable": true }, "trades": { "type": "integer", "description": "trades opened in the window" }, "clients": { "type": "integer", "description": "distinct clients who traded it" }, "share_pct": { "type": "number", "description": "share of all trades in the window, percent", "nullable": true }, "buy_pct": { "type": "number", "description": "percent of the symbol's trades that were buys; null below 10 clients", "nullable": true } } }, "Trending": { "type": "object", "properties": { "now": { "type": "integer", "description": "epoch ms" }, "as_of": { "type": "integer", "description": "epoch ms the list was computed" }, "scope": { "type": "string", "enum": [ "brand" ] }, "window": { "type": "string", "enum": [ "1h", "24h", "7d" ] }, "from": { "type": "integer", "description": "epoch seconds, window start" }, "min_clients": { "type": "integer", "description": "a symbol needs this many clients to be listed" }, "total_trades": { "type": "integer", "description": "all trades of the brand in the window" }, "symbols": { "type": "array", "items": { "$ref": "#/components/schemas/TrendingSymbol" } } } }, "Position": { "type": "object", "properties": { "id": { "type": "integer" }, "trading_account_id": { "type": "integer" }, "symbol_id": { "type": "integer" }, "symbol": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "open", "closed", "cancelled", "unknown" ] }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "type": { "type": "string", "enum": [ "market", "limit", "stop" ] }, "units": { "type": "number", "nullable": true }, "lots": { "type": "number", "nullable": true }, "leverage": { "type": "number", "nullable": true }, "price": { "type": "number", "description": "pending order price", "nullable": true }, "open_price": { "type": "number", "nullable": true }, "close_price": { "type": "number", "nullable": true }, "sl": { "type": "number", "nullable": true }, "tp": { "type": "number", "nullable": true }, "profit": { "type": "number", "description": "account currency; open = floating", "nullable": true }, "commission": { "type": "number", "description": "account currency; closed rows only, null while pending / open", "nullable": true }, "swap": { "type": "number", "nullable": true }, "market_price": { "type": "number", "nullable": true }, "source": { "type": "string", "enum": [ "api", "bot", "copy", "client" ] }, "api_key_id": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "opened_at": { "type": "string", "format": "date-time", "nullable": true }, "closed_at": { "type": "string", "format": "date-time", "nullable": true }, "closed_by": { "type": "string", "nullable": true } } }, "OrderRequest": { "type": "object", "properties": { "client_order_id": { "type": "string", "pattern": "^[A-Za-z0-9_\\-:.]{1,64}$" }, "trading_account_id": { "type": "integer" }, "symbol_id": { "type": "integer", "description": "or symbol" }, "symbol": { "type": "string", "description": "or symbol_id" }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "type": { "type": "string", "enum": [ "market", "limit", "stop" ], "default": "market" }, "units": { "type": "number", "description": "units (lots x contract size); or lots" }, "lots": { "type": "number", "description": "or units" }, "price": { "type": "number", "description": "limit / stop orders only" }, "sl": { "type": "number" }, "tp": { "type": "number" }, "leverage": { "type": "integer", "description": "default: the symbol's leverage" } }, "required": [ "trading_account_id", "side" ], "additionalProperties": false }, "ModifyPosition": { "type": "object", "properties": { "sl": { "type": "number", "nullable": true }, "tp": { "type": "number", "nullable": true }, "client_order_id": { "type": "string", "pattern": "^[A-Za-z0-9_\\-:.]{1,64}$" } }, "additionalProperties": false }, "ModifyOrder": { "type": "object", "properties": { "price": { "type": "number" }, "sl": { "type": "number", "nullable": true }, "tp": { "type": "number", "nullable": true }, "client_order_id": { "type": "string", "pattern": "^[A-Za-z0-9_\\-:.]{1,64}$" } }, "additionalProperties": false }, "ClientOrderId": { "type": "object", "properties": { "client_order_id": { "type": "string", "pattern": "^[A-Za-z0-9_\\-:.]{1,64}$" } }, "additionalProperties": false }, "OrderResult": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "placed", "replayed", "closed", "already_closed", "modified", "unchanged", "cancelled", "already_cancelled", "partially_closed" ] }, "client_order_id": { "type": "string", "nullable": true }, "order": { "$ref": "#/components/schemas/Position" } } }, "PositionResult": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "placed", "replayed", "closed", "already_closed", "modified", "unchanged", "cancelled", "already_cancelled", "partially_closed" ] }, "client_order_id": { "type": "string", "nullable": true }, "position": { "$ref": "#/components/schemas/Position" } } }, "CancelResult": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "placed", "replayed", "closed", "already_closed", "modified", "unchanged", "cancelled", "already_cancelled", "partially_closed" ] }, "client_order_id": { "type": "string" }, "order_id": { "type": "integer" }, "order": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Position" } ] } } } } }, "x-error-codes": [ "account_invalid", "account_not_allowed", "account_not_found", "api_key_expired", "api_key_required", "api_key_revoked", "api_trading_stopped", "balance_unavailable", "brand_inactive", "client_inactive", "client_order_id_required", "company_inactive", "history_unavailable", "insufficient_margin", "internal_error", "invalid_api_key", "invalid_client_order_id", "invalid_json", "invalid_levels", "invalid_leverage", "invalid_price", "invalid_request", "invalid_size", "ip_not_allowed", "ip_unverifiable", "market_closed", "mt_account", "mt_position", "no_conversion_rate", "no_price", "not_found", "not_open", "not_pending", "not_placed", "not_ready", "open_api_disabled", "order_in_flight", "order_rate_limited", "order_refused", "pending_order", "position_state", "quotes_unavailable", "rate_limit_unavailable", "rate_limited", "still_open", "stream_unavailable", "symbol_invalid", "symbol_not_allowed", "symbol_not_found", "too_many_invalid_keys", "too_many_orders", "trade_scope_required", "trading_denied", "trading_inactive", "trending_disabled", "trending_unavailable", "unknown_outcome", "websocket_disabled" ] }