Gordo Trader API

Programmatic access to your Gordo Trader account. Manage strategies, monitor positions, access market data, and automate your trading workflow.

Quick Start

Generate an API key in your dashboard settings, then make your first request:

curl https://api.gordotrader.com/v1/market/price \
  -H "X-API-Key: grd_live_your_key_here"

import requests

API_KEY = "grd_live_your_key_here"
BASE = "https://api.gordotrader.com/v1"

resp = requests.get(f"{BASE}/market/price",
                    headers={"X-API-Key": API_KEY})
print(resp.json())
# {"coin": "BTC", "price": 84521.30, "change_24h_pct": 2.14, ...}

const API_KEY = "grd_live_your_key_here";
const BASE = "https://api.gordotrader.com/v1";

const resp = await fetch(`${BASE}/market/price`, {
  headers: { "X-API-Key": API_KEY },
});
const data = await resp.json();
console.log(data);
// { coin: "BTC", price: 84521.30, change_24h_pct: 2.14, ... }

Authentication

All API requests require an X-API-Key header. Generate keys in your Settings > API tab.

Permission Scopes

Rate Limits

Rate limits depend on your subscription tier. Limits are applied per API key.

When you exceed a limit, the API returns 429 Too Many Requests.

Checking Usage

curl https://api.gordotrader.com/v1/account/usage \
  -H "X-API-Key: $API_KEY"

resp = requests.get(f"{BASE}/account/usage",
                    headers={"X-API-Key": API_KEY})
print(resp.json())
# {"total_requests_today": 142, "total_requests_month": 3891, ...}

const resp = await fetch(`${BASE}/account/usage`, {
  headers: { "X-API-Key": API_KEY },
});
console.log(await resp.json());

Error Handling

The API uses standard HTTP status codes. Error responses include a JSON body with a detail field.

Error Response Format

{
  "detail": "API key rate limit exceeded: 30 requests/minute for free tier"
}

Handling Errors

import requests

def gordo_get(path, params=None):
    resp = requests.get(f"{BASE}{path}",
                        headers={"X-API-Key": API_KEY},
                        params=params)
    if resp.status_code == 429:
        print("Rate limited — back off and retry")
        return None
    resp.raise_for_status()
    return resp.json()

async function gordoGet(path, params = {}) {
  const url = new URL(`${BASE}${path}`);
  Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));

  const resp = await fetch(url, {
    headers: { "X-API-Key": API_KEY },
  });

  if (resp.status === 429) {
    console.warn("Rate limited — back off and retry");
    return null;
  }
  if (!resp.ok) throw new Error(`API error ${resp.status}`);
  return resp.json();
}

Account

Get your account profile, subscription tier, and rate limits.

Response

{
  "user_id": 1,
  "username": "trader1",
  "email": "trader@example.com",
  "tier": "pro",
  "rate_limits": { "per_minute": 120, "per_day": 50000 },
  "key_name": "My Trading Bot",
  "key_permissions": "trade"
}

Get aggregate API usage across all your keys.

Response

{
  "total_requests_today": 142,
  "total_requests_month": 3891,
  "keys": [
    {
      "name": "My Trading Bot",
      "key_prefix": "grd_live_a3f2",
      "requests_today": 100,
      "requests_month": 2500,
      "last_used_at": "2026-02-27T07:30:00Z"
    }
  ]
}

Market Data

Get the current BTC price and 24-hour change.

resp = requests.get(f"{BASE}/market/price",
                    headers={"X-API-Key": API_KEY})
price = resp.json()
print(f"BTC: ${price['price']:,.2f} ({price['change_24h_pct']:+.2f}%)")

const { price, change_24h_pct } = await gordoGet("/market/price");
console.log(`BTC: $${price.toLocaleString()} (${change_24h_pct}%)`);

Response

{
  "coin": "BTC",
  "price": 84521.30,
  "change_24h_pct": 2.14,
  "high_24h": 85200.00,
  "low_24h": 82100.50,
  "timestamp": "2026-02-27T08:00:00Z"
}

Get OHLCV candle data. Supports multiple intervals aggregated from 1-minute base data.

Parameters

# Get 100 hourly candles
resp = requests.get(f"{BASE}/market/candles",
                    headers={"X-API-Key": API_KEY},
                    params={"interval": "1h", "limit": 100})
candles = resp.json()

for c in candles[-3:]:
    print(f"{c['timestamp']} O:{c['open']} H:{c['high']} L:{c['low']} C:{c['close']}")

const candles = await gordoGet("/market/candles", {
  interval: "1h", limit: "100",
});
candles.slice(-3).forEach(c =>
  console.log(`${c.timestamp} O:${c.open} H:${c.high} L:${c.low} C:${c.close}`)
);

