Developers

API documentation

Build apps that trade for your users, stream prices, and read live market data. Your users authorize your app with OAuth 2.0, you get a scoped token, and you trade over REST or the real-time WebSocket gateway.

Overview

ProductionTesting
RESThttps://api.miletrades.sitehttps://stg-backend.miletraders.com
Trading gatewaywss://api.miletrades.site/ws/v1wss://stg-backend.miletraders.com/ws/v1
Price feedwss://api.miletrades.site/api/v1/feed/wswss://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

  1. Register an app with its redirect URIs and the scopes it needs. You get an 8-digit app_id.
  2. Send the user through OAuth 2.0 with PKCE and exchange the code for an access token.
  3. Call REST with Authorization: Bearer mp_…, or open the gateway and send {"authorize": "mp_…"}.
  4. 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

NameInTypeDescription
app_id*querystringYour 8-digit app_id.
redirect_uri*querystringMust exactly equal one of the app's registered redirect_uris.
code_challenge*querystringbase64url(SHA-256(code_verifier)) with no padding.
code_challenge_methodquerystringOnly S256 is accepted. May be omitted; the challenge is always verified as S256.
response_typequerystringOnly code is accepted. May be omitted.
scopequerystringSpace or comma separated. Must be a subset of the app's registered scopes. Defaults to all of the app's scopes.
statequerystringOpaque 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

NameInTypeDescription
grant_type*formstringMust be authorization_code. No other grant type exists (no refresh_token, no client_credentials).
code*formstringThe mpc_ code from the redirect.
redirect_uri*formstringMust equal the redirect_uri used on the authorize request.
code_verifier*formstringThe PKCE verifier whose S256 hash was sent as code_challenge.
app_idformstringOptional. 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"
}
400unsupported_grant_typegrant_type is not authorization_code.
400invalid_grantCode unknown, already used or expired; app_id mismatch; redirect_uri mismatch; PKCE verification failed.
500server_errorThe 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.

ScopeThe user seesGrants
readView your markets, balance, portfolio and historyGateway: 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.
tradeBuy and sell contracts on your behalfGateway: buy, new_account_real, new_account_virtual. REST: POST /api/v1/contracts, POST /api/v1/contracts/bulk, POST /api/v1/accounts.
paymentsDeposit and withdraw from your accountGateway: 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.
adminManage your API apps and tokensREST: 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.

OAuth 2.0

Authorization code flow with mandatory PKCE (S256). The authorize endpoints are browser pages; only the token endpoint is called by your server.

GET/api/v1/oauth/authorize
Browser page200

Show the consent page.

Open this URL in the user's browser. It renders an HTML login and consent page. See AUTH.oauth for parameters.

Parameters

NameInTypeDescription
app_id*querystringYour 8-digit app_id.
redirect_uri*querystringMust exactly equal one of the app's registered redirect_uris.
code_challenge*querystringbase64url(SHA-256(code_verifier)) with no padding.
code_challenge_methodquerystringOnly S256 is accepted. May be omitted; the challenge is always verified as S256.
response_typequerystringOnly code is accepted. May be omitted.
scopequerystringSpace or comma separated. Must be a subset of the app's registered scopes. Defaults to all of the app's scopes.
statequerystringOpaque value echoed back on the redirect. Use it for CSRF protection.

Response 200

HTML consent page (text/html)

Errors

  • 200 Invalid parameters render an HTML "Can't authorize" page with the reason.
POST/api/v1/oauth/authorize
Browser page302

Consent form submission (posted by the consent page).

Not for direct use. The consent page posts app_id, redirect_uri, scope, state, code_challenge, action (approve or deny) and, when the browser has no session, email and password. On approve it redirects with code and state; on deny it redirects with error=access_denied and state.

Parameters

NameInTypeDescription
action*form"approve" | "deny"deny redirects with error=access_denied. Any other value is treated as approve.
emailformstringOnly when the browser has no session.
passwordformstringOnly when the browser has no session.

Response 302

302 Found
Location: https://example.com/callback?code=mpc_EXAMPLEauthCode000000000000000&state=Xy7pQ2

Errors

  • 200 Wrong email or password re-renders the consent page with "Incorrect email or password."
POST/api/v1/oauth/token
No auth200

Exchange an authorization code for an API token.

Parameters

NameInTypeDescription
grant_type*formstringMust be authorization_code. No other grant type exists (no refresh_token, no client_credentials).
code*formstringThe mpc_ code from the redirect.
redirect_uri*formstringMust equal the redirect_uri used on the authorize request.
code_verifier*formstringThe PKCE verifier whose S256 hash was sent as code_challenge.
app_idformstringOptional. If sent, must match the app the code was issued to.

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

Response 200

{
  "access_token": "mp_EXAMPLEaccessToken0000000000000",
  "token_type": "bearer",
  "scope": "read trade",
  "app_id": "10482736"
}

Errors

  • 400 unsupported_grant_type or invalid_grant (see AUTH.oauth.tokenErrors).
  • 500 server_error: could not issue token.
  • 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.

Developer apps

Register and manage OAuth apps, and read and claim app earnings. Intended for the app owner's signed-in browser session (the Developer apps page); these routes also accept the owner's API token.

POST/api/v1/apps
Bearer token201

