Accounts, IDs & scopes
Every endpoint acts on your account
Trader API paths end in /me or /accounts/me, for example
GET /api/v1/positions/accounts/me. They always act on the account your token
belongs to, so you never pass an account ID and can never touch anyone else's
account.
IDs you'll see
| ID | What it is |
|---|---|
account_id | Your trading account — holds the balance, orders and positions. It's also the username for password login. |
client_id | Your API key's identifier (<account_id>_<digits>). Only used to get a token. |
session_id | One login. An account can have several sessions at once. The WebSocket needs it. |
symbol_id | An instrument, e.g. EURUSD. Orders, positions and price ticks use the numeric ID, not the name. |
order_id | An order (market or pending). |
position_id | An open or closed trade that came from a filled order. |
deal id | One booked leg of a trade — an entry (direction: 0) or an exit (direction: 1). |
How they relate is explained in Orders, positions & deals.
Scopes
The scope returned with your token decides what it can do.
| Scope | How you get it | Can |
|---|---|---|
API_Trader | API key | Trade and read everything a bot needs. No password changes, API keys, inbox or reports. |
Trader | Password login | Everything API_Trader can, plus password changes, API keys, and reports. |
Investor | Login with the investor password | Read only. Every order and position change is refused. |
Calling an endpoint your scope can't use returns 403 with the message
unauthorized to access this resource.
To let someone watch your account (a signal subscriber, a monitoring dashboard), give them the investor password, not your API key.
The endpoints a bot uses
| Need | Endpoint |
|---|---|
| Balance, equity, margin, leverage, prop status | GET /api/v1/accounts/me |
| Tradable symbols | GET /api/v1/symbols/me |
| One symbol by name | GET /api/v1/symbols/me/by_name?symbol=EURUSD |
| Candles | GET /api/v1/market/history |
| Place an order | POST /api/v1/orders/accounts/me |
| Pending orders | GET /api/v1/orders/accounts/me |
| Open positions | GET /api/v1/positions/accounts/me |
| Change SL/TP | PUT /api/v1/positions/{position_id}/accounts/me |
| Close | POST /api/v1/positions/{position_id}/accounts/me |
| Closed trades | GET /api/v1/deals/accounts/me |
| Deposits and withdrawals | GET /api/v1/accounts/me/transactions |
The full list, with a Try It panel for each, is in the API Reference.
Account fields worth watching
GET /api/v1/accounts/me returns, among others:
| Field | Meaning |
|---|---|
balance | Settled cash. |
credit | Broker credit (bonus) — counts toward equity, not withdrawable. |
equity | Balance plus credit plus floating P/L of open positions. |
used_margin / free_margin | Margin held by open positions / what's left for new ones. |
margin_level | Equity relative to used margin. Your broker's margin-call and stop-out levels apply to this. |
leverage | Your leverage. 0 means the group default applies. |
currency, currency_digits | Account currency and its decimal places. |
status | 2 active. 0 read-only, 1 pending, 3 rejected, 4 liquidation, 5 liquidated, 6 trial expired. |
trade_type | 0 live, 1 demo. |
prop, prop_status, prop_phase | Prop-firm rules, how close you are to breaching them, and challenge progress. A bot on a prop account should check prop_status before trading. |
The same live numbers stream over the WebSocket as
account_Summary, so poll this
endpoint once at startup, not in a loop.