Response

[
  {
    "timestamp": "2026-02-27T07:00:00Z",
    "open": 84100.50, "high": 84600.00,
    "low": 84050.25, "close": 84521.30,
    "volume": 125.43
  }
]

Get funding rate history for BTC perpetual futures.

Parameters

resp = requests.get(f"{BASE}/market/funding",
                    headers={"X-API-Key": API_KEY},
                    params={"hours": 72})
for r in resp.json()[-5:]:
    print(f"{r['timestamp']}  rate={r['funding_rate']:.6f}")

const funding = await gordoGet("/market/funding", { hours: "72" });
funding.slice(-5).forEach(r =>
  console.log(`${r.timestamp}  rate=${r.funding_rate}`)
);

Get open interest snapshots showing aggregate positioning.

Parameters

Get detected liquidation burst events — aggregated clusters of liquidation activity.

Parameters

Get the current market regime classification with a composite score.

resp = requests.get(f"{BASE}/market/regime",
                    headers={"X-API-Key": API_KEY})
regime = resp.json()
print(f"Regime: {regime['regime']}  Score: {regime['score']}/100")

const regime = await gordoGet("/market/regime");
console.log(`Regime: ${regime.regime}  Score: ${regime.score}/100`);

Response

{
  "regime": "trending_up",
  "score": 72,
  "components": {
    "trend_strength": 0.81,
    "volatility_percentile": 0.45,
    "funding_bias": 0.12,
    "oi_momentum": 0.38
  },
  "timestamp": "2026-02-27T08:00:00Z"
}

Positions

List all open positions across your strategies.

Parameters

resp = requests.get(f"{BASE}/positions",
                    headers={"X-API-Key": API_KEY},
                    params={"mode": "live"})
for pos in resp.json():
    pnl = pos.get("unrealized_pnl", 0)
    print(f"{pos['strategy_name']} {pos['side']} {pos['size']} @ {pos['entry_price']}  PnL: ${pnl:+.2f}")

const positions = await gordoGet("/positions", { mode: "live" });
positions.forEach(pos =>
  console.log(`${pos.strategy_name} ${pos.side} ${pos.size} @ ${pos.entry_price}`)
);

Get full details for a single position, including linked signals and fills.

Requires trade scope

Close a position by emitting a flatten signal. The executor processes it on the next cycle.

resp = requests.post(f"{BASE}/positions/42/close",
                     headers={"X-API-Key": API_KEY})
print(resp.json())
# {"status": "flatten_signal_emitted", "position_id": 42}

const result = await fetch(`${BASE}/positions/42/close`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY },
}).then(r => r.json());
// { status: "flatten_signal_emitted", position_id: 42 }

Get a portfolio summary including total equity, unrealized P&L, and exposure breakdown.

Response

{
  "total_equity_usd": 52450.00,
  "unrealized_pnl": 340.25,
  "realized_pnl_today": -120.50,
  "open_positions": 3,
  "total_exposure_usd": 15200.00,
  "available_margin_usd": 37250.00
}

Get equity curve snapshots over time.

Parameters

Orders & Fills

List order history.

Parameters

Get order details with associated fills.

List fill history.

Parameters

Signals

List signal history — entry, exit, and flatten signals emitted by your strategies.

Parameters

Get the most recent signal from each active strategy. Useful for "last known state" dashboards.

resp = requests.get(f"{BASE}/signals/latest",
                    headers={"X-API-Key": API_KEY})
for sig in resp.json():
    print(f"[{sig['strategy_name']}] {sig['action']} at {sig['price']}  conf={sig['confidence']}")

const signals = await gordoGet("/signals/latest");
signals.forEach(s =>
  console.log(`[${s.strategy_name}] ${s.action} at ${s.price}`)
);

Get full signal detail including metadata and strategy context.

Strategies

List all your strategy packages.

Parameters

resp = requests.get(f"{BASE}/strategies/",
                    headers={"X-API-Key": API_KEY},
                    params={"active_only": True})
for s in resp.json():
    print(f"{s['display_name']}  state={s['state']}  mode={s['trading_mode']}")

const strategies = await gordoGet("/strategies/", { active_only: "true" });
strategies.forEach(s =>
  console.log(`${s.display_name}  state=${s.state}  mode=${s.trading_mode}`)
);

Get full strategy details including performance stats, current position, and promotion history.

Requires trade scope

Pause or resume a strategy. Paused strategies stop emitting signals but retain their state.

# Pause strategy #5
requests.post(f"{BASE}/strategies/5/pause",
              headers={"X-API-Key": API_KEY})