Register an app.

Parameters

NameInTypeDescription
name*bodystringDisplay name shown on the consent page.
redirect_uris*bodystring[]At least one. Matched exactly on authorize and token requests.
scopesbodystring[]Any of read, trade, payments, admin. Defaults to ["read"].
homepagebodystringLinked from the consent page.
markup_bpbodyintegerStored and clamped to 0..3000. Not used to compute earnings.

Request

{
  "name": "Example Trading App",
  "redirect_uris": ["https://example.com/callback"],
  "scopes": ["read", "trade"],
  "homepage": "https://example.com"
}

Response 201

{
  "app": {
    "app_id": "10482736",
    "name": "Example Trading App",
    "redirect_uris": ["https://example.com/callback"],
    "scopes": ["read", "trade"],
    "markup_bp": 0,
    "homepage": "https://example.com",
    "verified": false,
    "created_at": "2026-11-16T09:00:00Z"
  },
  "app_secret": "mps_EXAMPLEappSecret00000000000000"
}

Errors

  • 400 Body is not valid JSON, contains an unknown field, or exceeds 1 MB ("invalid json").
  • 400 name is empty ("name is required").
  • 400 redirect_uris is empty ("at least one redirect_uri is required").
  • 400 Unknown scope ("invalid scope (allowed: read, trade, payments, admin)").
  • 401 No valid token or session ("not authenticated").
  • app_secret is returned only once.
GET/api/v1/apps
Bearer token200

List the caller's apps, newest first.

Response 200

{
  "apps": [
    {
      "app_id": "10482736",
      "name": "Example Trading App",
      "redirect_uris": ["https://example.com/callback"],
      "scopes": ["read", "trade"],
      "markup_bp": 0,
      "homepage": "https://example.com",
      "verified": false,
      "created_at": "2026-11-16T09:00:00Z"
    }
  ]
}

Errors

  • 401 No valid token or session ("not authenticated").
PATCH/api/v1/apps/{app_id}/markup
Bearer token200

Change an app's stored markup.

Parameters

NameInTypeDescription
app_id*pathstringOne of the caller's apps.
markup_bp*bodyintegerClamped to 0..3000 (0% to 30%).

Request

{ "markup_bp": 1500 }

Response 200

{
  "app": {
    "app_id": "10482736",
    "name": "Example Trading App",
    "redirect_uris": ["https://example.com/callback"],
    "scopes": ["read", "trade"],
    "markup_bp": 1500,
    "homepage": "https://example.com",
    "verified": false,
    "created_at": "2026-11-16T09:00:00Z"
  }
}

Errors

  • 400 Body is not valid JSON, contains an unknown field, or exceeds 1 MB ("invalid json").
  • 404 Not one of the caller's apps ("app not found").
  • 401 No valid token or session ("not authenticated").
  • Earnings use the platform-wide rate, not markup_bp. The field is kept for display.
DELETE/api/v1/apps/{app_id}
Bearer token200

Delete an app.

Parameters

NameInTypeDescription
app_id*pathstringOne of the caller's apps.

Response 200

{ "deleted": true }

Errors

  • 404 Not one of the caller's apps ("app not found").
  • 401 No valid token or session ("not authenticated").
  • Tokens already issued for the app are not deleted and keep working.
GET/api/v1/apps/earnings
Bearer token200

Revenue-share earnings for each of the caller's apps.

ngr_cents is lifetime stake minus payout over settled (won or lost) contracts attributed to the app, counting only real-money USD accounts. commission_cents is ngr_cents times the platform rate (app_profit_share_bp, default 1000 = 10%), floored at 0. claimable_cents = commission_cents minus paid_cents, floored at 0.

Response 200

{
  "apps": [
    {
      "app_id": "10482736",
      "name": "Example Trading App",
      "markup_bp": 0,
      "ngr_cents": 124500,
      "commission_cents": 12450,
      "paid_cents": 5000,
      "claimable_cents": 7450,
      "users": 42
    }
  ],
  "min_claim_cents": 500
}

Errors

  • 401 No valid token or session ("not authenticated").
POST/api/v1/apps/{app_id}/claim
Bearer tokenscope: payments200

Claim an app's outstanding earnings to the owner's real USD account.

Parameters

NameInTypeDescription
app_id*pathstringOne of the caller's apps.

Response 200

{
  "app_id": "10482736",
  "claimed_cents": 7450,
  "new_balance_cents": 57450,
  "claimable_cents": 0
}

Errors

  • 400 Claimable amount below 500 cents ("nothing to claim yet (minimum $5)").
  • 400 The owner has no real USD account ("no USD wallet on this account").
  • 403 Demo user ("demo accounts have no earnings") or token without payments.
  • 404 Not one of the caller's apps ("app not found").
  • 401 No valid token or session ("not authenticated").

API tokens

Personal API tokens for the signed-in user. OAuth-issued tokens for that user also appear here and can be deleted here.

POST/api/v1/tokens
Bearer token201

Create a token. The plaintext is returned once.

Parameters

NameInTypeDescription
namebodystringLabel for the token.
scopesbodystring[]Any of read, trade, payments, admin. Defaults to ["read"].
app_idbodystringBinds the token to an app_id for revenue attribution. Not validated.

