API

A small REST API serves everything the platform stores: asset metadata, daily price history, per-asset forecasts, country/day factors, and long-term trading-strategy suggestions. All responses are JSON. The public website talks to it under the /api prefix (e.g. /api/assets/GOLD/prices).

Endpoints

Method	Path	Description
GET	/assets	List the asset catalog. Filter with `?class=metal\|fx\|crypto\|equity\|energy\|agriculture\|commodity`.
GET	/trading-assets	Portfolio and target-picker catalog. FX pairs are represented as USD-valued currencies such as EUR, CHF and JPY.
GET	/assets/:symbol	Single asset metadata.
GET	/assets/:symbol/prices	Daily price series; optional `?from=&to=` (YYYY-MM-DD).
GET	/assets/:symbol/forecast	ML forecast path; `?horizon=7\|30` with per-day Range band.
POST	/trading-suggestion	Long-term trading-strategy advice for a user's holdings (see below).

Authentication

Public endpoints (/assets, /prices, /forecast, /factors, /countries) require no authentication.

The /trading-suggestion endpoint requires an API key passed in the x-api-key header. To get your key, open @timemachinetradingbot in Telegram and use the /key command. The bot will generate a personal key you can use for API and MCP access.

Trading-strategy suggestions

POST /trading-suggestion turns the forecast into actionable, long-term (hold horizon of one day to several months) advice for a user's current holdings. For each asset it reads the freshest forecast as of the trading day, computes the expected return to the end of the 30-day path net of the round-trip fee, and returns a per-asset action — buy, sell, hold or pending — plus the estimated USD fees. Every request is logged for later audit.

Request

POST /api/trading-suggestion
{
  "userId": "u1",
  "assets": [
    { "name": "USD",  "value": 10000 },
    { "name": "GOLD", "value": 0 }
  ],
  "date": "2026-02-02",          // optional
  "approved": false,             // optional
  "availableAssets": ["GOLD"]    // optional whitelist
}

Response

{
  "userId": "u1",
  "date": "2026-02-02",
  "fee": 20,            // total USD fee
  "balance": 10000,     // portfolio USD value
  "assets": [
    { "name": "USD",  "value": 10000, "action": "sell", "fee": 0 },
    { "name": "GOLD", "value": 0,     "action": "buy",  "fee": 20 }
  ]
}

buy — fee-adjusted expected return clears +3%; capital concentrates in the single strongest candidate to keep turnover (and fees) low.
sell — expected return falls below −2%: rotate the position back to USD cash.
hold — a forecast exists but the edge is inside the no-trade band.
pending — no forecast coverage on/before that day, so no blind trades.
availableAssets — optional whitelist: when non-empty, only those symbols are analyzed and may be recommended (USD is always allowed); everything else stays pending.

Example

curl 'https://<host>/api/assets/GOLD/prices?from=2008-01-01&to=2008-12-31'

curl -X POST 'https://<host>/api/trading-suggestion' \
  -H 'content-type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{ "userId": "u1", "date": "2026-02-02",
        "assets": [ { "name": "USD", "value": 10000 }, { "name": "GOLD", "value": 0 } ] }'

Try it

Use the interactive tester to call /trading-suggestion with your username and API key, build a holdings list, and read the response in a friendly table.

Open the API tester

MCP Server

A Model Context Protocol server exposes the public API as tools that any MCP-compatible client (Claude Code, Claude Desktop, Cursor, etc.) can call directly. The server communicates over stdio and proxies requests to the REST API.

Available tools

Tool	Description
list_assets	List all tracked assets; filter by class
get_asset	Metadata for a single asset
get_prices	Daily price history with optional date range
get_forecast	ML forecast path (yhat + confidence bands)
list_countries	Countries for the factors system
list_factor_types	Factor types with 0–10 scale descriptions
get_factors	Daily factor intensity for a country + factor
trading_suggestion	Trading-strategy advice for holdings (requires `TM_API_KEY`)

Setup

Install from npm and connect — no clone required:

# Claude Code
claude mcp add time-machine -e TM_API_KEY=YOUR_API_KEY -- npx time-machine-mcp

# Claude Desktop / Cursor — add to settings:
{
  "mcpServers": {
    "time-machine": {
      "command": "npx",
      "args": ["time-machine-mcp"],
      "env": {
        "TM_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}