The Metrand API
Strategies, checks and backtests from your own code, scripts and AI agents: keys, limits, every endpoint and every error.
Write a strategy, check it, backtest it on years of exchange history and read every trade: from code, a script or an AI agent. Everything here is also in the OpenAPI document, which code generators and AI assistants read directly, and this page is plain Markdown at metrand.com/docs/api.md.
Base URL: https://metrand.com/api/v1
Keys
Make a key in the app under Account → API keys. It is shown once: keep it like a password. Send it with every request:
Authorization: Bearer mtr_AbCdEfGhIjKl_…
A key acts as you, in your workspace, narrowed by its scopes:
| Scope | Allows |
|---|---|
read |
strategies, versions, backtests, trades, the op catalog, templates and market rules |
research |
checking graphs and running backtests, which spend the workspace’s daily backtests |
strategies:write |
creating strategies and saving versions |
A key can be limited to some IP addresses and given an expiry date. Revoking it stops it at once; resetting your password revokes all of yours.
Limits
Every key of a workspace draws on the same limits, set by its plan:
| Plan | Requests a minute | Backtests running at once | Backtests waiting | Backtests a day | Bars per backtest |
|---|---|---|---|---|---|
| Free | 60 | 1 | 10 | 20 | 5,000 |
| Pro | 300 | 2 | 50 | 200 | 20,000 |
| Expert | 1,200 | 4 | 200 | 2,000 | 50,000 |
The daily backtests and the longest window are the plan’s, shared with the app; an Enterprise plan with larger limits
is arranged with us. Every answer says how much of the minute is left (RateLimit-Limit, RateLimit-Remaining,
RateLimit-Reset); a refusal says when to come back (Retry-After). GET /me shows the limits and today’s use.
Conventions
- JSON in and out, request bodies up to 1 MB.
- Times are RFC 3339 in UTC (
2025-01-31T00:00:00Z); inputs also take epoch milliseconds. - Money, prices and quantities are decimal strings, so nothing is rounded on the way.
- Every object says what it is in
object. - A list is
{"object": "list", "data": [...], "next_cursor": ...}. Passnext_cursorback ascursorfor the next page of the same list;nullmeans the last page.limitis 1 to 100, 25 when left out; trades take up to 1,000. The lists of reference data (/markets,/templates) come whole, withnext_cursoralwaysnull. - Every answer has
X-Request-Id; quote it when something looks wrong. - Version 1 only grows. New fields, endpoints and values may appear; nothing is renamed or removed. Ignore fields you do not know.
Quick start
With curl:
KEY=mtr_…
API=https://metrand.com/api/v1
# 1. Start a strategy from a template (GET /templates lists them, with their graphs).
curl -s -X POST $API/strategies -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
-d '{"name": "Momentum test", "template": "momentum"}'
# → {"object":"strategy","id":"…","version":{"hash":"9f2c…"},…}
# 2. Backtest it on two years of hourly BTCUSDT, waiting up to 20 s for the result.
curl -s -X POST $API/backtests -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
-H 'Prefer: wait=20' -H 'Idempotency-Key: momentum-btc-2y' \
-d '{"strategy": {"id": "…", "version": "9f2c…"},
"market": {"exchange": "binance", "symbol": "BTCUSDT", "interval": "1h"},
"window": {"start": "2023-10-01T00:00:00Z", "end": "2025-10-01T00:00:00Z"},
"costs": {"taker_bps": 5, "slippage_bps": 2}}'
# → 201 with "status":"succeeded" and the result, or 202 with "status":"queued": read it again
# 3. Read the backtest, its trades and its equity curve.
curl -s $API/backtests/<id> -H "Authorization: Bearer $KEY"
curl -s "$API/backtests/<id>/trades?limit=500" -H "Authorization: Bearer $KEY"
curl -s "$API/backtests/<id>/equity?points=300" -H "Authorization: Bearer $KEY"
The same in Python, waiting out a limit when told to:
import time, uuid, requests
API = "https://metrand.com/api/v1"
s = requests.Session()
s.headers["Authorization"] = "Bearer mtr_…"
def call(method, path, **kw):
r = s.request(method, API + path, timeout=90, **kw)
if r.status_code == 429: # a limit: wait as told, then try again
time.sleep(int(r.headers.get("Retry-After", "5")))
return call(method, path, **kw)
if r.status_code >= 400:
raise RuntimeError(r.json()) # problem details: code, detail, errors
return r.json()
strategy = call("POST", "/strategies", json={"name": "Momentum test", "template": "momentum"},
headers={"Idempotency-Key": str(uuid.uuid4())})
bt = call("POST", "/backtests", headers={"Prefer": "wait=20"}, json={
"strategy": {"id": strategy["id"], "version": strategy["version"]["hash"]},
"market": {"symbol": "BTCUSDT", "interval": "4h"},
"window": {"bars": 3000},
})
while bt["status"] in ("queued", "running"):
time.sleep(2)
bt = call("GET", f"/backtests/{bt['id']}")
print(bt["status"], bt["result"]["report"]["net_pnl"] if bt["result"] else bt["error"])
Endpoints
| Endpoint | Scope | Does |
|---|---|---|
GET /me |
any key | The key, its user and workspace, the plan’s limits and today’s use. |
GET /catalog |
read |
Every op a strategy graph may hold: kind, parameters, ports. |
GET /templates |
read |
The templates a strategy can start from, with their graphs and latest measurement. |
GET /markets |
read |
Every USDT perpetual the exchange lists (?exchange=binance or bybit). |
GET /markets/{exchange}/{symbol} |
read |
One market’s timeframes, lot rules, leverage tiers and standard fees. |
GET /strategies |
read |
The workspace’s strategies (?archived=true for the archived ones). |
POST /strategies |
strategies:write |
A new strategy from a template or a graph. |
GET /strategies/{id} |
read |
One strategy and its latest version. |
GET /strategies/{id}/versions |
read |
A strategy’s versions, newest first. |
POST /strategies/{id}/versions |
strategies:write |
Save a graph as a version; the same graph returns the version it already is. |
GET /strategies/{id}/versions/{hash} |
read |
One version with its graph. |
POST /strategies/validate |
research |
Whether the engine compiles a graph, without saving it. |
GET /backtests |
read |
The backtests run here and in the app (?strategy=, ?version=, ?status=). |
POST /backtests |
research |
Ask for a backtest. |
GET /backtests/{id} |
read |
One backtest, finished or not. |
POST /backtests/{id}/cancel |
research |
Cancel a queued backtest; its charge comes back. |
GET /backtests/{id}/trades |
read |
A finished backtest’s trades, in the order they closed. |
GET /backtests/{id}/equity |
read |
A finished backtest’s equity curve. |
GET /openapi.json |
none | The OpenAPI 3.1 document of all of this. |
The fields of every request and answer are in the OpenAPI document. Paths
are relative to the base URL: GET /me is https://metrand.com/api/v1/me.
Strategies
A strategy is a name and a list of immutable versions. A version is a graph, named by its content hash: saving the
same graph again returns the version it already is (200), so it is safe to save before every backtest.
POST /strategiestakes anameand either atemplate(a key fromGET /templates) or a graph asdsl.POST /strategies/{id}/versionsandPOST /strategies/validatetake the graph asdsl.
The op catalog (GET /catalog) lists every node a graph may hold. The format is explained in the guide
Strategy graphs, and all of it is in one file,
the strategy format pack, to hand to an AI assistant. Graphs
beyond what the app’s Builder makes need a plan with the Graph editor (plan_required).
Backtests
A backtest is a job. POST /backtests checks the request, charges one backtest and answers at once.
| Field | Means |
|---|---|
strategy |
id and version (the hash, or a unique prefix of at least 6 characters) |
market |
exchange (binance or bybit, binance when left out), symbol (one that GET /markets lists; any other is refused before the charge), interval (1h when left out) |
window |
either bars, the last bars closed by now, or start and end; up to the plan’s bars per backtest |
costs |
taker_bps, maker_bps, slippage_bps, start_equity, leverage; each is the exchange’s standard when left out |
| Answer | Means |
|---|---|
202 |
waiting or running: read it again, or ask with Prefer: wait=N (up to 20 seconds) |
201 |
accepted and ended within the wait; look at status: succeeded or failed |
200 + Backtest-Reused: true |
an identical backtest already had this result; no charge |
202 + Backtest-Reused: true |
an identical backtest is under way; no charge, the same id |
Prefer: wait=N holds the answer up to N seconds, 20 at most, and says so with Preference-Applied: wait=N. A
waiting request holds a server worker, so a workspace has at most two waiting at once: a third, or one that comes while
the server already holds many, is answered at once, 202 without Preference-Applied, and the backtest is read again
like any other.
Identical means the same strategy and version, market, resolved window, costs and engine release. A window ends at
the last bar closed by end (now, when left out), so “the last 500 bars” is computed again once a new bar closes.
The states are queued → running → succeeded, failed or canceled. A queued backtest can be canceled and its
charge comes back. A backtest that fails for a reason that is not the request’s, the exchange’s history or the engine
unreachable, is tried again, and if it still fails its charge comes back too (error.code: market_data_unavailable,
service_unavailable). One the engine refuses (backtest_failed: the graph cannot trade as written) keeps its charge:
the engine did the work.
The result carries the engine’s report, the bars it was measured on (result.measured_on), the costs and its
provenance (provenance.fingerprint, provenance.release).
/trades: the trades in the order they closed, net of fees and funding, up to 1,000 a page./equity: the equity curve thinned topointspoints, 10 to 5,000 (500 when left out). Each stretch keeps its lowest and highest point, so drawdowns survive;total_pointssays how many there were.
How the engine fills orders inside a bar, and what it does not model, is in the guide How a backtest is computed.
Errors
Failures are problem details (application/problem+json) with a stable code to branch on:
{
"type": "https://metrand.com/docs/api#quota_exceeded",
"title": "Quota exceeded",
"status": 429,
"code": "quota_exceeded",
"detail": "Daily backtest limit reached (200) — upgrade for more.",
"request_id": "6f0c2c1e-…"
}
type links to the code below. A refused field is named in errors, by its path in the request. Nothing is charged
for a 503. Retry 429 after Retry-After, and 5xx with backoff.
unauthenticated · 401
No key was sent. Send it as Authorization: Bearer mtr_….
invalid_api_key · 401
The key is unknown, revoked or expired. Make a new one.
forbidden · 403
The key’s user may not do this, for example a viewer of the workspace writing to it.
insufficient_scope · 403
The key lacks the scope this needs; detail names it. Make a key with that scope.
plan_required · 403
The workspace’s plan does not include this, for example an op of the Graph editor.
ip_not_allowed · 403
The key is limited to other IP addresses.
not_found · 404
Nothing with that id in this workspace, or a path the API does not have.
method_not_allowed · 405
The path does not take that method.
conflict · 409
The resource is in a state that does not allow this, for example canceling a backtest already running.
idempotency_in_progress · 409
The first request with this Idempotency-Key is still being answered. Retry in a moment.
payload_too_large · 413
The body is over 1 MB.
unsupported_media_type · 415
Send JSON, with Content-Type: application/json.
validation_failed · 422
A field is refused: errors names each one by its path (market.symbol, window.start). Fix the request; retrying it
unchanged fails again.
idempotency_key_reused · 422
This Idempotency-Key was used with a different request. Use a new key for a new request.
rate_limited · 429
Too many requests this minute. Wait for Retry-After seconds.
quota_exceeded · 429
The workspace has used today’s backtests. They renew at 00:00 UTC.
too_many_jobs · 429
The workspace has as many backtests waiting as its plan allows. Wait for some to finish.
internal_error · 500
Something failed on our side. Quote request_id when you write to us.
market_data_unavailable · 503
The exchange’s history could not be read just now; nothing was charged. Retry after Retry-After.
service_unavailable · 503
A service this needs is down; nothing was charged. Retry with backoff.
Retrying safely
Send an Idempotency-Key (any string up to 255 characters, unique per action) with a POST that creates or changes
something: a strategy, a version, a backtest, a cancel. If the answer is lost, send the same request with the same key:
within 24 hours you get the first answer again (Idempotent-Replayed: true), and nothing is created or charged twice.
The same key with a different body is refused (idempotency_key_reused). Only successes and refusals of the request
as written are kept; after any other answer (a limit, a conflict, an outage) the retry runs again.
For AI agents
An agent that runs every day should watch daily and change rarely: a daily or 4-hour strategy gains one to six
bars a day, and tuning on them every day fits noise. Read the market and the results daily; propose a new version on a
fixed, slower schedule, and keep it only if it wins on data it was not tuned on. Keep every version: they are cheap,
immutable, and their backtests show what was tried. Use Idempotency-Key on every POST, and Prefer: wait instead
of polling.
Not in version 1 yet
Webhooks when a backtest ends; comparisons, periods, baskets and parameter sweeps as jobs; paper runs; live trading; an MCP server for AI assistants. Raw candles are not served: they are the exchanges’ data.