Request

{ "name": "My trading script", "scopes": ["read", "trade"] }

Response 201

{
  "token": "mp_EXAMPLEpersonalToken00000000000",
  "meta": {
    "id": "5e0c2a7d-81f4-4b9e-a3c6-2d1f0e9b8a77",
    "display": "mp_EXAMPL…",
    "name": "My trading script",
    "scopes": ["read", "trade"],
    "created_at": "2026-11-16T09:05:00Z"
  }
}

Errors

  • 400 Body is not valid JSON, contains an unknown field, or exceeds 1 MB ("invalid json").
  • 400 Unknown scope ("invalid scope (allowed: read, trade, payments, admin)").
  • 401 No valid token or session ("not authenticated").
  • display is the first 9 characters followed by an ellipsis character.
  • app_id is omitted from meta when empty; last_used_at is omitted until first use.
GET/api/v1/tokens
Bearer token200

List the caller's tokens, newest first. Plaintext is never returned.

Response 200

{
  "tokens": [
    {
      "id": "5e0c2a7d-81f4-4b9e-a3c6-2d1f0e9b8a77",
      "display": "mp_EXAMPL…",
      "name": "oauth:10482736",
      "scopes": ["read", "trade"],
      "app_id": "10482736",
      "created_at": "2026-11-16T09:05:00Z",
      "last_used_at": "2026-11-16T10:12:44Z"
    }
  ]
}

Errors

  • 401 No valid token or session ("not authenticated").
DELETE/api/v1/tokens/{id}
Bearer token200

Delete (revoke) one of the caller's tokens.

Parameters

NameInTypeDescription
id*pathuuidToken id from the list.

Response 200

{ "revoked": true }

Errors

  • 400 id is not a UUID ("invalid id").
  • 404 Not one of the caller's tokens ("token not found").
  • 401 No valid token or session ("not authenticated").

Account and balances

The user's profile, options accounts (wallets) and multi-currency transfers. Account ids (loginid) are MP followed by 10 hex characters for real accounts and VR followed by 10 hex characters for demo accounts.

GET/api/v1/auth/me
Bearer token200

The caller's user record, wallets and verification state.

Response 200

{
  "user": {
    "id": "3b1e8f6a-2c4d-4e7f-9a10-5d6c7b8a9e01",
    "email": "trader@example.com",
    "is_demo": false,
    "kyc_tier": 0,
    "is_partner": false,
    "country": "KE",
    "created_at": "2026-10-01T08:00:00Z"
  },
  "wallets": [
    {
      "type": "wallet",
      "id": "c4a9e2f1-7b3d-4a6e-8c5f-1d2e3f4a5b6c",
      "loginid": "MPC4A9E2F17B",
      "kind": "real",
      "currency": "USD",
      "balance_cents": 50000,
      "locked_cents": 0,
      "is_crypto": false,
      "in_transfer_cents": 0,
      "withdrawable_cents": 50000
    }
  ],
  "email_verified": true,
  "onboarding_rung": 1,
  "kyc_status": "not_started",
  "kyc_tier": 0,
  "kyc_documents": []
}

Errors

  • 401 No valid token or session ("not authenticated").
  • 500 Wallets could not be loaded.
  • user also carries phone, display_name and admin_role when set (omitted when empty).
GET/api/v1/currencies
Bearer token200

Supported account currencies with live USD rates and crypto networks.

Response 200

{
  "currencies": [
    { "code": "USD", "name": "US Dollar", "decimals": 2, "class": "fiat", "is_crypto": false, "usd_rate": 1 },
    { "code": "KES", "name": "Kenyan Shilling", "decimals": 2, "class": "fiat", "is_crypto": false, "usd_rate": 129.2 },
    {
      "code": "USDT", "name": "Tether", "decimals": 6, "class": "crypto", "is_crypto": true, "usd_rate": 1,
      "networks": [{ "network": "trc20", "chain": "tron" }]
    }
  ]
}

Errors

  • 401 No valid token or session ("not authenticated").
  • usd_rate is units of the currency per 1 USD; omitted when no rate is available.
POST/api/v1/accounts
Bearer tokenscope: trade200

Open a currency account.

Real accounts start empty. Demo accounts are seeded with the equivalent of 10,000 USD in their own currency.

Parameters

NameInTypeDescription
kindbody"real" | "demo"Default real.
currency*bodystringA supported code from /api/v1/currencies, for example EUR or BTC.

Request

{ "kind": "real", "currency": "EUR" }

Response 200

{
  "account": {
    "loginid": "MP8F3B21C0DA",
    "kind": "real",
    "currency": "EUR",
    "is_crypto": false,
    "is_virtual": false,
    "balance_cents": 0,
    "balance": 0
  }
}

Errors

  • 400 Body is not valid JSON, contains an unknown field, or exceeds 1 MB ("invalid json").
  • 400 kind is not real or demo, or the currency is unsupported.
  • 403 Demo-only user asking for a real account ("this is a virtual-only account"), or token without trade.
  • 409 The user already holds that currency and kind.
  • 401 No valid token or session ("not authenticated").
POST/api/v1/accounts/transfer
Bearer tokenscope: payments200

Move money between two of the caller's accounts, converting by FX when currencies differ.

Parameters

