API reference

Quickstart

1. Sign in at the app with Telegram and open the Desk.
2. Connect an MT5 account as a trader account: broker server, login, and the trading password (not investor). It must be a hedging account. The password is encrypted on your device.
3. In AGENT ACCESS create a key. Choose scopes, accounts and limits. The secret kp_live_... is shown once; copy it.
4. Call the API.

export KOPIARD_API_KEY=kp_live_YOUR_KEY
curl -s {{BASE}}/v1/accounts \
  -H "Authorization: Bearer $KOPIARD_API_KEY"

{ "accounts": [ { "id": "acc_123", "status": "connected", "login": 12345678,
    "server": "Broker-Demo", "currency": "USD", "balance": 10000, "equity": 10012.5,
    "margin": 220.4, "free_margin": 9792.1, "margin_level": 4543.1, "leverage": 500,
    "trade_allowed": true, "halted": false, "updated_at": 1760000000, "last_error": null } ] }

Authentication

Send the key as a bearer token: Authorization: Bearer kp_live_.... Keys are stored as hashes and shown once. A revoked or expired key gets 401 unauthorized.

Scopes are independent: a trade key does not imply read, and a key without the needed scope gets 403 forbidden_scope. A key is bound to specific account ids, or to all of your trader accounts.

Base URL

Use the API Worker URL above for everything, including the stream. Streams do not go through the web host.

Conventions

• JSON bodies with Content-Type: application/json. Times are unix seconds. Numbers are JSON numbers.
• Tickets (position and order ids) are strings.
• Write calls take ?wait=<ms>, 0 to 10000, default 5000. 201 (or 200 for close, modify, cancel) means done. 202 with {"command_id","status":"pending"} means accepted but not finished (wait=0, or the terminal was slow): poll the command.
• Latency: order commands typically complete in under a second; state is fresh to within about two seconds. This is not for high-frequency trading.
• Hedging accounts only. Netting accounts return 409 netting_unsupported.

Accounts

Quotes, symbols, history

{ "quotes": [ { "symbol": "EURUSD", "bid": 1.0851, "ask": 1.0853, "time": 1760000001 } ],
  "updated_at": 1760000001 }

{ "trades": [ { "ticket": "987654", "symbol": "EURUSD", "side": "buy", "volume": 0.1,
    "open_price": 1.0852, "close_price": 1.0861, "profit": 9, "swap": 0,
    "open_time": 1760000100, "close_time": 1760003700, "comment": "Kopiard" } ] }

Candles

{ "symbol": "EURUSD", "timeframe": "H1",
  "bars": [ { "time": 1760000400, "open": 1.0851, "high": 1.0862, "low": 1.0847, "close": 1.0859,
              "tick_volume": 1204, "spread": 8, "real_volume": 0 } ],
  "partial": false, "forming_last": true, "updated_at": 1760003712 }

r = k.candles(acct, "EURUSD", "H1", count=250)
bars = r["bars"][:-1] if r["forming_last"] else r["bars"]
closes = [b["close"] for b in bars]
fast = sum(closes[-20:]) / 20
slow = sum(closes[-100:]) / 100
if fast > slow:        # decided on CLOSED bars only
    k.buy(acct, "EURUSD", 0.01, sl=closes[-1] - 0.0030)

const r = await k.candles(acct, { symbol: "EURUSD", timeframe: "H1", count: 250 });
const bars = r.forming_last ? r.bars.slice(0, -1) : r.bars;  // closedBars(r)
const closes = bars.map((b) => b.close);
const avg = (xs: number[]) => xs.reduce((a, b) => a + b, 0) / xs.length;
if (avg(closes.slice(-20)) > avg(closes.slice(-100)))        // CLOSED bars only
  await k.buy(acct, "EURUSD", 0.01, { sl: closes.at(-1)! - 0.0030 });

Positions and orders

{ "positions": [ { "ticket": "987654", "symbol": "EURUSD", "side": "buy", "volume": 0.1,
    "open_price": 1.0852, "price": 1.0858, "sl": 1.08, "tp": 1.09, "profit": 6, "swap": 0,
    "open_time": 1760000100, "comment": "Kopiard", "magic": 5674273 } ],
  "updated_at": 1760000200 }

Place an order

