On this page

API Reference#

The tramiro REST API gives you programmatic access to your trading platform data — accounts, trades, performance metrics, and alerts. Integrate tramiro into your own tools, dashboards, and automation pipelines.

Authentication#

Authentication is a two-step process: create an API client to get credentials, then exchange them for a short-lived JWT token.

1. Create an API client
Log in to the tramiro app and create an API client. You will receive an appId and appSecret. The secret is shown once — store it securely.

2. Exchange credentials for a JWT

Send your credentials to the token endpoint to receive a JWT:

Request

curl -X POST https://api.tramiro.com/api/1.0/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "YOUR_APP_ID",
    "appSecret": "YOUR_APP_SECRET"
  }'

Response

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expiresInSeconds": 3600
}

When the token expires, call the token endpoint again — there is no refresh token for API clients.

3. Use the JWT on every request
Pass the token in the Authorization header:
Header
```
Authorization: Bearer <token>
```

Base URL#

All API endpoints are relative to the following base URL:

https://api.tramiro.com/api/1.0/

Endpoint Reference#

All paths below are relative to the base URL. Endpoints require a valid JWT unless noted otherwise.

Authentication#

Exchange API client credentials for a short-lived JWT token.

POST/auth/token

Exchange appId + appSecret for a JWT token. No authentication required.

Request Body

Field	Type	Description
appId*	string	Your API client ID
appSecret*	string	Your API client secret

Example request

{
  "appId": "your-app-id",
  "appSecret": "your-app-secret"
}

Response

Field	Type	Description
token	string	JWT token to use in Authorization header
expiresInSeconds	number	Token lifetime in seconds

Example response

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expiresInSeconds": 3600
}

Me#

Retrieve information about the authenticated API client.

GET/me

Get current authenticated user or API client info.

Response

Field	Type	Description
id	UUID	User ID
email	string	Email address
firstName	string	First name
lastName	string	Last name
role	string	User role
timezone	string	Timezone setting
apiClientId	UUID \| null	API client ID (only for API clients)
apiClientAppId	string \| null	API client app ID (only for API clients)
apiClientDescription	string \| null	API client description (only for API clients)

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "role": "API",
  "timezone": "Europe/Prague",
  "apiClientId": "660e8400-e29b-41d4-a716-446655440001",
  "apiClientAppId": "your-app-id",
  "apiClientDescription": "My integration"
}

Trading Platform Instances#

Manage trading platform instances — create, list, update, and delete.

GET/trading-platform-instances

List all trading platform instances for the authenticated user.

Query Parameters

Field	Type	Description
identifier	string	Filter by instance identifier

Response

Field	Type	Description
id	UUID	Instance ID
identifier	string	Unique identifier
name	string	Display name
description	string	Description
createdAtUtc	datetime	Creation timestamp (UTC)
metrics	object	Instance metrics (status, last heartbeat, account metrics)

Example response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "identifier": "my-mt5",
    "name": "My MT5 Account",
    "description": "Production trading account",
    "createdAtUtc": "2026-01-15T10:30:00",
    "metrics": {
      "status": "ONLINE",
      "lastHeartbeatAtUtc": "2026-04-13T12:00:00",
      "accountMetrics": {
        "balance": 10000.00,
        "equity": 10250.50,
        "profitLoss": 250.50,
        "currency": "USD"
      }
    }
  }
]

GET/trading-platform-instance/{id}

Get a single trading platform instance by ID.

Response

Same shape as a single item from the list endpoint.

POST/trading-platform-instance

Create a new trading platform instance.

Request Body

Field	Type	Description
identifier*	string	Unique identifier (min 2 chars)
name*	string	Display name (min 2 chars)
description*	string	Description of this instance

Example request

{
  "identifier": "my-mt5",
  "name": "My MT5 Account",
  "description": "Production trading account"
}

Response

Returns the created instance (same shape as GET). Status 201.

PUT/trading-platform-instance/{id}

Update an existing trading platform instance.

Request Body

Field	Type	Description
name	string	New display name (min 2 chars)
description	string	New description

Example request

{
  "name": "Updated Name",
  "description": "Updated description"
}

Response

Returns the updated instance. Status 200.

DELETE/trading-platform-instance/{id}

Delete a trading platform instance.

Response

No content. Status 204.

Trade History#

Query and export trade history for a trading platform instance.

GET/trading-platform-instance/{id}/trade-history

List trades with pagination, filtering, and sorting.

Query Parameters

Field	Type	Description
page	integer	Page number (default: 0)
size	integer	Page size (default: 50, max: 500)
sort	string	Sort field: openTime, closeTime, profit, pips, symbol, ticket
tradeType	string[]	Filter by trade type

Response

Field	Type	Description
trades	TradeRecord[]	Array of trade records
page	integer	Current page number
size	integer	Page size
totalElements	integer	Total number of trades
totalPages	integer	Total number of pages

Example response

{
  "trades": [
    {
      "ticket": 12345,
      "symbol": "EURUSD",
      "direction": "BUY",
      "lots": 0.10,
      "openPrice": 1.08500,
      "closePrice": 1.08750,
      "openTime": "2026-04-10T09:30:00",
      "closeTime": "2026-04-10T14:15:00",
      "profit": 25.00,
      "swap": -0.50,
      "commission": -0.70,
      "pips": 25.0,
      "netProfit": 23.80
    }
  ],
  "page": 0,
  "size": 50,
  "totalElements": 142,
  "totalPages": 3
}