NameInTypeDescription
from_loginid*bodystringSource account.
to_loginid*bodystringDestination account. Same kind (real or demo) as the source.
amount*bodynumberAmount in the source currency, major units (for example 25.50).

Request

{ "from_loginid": "MPC4A9E2F17B", "to_loginid": "MP8F3B21C0DA", "amount": 25.5 }

Response 200

{
  "from_loginid": "MPC4A9E2F17B",
  "to_loginid": "MP8F3B21C0DA",
  "from_currency": "USD",
  "to_currency": "EUR",
  "amount": 25.5,
  "amount_credited": 23.46,
  "rate": 0.92,
  "from_balance_after": 474.5,
  "to_balance_after": 23.46
}

Errors

  • 400 Body is not valid JSON, contains an unknown field, or exceeds 1 MB ("invalid json").
  • 400 Same account, unknown account, real to demo transfer, or amount not greater than zero.
  • 402 Insufficient balance.
  • 403 Token without payments.
  • 503 No exchange rate for the pair.
  • 401 No valid token or session ("not authenticated").
GET/api/v1/accounts/{loginid}/transactions
Bearer token200

Ledger history of one options account, newest first.

Parameters

NameInTypeDescription
loginid*pathstringOne of the caller's options accounts.
limitqueryintegerDefault 50, max 200.
beforequeryintegerLedger id cursor: return rows older than this id. Use next_before from the previous page.

Response 200

{
  "loginid": "MPC4A9E2F17B",
  "currency": "USD",
  "transactions": [
    {
      "id": 90211,
      "category": "trade",
      "kind": "stake_hold",
      "description": "Contract purchase",
      "note": "contract opened",
      "amount_minor": -100,
      "balance_after_minor": 49900,
      "currency": "USD",
      "created_at": "2026-11-16T09:30:12Z"
    }
  ],
  "next_before": 90211
}

Errors

  • 400 limit is not a positive integer, or before is not a ledger id.
  • 404 Not one of the caller's options accounts ("account not found").
  • 401 No valid token or session ("not authenticated").
  • category is one of deposit, withdrawal, refund, transfer, trade, commission, adjustment.
  • next_before is omitted on the last page.

Contracts (REST trading)

Price, place and list contracts over REST. Trades placed with an OAuth-issued token are attributed to that token's app for revenue share. Digit contracts: even, odd, match, differ, over, under (synthetic indices only). Price contracts: rise, fall (any instrument). Amounts are integer minor units (cents) of the account currency.

POST/api/v1/contracts/proposal
Bearer token200

Price a prospective contract. Changes nothing.

Parameters

NameInTypeDescription
symbolbodystringInstrument, for example volatility_100. Defaults to the first registered index.
contract_type*bodystringeven, odd, match, differ, over, under, rise or fall (lowercase).
paramsbody{ digit?: integer; threshold?: integer }match and differ: digit 0..9. over: threshold 0..8. under: threshold 1..9. even, odd, rise, fall: none.
stake_centsbodyintegerWhen greater than 0, payout_cents is computed.
wallet_kindbody"real" | "demo"Selects the RTP tier. Defaults to the user's kind.

Request

{
  "symbol": "volatility_100",
  "contract_type": "over",
  "params": { "threshold": 4 },
  "stake_cents": 100
}

Response 200

{
  "payout_multiplier_bp": 19500,
  "payout_cents": 195,
  "win_probability": 0.5,
  "spot_price": 1031.47,
  "spot_digit": 7
}

Errors

  • 400 Body is not valid JSON, contains an unknown field, or exceeds 1 MB ("invalid json").
  • 400 Unknown symbol, digit contract on a non-synthetic instrument, or invalid type or params.
  • 401 No valid token or session ("not authenticated").
POST/api/v1/contracts
Bearer tokenscope: trade200

Buy a contract. The stake is debited immediately.

The contract enters at the latest tick and settles a number of ticks later (the platform default, currently 3, unless duration_ticks is given). Settlement is pushed on the price feed WebSocket as contract.settled.

Parameters

NameInTypeDescription
symbolbodystringInstrument. Defaults to the first registered index.
contract_type*bodystringeven, odd, match, differ, over, under, rise or fall.
stake_cents*bodyintegerStake in minor units of the account currency. Must be greater than 0.
paramsbody{ digit?: integer; threshold?: integer }Same rules as the proposal endpoint.
wallet_kindbody"real" | "demo"Defaults to the user's kind. Selects that kind's USD account when loginid is not given.
loginidbodystringStake from this specific options account (and in its currency).
duration_ticksbodyintegerTicks after entry until settlement, clamped to 1..3600.

Request

{
  "symbol": "volatility_100",
  "contract_type": "over",
  "params": { "threshold": 4 },
  "stake_cents": 100,
  "wallet_kind": "real"
}

Response 200

{
  "contract": {
    "id": "7d2f4c1e-9a3b-4c55-8e21-0b6f3a9d1c42",
    "user_id": "3b1e8f6a-2c4d-4e7f-9a10-5d6c7b8a9e01",
    "wallet_id": "c4a9e2f1-7b3d-4a6e-8c5f-1d2e3f4a5b6c",
    "currency": "USD",
    "symbol": "volatility_100",
    "contract_type": "over",
    "params": { "threshold": 4 },
    "stake_cents": 100,
    "payout_multiplier_bp": 19500,
    "status": "pending",
    "entry_tick_id": 884213,
    "entry_price": 1031.47,
    "settle_tick_id": 884216,
    "created_at": "2026-11-16T09:30:12.418Z"
  },
  "new_balance_cents": 49900
}

