Overview
| Production | Testing |
|---|
| REST | https://api.miletrades.site | https://stg-backend.miletraders.com |
| Trading gateway | wss://api.miletrades.site/ws/v1 | wss://stg-backend.miletraders.com/ws/v1 |
| Price feed | wss://api.miletrades.site/api/v1/feed/ws | wss://stg-backend.miletraders.com/api/v1/feed/ws |
All requests and responses are JSON. Money amounts on REST are in cents unless a field says otherwise. Connect WebSockets to the API origin directly. Build and test against the testing environment first: it gets new endpoints before production does.
Quickstart
- Register an app with its redirect URIs and the scopes it needs. You get an 8-digit
app_id. - Send the user through OAuth 2.0 with PKCE and exchange the code for an access token.
- Call REST with
Authorization: Bearer mp_…, or open the gateway and send {"authorize": "mp_…"}. - Get a price proposal, buy, and follow the contract until it settles.
Trade over the gateway (JavaScript)
const ws = new WebSocket("wss://api.miletrades.site/ws/v1");
ws.onopen = () => ws.send(JSON.stringify({ authorize: "mp_USER_TOKEN" }));
ws.onmessage = (ev) => {
const msg = JSON.parse(ev.data);
if (msg.error) return console.error(msg.error.code, msg.error.message);
switch (msg.msg_type) {
case "authorize":
ws.send(JSON.stringify({
proposal: 1, req_id: 1,
contract_type: "DIGITOVER", symbol: "volatility_100", amount: 1, barrier: 4
}));
break;
case "proposal":
ws.send(JSON.stringify({ buy: msg.proposal.id, price: msg.proposal.ask_price, req_id: 2 }));
break;
case "buy":
ws.send(JSON.stringify({ proposal_open_contract: msg.buy.contract_id, subscribe: 1, req_id: 3 }));
break;
case "proposal_open_contract":
if (msg.proposal_open_contract.is_sold) {
console.log(msg.proposal_open_contract.status, msg.proposal_open_contract.profit);
}
break;
}
};
Authentication
Third-party apps get a scoped API token for a user through OAuth 2.0 authorization code with PKCE (S256). A user can also create personal API tokens. Both kinds are the same mp_ token. Tokens authenticate REST calls and the /ws/v1 gateway (via the authorize call).
Presenting a token
- REST: Authorization: Bearer mp_... header (the scheme is matched as "Bearer " or "bearer ").
- REST (alternative): ?token=mp_... query parameter. Works, but puts the secret in URLs; prefer the header.
- Gateway /ws/v1: Send {"authorize": "mp_..."} as the first message. Only API tokens are accepted here, not browser session tokens.
- Price feed /api/v1/feed/ws: ?token=mp_... on the connection URL (or the browser session cookie).
Token formats
mp_ API access token. 24 random bytes, base64url. Only a SHA-256 hash is stored. Does not expire; valid until deleted.mps_ App secret, shown once at registration. Not used by any current endpoint (the token exchange does not take it).mpc_ OAuth authorization code. One-time use, expires 5 minutes after issue.(none) app_id: 8-digit numeric string, for example "10482736".
OAuth 2.0 with PKCE
1. Create a code verifier and its S256 challenge. 2. Send the user to /api/v1/oauth/authorize. 3. They approve on our consent page and come back to your redirect_uri with a code. 4. Exchange it at /api/v1/oauth/token from your server.
PKCE (browser or Node)
function base64url(bytes) {
return btoa(String.fromCharCode(...new Uint8Array(bytes)))
.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
}
const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
const challenge = base64url(
await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))
);
Authorize parameters
| Name | In | Type | Description |
|---|
| app_id* | query | string | Your 8-digit app_id. |
| redirect_uri* | query | string | Must exactly equal one of the app's registered redirect_uris. |
| code_challenge* | query | string | base64url(SHA-256(code_verifier)) with no padding. |
| code_challenge_method | query | string | Only S256 is accepted. May be omitted; the challenge is always verified as S256. |
| response_type | query | string | Only code is accepted. May be omitted. |
| scope | query | string | Space or comma separated. Must be a subset of the app's registered scopes. Defaults to all of the app's scopes. |
| state | query | string | Opaque value echoed back on the redirect. Use it for CSRF protection. |
Authorize
GET https://api.miletrades.site/api/v1/oauth/authorize?app_id=10482736&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&response_type=code&scope=read%20trade&state=Xy7pQ2&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256
The server renders an HTML consent page listing the requested scopes. If the browser has no session on the API origin, the page asks for email and password. Approving POSTs the form back to /api/v1/oauth/authorize.
Approved
https://example.com/callback?code=mpc_EXAMPLEauthCode000000000000000&state=Xy7pQ2
Denied
https://example.com/callback?error=access_denied&state=Xy7pQ2
Invalid input on the authorize request (unknown app_id, unregistered redirect_uri, wrong response_type or code_challenge_method, missing code_challenge, scope beyond the app's scopes) renders an HTML "Can't authorize" page. It never redirects to an unvalidated URI.
Token exchange parameters
| Name | In | Type | Description |
|---|
| grant_type* | form | string | Must be authorization_code. No other grant type exists (no refresh_token, no client_credentials). |
| code* | form | string | The mpc_ code from the redirect. |
| redirect_uri* | form | string | Must equal the redirect_uri used on the authorize request. |
| code_verifier* | form | string | The PKCE verifier whose S256 hash was sent as code_challenge. |
| app_id | form | string | Optional. If sent, must match the app the code was issued to. |
Token request
POST /api/v1/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=mpc_EXAMPLEauthCode000000000000000&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk&app_id=10482736
Token response
{
"access_token": "mp_EXAMPLEaccessToken0000000000000",
"token_type": "bearer",
"scope": "read trade",
"app_id": "10482736"
}
| 400 | unsupported_grant_type | grant_type is not authorization_code. |
| 400 | invalid_grant | Code unknown, already used or expired; app_id mismatch; redirect_uri mismatch; PKCE verification failed. |
| 500 | server_error | The token could not be issued. |
- Parameters are read from a form body (application/x-www-form-urlencoded) or the query string. A JSON body is not read.
- No expires_in and no refresh_token are returned: the token does not expire.
- Each successful exchange creates a new token named oauth:<app_id> in the user's token list.
Personal tokens and revocation
A signed-in user can create personal tokens with POST /api/v1/tokens, list them with GET /api/v1/tokens and delete them with DELETE /api/v1/tokens/{id}. See the API tokens group.
There is no OAuth revocation endpoint. A token stops working only when the user deletes it (DELETE /api/v1/tokens/{id}). OAuth-issued tokens appear in that list with the name oauth:<app_id>. Deleting an app does not delete tokens already issued for it.
Scopes
Request only the scopes your app needs. The user sees each one on the consent page.
| Scope | The user sees | Grants |
|---|
| read | View your markets, balance, portfolio and history | Gateway: balance, portfolio, proposal, proposal_open_contract, statement, profit_table, transaction, account_status, account_list, set_account. REST has no endpoint gated on read: every signed-in REST read accepts any valid token. |
| trade | Buy and sell contracts on your behalf | Gateway: buy, new_account_real, new_account_virtual. REST: POST /api/v1/contracts, POST /api/v1/contracts/bulk, POST /api/v1/accounts. |
| payments | Deposit and withdraw from your account | Gateway: transfer_between_accounts. REST: every deposit and withdrawal initiation (POST /api/v1/deposits/*, POST /api/v1/withdrawals/*), POST /api/v1/accounts/transfer, POST /api/v1/apps/{app_id}/claim, POST /api/v1/partner/claim, POST /api/v1/ib/transfer. |
| admin | Manage your API apps and tokens | REST: satisfies every REST scope check (read, trade, payments). Gateway: grants nothing by itself, because the gateway checks for the exact scope name. |
REST API
Base URL https://api.miletrades.site. Send JSON bodies with Content-Type: application/json; unknown fields are rejected.
Trading gateway (WebSocket)
Open wss://<api-origin>/ws/v1. Any Origin is accepted. Optional ?app_id=<app_id> on the URL sets attribution for tokens that are not bound to an app; a token bound to an app always uses its own app_id.
Send {"authorize": "mp_..."} first. Market calls (active_symbols, ticks, ticks_history, ping, time, forget, forget_all) work without it. Every other call returns AuthorizationRequired until authorized, and PermissionDenied if the token lacks the exact scope (admin does not stand in for other scopes here).
A request is one JSON object. The first recognised call key names the call. Envelope fields: req_id (integer, echoed back), subscribe (1 to stream, where supported), passthrough and app_id (ignored by the server; passthrough is not echoed separately, but appears inside echo_req). A response is {"msg_type": <type>, "echo_req": <your request>, <type>: <payload>, "req_id"?: <int>, "subscription"?: {"id": <id>}}.
The server sends a WebSocket ping control frame every 25 seconds; standard clients answer with pong automatically. The server does not close idle connections itself. You can also send {"ping": 1}.
DIGITOVER or OVER, DIGITUNDER or UNDER, DIGITMATCH or MATCH, DIGITDIFF or DIFFER or DIFF, DIGITEVEN or EVEN, DIGITODD or ODD (case-insensitive). Rise and fall are not available on the gateway. Responses always use the DIGIT... names.
Error frame
{
"msg_type": "proposal",
"echo_req": { "proposal": 1, "contract_type": "DIGITOVER", "symbol": "volatility_100", "amount": 1, "barrier": 12, "req_id": 7 },
"error": { "code": "InputValidationFailed", "message": "barrier must be 0-9 for over/under" },
"req_id": 7
}
Calls
You sendauthorizeno auth
Authenticate the connection with an API token.
Fields
| Name | In | Type | Description |
|---|
| authorize* | message | string | The mp_ token. |
Example
{ "authorize": "mp_USER_TOKEN", "req_id": 1 }
- Sets the active account to the user's USD account of their kind (real, or demo for demo-only users).
You sendpingno auth
Application-level ping.
Fields
| Name | In | Type | Description |
|---|
| ping* | message | any | Value is ignored, for example 1. |
You sendtimeno auth
Server time.
Fields
| Name | In | Type | Description |
|---|
| time* | message | any | Value is ignored. |
You sendactive_symbolsno auth
List tradeable markets.
Fields
| Name | In | Type | Description |
|---|
| active_symbols* | message | any | Value is ignored (for example "brief"). |
Example
{ "active_symbols": "brief" }
You sendticksno authsubscribable
Latest tick, or a tick stream with subscribe: 1.
Fields
| Name | In | Type | Description |
|---|
| ticks* | message | string | Symbol. |
Example
{ "ticks": "volatility_100", "subscribe": 1 }
- Replies have msg_type tick. Errors: UnknownSymbol; InternalError "no price yet".
You sendticks_historyno authsubscribable
Recent ticks; with subscribe: 1 also streams new ticks.
Fields
| Name | In | Type | Description |
|---|
| ticks_history* | message | string | Symbol. |
| count | message | integer | Default 100, max 5000. |
Example
{ "ticks_history": "volatility_100", "count": 100 }
- Replies have msg_type history. Error: UnknownSymbol.
You sendforgetno auth
Stop one subscription.
Fields
| Name | In | Type | Description |
|---|
| forget* | message | string | Subscription id. |
Example
{ "forget": "sub_9f1c2a3b4d5e6f70" }
You sendforget_allno auth
Stop every subscription of one type, or all.
Fields
| Name | In | Type | Description |
|---|
| forget_all* | message | string | ticks, balance, transaction, proposal or proposal_open_contract. An empty string stops all. A non-string value (an array, for example) is read as empty and also stops all. |
Example
{ "forget_all": "ticks" }
You sendbalancescope: readsubscribable
Account balance; with subscribe: 1, re-sent after every account event for the user.
Fields
| Name | In | Type | Description |
|---|
| balance* | message | any | Value is ignored. |
| account | message | string | Operate on this account: a loginid, "real" or "demo". Defaults to the connection's active account. Demo-only users are always pinned to their demo account. |
Example
{ "balance": 1, "account": "real", "subscribe": 1 }
You sendaccount_listscope: read
List the user's options accounts.
Fields
| Name | In | Type | Description |
|---|
| account_list* | message | any | Value is ignored. |
Example
{ "account_list": 1 }
You sendset_accountscope: read
Switch the connection's active account.
Fields
| Name | In | Type | Description |
|---|
| set_account* | message | string | A loginid, "real" or "demo". |
Example
{ "set_account": "VR7E21D0A9C3" }
- Errors: InputValidationFailed ("no such account"), PermissionDenied for a demo-only user picking a real account.
You sendnew_account_realscope: trade
Open a real currency account.
Fields
| Name | In | Type | Description |
|---|
| new_account_real* | message | any | Value is ignored. |
| currency | message | string | Default USD. |
Example
{ "new_account_real": 1, "currency": "EUR" }
- Errors: PermissionDenied for demo-only users; InputValidationFailed for an unsupported currency or an account that already exists.
You sendnew_account_virtualscope: trade
Open a demo currency account, seeded with the equivalent of 10,000 USD.
Fields
| Name | In | Type | Description |
|---|
| new_account_virtual* | message | any | Value is ignored. |
| currency | message | string | Default USD. |
Example
{ "new_account_virtual": 1, "currency": "BTC" }
You sendtransfer_between_accountsscope: payments
Transfer between two of the user's accounts (same kind). Without both account ids, returns the account list.
Fields
| Name | In | Type | Description |
|---|
| transfer_between_accounts* | message | any | Value is ignored. |
| account_from | message | string | Source loginid. |
| account_to | message | string | Destination loginid. |
| amount | message | number | Source currency, major units. Required when both ids are given. |
Example
{ "transfer_between_accounts": 1, "account_from": "MPC4A9E2F17B", "account_to": "MP8F3B21C0DA", "amount": 25 }
- Errors: InputValidationFailed (same account, bad amount, unknown account, real to demo); PermissionDenied (insufficient balance); InternalError (no exchange rate).
You sendaccount_statusscope: read
Verification tier and withdrawal limit.
Fields
| Name | In | Type | Description |
|---|
| account_status* | message | any | Value is ignored. |
| account | message | string | Operate on this account: a loginid, "real" or "demo". Defaults to the connection's active account. Demo-only users are always pinned to their demo account. |
Example
{ "account_status": 1 }
You sendstatementscope: read
Ledger rows of one account, newest first.
Fields
| Name | In | Type | Description |
|---|
| statement* | message | any | Value is ignored. |
| limit | message | integer | Default 50, max 200. |
| account | message | string | Operate on this account: a loginid, "real" or "demo". Defaults to the connection's active account. Demo-only users are always pinned to their demo account. |
Example
{ "statement": 1, "limit": 50 }
You sendprofit_tablescope: read
Settled contracts on the active (or chosen) account.
Fields
| Name | In | Type | Description |
|---|
| profit_table* | message | any | Value is ignored. |
| limit | message | integer | Default 50, max 200. Drawn from the user's 200 most recent settled contracts. |
| account | message | string | Operate on this account: a loginid, "real" or "demo". Defaults to the connection's active account. Demo-only users are always pinned to their demo account. |
Example
{ "profit_table": 1, "limit": 20 }
You sendtransactionscope: readsubscribable
Stream of the user's money events. Must be sent with subscribe: 1.
Fields
| Name | In | Type | Description |
|---|
| transaction* | message | any | Value is ignored. |
Example
{ "transaction": 1, "subscribe": 1 }
- Without subscribe: 1 the reply is {"info": "add \"subscribe\":1 to stream transactions"} and nothing streams.
You sendportfolioscope: read
Open (pending) contracts across all accounts, up to 100.
Fields
| Name | In | Type | Description |
|---|
| portfolio* | message | any | Value is ignored. |
Example
{ "portfolio": 1 }
You sendproposalscope: readsubscribable
Price a digit contract. With subscribe: 1, re-priced on every tick.
Fields
| Name | In | Type | Description |
|---|
| proposal* | message | any | Value is ignored, for example 1. |
| contract_type* | message | string | See GATEWAY.contractTypes. |
| symbol* | message | string | Market. |
| amount* | message | number | Stake, account currency, major units, greater than 0. |
| barrier | message | integer | string | 0..9 for over, under, match, differ. Ignored for even, odd. Over 9 and under 0 pass here but fail at buy. |
| account | message | string | Operate on this account: a loginid, "real" or "demo". Defaults to the connection's active account. Demo-only users are always pinned to their demo account. |
Example
{ "proposal": 1, "contract_type": "DIGITOVER", "symbol": "volatility_100", "amount": 1, "barrier": 4, "req_id": 2 }
- Errors: InputValidationFailed, UnknownSymbol. The proposal id is valid only on this connection; the subscription id equals the proposal id.
You sendbuyscope: trade
Buy a proposal by id, or buy directly with parameters.
Fields
| Name | In | Type | Description |
|---|
| buy* | message | string | Proposal id from this connection. Any value when parameters is used. |
| price | message | number | Maximum price. Rejected if the stake is higher. |
| parameters | message | object | Used when buy is not a known proposal id: contract_type, symbol, amount, barrier, account (same meanings as proposal). |
Example
{ "buy": "prop_4f6a8b2c1d3e", "price": 1, "req_id": 3 }
- Errors: InputValidationFailed (unknown proposal, bad parameters, price moved, invalid contract), UnknownSymbol, PermissionDenied (insufficient balance), InternalError.
You sendproposal_open_contractscope: readsubscribable
State of one contract. With subscribe: 1 on an open contract, updates every tick and once more on settlement, then the subscription ends.
Fields
| Name | In | Type | Description |
|---|
| proposal_open_contract* | message | string | Contract UUID. |
Example
{ "proposal_open_contract": "7d2f4c1e-9a3b-4c55-8e21-0b6f3a9d1c42", "subscribe": 1 }
- Errors: InputValidationFailed (not a UUID, contract not found), InternalError.
Replies
Server sendsauthorize
Authorization result.
Fields
| Name | In | Type | Description |
|---|
| loginid* | message | string | Primary account. |
| email* | message | string | null | User email. |
| scopes* | message | string[] | Token scopes. |
| balance* | message | number | Primary account balance. |
| currency* | message | string | Primary account currency. |
| is_virtual* | message | 0 | 1 | Primary account is demo. |
| account_list* | message | object[] | Every account: loginid, currency, is_crypto, is_virtual, balance. |
Example
{
"msg_type": "authorize",
"echo_req": { "authorize": "mp_USER_TOKEN", "req_id": 1 },
"authorize": {
"loginid": "MPC4A9E2F17B",
"email": "trader@example.com",
"scopes": ["read", "trade"],
"balance": 500,
"currency": "USD",
"is_virtual": 0,
"account_list": [
{ "loginid": "MPC4A9E2F17B", "currency": "USD", "is_crypto": 0, "is_virtual": 0, "balance": 500 },
{ "loginid": "VR7E21D0A9C3", "currency": "USD", "is_crypto": 0, "is_virtual": 1, "balance": 10000 }
]
},
"req_id": 1
}
- Error: InvalidToken ("invalid or expired token").
Server sendsping
Ping reply.
Fields
| Name | In | Type | Description |
|---|
| ping* | message | "pong" | Always pong. |
Example
{ "msg_type": "ping", "echo_req": { "ping": 1 }, "ping": "pong" }
Server sendstime
Server time as Unix seconds.
Fields
| Name | In | Type | Description |
|---|
| time* | message | integer | Unix seconds. |
Example
{ "msg_type": "time", "echo_req": { "time": 1 }, "time": 1794821412 }
Server sendsactive_symbols
Tradeable markets. Display-only instruments are excluded.
Fields
| Name | In | Type | Description |
|---|
| symbol* | message | string | Market id, for example volatility_100. |
| display_name* | message | string | Label. |
| market* | message | string | Always synthetic_index. |
| submarket* | message | string | Always random_index. |
| pip* | message | number | Always 0.01. |
| exchange_is_open* | message | 1 | Always 1. |
| spot | message | number | Latest price, when available. |
| spot_time | message | integer | Unix seconds of spot. |
Example
{
"msg_type": "active_symbols",
"echo_req": { "active_symbols": "brief" },
"active_symbols": [
{ "symbol": "volatility_100", "display_name": "Volatility 100 (1s) Index", "market": "synthetic_index", "submarket": "random_index", "pip": 0.01, "exchange_is_open": 1, "spot": 1031.47, "spot_time": 1794821412 }
]
}
Server sendstick
One tick (reply to ticks, and stream frames for ticks and ticks_history subscriptions).
Fields
| Name | In | Type | Description |
|---|
| symbol* | message | string | Symbol. |
| id* | message | string | Subscription id, empty for a one-off. |
| epoch* | message | integer | Unix seconds. |
| quote* | message | number | Price. |
| pip_size* | message | integer | Always 2. |
| digit* | message | integer | Last digit used for settlement. |
Example
{
"msg_type": "tick",
"echo_req": { "ticks": "volatility_100", "subscribe": 1 },
"tick": { "symbol": "volatility_100", "id": "sub_9f1c2a3b4d5e6f70", "epoch": 1794821413, "quote": 1031.52, "pip_size": 2, "digit": 2 },
"subscription": { "id": "sub_9f1c2a3b4d5e6f70" }
}
Server sendshistory
Tick history as parallel arrays, oldest first.
Fields
| Name | In | Type | Description |
|---|
| prices* | message | number[] | Prices. |
| times* | message | integer[] | Unix seconds. |
| digits* | message | integer[] | Last digits. |
Example
{
"msg_type": "history",
"echo_req": { "ticks_history": "volatility_100", "count": 3 },
"history": { "prices": [1031.2, 1031.47, 1031.52], "times": [1794821411, 1794821412, 1794821413], "digits": [0, 7, 2] }
}
Server sendsforget
1 if a subscription was removed, else 0.
Fields
| Name | In | Type | Description |
|---|
| forget* | message | 0 | 1 | Removed count. |
Example
{ "msg_type": "forget", "echo_req": { "forget": "sub_9f1c2a3b4d5e6f70" }, "forget": 1 }
Server sendsforget_all
Ids of the removed subscriptions.
Fields
| Name | In | Type | Description |
|---|
| forget_all* | message | string[] | Removed ids. |
Example
{ "msg_type": "forget_all", "echo_req": { "forget_all": "ticks" }, "forget_all": ["sub_9f1c2a3b4d5e6f70"] }
Server sendsbalance
Balance of the resolved account.
Fields
| Name | In | Type | Description |
|---|
| balance* | message | number | Major units. |
| currency* | message | string | Currency. |
| loginid* | message | string | Account. |
Example
{
"msg_type": "balance",
"echo_req": { "balance": 1, "subscribe": 1 },
"balance": { "balance": 499, "currency": "USD", "loginid": "MPC4A9E2F17B" },
"subscription": { "id": "sub_0a1b2c3d4e5f6071" }
}
Server sendsaccount_list
Accounts and count.
Fields
| Name | In | Type | Description |
|---|
| count* | message | integer | Number of accounts. |
| accounts* | message | object[] | loginid, currency, is_crypto, is_virtual, balance. |
Example
{
"msg_type": "account_list",
"echo_req": { "account_list": 1 },
"account_list": { "count": 1, "accounts": [ { "loginid": "MPC4A9E2F17B", "currency": "USD", "is_crypto": 0, "is_virtual": 0, "balance": 499 } ] }
}
Server sendsset_account
The new active account.
Fields
| Name | In | Type | Description |
|---|
| loginid* | message | string | Account id (MP... real, VR... demo). |
| currency* | message | string | Account currency. |
| is_crypto* | message | 0 | 1 | 1 for crypto currencies. |
| is_virtual* | message | 0 | 1 | 1 for demo accounts. |
| balance* | message | number | Balance in major units. |
Example
{
"msg_type": "set_account",
"echo_req": { "set_account": "VR7E21D0A9C3" },
"set_account": { "loginid": "VR7E21D0A9C3", "currency": "USD", "is_crypto": 0, "is_virtual": 1, "balance": 10000 }
}
Server sendsnew_account_real
The new account (same shape as set_account).
Fields
| Name | In | Type | Description |
|---|
| loginid* | message | string | Account id (MP... real, VR... demo). |
| currency* | message | string | Account currency. |
| is_crypto* | message | 0 | 1 | 1 for crypto currencies. |
| is_virtual* | message | 0 | 1 | 1 for demo accounts. |
| balance* | message | number | Balance in major units. |
Example
{
"msg_type": "new_account_real",
"echo_req": { "new_account_real": 1, "currency": "EUR" },
"new_account_real": { "loginid": "MP8F3B21C0DA", "currency": "EUR", "is_crypto": 0, "is_virtual": 0, "balance": 0 }
}
Server sendsnew_account_virtual
The new demo account (same shape as set_account).
Fields
| Name | In | Type | Description |
|---|
| loginid* | message | string | Account id (MP... real, VR... demo). |
| currency* | message | string | Account currency. |
| is_crypto* | message | 0 | 1 | 1 for crypto currencies. |
| is_virtual* | message | 0 | 1 | 1 for demo accounts. |
| balance* | message | number | Balance in major units. |
Example
{
"msg_type": "new_account_virtual",
"echo_req": { "new_account_virtual": 1, "currency": "BTC" },
"new_account_virtual": { "loginid": "VR2C9D8E7F6A", "currency": "BTC", "is_crypto": 1, "is_virtual": 1, "balance": 0.105 }
}
Server sendstransfer_between_accounts
Transfer result (or {"accounts": [...]} when no ids were given).
Fields
| Name | In | Type | Description |
|---|
| account_from* | message | string | Source loginid. |
| account_to* | message | string | Destination loginid. |
| amount* | message | number | Debited, source currency. |
| amount_credited* | message | number | Credited, destination currency. |
| from_currency* | message | string | Source currency. |
| to_currency* | message | string | Destination currency. |
| rate* | message | number | FX rate used (1 for same currency). |
| from_balance_after* | message | number | Source balance after. |
| to_balance_after* | message | number | Destination balance after. |
Example
{
"msg_type": "transfer_between_accounts",
"echo_req": { "transfer_between_accounts": 1, "account_from": "MPC4A9E2F17B", "account_to": "MP8F3B21C0DA", "amount": 25 },
"transfer_between_accounts": { "account_from": "MPC4A9E2F17B", "account_to": "MP8F3B21C0DA", "amount": 25, "amount_credited": 23, "from_currency": "USD", "to_currency": "EUR", "rate": 0.92, "from_balance_after": 474, "to_balance_after": 23 }
}
Server sendsaccount_status
Status summary.
Fields
| Name | In | Type | Description |
|---|
| kyc_tier* | message | integer | Verification tier. |
| is_virtual* | message | 0 | 1 | Demo-only user. |
| status* | message | string[] | One of unverified (tier 0 to 1), fully_authenticated (tier 2), withdrawal_locked (tier 3 or more). |
| daily_withdrawal_limit* | message | string | "100.00", "unlimited" or "0.00". |
| currency* | message | string | Resolved account currency. |
Example
{
"msg_type": "account_status",
"echo_req": { "account_status": 1 },
"account_status": { "kyc_tier": 0, "is_virtual": 0, "status": ["unverified"], "daily_withdrawal_limit": "100.00", "currency": "USD" }
}
Server sendsstatement
Ledger rows with running balance.
Fields
| Name | In | Type | Description |
|---|
| count* | message | integer | Rows returned. |
| transactions* | message | object[] | transaction_id, type (ledger kind), amount, balance_after, currency, transaction_time (Unix seconds), description, longcode (ledger note, optional), contract_id (optional). |
Example
{
"msg_type": "statement",
"echo_req": { "statement": 1, "limit": 1 },
"statement": {
"count": 1,
"transactions": [
{ "transaction_id": 90211, "type": "stake_hold", "amount": -1, "balance_after": 499, "currency": "USD", "transaction_time": 1794821412, "description": "Contract purchase", "longcode": "contract opened", "contract_id": "7d2f4c1e-9a3b-4c55-8e21-0b6f3a9d1c42" }
]
}
}
Server sendsprofit_table
Settled contracts.
Fields
| Name | In | Type | Description |
|---|
| count* | message | integer | Rows returned. |
| transactions* | message | object[] | contract_id, contract_type, symbol, buy_price, sell_price, payout, currency, profit, is_win (0 or 1), purchase_time, sell_time, longcode. |
Example
{
"msg_type": "profit_table",
"echo_req": { "profit_table": 1, "limit": 1 },
"profit_table": {
"count": 1,
"transactions": [
{ "contract_id": "7d2f4c1e-9a3b-4c55-8e21-0b6f3a9d1c42", "contract_type": "DIGITOVER", "symbol": "volatility_100", "buy_price": 1, "sell_price": 1.95, "payout": 1.95, "currency": "USD", "profit": 0.95, "is_win": 1, "purchase_time": 1794821412, "sell_time": 1794821415, "longcode": "Win payout if the last digit of Volatility 100 (1s) Index is strictly higher than the barrier." }
]
}
}
Server sendstransaction
First an ack {"action": "subscribed"}, then one frame per event.
Fields
| Name | In | Type | Description |
|---|
| action* | message | string | subscribed (ack), buy, sell, deposit, withdrawal, withdrawal_refund. |
| transaction_time | message | integer | Unix seconds (server time when sent). |
| currency | message | string | Contract currency; USD for cashier events. |
| balance_after | message | number | When the event carries a new balance. |
| contract_id | message | string | buy and sell. |
| amount | message | number | buy: negative stake. sell: payout. |
| longcode | message | string | buy only. |
Example
{
"msg_type": "transaction",
"echo_req": { "transaction": 1, "subscribe": 1 },
"transaction": { "transaction_time": 1794821415, "balance_after": 500.95, "currency": "USD", "action": "sell", "contract_id": "7d2f4c1e-9a3b-4c55-8e21-0b6f3a9d1c42", "amount": 1.95 },
"subscription": { "id": "sub_1122334455667788" }
}
Server sendsportfolio
Open contracts.
Fields
| Name | In | Type | Description |
|---|
| contracts* | message | object[] | contract_id, symbol, contract_type, buy_price, payout, currency, longcode, date_start. |
Example
{
"msg_type": "portfolio",
"echo_req": { "portfolio": 1 },
"portfolio": { "contracts": [ { "contract_id": "7d2f4c1e-9a3b-4c55-8e21-0b6f3a9d1c42", "symbol": "volatility_100", "contract_type": "DIGITOVER", "buy_price": 1, "payout": 1.95, "currency": "USD", "longcode": "Win payout if the last digit of Volatility 100 (1s) Index is strictly higher than the barrier.", "date_start": 1794821412 } ] }
}
Server sendsproposal
A priced proposal you can buy.
Fields
| Name | In | Type | Description |
|---|
| id* | message | string | Proposal id (prop_...). Pass to buy. |
| ask_price* | message | number | Equals your amount. |
| payout* | message | number | Payout if the contract wins. |
| currency* | message | string | Account currency. |
| spot* | message | number | Latest price. |
| spot_time* | message | integer | Unix seconds. |
| display_value* | message | number | Equals your amount. |
| payout_multiplier* | message | number | payout / stake, for example 1.95. |
| longcode* | message | string | Human description. |
Example
{
"msg_type": "proposal",
"echo_req": { "proposal": 1, "contract_type": "DIGITOVER", "symbol": "volatility_100", "amount": 1, "barrier": 4, "req_id": 2 },
"proposal": { "id": "prop_4f6a8b2c1d3e", "ask_price": 1, "payout": 1.95, "currency": "USD", "spot": 1031.47, "spot_time": 1794821412, "display_value": 1, "payout_multiplier": 1.95, "longcode": "Win payout if the last digit of Volatility 100 (1s) Index is strictly higher than the barrier." },
"req_id": 2
}
Server sendsbuy
The purchased contract.
Fields
| Name | In | Type | Description |
|---|
| contract_id* | message | string | Contract UUID. |
| transaction_id* | message | string | Same value as contract_id. |
| buy_price* | message | number | Stake. |
| balance_after* | message | number | Balance after the stake. |
| payout* | message | number | Payout if won. |
| currency* | message | string | Currency. |
| start_time* | message | integer | Unix seconds. |
| longcode* | message | string | Description. |
Example
{
"msg_type": "buy",
"echo_req": { "buy": "prop_4f6a8b2c1d3e", "price": 1, "req_id": 3 },
"buy": { "contract_id": "7d2f4c1e-9a3b-4c55-8e21-0b6f3a9d1c42", "transaction_id": "7d2f4c1e-9a3b-4c55-8e21-0b6f3a9d1c42", "buy_price": 1, "balance_after": 499, "payout": 1.95, "currency": "USD", "start_time": 1794821412, "longcode": "Win payout if the last digit of Volatility 100 (1s) Index is strictly higher than the barrier." },
"req_id": 3
}
Server sendsproposal_open_contract
Contract state.
Fields
| Name | In | Type | Description |
|---|
| contract_id* | message | string | Contract UUID. |
| symbol* | message | string | Market. |
| contract_type* | message | string | DIGIT... name. |
| longcode* | message | string | Description. |
| buy_price* | message | number | Stake. |
| currency* | message | string | Currency. |
| payout* | message | number | Payout if won. |
| entry_spot* | message | number | Entry price. |
| current_spot* | message | number | Latest price. |
| current_spot_time* | message | integer | Unix seconds. |
| status* | message | "open" | "won" | "lost" | Contract status. |
| is_sold* | message | 0 | 1 | 1 once settled. |
| profit* | message | number | 0 while open. |
| date_start* | message | integer | Unix seconds. |
| tick_count* | message | integer | Ticks from entry to settlement. |
| exit_spot | message | number | After settlement. |
| exit_digit | message | integer | After settlement. |
Example
{
"msg_type": "proposal_open_contract",
"echo_req": { "proposal_open_contract": "7d2f4c1e-9a3b-4c55-8e21-0b6f3a9d1c42", "subscribe": 1 },
"proposal_open_contract": { "contract_id": "7d2f4c1e-9a3b-4c55-8e21-0b6f3a9d1c42", "symbol": "volatility_100", "contract_type": "DIGITOVER", "longcode": "Win payout if the last digit of Volatility 100 (1s) Index is strictly higher than the barrier.", "buy_price": 1, "currency": "USD", "payout": 1.95, "entry_spot": 1031.47, "current_spot": 1032.18, "current_spot_time": 1794821415, "status": "won", "is_sold": 1, "profit": 0.95, "date_start": 1794821412, "tick_count": 3, "exit_spot": 1032.18, "exit_digit": 8 },
"subscription": { "id": "sub_a1b2c3d4e5f60718" }
}
Server sends(error)
Any call can fail with this envelope instead of its payload.
Fields
| Name | In | Type | Description |
|---|
| msg_type* | message | string | The call's reply type (for unknown calls, the unknown key). |
| echo_req* | message | object | Your request. |
| error.code* | message | string | See ERRORS.gatewayCodes. |
| error.message* | message | string | Human-readable reason. |
| req_id | message | integer | Echoed when sent. |
Example
{
"msg_type": "proposal",
"echo_req": { "proposal": 1, "contract_type": "DIGITOVER", "symbol": "volatility_100", "amount": 1, "barrier": 12, "req_id": 7 },
"error": { "code": "InputValidationFailed", "message": "barrier must be 0-9 for over/under" },
"req_id": 7
}
Price feed (WebSocket)
Open wss://<api-origin>/api/v1/feed/ws. Without credentials you get market data only. Add ?token=mp_... (or have a browser session cookie) to also receive the user's account events and to use user channels. Connections that carry ?token= are accepted from any Origin; connections without a token must come from an allow-listed Origin or send no Origin.
The server immediately sends one symbols message, then one history message per tradeable symbol (up to 300 ticks each), then streams tick messages for every symbol. There is no per-symbol subscription for ticks.
The server sends a WebSocket ping control frame every 20 seconds.
Server sendssymbols
Catalog of tradeable platform instruments. First message after connect.
Fields
| Name | In | Type | Description |
|---|
| symbols* | message | object[] | symbol, label, asset_class, submarket (optional), price_precision, trade_types. |
Example
{
"type": "symbols",
"symbols": [
{ "symbol": "volatility_100", "label": "Volatility 100 (1s) Index", "asset_class": "synthetic", "submarket": "continuous_indices", "price_precision": 2, "trade_types": ["even_odd", "match_differ", "over_under", "rise_fall", "higher_lower", "touch_no_touch"] }
]
}
- trade_types lists contract families for the instrument's asset class. Only even/odd, match/differ, over/under and rise/fall can actually be traded through the API.
Server sendshistory
Initial tick snapshot for one symbol (up to 300 ticks).
Fields
| Name | In | Type | Description |
|---|
| symbol* | message | string | Symbol. |
| history* | message | object[] | Ticks: id, symbol, ts (RFC 3339), price, digit. |
Example
{
"type": "history",
"symbol": "volatility_100",
"history": [ { "id": 884212, "symbol": "volatility_100", "ts": "2026-11-16T09:30:11Z", "price": 1031.2, "digit": 0 } ]
}
Server sendstick
One new tick for any symbol.
Fields
| Name | In | Type | Description |
|---|
| tick* | message | object | id, symbol, ts, price, digit. |
Example
{ "type": "tick", "tick": { "id": 884213, "symbol": "volatility_100", "ts": "2026-11-16T09:30:12Z", "price": 1031.47, "digit": 7 } }
- Ticks are dropped for a slow client rather than queued.
Server sendscontract.opened
Authenticated only. A contract was bought (web, REST or gateway).
Fields
| Name | In | Type | Description |
|---|
| contract* | message | object | Event data: { contract: <Contract>, new_balance_cents }. The outer key is named contract for every event type. |
Example
{ "type": "contract.opened", "contract": { "contract": { "id": "7d2f4c1e-9a3b-4c55-8e21-0b6f3a9d1c42", "status": "pending", "stake_cents": 100 }, "new_balance_cents": 49900 } }
Server sendscontract.settled
Authenticated only. A contract settled.
Fields
| Name | In | Type | Description |
|---|
| contract* | message | object | Event data: { contract: <Contract>, new_balance_cents, won }. |
Example
{ "type": "contract.settled", "contract": { "contract": { "id": "7d2f4c1e-9a3b-4c55-8e21-0b6f3a9d1c42", "status": "won", "payout_cents": 195 }, "new_balance_cents": 50095, "won": true } }
Server sends(payment event)
Authenticated only. Cashier events: deposit.completed, deposit.failed, ugx_deposit.completed, ugx_deposit.failed, withdrawal.opened, withdrawal.completed, withdrawal.failed, crypto_withdrawal.updated, transfer.completed.
Fields
| Name | In | Type | Description |
|---|
| type* | message | string | The event name. |
| contract* | message | object | Event data, despite the key name. Usually { deposit: {...} } or { withdrawal: {...} }, sometimes with new_balance_cents. transfer.completed carries { from_wallet_id, to_wallet_id }. |
Example
{ "type": "withdrawal.completed", "contract": { "withdrawal": { "id": "f0e1d2c3-b4a5-4697-8879-6a5b4c3d2e1f", "status": "succeeded" } } }
You sendsubscribe
Subscribe to a channel. User channels need a token or session.
Fields
| Name | In | Type | Description |
|---|
| type* | message | "subscribe" | Literal. |
| channel* | message | string | mt5.state (the user's MT5 account balance and equity) or mt5.positions (full open-position list of one of the user's MT5 accounts). Other names are staff-only or unknown. |
| loginid | message | string | Only deliver events for this MT5 loginid. |
Example
{ "type": "subscribe", "channel": "mt5.positions", "loginid": "MTR40012345" }
You sendunsubscribe
Unsubscribe from a channel. No reply is sent.
Fields
| Name | In | Type | Description |
|---|
| type* | message | "unsubscribe" | Literal. |
| channel* | message | string | Channel name. |
Example
{ "type": "unsubscribe", "channel": "mt5.positions" }
Server sendssubscribed
Subscription confirmed. A repeat subscribe to the same channel gets no reply.
Fields
| Name | In | Type | Description |
|---|
| channel* | message | string | Channel name. |
Example
{ "type": "subscribed", "channel": "mt5.positions" }
Server sendserror
Subscribe refused.
Fields
| Name | In | Type | Description |
|---|
| channel* | message | string | Channel name. |
| code* | message | string | unknown_channel, forbidden (staff channel) or unauthenticated (user channel without a token or session). |
Example
{ "type": "error", "channel": "mt5.state", "code": "unauthenticated" }
Server sends(channel event)
One event on a subscribed channel. Note: this frame has no type field.
Fields
| Name | In | Type | Description |
|---|
| channel* | message | string | mt5.state or mt5.positions. |
| loginid | message | string | MT5 account (MTR... real, MTD... demo). |
| ts* | message | string | RFC 3339 time. |
| user_id | message | string | Owner user id. |
| payload* | message | object | mt5.state: balance_minor, equity_minor, margin_minor, margin_free_minor, profit_minor, currency. mt5.positions: { positions: [ticket, symbol, side, volume_units, price_open, price_current, digits, open_time, profit_minor, swap_minor, ...] }. |
Example
{
"channel": "mt5.state",
"loginid": "MTR40012345",
"ts": "2026-11-16T09:31:00Z",
"user_id": "3b1e8f6a-2c4d-4e7f-9a10-5d6c7b8a9e01",
"payload": { "balance_minor": 100000, "equity_minor": 101250, "margin_minor": 2000, "margin_free_minor": 99250, "profit_minor": 1250, "currency": "USD" }
}
Errors
REST errors are JSON {"error": "<message>"} with an HTTP status. A few routes add fields, for example the withdrawal step-up 401 (code, stepup_id, ...) and the prelive allow-list 403 ({"error": "prelive_not_allowlisted"}). The scope gate message is "token is missing the `<scope>` scope".
REST
{ "error": "insufficient balance" }
OAuth
{
"error": "invalid_grant",
"error_description": "invalid or expired authorization code"
}
Gateway
{
"msg_type": "proposal",
"echo_req": { "proposal": 1, "contract_type": "DIGITOVER", "symbol": "volatility_100", "amount": 1, "barrier": 12, "req_id": 7 },
"error": { "code": "InputValidationFailed", "message": "barrier must be 0-9 for over/under" },
"req_id": 7
}
HTTP statuses
- 200 Success.
- 201 Created (app registration, token creation).
- 202 Accepted: a deposit or withdrawal was started and completes asynchronously.
- 302 OAuth consent redirect back to your redirect_uri.
- 400 Invalid input, including JSON with unknown fields or a body over 1 MB.
- 401 Not authenticated, or a withdrawal step-up is required.
- 402 Insufficient balance (contracts, transfers, withdrawals).
- 403 Token is missing the required scope, or the action is not allowed for this user.
- 404 Not found, or not owned by the caller.
- 409 Conflict, for example the currency account already exists.
- 429 Too soon: repeated withdrawal or step-up code request.
- 500 Server error.
- 502 Payment provider call failed.
- 503 Temporarily unavailable: price feed not ready, no FX rate, market browser not available, Kenyan deposits switched off.
Gateway error codes
InvalidToken authorize with an unknown or deleted token.AuthorizationRequired A call that needs a token before authorize succeeded.PermissionDenied Token lacks the exact scope; demo-only restrictions; insufficient balance on buy or transfer.UnrecognisedRequest No known call key in the message, or an unknown call.InputValidationFailed Bad or missing parameters.UnknownSymbol Symbol not found.RateLimit More than the per-connection message budget (see LIMITS).InternalError Server-side failure, no price yet, no account, no exchange rate.
OAuth error codes
unsupported_grant_type grant_type is not authorization_code.invalid_grant Bad, used or expired code; app_id or redirect_uri mismatch; PKCE failed.server_error Token could not be issued.access_denied Redirect parameter when the user cancels on the consent page.
Feed error codes
unknown_channel Subscribe to a channel name that does not exist.forbidden Subscribe to a staff channel.unauthenticated Subscribe to a user channel without a token or session.
Limits
| Gateway message rate | Token bucket per connection: 30 messages per second sustained, burst 60. Over the limit returns a RateLimit error for that message. |
| REST rate limiting | None found. No HTTP rate limiter is mounted on the router. |
| Withdrawal frequency | About one withdrawal initiation per minute per user (429). |
| REST JSON body | 1 MB maximum; unknown fields are rejected. |
| Bulk contracts | 1 to 60 items per request. |
| Contract duration | Platform default 3 ticks (admin setting contract_duration_ticks). REST duration_ticks clamped to 1..3600. Gateway contracts always use the default. |
| Contract list | GET /api/v1/contracts limit default 50, max 1000. |
| Gateway history | ticks_history count default 100, max 5000. statement and profit_table limit default 50, max 200. portfolio up to 100 open contracts. |
| Feed snapshot | Up to 300 ticks per symbol on connect. |
| Market catalog | /markets/symbols limit default 50, max 200. /markets/quotes up to 200 symbols. |
| Account transactions | limit default 50, max 200. |
| Unified deposits | limit default 30, max 100. |
| App earnings claim | Minimum 500 cents (5 USD) claimable. |
| App markup | markup_bp clamped to 0..3000. |
| Authorization code | Single use, 5 minute lifetime. |
| Access token lifetime | No expiry. |
App earnings
An app earns a flat platform share (setting app_profit_share_bp, default 1000 = 10%) of the net house revenue from contracts attributed to it. Net revenue counts settled contracts on real USD accounts only: stake minus payout, summed over the app's lifetime and floored at 0. The per-app markup_bp does not change this.
A contract is attributed to an app when it is bought with a token bound to that app (an OAuth-issued token, or a personal token created with app_id), on the gateway buy call, REST POST /api/v1/contracts or REST POST /api/v1/contracts/bulk. On the gateway, a token with no app binding uses ?app_id= from the connection URL.
Endpoints: GET /api/v1/apps/earnings, POST /api/v1/apps/{app_id}/claim. See Developer apps.