GET/trading-platform-instance/{id}/trade-history/sync-state

Get the trade history synchronization state.

Response

Field	Type	Description
lastSyncTimestamp	datetime	Last sync timestamp (UTC)
totalClosedTrades	integer	Total number of closed trades

Example response

{
  "lastSyncTimestamp": "2026-04-13T12:00:00",
  "totalClosedTrades": 142
}

GET/trading-platform-instance/{id}/trade-history/export/csv

Export trade history as a CSV file.

Query Parameters

Field	Type	Description
tradeType	string[]	Filter by trade type
sort	string	Sort field: openTime, closeTime, profit, pips, symbol, ticket

Response

Returns a streaming CSV file with Content-Type: text/csv.

Performance#

Retrieve performance metrics and time-series curves. All endpoints accept an optional range query parameter.

GET/trading-platform-instance/{id}/performance/*

Three curve endpoints share the same shape. Each accepts an optional range query parameter ("1h", "24h", "7d", "30d", "90d", "365d" — default "30d").

Path	Points field	Description
/performance/cumulative-pl	cumulativePl	Cumulative profit/loss over time
/performance/equity-curve	equity	Equity value over time
/performance/percentage-curve	percentage	Percentage change over time

Shared response shape

Example response (replace <field> with the points field name)

{
  "points": [
    { "timestamp": "2026-03-14T00:00:00", "<field>": 0 },
    { "timestamp": "2026-03-15T00:00:00", "<field>": 150.25 }
  ],
  "range": "30d"
}

GET/trading-platform-instance/{id}/performance/stats

Get performance statistics for a time range.

Query Parameters

Field	Type	Description
range	string	Time range — "1h", "24h", "7d", "30d", "90d", "365d" (default: "30d")

Response

Field	Type	Description
totalProfitLoss	number	Total P/L in account currency
roi	number	Return on investment (%)
profitFactor	number	Profit factor (gross profit / gross loss)
winRate	number	Win rate (%)
totalTrades	integer	Number of trades in range
range	string	Applied range
historyMayBeIncomplete	boolean	True if trade history may not cover the full range

Example response

{
  "totalProfitLoss": 1250.50,
  "roi": 12.5,
  "profitFactor": 2.35,
  "winRate": 68.5,
  "totalTrades": 47,
  "range": "30d",
  "historyMayBeIncomplete": false
}

Average Spreads#

Retrieve average spread data for a trading platform instance.

GET/trading-platform-instance/{id}/average-spreads

Get average spreads by symbol for a time range.

Query Parameters

Field	Type	Description
range	string	Time range — "1h", "24h", "7d" (default: "24h")

Response

Field	Type	Description
spreads	array	Array of { symbol, averageSpreadInPoints }
range	string	Applied range

Example response

{
  "spreads": [
    { "symbol": "EURUSD", "averageSpreadInPoints": 12 },
    { "symbol": "GBPUSD", "averageSpreadInPoints": 18 }
  ],
  "range": "24h"
}

Error Model#

All error responses return a JSON array. There are two shapes depending on the error type.

General errors

Returned for 401, 403, 404, and general 400 errors. Each object contains a message field.

General error

[
  { "message": "Unauthorized" }
]

Validation errors

Returned for 400 responses caused by invalid input. Each object contains a field and message.

Validation error

[
  { "field": "appId", "message": "must not be blank" },
  { "field": "appSecret", "message": "must not be blank" }
]

Examples#

Common API calls using curl. Replace placeholder values with your actual credentials and IDs.

Create a trading platform instance

POST /trading-platform-instance

curl -X POST https://api.tramiro.com/api/1.0/trading-platform-instance \
  -H "Authorization: Bearer $TRAMIRO_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "my-mt5",
    "name": "My MT5 Account",
    "description": "Production trading account"
  }'

List trading platform instances

GET /trading-platform-instances

curl https://api.tramiro.com/api/1.0/trading-platform-instances \
  -H "Authorization: Bearer $TRAMIRO_JWT"

Get trade history

GET /trading-platform-instance/{id}/trade-history

curl https://api.tramiro.com/api/1.0/trading-platform-instance/1/trade-history \
  -H "Authorization: Bearer $TRAMIRO_JWT"

Get performance stats

GET /trading-platform-instance/{id}/performance/stats

curl "https://api.tramiro.com/api/1.0/trading-platform-instance/1/performance/stats?range=30d" \
  -H "Authorization: Bearer $TRAMIRO_JWT"

API Reference#

Authentication#

1. Create an API client

2. Exchange credentials for a JWT

3. Use the JWT on every request

Base URL#

Endpoint Reference#

Authentication#

Request Body

Response

Me#

Response

Trading Platform Instances#

Query Parameters

Response

Response

Request Body

Response

Request Body

Response

Response

Trade History#

Query Parameters

Response

Response

Query Parameters

Response

Performance#

Shared response shape

Query Parameters

Response

Average Spreads#

Query Parameters

Response

Error Model#

General errors

Validation errors

Examples#

Create a trading platform instance

List trading platform instances

Get trade history

Get performance stats