Errors

  • 400 Body is not valid JSON, contains an unknown field, or exceeds 1 MB ("invalid json").
  • 400 Unknown symbol or account, demo user on a real wallet, digit contract off synthetics, invalid type, params or stake, wallet not found, or a view-only market.
  • 402 Insufficient balance.
  • 403 Token without trade.
  • 503 Price feed not ready.
  • 401 No valid token or session ("not authenticated").
POST/api/v1/contracts/bulk
Bearer tokenscope: trade200

Place up to 60 contracts in one request. Each item succeeds or fails on its own.

Parameters

NameInTypeDescription
items*bodyobject[]1..60 items with the same fields as POST /api/v1/contracts. The loginid field is accepted but ignored: bulk items always use the USD account of wallet_kind.

Request

{
  "items": [
    { "symbol": "volatility_100", "contract_type": "even", "stake_cents": 100 },
    { "symbol": "volatility_50", "contract_type": "match", "params": { "digit": 3 }, "stake_cents": 50 }
  ]
}

Response 200

{
  "results": [
    { "index": 0, "symbol": "volatility_100", "contract": { "id": "7d2f4c1e-9a3b-4c55-8e21-0b6f3a9d1c42", "status": "pending" }, "new_balance_cents": 49900 },
    { "index": 1, "symbol": "volatility_50", "error": "insufficient balance" }
  ],
  "placed": 1,
  "failed": 1,
  "new_balance_cents": 49900
}

Errors

  • 400 Body is not valid JSON, contains an unknown field, or exceeds 1 MB ("invalid json").
  • 400 No items, or more than 60 ("too many items").
  • 403 Token without trade.
  • 401 No valid token or session ("not authenticated").
  • Each placed result carries a full contract object (abbreviated in the example).
  • Item error strings: unknown symbol, demo users can only trade the demo wallet, price feed not ready, invalid contract type, invalid params, invalid stake, wallet not found, insufficient balance, could not create contract.
GET/api/v1/contracts
Bearer token200

List the caller's contracts, newest first.

Parameters

NameInTypeDescription
statusquery"open" | "closed"open = pending. closed = won, lost or cancelled. Omitted or any other value = all.
symbolquerystringFilter by instrument.
fromquerystringRFC 3339 time or YYYY-MM-DD. Unparseable values are ignored.
toquerystringRFC 3339 time or YYYY-MM-DD. Unparseable values are ignored.
limitqueryintegerDefault 50. Values above 1000 fall back to 50.

Response 200

{
  "contracts": [
    {
      "id": "7d2f4c1e-9a3b-4c55-8e21-0b6f3a9d1c42",
      "user_id": "3b1e8f6a-2c4d-4e7f-9a10-5d6c7b8a9e01",
      "wallet_id": "c4a9e2f1-7b3d-4a6e-8c5f-1d2e3f4a5b6c",
      "currency": "USD",
      "symbol": "volatility_100",
      "contract_type": "over",
      "params": { "threshold": 4 },
      "stake_cents": 100,
      "payout_multiplier_bp": 19500,
      "status": "won",
      "entry_tick_id": 884213,
      "entry_price": 1031.47,
      "settle_tick_id": 884216,
      "settle_price": 1032.18,
      "settle_digit": 8,
      "payout_cents": 195,
      "settled_at": "2026-11-16T09:30:15.402Z",
      "created_at": "2026-11-16T09:30:12.418Z"
    }
  ]
}

Errors

  • 401 No valid token or session ("not authenticated").
  • status values: pending, won, lost, cancelled. settle_price, settle_digit, payout_cents and settled_at are omitted until settlement.

Market data (public)

Read-only prices with no authentication and CORS open to any origin (Access-Control-Allow-Origin: *). /api/v1/quotes covers the platform's own instruments (synthetic indices plus display-only real-feed prices). /api/v1/markets/* is the MT5 trade server's symbol catalog.

GET/api/v1/quotes
No auth200

Latest price for every live platform instrument.

Response 200

{
  "quotes": [
    { "symbol": "volatility_100", "label": "Volatility 100 (1s) Index", "asset_class": "synthetic", "price": 1031.47, "precision": 2 }
  ]
}
  • asset_class is one of synthetic, forex, crypto, indices, commodities. Non-synthetic entries here are display-only and cannot be traded.
GET/api/v1/markets/paths
No auth200

Market categories with symbol counts.

Response 200

{
  "total": 412,
  "paths": [
    { "path": "Forex Majors", "count": 7 },
    { "path": "US Stocks", "count": 120 }
  ]
}

Errors

  • 503 Market browser not configured on this server, or the catalog is still loading.
GET/api/v1/markets/symbols
No auth200

One page of symbols with live prices.

Parameters

NameInTypeDescription
pathquerystringCategory prefix. Empty = all.
qquerystringCase-insensitive match on name, symbol or description.
offsetqueryintegerDefault 0.
limitqueryintegerDefault 50, max 200.