# Resume later
requests.post(f"{BASE}/strategies/5/resume",
              headers={"X-API-Key": API_KEY})

await fetch(`${BASE}/strategies/5/pause`, {
  method: "POST", headers: { "X-API-Key": API_KEY },
});

await fetch(`${BASE}/strategies/5/resume`, {
  method: "POST", headers: { "X-API-Key": API_KEY },
});

Requires full scope

Update risk assumptions for a strategy (max position size, leverage, etc.).

Request Body

{
  "risk_assumptions": {
    "max_position_usd": 5000,
    "max_leverage": 3,
    "stop_loss_pct": 2.0,
    "take_profit_pct": 5.0
  }
}

List available strategy templates with their parameter schemas.

Get promotion/rollback history across all strategies.

Parameters

Analytics

Get reconstructed round-trip trades with entry/exit prices, P&L, and duration.

Parameters

resp = requests.get(f"{BASE}/analytics/trades",
                    headers={"X-API-Key": API_KEY},
                    params={"days": 30})
trades = resp.json()

wins = [t for t in trades if t["pnl"] and t["pnl"] > 0]
losses = [t for t in trades if t["pnl"] and t["pnl"] < 0]
print(f"Trades: {len(trades)}  Win rate: {len(wins)}/{len(wins)+len(losses)}")
print(f"Total PnL: ${sum(t['pnl'] for t in trades if t['pnl']):,.2f}")

const trades = await gordoGet("/analytics/trades", { days: "30" });
const wins = trades.filter(t => t.pnl > 0);
const losses = trades.filter(t => t.pnl < 0);
console.log(`Win rate: ${wins.length}/${wins.length + losses.length}`);

Response

[
  {
    "strategy": "mean_reversion_v2",
    "package_id": 5,
    "side": "long",
    "entry_price": 83500.00,
    "exit_price": 84200.50,
    "size": 0.05,
    "pnl": 32.53,
    "pnl_pct": 0.84,
    "fees": 1.72,
    "duration_hours": 4.2,
    "entry_time": "2026-02-26T14:30:00Z",
    "exit_time": "2026-02-26T18:42:00Z",
    "status": "closed"
  }
]

Get aggregate trade statistics for a given period.

Parameters

Response

{
  "period_days": 90,
  "total_fills": 342,
  "total_volume_usd": 1250000.50,
  "total_fees_usd": 312.45,
  "avg_slippage_bps": 1.23,
  "signals": {"long_entry": 45, "short_entry": 32, "exit": 68, "flatten": 9},
  "entries": 77,
  "exits": 77
}

Get daily P&L breakdown from equity snapshots.

Parameters

Trade journal — read and create notes linked to specific trades or strategies.

requests.post(f"{BASE}/analytics/notes",
              headers={"X-API-Key": API_KEY},
              json={
                  "content": "Took profit early due to funding rate spike",
                  "package_id": 5,
                  "tags": ["funding", "early-exit"]
              })

await fetch(`${BASE}/analytics/notes`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    content: "Took profit early due to funding rate spike",
    package_id: 5,
    tags: ["funding", "early-exit"],
  }),
});

Export trade data as JSON or CSV.

Parameters

resp = requests.get(f"{BASE}/analytics/export",
                    headers={"X-API-Key": API_KEY},
                    params={"format": "csv", "days": 90})
with open("gordo_trades.csv", "w") as f:
    f.write(resp.text)
print("Exported to gordo_trades.csv")

import fs from "fs";
const resp = await fetch(`${BASE}/analytics/export?format=csv&days=90`, {
  headers: { "X-API-Key": API_KEY },
});
fs.writeFileSync("gordo_trades.csv", await resp.text());

Risk

Get current risk engine status including kill switch state, leverage, and position limits.

Response

{
  "kill_switch_active": false,
  "max_leverage": 5,
  "max_position_usd": 10000,
  "max_daily_loss_usd": 500,
  "manual_entry_block": false,
  "allocation_guard_active": false,
  "auto_throttle_enabled": true,
  "position_size_pct": 2.0,
  "playbook_budget_pct": 30.0,
  "portfolio_budget_pct": 60.0
}

Get risk event log (breaches, throttling, guard activations).

Parameters

Get or update your risk limits.

PATCH Request Body

{
  "max_leverage": 3,
  "max_position_usd": 5000,
  "max_daily_loss_usd": 250,
  "position_size_pct": 1.5
}

Requires trade scope

Toggle the emergency kill switch. When active, all trading is halted immediately.

resp = requests.post(f"{BASE}/risk/kill-switch",
                     headers={"X-API-Key": API_KEY})
print(resp.json())
# {"kill_switch_active": true, "action": "activated"}