curl -s -X POST "{{BASE}}/v1/accounts/acc_123/orders?wait=5000" \
  -H "Authorization: Bearer $KOPIARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"symbol":"EURUSD","side":"buy",
       "type":"market","volume":0.1,
       "sl":1.0800,"tp":1.0900,
       "client_id":"my-agent-0001"}'

{
  "command_id": "cmd_1",
  "status": "filled",
  "ticket": "987654",
  "price": 1.0852,
  "volume": 0.1
}

Close, modify, cancel

{ "sl": 1.0810, "tp": null }

Halt and resume

{ "halted": true }

Commands

SSE stream

curl -N "{{BASE}}/v1/accounts/acc_123/stream?symbols=EURUSD" \
  -H "Authorization: Bearer $KOPIARD_API_KEY"

event: snapshot
data: {"account":{...},"positions":[],"orders":[],"quotes":[]}

event: quote
data: {"symbol":"EURUSD","bid":1.0851,"ask":1.0853,"time":1760000001}

: hb

Idempotency

Send client_id (40 characters at most) on writes. It is unique per account. Repeat the same client_id and you get the original result back with 200 and the header Idempotent-Replay: true, or the original 422 or 504 body. No second trade is made. client_id is also read from close, modify and close-all bodies, and an Idempotency-Key header works on every write including cancel. Retry network errors, timeouts, 5xx and 429 with the same id. Do not retry 422.

Trade comments

An order with no comment gets, in order: the key's comment tag, the account's default comment, then the literal Kopiard. An explicit comment always wins. Allowed characters are A-Z a-z 0-9 space _ . - # @ / :; others are stripped from defaults. A comment containing |, ; or a line break is rejected with 422. The comment cannot be changed after the trade opens.

Key limits

Set when the key is created, in the Desk. Enforced by the API on every command.

A breach returns 422 key_limit. Separately, you can set account-level caps (max lot, max positions, allowed symbols) in the Desk; the terminal's EA enforces those independently of the API, so they hold even for a signed-in session. The SDKs never try to get around any limit.

Errors

Shape: {"error":{"code","message","request_id"}}. Quote the request_id when you ask for help.

{ "error": { "code": "order_rejected", "message": "Not enough money",
    "request_id": "req_abc", "retcode": 10019, "broker_message": "No money" } }

Rate limits and tiers

Requests are counted per trading account over a sliding 60 seconds, across all keys and the Desk. Over the limit: 429 rate_limited with Retry-After in seconds. Limits come from your tier:

Paid checkout is not switched on yet; contact us on Telegram to change tier.

SDKs

import { Kopiard } from "@kopiard/sdk";
const k = new Kopiard({
  apiKey: process.env.KOPIARD_API_KEY!,
  baseUrl: "{{BASE}}",
});
const [a] = await k.accounts.list();
await k.buy(a.id, "EURUSD", 0.01,
  { sl: 1.0800, tp: 1.0900 });

from kopiard import Kopiard
k = Kopiard(api_key=KEY,
            base_url="{{BASE}}")
acct = k.list_accounts()[0]["id"]
k.buy(acct, "EURUSD", 0.01,
      sl=1.0800, tp=1.0900)

Both generate a client_id for you and retry network errors, 5xx and 429 (honouring Retry-After) with the same id. They never retry a 422. The TypeScript client has no runtime dependencies; Python offers sync and asyncio clients. The machine-readable spec is OpenAPI 3.1 in sdk/openapi.yaml.

MCP server

@kopiard/mcp is a stdio MCP server so Claude and other agents can trade without glue code. Tools: list_accounts, get_account, get_quotes, get_positions, get_orders, get_history, get_candles, place_order, close_position, modify_position, cancel_order, close_all, halt_trading. Each tool description states the risk limits. There is no resume tool.

{
  "mcpServers": {
    "kopiard": {
      "command": "npx",
      "args": ["-y", "@kopiard/mcp"],
      "env": {
        "KOPIARD_API_KEY": "kp_live_YOUR_KEY",
        "KOPIARD_BASE_URL": "{{BASE}}"
      }
    }
  }
}

Like the SDKs, the package is built but not published yet; run it from the repository's sdk/mcp folder for now. Use a dedicated key with a small max_volume for any agent.

Not built yet

• Webhooks.
• Published npm and PyPI packages.

Nothing else on this page is a promise: every call above exists today.