Response 200

{
  "total": 7,
  "symbols": [
    {
      "symbol": "EURUSD.s",
      "name": "EURUSD",
      "description": "Euro vs US Dollar",
      "path": "Forex Majors/EURUSD",
      "category": "Forex Majors",
      "digits": 5,
      "currency_base": "EUR",
      "currency_profit": "USD",
      "trade_mode": 4,
      "bid": 1.08412,
      "ask": 1.08419,
      "time": "2026-11-16T09:30:12Z",
      "open": 1.08201,
      "high": 1.08533,
      "low": 1.08177,
      "change_pct": 0.195,
      "spread_points": 7,
      "point": 0.00001,
      "spreads": [
        { "tier": "standard", "symbol": "EURUSD.s", "bid": 1.08412, "ask": 1.08419, "spread_points": 7 }
      ]
    }
  ]
}

Errors

  • 503 Market browser not configured, or catalog loading.
GET/api/v1/markets/quotes
No auth200

Latest prices for named symbols.

Parameters

NameInTypeDescription
symbols*querystringComma-separated trade-server symbols, 1..200. Unknown names are skipped.

Response 200

{ "symbols": [ { "symbol": "EURUSD.s", "name": "EURUSD", "bid": 1.08412, "ask": 1.08419, "change_pct": 0.195, "spread_points": 7 } ] }

Errors

  • 400 No symbols ("symbols required") or more than 200 ("too many symbols").
  • 503 Market browser not configured, or catalog loading.
  • Each row has the full shape shown on /api/v1/markets/symbols (abbreviated here).
GET/api/v1/markets/instruments/{name}
No auth200

One instrument with every account tier's specification and price.

Parameters

NameInTypeDescription
name*pathstringClient-facing name without tier suffix, for example EURUSD (case-insensitive).

Response 200

{
  "symbol": "EURUSD.s",
  "name": "EURUSD",
  "category": "Forex Majors",
  "digits": 5,
  "bid": 1.08412,
  "ask": 1.08419,
  "spread_points": 7,
  "tiers": [
    {
      "tier": "standard",
      "symbol": "EURUSD.s",
      "bid": 1.08412,
      "ask": 1.08419,
      "spread_points": 7,
      "spec": {
        "point": 0.00001,
        "contract_size": 100000,
        "volume_min": 0.01,
        "volume_max": 100,
        "volume_step": 0.01,
        "stops_level": 0,
        "calc_mode": 0,
        "swap_mode": 1,
        "swap_unit": "points",
        "swap_long": -6.5,
        "swap_short": 1.2,
        "swap_3day": 3,
        "sessions": [[], [{ "open": 0, "close": 1440 }], [{ "open": 0, "close": 1440 }], [{ "open": 0, "close": 1440 }], [{ "open": 0, "close": 1440 }], [{ "open": 0, "close": 1435 }], []]
      }
    }
  ]
}

Errors

  • 404 No such instrument.
  • 503 Market browser not configured, or catalog loading.
  • The top level also carries every field of a /symbols row (abbreviated here).
  • tier is standard, pro or vip. sessions has 7 entries, Sunday first; times are minutes since 00:00 trade-server time. swap_3day: 0 = Sunday, -1 = none. The example values are illustrative.
GET/health
No auth200

Liveness check.

Response 200

{ "status": "ok" }

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

NameInTypeDescription
authorize*messagestringThe 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

NameInTypeDescription
ping*messageanyValue is ignored, for example 1.

Example

{ "ping": 1 }
You sendtimeno auth

Server time.

Fields

NameInTypeDescription
time*messageanyValue is ignored.

Example

{ "time": 1 }
You sendactive_symbolsno auth

List tradeable markets.

Fields

NameInTypeDescription
active_symbols*messageanyValue is ignored (for example "brief").

Example

{ "active_symbols": "brief" }
You sendticksno authsubscribable

Latest tick, or a tick stream with subscribe: 1.

Fields

NameInTypeDescription
ticks*messagestringSymbol.

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

NameInTypeDescription
ticks_history*messagestringSymbol.
countmessageintegerDefault 100, max 5000.

Example

{ "ticks_history": "volatility_100", "count": 100 }
  • Replies have msg_type history. Error: UnknownSymbol.
You sendforgetno auth

Stop one subscription.

Fields

NameInTypeDescription
forget*messagestringSubscription id.

Example

{ "forget": "sub_9f1c2a3b4d5e6f70" }
You sendforget_allno auth

Stop every subscription of one type, or all.

Fields

NameInTypeDescription
forget_all*messagestringticks, 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

NameInTypeDescription
balance*messageanyValue is ignored.
accountmessagestringOperate 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

NameInTypeDescription
account_list*messageanyValue is ignored.

Example

{ "account_list": 1 }
You sendset_accountscope: read

Switch the connection's active account.

Fields

NameInTypeDescription
set_account*messagestringA 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

NameInTypeDescription
new_account_real*messageanyValue is ignored.
currencymessagestringDefault 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

NameInTypeDescription
new_account_virtual*messageanyValue is ignored.
currencymessagestringDefault 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