const result = await fetch(`${BASE}/risk/kill-switch`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY },
}).then(r => r.json());
// { kill_switch_active: true, action: "activated" }

Research

Requires full scope

Submit a backtest job. Returns a job ID for polling progress and results.

Request Body

{
  "template_name": "mean_reversion",
  "days": 180,
  "parameters": {"lookback_period": 20, "zscore_threshold": 2.0},
  "risk_per_trade_pct": 2.0,
  "coin": "BTC"
}

import time

# Submit backtest
resp = requests.post(f"{BASE}/research/backtest",
                     headers={"X-API-Key": API_KEY},
                     json={"template_name": "mean_reversion", "days": 180,
                           "parameters": {"lookback_period": 20}})
job_id = resp.json()["job_id"]

# Poll for results
while True:
    status = requests.get(f"{BASE}/research/backtest/{job_id}",
                          headers={"X-API-Key": API_KEY}).json()
    print(f"Status: {status['status']}  Progress: {status.get('progress', 0)}%")
    if status["status"] in ("completed", "failed"):
        break
    time.sleep(3)

# Get results
results = requests.get(f"{BASE}/research/backtest/{job_id}/results",
                        headers={"X-API-Key": API_KEY}).json()
print(f"Sharpe: {results['sharpe_ratio']}  PnL: {results['total_pnl_pct']}%")

// Submit backtest
const job = await fetch(`${BASE}/research/backtest`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    template_name: "mean_reversion", days: 180,
    parameters: { lookback_period: 20 },
  }),
}).then(r => r.json());

// Poll for results
const poll = async () => {
  const status = await gordoGet(`/research/backtest/${job.job_id}`);
  console.log(`Status: ${status.status}  Progress: ${status.progress || 0}%`);
  if (!["completed", "failed"].includes(status.status)) {
    setTimeout(poll, 3000);
  } else {
    const results = await gordoGet(`/research/backtest/${job.job_id}/results`);
    console.log(`Sharpe: ${results.sharpe_ratio}`);
  }
};
poll();

Requires full scope

Submit a Bayesian optimization job. Uses Optuna TPE sampler for sample-efficient parameter search.

Request Body

{
  "template_name": "mean_reversion",
  "param_names": ["lookback_period", "zscore_threshold"],
  "n_trials": 50,
  "objective": "sharpe_ratio",
  "days": 180,
  "use_bayesian": true
}

List or get detail for research experiments (backtests, optimizations, walk-forwards).

Webhooks

Webhooks let you receive real-time notifications when events occur in your Gordo account. All webhook payloads are signed with HMAC-SHA256 for verification.

Requires full scope

List all configured webhooks.

Requires full scope

Create a webhook. Returns the HMAC secret for signature verification (shown once).

Request Body

{
  "name": "My Discord Bot",
  "url": "https://my-server.com/gordo-webhook",
  "events": ["signal.created", "order.filled", "risk.event"]
}

import hmac, hashlib

# Create a webhook
resp = requests.post(f"{BASE}/webhooks/",
                     headers={"X-API-Key": API_KEY},
                     json={
                         "name": "My Trading Alerts",
                         "url": "https://my-server.com/gordo-webhook",
                         "events": ["signal.created", "order.filled"]
                     })
webhook = resp.json()
print(f"Webhook ID: {webhook['id']}")
print(f"Secret (save this!): {webhook['secret']}")

# Verify webhook signatures in your receiver:
def verify_signature(payload_bytes, signature, secret):
    expected = hmac.new(secret.encode(), payload_bytes,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

import crypto from "crypto";

// Create a webhook
const webhook = await fetch(`${BASE}/webhooks/`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "My Trading Alerts",
    url: "https://my-server.com/gordo-webhook",
    events: ["signal.created", "order.filled"],
  }),
}).then(r => r.json());

console.log(`Secret: ${webhook.secret}`); // Save this!

// Verify signatures in your Express handler:
function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return signature === `sha256=${expected}`;
}

Requires full scope

Update webhook URL, name, events, or active status.

Requires full scope

Delete a webhook.

Get delivery log for a webhook — status codes, response times, and any errors.

Webhook Event Types

Webhook Payload Format

{
  "event": "signal.created",
  "timestamp": "2026-02-27T08:15:30Z",
  "data": {
    "signal_id": 1234,
    "action": "long_entry",
    "strategy": "mean_reversion_v2",
    "package_id": 5,
    "price": 84500.00,
    "confidence": 0.82
  }
}

Signature Header

Each delivery includes an X-Gordo-Signature header with sha256={hmac_hex_digest}. Verify this against the raw request body using your webhook secret.