API Reference

Nine read-only endpoints at https://app.telegramtometatrader.com/api/v1.

All requests require Authorization: Bearer ttmt_live_…. See Authentication and Errors.

---

Endpoints

Endpoint	Description
GET /accounts	List your connected MetaAPI accounts
GET /signals	List signals with filters and cursor pagination
GET /signals/{id}	Full signal including raw Telegram message text
GET /trades	List trades with filters and cursor pagination
GET /trades/{id}	Fat trade: signal + positions + orders embedded
GET /trades/{id}/positions	Positions for a specific trade
GET /trades/{id}/orders	Orders for a specific trade
GET /positions	Currently-open positions across your accounts
GET /stream	SSE live event feed

---

Pagination

List endpoints (/signals, /trades) use cursor-only keyset pagination, newest first.

{
  "data": [ /* items */ ],
  "has_more": true,
  "next_cursor": "MjAyNi0wNi0wOFQwOToxNDoyMlp8N2Y4ZQ"
}

Pass ?after=<next_cursor> for the next page. Pass ?limit= (1–100, default 50). The cursor is opaque — never build it yourself.

after_date / before_date are a date window for filtering — a different concept from the after pagination cursor.

---

Filters quick reference

Parameter	Endpoints	Notes
status	signals, trades	validated enum; unknown → 400
symbol	trades	exact match
channel_id	signals, trades	UUID
account_id	signals, trades, positions, stream	DB UUID from GET /accounts
after_date / before_date	signals, trades	ISO-8601
limit / after	signals, trades	pagination
include	trades	signal,positions,orders

---

Money and shapes

All financial objects carry currency, account_id, and account_label. Amounts are in the account's currency. Null TP/SL are JSON null, never 0.

Terminal GET /trades/{id} and GET /signals/{id} return a strong ETag and answer If-None-Match with 304. Active records return no-cache.

---

Default

Operations

GET/accountsGET/signalsGET/signals/{id}GET/tradesGET/trades/{id}GET/trades/{id}/positionsGET/trades/{id}/ordersGET/positionsGET/stream

---

List your MetaAPI accounts

GET

/accounts

Authorizations

bearerAuth

TypeHTTP (bearer)

Responses

OK

Content-Type

application/json

{

"data": [

{

"account_id": "string",

"label": "string",

"currency": "string",

"type": "string",

"server": "string",

"platform": "string",

"state": "string",

"is_active": true

}

]

}

GET

/accounts

Playground

Authorization

bearerAuth

Samples

---

List signals

GET

/signals

Authorizations

bearerAuth

TypeHTTP (bearer)

Parameters

Query Parameters

status

Typestring

Enum

pendingqueuedparsingexecutingexecutedexecuted_awaiting_modificationexecuted_via_followuppending_followupexecution_pausedfaileddelivery_failedrejectedignoredskipped

channel_id

Typestring

formatuuid

account_id

Typestring

formatuuid

after_date

Typestring

formatdate-time

before_date

Typestring

formatdate-time

limit

Typeinteger

minimum1

maximum100

default50

after

opaque pagination cursor (next_cursor)

Typestring

Responses

OK

Content-Type

application/json

{

"data": [

],

"has_more": true,

"next_cursor": "string"

}

GET

/signals

Playground

Authorization

bearerAuth

Variables

Key

Value

status

channel_id

account_id

after_date

before_date

limit

after

Samples

---

Full signal incl. raw Telegram message

GET

/signals/{id}

Authorizations

bearerAuth

TypeHTTP (bearer)

Parameters

Path Parameters

id*

Typestring

Required

formatuuid

Responses

OK

GET

/signals/{id}

Playground

Authorization

bearerAuth

Variables

Key

Value

id*

Samples

---

List trades

GET

/trades

Authorizations

bearerAuth

TypeHTTP (bearer)

Parameters

Query Parameters

status

Typestring

Enum

pendingactiveclosed_profitclosed_lossfailedneeds_recoveryclosed_timeout_cleanupclosed_unfilled

symbol

Typestring

channel_id

Typestring

formatuuid

account_id

Typestring

formatuuid

after_date

Typestring

formatdate-time

before_date

Typestring

formatdate-time

limit

Typeinteger

minimum1

maximum100

default50

after

opaque pagination cursor (next_cursor)

Typestring

include

comma list of signal,positions,orders

Typestring

Responses

OK

Content-Type

application/json

{

"data": [

],

"has_more": true,

"next_cursor": "string"

}

GET

/trades

Playground

Authorization

bearerAuth

Variables

Key

Value

status

symbol

channel_id

account_id

after_date

before_date

limit

after

include

Samples

---

Fat trade (signal + positions + orders embedded)

GET

/trades/{id}

Authorizations

bearerAuth

TypeHTTP (bearer)

Parameters

Path Parameters

id*

Typestring

Required

formatuuid

Responses

OK (strong ETag on terminal trades)

GET

/trades/{id}

Playground

Authorization

bearerAuth

Variables

Key

Value

id*

Samples

---

Positions for a trade

GET

/trades/{id}/positions

Authorizations

bearerAuth

TypeHTTP (bearer)

Parameters

Path Parameters

id*

Typestring

Required

formatuuid

Responses

OK

GET

/trades/{id}/positions

Playground

Authorization

bearerAuth

Variables

Key

Value

id*

Samples

---

Orders for a trade

GET

/trades/{id}/orders

Authorizations

bearerAuth

TypeHTTP (bearer)

Parameters

Path Parameters

id*

Typestring

Required

formatuuid

Responses

OK

GET

/trades/{id}/orders

Playground

Authorization

bearerAuth

Variables

Key

Value

id*

Samples

---

Currently-open positions across accounts

GET

/positions

Each position includes a nested signal sub-object with the originating Telegram message ID. See SignalSummary for null semantics.

Authorizations

bearerAuth

TypeHTTP (bearer)

Parameters

Query Parameters

account_id

Typestring

formatuuid

Responses

OK

Content-Type

application/json

{

"data": [

{

"id": "string",

"metaapi_position_id": "string",

"symbol": "string",

"direction": "string",

"volume": 0,

"entry_price": 0,

"current_price": 0,

"unrealized_pl": 0,

"status": "string",

"trade_id": "string",

"signal": {

"signal_id": "string",

"telegram_message_id": 0

},

"account_id": "string",

"account_label": "string",

"currency": "string"

}

]

}

GET

/positions

Playground

Authorization

bearerAuth

Variables

Key

Value

account_id

Samples

---

SSE live feed (text/event-stream)

GET

/stream

Events carry a signal sub-object (SignalSummary) on position_update, position_closed, tp_hit, trade_executed, trade_finalized, breakeven_failed, and order_fill. For breakeven_set, signal is always null (event carries only a DB position UUID, not the MetaAPI ID required for watchdog lookup).

Authorizations

bearerAuth

TypeHTTP (bearer)

Parameters

Query Parameters

account_id

Typestring

formatuuid

Responses

event stream

Content-Type

text/event-stream

GET

/stream

Playground

Authorization

bearerAuth

Variables

Key

Value

account_id

Samples

---