NameInTypeDescription
transfer_between_accounts*messageanyValue is ignored.
account_frommessagestringSource loginid.
account_tomessagestringDestination loginid.
amountmessagenumberSource 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

NameInTypeDescription
account_status*messageanyValue is ignored.
accountmessagestringOperate 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

NameInTypeDescription
statement*messageanyValue is ignored.
limitmessageintegerDefault 50, max 200.
accountmessagestringOperate 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

NameInTypeDescription
profit_table*messageanyValue is ignored.
limitmessageintegerDefault 50, max 200. Drawn from the user's 200 most recent settled contracts.
accountmessagestringOperate 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

NameInTypeDescription
transaction*messageanyValue 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

NameInTypeDescription
portfolio*messageanyValue is ignored.

Example

{ "portfolio": 1 }
You sendproposalscope: readsubscribable

Price a digit contract. With subscribe: 1, re-priced on every tick.

Fields

NameInTypeDescription
proposal*messageanyValue is ignored, for example 1.
contract_type*messagestringSee GATEWAY.contractTypes.
symbol*messagestringMarket.
amount*messagenumberStake, account currency, major units, greater than 0.
barriermessageinteger | string0..9 for over, under, match, differ. Ignored for even, odd. Over 9 and under 0 pass here but fail at buy.
accountmessagestringOperate 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

NameInTypeDescription
buy*messagestringProposal id from this connection. Any value when parameters is used.
pricemessagenumberMaximum price. Rejected if the stake is higher.
parametersmessageobjectUsed 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

NameInTypeDescription
proposal_open_contract*messagestringContract 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

NameInTypeDescription
loginid*messagestringPrimary account.
email*messagestring | nullUser email.
scopes*messagestring[]Token scopes.
balance*messagenumberPrimary account balance.
currency*messagestringPrimary account currency.
is_virtual*message0 | 1Primary account is demo.
account_list*messageobject[]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

NameInTypeDescription
ping*message"pong"Always pong.

Example

{ "msg_type": "ping", "echo_req": { "ping": 1 }, "ping": "pong" }
Server sendstime

Server time as Unix seconds.

Fields

NameInTypeDescription
time*messageintegerUnix seconds.

Example

{ "msg_type": "time", "echo_req": { "time": 1 }, "time": 1794821412 }
Server sendsactive_symbols

Tradeable markets. Display-only instruments are excluded.

Fields

NameInTypeDescription
symbol*messagestringMarket id, for example volatility_100.
display_name*messagestringLabel.
market*messagestringAlways synthetic_index.
submarket*messagestringAlways random_index.
pip*messagenumberAlways 0.01.
exchange_is_open*message1Always 1.
spotmessagenumberLatest price, when available.
spot_timemessageintegerUnix 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

NameInTypeDescription
symbol*messagestringSymbol.
id*messagestringSubscription id, empty for a one-off.
epoch*messageintegerUnix seconds.
quote*messagenumberPrice.
pip_size*messageintegerAlways 2.
digit*messageintegerLast 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

NameInTypeDescription
prices*messagenumber[]Prices.
times*messageinteger[]Unix seconds.
digits*messageinteger[]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

NameInTypeDescription
forget*message0 | 1Removed count.

Example

{ "msg_type": "forget", "echo_req": { "forget": "sub_9f1c2a3b4d5e6f70" }, "forget": 1 }
Server sendsforget_all

Ids of the removed subscriptions.

Fields

NameInTypeDescription
forget_all*messagestring[]Removed ids.

Example

{ "msg_type": "forget_all", "echo_req": { "forget_all": "ticks" }, "forget_all": ["sub_9f1c2a3b4d5e6f70"] }
Server sendsbalance

Balance of the resolved account.

Fields

NameInTypeDescription
balance*messagenumberMajor units.
currency*messagestringCurrency.
loginid*messagestringAccount.

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

NameInTypeDescription
count*messageintegerNumber of accounts.
accounts*messageobject[]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

NameInTypeDescription
loginid*messagestringAccount id (MP... real, VR... demo).
currency*messagestringAccount currency.
is_crypto*message0 | 11 for crypto currencies.
is_virtual*message0 | 11 for demo accounts.
balance*messagenumberBalance 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

NameInTypeDescription
loginid*messagestringAccount id (MP... real, VR... demo).
currency*messagestringAccount currency.
is_crypto*message0 | 11 for crypto currencies.
is_virtual*message0 | 11 for demo accounts.
balance*messagenumberBalance 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

NameInTypeDescription
loginid*messagestringAccount id (MP... real, VR... demo).
currency*messagestringAccount currency.
is_crypto*message0 | 11 for crypto currencies.
is_virtual*message0 | 11 for demo accounts.
balance*messagenumberBalance 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

NameInTypeDescription
account_from*messagestringSource loginid.
account_to*messagestringDestination loginid.
amount*messagenumberDebited, source currency.
amount_credited*messagenumberCredited, destination currency.
from_currency*messagestringSource currency.
to_currency*messagestringDestination currency.
rate*messagenumberFX rate used (1 for same currency).
from_balance_after*messagenumberSource balance after.
to_balance_after*messagenumberDestination 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

NameInTypeDescription
kyc_tier*messageintegerVerification tier.
is_virtual*message0 | 1Demo-only user.
status*messagestring[]One of unverified (tier 0 to 1), fully_authenticated (tier 2), withdrawal_locked (tier 3 or more).
daily_withdrawal_limit*messagestring"100.00", "unlimited" or "0.00".
currency*messagestringResolved 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

NameInTypeDescription
count*messageintegerRows returned.
transactions*messageobject[]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

NameInTypeDescription
count*messageintegerRows returned.
transactions*messageobject[]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

NameInTypeDescription
action*messagestringsubscribed (ack), buy, sell, deposit, withdrawal, withdrawal_refund.
transaction_timemessageintegerUnix seconds (server time when sent).
currencymessagestringContract currency; USD for cashier events.
balance_aftermessagenumberWhen the event carries a new balance.
contract_idmessagestringbuy and sell.
amountmessagenumberbuy: negative stake. sell: payout.
longcodemessagestringbuy 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

NameInTypeDescription
contracts*messageobject[]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

NameInTypeDescription
id*messagestringProposal id (prop_...). Pass to buy.
ask_price*messagenumberEquals your amount.
payout*messagenumberPayout if the contract wins.
currency*messagestringAccount currency.
spot*messagenumberLatest price.
spot_time*messageintegerUnix seconds.
display_value*messagenumberEquals your amount.
payout_multiplier*messagenumberpayout / stake, for example 1.95.
longcode*messagestringHuman 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

NameInTypeDescription
contract_id*messagestringContract UUID.
transaction_id*messagestringSame value as contract_id.
buy_price*messagenumberStake.
balance_after*messagenumberBalance after the stake.
payout*messagenumberPayout if won.
currency*messagestringCurrency.
start_time*messageintegerUnix seconds.
longcode*messagestringDescription.

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

NameInTypeDescription
contract_id*messagestringContract UUID.
symbol*messagestringMarket.
contract_type*messagestringDIGIT... name.
longcode*messagestringDescription.
buy_price*messagenumberStake.
currency*messagestringCurrency.
payout*messagenumberPayout if won.
entry_spot*messagenumberEntry price.
current_spot*messagenumberLatest price.
current_spot_time*messageintegerUnix seconds.
status*message"open" | "won" | "lost"Contract status.
is_sold*message0 | 11 once settled.
profit*messagenumber0 while open.
date_start*messageintegerUnix seconds.
tick_count*messageintegerTicks from entry to settlement.
exit_spotmessagenumberAfter settlement.
exit_digitmessageintegerAfter 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

NameInTypeDescription
msg_type*messagestringThe call's reply type (for unknown calls, the unknown key).
echo_req*messageobjectYour request.
error.code*messagestringSee ERRORS.gatewayCodes.
error.message*messagestringHuman-readable reason.
req_idmessageintegerEchoed 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

NameInTypeDescription
symbols*messageobject[]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

NameInTypeDescription
symbol*messagestringSymbol.
history*messageobject[]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

NameInTypeDescription
tick*messageobjectid, 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

NameInTypeDescription
contract*messageobjectEvent 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

NameInTypeDescription
contract*messageobjectEvent 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

NameInTypeDescription
type*messagestringThe event name.
contract*messageobjectEvent 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

NameInTypeDescription
type*message"subscribe"Literal.
channel*messagestringmt5.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.
loginidmessagestringOnly 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

NameInTypeDescription
type*message"unsubscribe"Literal.
channel*messagestringChannel name.

Example

{ "type": "unsubscribe", "channel": "mt5.positions" }
Server sendssubscribed

Subscription confirmed. A repeat subscribe to the same channel gets no reply.

Fields

NameInTypeDescription
channel*messagestringChannel name.

Example

{ "type": "subscribed", "channel": "mt5.positions" }
Server sendserror

Subscribe refused.

Fields

NameInTypeDescription
channel*messagestringChannel name.
code*messagestringunknown_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

NameInTypeDescription
channel*messagestringmt5.state or mt5.positions.
loginidmessagestringMT5 account (MTR... real, MTD... demo).
ts*messagestringRFC 3339 time.
user_idmessagestringOwner user id.
payload*messageobjectmt5.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 rateToken bucket per connection: 30 messages per second sustained, burst 60. Over the limit returns a RateLimit error for that message.
REST rate limitingNone found. No HTTP rate limiter is mounted on the router.
Withdrawal frequencyAbout one withdrawal initiation per minute per user (429).
REST JSON body1 MB maximum; unknown fields are rejected.
Bulk contracts1 to 60 items per request.
Contract durationPlatform default 3 ticks (admin setting contract_duration_ticks). REST duration_ticks clamped to 1..3600. Gateway contracts always use the default.
Contract listGET /api/v1/contracts limit default 50, max 1000.
Gateway historyticks_history count default 100, max 5000. statement and profit_table limit default 50, max 200. portfolio up to 100 open contracts.
Feed snapshotUp to 300 ticks per symbol on connect.
Market catalog/markets/symbols limit default 50, max 200. /markets/quotes up to 200 symbols.
Account transactionslimit default 50, max 200.
Unified depositslimit default 30, max 100.
App earnings claimMinimum 500 cents (5 USD) claimable.
App markupmarkup_bp clamped to 0..3000.
Authorization codeSingle use, 5 minute lifetime.
Access token lifetimeNo 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.