Integrations

API Reference

TradeClaw exposes a REST API with 42 endpoints. All endpoints return JSON. An OpenAPI 3.0 spec is available at /api/openapi.

Base URL

bash

https://your-instance.com/api

All endpoints are relative to your deployment URL. Set NEXT_PUBLIC_BASE_URL in your environment.

Authentication

Public endpoints (signals, prices, health) require no authentication. Endpoints that act on your account check the Authorization header or your session cookie. API keys share a single free rate limit of 100 requests per hour.

bash

curl https://your-instance.com/api/signals \
  -H "Authorization: Bearer YOUR_API_KEY"

Signals

GET/api/signals

List trading signals with optional filtering.

symboltimeframedirectionminConfidencelimit

GET/api/signals/history

Historical signal archive with export support (CSV/JSON).

symbolfromtoformat

GET/api/signals/multi-tf

Multi-timeframe consensus — returns M15/H1/H4/D1 alignment for each symbol.

symbol

Example: fetch high-confidence BUY signals on H1

curl "https://your-instance.com/api/signals?direction=BUY&timeframe=H1&minConfidence=80"

# Response
{
  "signals": [
    {
      "id": "sig_abc123",
      "symbol": "XAUUSD",
      "timeframe": "H1",
      "direction": "BUY",
      "confidence": 87,
      "entryPrice": 2345.50,
      "tp1": 2360.00,
      "tp2": 2374.50,
      "tp3": 2389.00,
      "sl": 2331.00,
      "timestamp": "2026-03-27T12:00:00Z",
      "status": "active"
    }
  ],
  "total": 1
}

Prices

GET/api/prices

Fetch current prices. Crypto from CoinGecko, Forex/Metals from Stooq.

symbols

GET/api/prices/stream

Server-Sent Events stream. Emits price updates within seconds (~2s crypto, ≤60s FX/metals/stocks) and new signals on each 5-minute cron tick.

SSE client example

const es = new EventSource('/api/prices/stream');

es.addEventListener('price', (e) => {
  const { symbol, price, change } = JSON.parse(e.data);
  console.log(`${symbol}: ${price} (${change > 0 ? '+' : ''}${change}%)`);
});

es.addEventListener('signal', (e) => {
  const signal = JSON.parse(e.data);
  console.log('New signal:', signal.symbol, signal.direction, signal.confidence);
});

Price Alerts

GET/api/alerts

List all price alerts.

statussymbol

POST/api/alerts

Create a price alert. Triggers a browser notification when price crosses the threshold.

symbol (required)price (required)direction (above|below)note

GET/api/alerts/[id]

Get a single alert by ID.

GET/api/alerts/check

Poll for triggered alerts. Call this to update alert status.

GET/api/alerts/stats

Alert statistics — total, triggered, pending.

Paper Trading

GET/api/paper-trading

Get portfolio — balance, open positions, history, equity curve.

POST/api/paper-trading/open

Open a simulated position.

symboldirectionquantitysltp1tp2tp3

POST/api/paper-trading/close

Close a specific position by ID.

positionId

POST/api/paper-trading/close-all

Close all open positions.

POST/api/paper-trading/follow-signal

Auto-open a position from a signal.

signalIdquantity

POST/api/paper-trading/reset

Reset portfolio to $10,000 starting balance.

GET/api/paper-trading/stats

P&L stats — win rate, Sharpe ratio, max drawdown, profit factor.

Open a position

curl -X POST https://your-instance.com/api/paper-trading/open \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTCUSD",
    "direction": "BUY",
    "quantity": 500,
    "sl": 65000,
    "tp1": 70000,
    "tp2": 75000,
    "tp3": 80000
  }'

Screener

GET/api/screener

Market screener with composite TA filters.

minRSImaxRSImacdSignalemaTrendminVolatilityminConfidence

Webhooks

GET/api/webhooks

List all webhooks (secrets redacted).

POST/api/webhooks

Create a webhook.

url (required)namesecret

PATCH/api/webhooks

Update webhook URL, name, or enabled state.

idurlnameenabled

DELETE/api/webhooks

Delete a webhook.

id

POST/api/webhooks/[id]/test

Send a test payload to the webhook.

GET/api/webhooks/[id]/deliveries

View delivery history for a webhook.

POST/api/webhooks/deliver

Manually trigger a delivery.

idpayload

POST/api/webhooks/dispatch

Broadcast a payload to all enabled webhooks.

Plugins

GET/api/plugins

List all installed plugins.

POST/api/plugins

Install a new plugin. Pass indicator metadata and JS code.

namedescriptionversioncategorycodeparams

GET/api/plugins/[id]

Get plugin details and code.

GET/api/plugins/test

Test a plugin with dummy OHLCV data.

id

POST/api/telegram/webhook

Telegram update receiver. Set this as your bot webhook URL.

POST/api/telegram/send

Send a message to a chat.

chatIdtextparseMode

GET/api/telegram/status

Check bot connection status and webhook info.

Utility

GET/api/health

Readiness check. Returns 200 only when PostgreSQL and the required schema migration are ready; otherwise 503.

GET/api/openapi

OpenAPI 3.0 specification in JSON format.

GET/api/embed

Generate embeddable widget script.

pairthemewidthheight

GET/api/explain

AI explanation of a signal's reasoning.

signalId

GET/api/mtf

Detailed multi-timeframe analysis for a symbol.

symbol

GET/api/tpsl

TP/SL calculator using ATR and Fibonacci extensions.

symboldirectionentryPricerisk

GET/api/leaderboard

Signal accuracy leaderboard by symbol and timeframe.

Error Format

All errors return a JSON body with an error field.

json

// 400 Bad Request
{ "error": "symbol is required" }

// 404 Not Found
{ "error": "signal not found" }

// 429 Too Many Requests
{ "error": "rate limit exceeded", "retryAfter": 60 }

// 500 Internal Server Error
{ "error": "internal server error" }

PreviousStrategy Builder NextWebhooks

Edit this page on GitHub

Integrations

API Reference

TradeClaw exposes a REST API with 42 endpoints. All endpoints return JSON. An OpenAPI 3.0 spec is available at /api/openapi.

Base URL

bash

https://your-instance.com/api

All endpoints are relative to your deployment URL. Set NEXT_PUBLIC_BASE_URL in your environment.

Authentication

bash

curl https://your-instance.com/api/signals \
  -H "Authorization: Bearer YOUR_API_KEY"

Signals

GET/api/signals

List trading signals with optional filtering.

symboltimeframedirectionminConfidencelimit

GET/api/signals/history

Historical signal archive with export support (CSV/JSON).

symbolfromtoformat

GET/api/signals/multi-tf

Multi-timeframe consensus — returns M15/H1/H4/D1 alignment for each symbol.

symbol

Example: fetch high-confidence BUY signals on H1

curl "https://your-instance.com/api/signals?direction=BUY&timeframe=H1&minConfidence=80"

# Response
{
  "signals": [
    {
      "id": "sig_abc123",
      "symbol": "XAUUSD",
      "timeframe": "H1",
      "direction": "BUY",
      "confidence": 87,
      "entryPrice": 2345.50,
      "tp1": 2360.00,
      "tp2": 2374.50,
      "tp3": 2389.00,
      "sl": 2331.00,
      "timestamp": "2026-03-27T12:00:00Z",
      "status": "active"
    }
  ],
  "total": 1
}

Prices

GET/api/prices

Fetch current prices. Crypto from CoinGecko, Forex/Metals from Stooq.

symbols

GET/api/prices/stream

Server-Sent Events stream. Emits price updates within seconds (~2s crypto, ≤60s FX/metals/stocks) and new signals on each 5-minute cron tick.

SSE client example

const es = new EventSource('/api/prices/stream');

es.addEventListener('price', (e) => {
  const { symbol, price, change } = JSON.parse(e.data);
  console.log(`${symbol}: ${price} (${change > 0 ? '+' : ''}${change}%)`);
});

es.addEventListener('signal', (e) => {
  const signal = JSON.parse(e.data);
  console.log('New signal:', signal.symbol, signal.direction, signal.confidence);
});

Price Alerts

GET/api/alerts

List all price alerts.

statussymbol

POST/api/alerts

Create a price alert. Triggers a browser notification when price crosses the threshold.

symbol (required)price (required)direction (above|below)note

GET/api/alerts/[id]

Get a single alert by ID.

GET/api/alerts/check

Poll for triggered alerts. Call this to update alert status.

GET/api/alerts/stats

Alert statistics — total, triggered, pending.

Paper Trading

GET/api/paper-trading

Get portfolio — balance, open positions, history, equity curve.

POST/api/paper-trading/open

Open a simulated position.

symboldirectionquantitysltp1tp2tp3

POST/api/paper-trading/close

Close a specific position by ID.

positionId

POST/api/paper-trading/close-all

Close all open positions.

POST/api/paper-trading/follow-signal

Auto-open a position from a signal.

signalIdquantity

POST/api/paper-trading/reset

Reset portfolio to $10,000 starting balance.

GET/api/paper-trading/stats

P&L stats — win rate, Sharpe ratio, max drawdown, profit factor.

Open a position

curl -X POST https://your-instance.com/api/paper-trading/open \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTCUSD",
    "direction": "BUY",
    "quantity": 500,
    "sl": 65000,
    "tp1": 70000,
    "tp2": 75000,
    "tp3": 80000
  }'

Screener

GET/api/screener

Market screener with composite TA filters.

minRSImaxRSImacdSignalemaTrendminVolatilityminConfidence

Webhooks

GET/api/webhooks

List all webhooks (secrets redacted).

POST/api/webhooks

Create a webhook.

url (required)namesecret

PATCH/api/webhooks

Update webhook URL, name, or enabled state.

idurlnameenabled

DELETE/api/webhooks

Delete a webhook.

id

POST/api/webhooks/[id]/test

Send a test payload to the webhook.

GET/api/webhooks/[id]/deliveries

View delivery history for a webhook.

POST/api/webhooks/deliver

Manually trigger a delivery.

idpayload

POST/api/webhooks/dispatch

Broadcast a payload to all enabled webhooks.

Plugins

GET/api/plugins

List all installed plugins.

POST/api/plugins

Install a new plugin. Pass indicator metadata and JS code.

namedescriptionversioncategorycodeparams

GET/api/plugins/[id]

Get plugin details and code.

GET/api/plugins/test

Test a plugin with dummy OHLCV data.

id

POST/api/telegram/webhook

Telegram update receiver. Set this as your bot webhook URL.

POST/api/telegram/send

Send a message to a chat.

chatIdtextparseMode

GET/api/telegram/status

Check bot connection status and webhook info.

Utility

GET/api/health

Readiness check. Returns 200 only when PostgreSQL and the required schema migration are ready; otherwise 503.

GET/api/openapi

OpenAPI 3.0 specification in JSON format.

GET/api/embed

Generate embeddable widget script.

pairthemewidthheight

GET/api/explain

AI explanation of a signal's reasoning.

signalId

GET/api/mtf

Detailed multi-timeframe analysis for a symbol.

symbol

GET/api/tpsl

TP/SL calculator using ATR and Fibonacci extensions.

symboldirectionentryPricerisk

GET/api/leaderboard

Signal accuracy leaderboard by symbol and timeframe.

Error Format

All errors return a JSON body with an error field.

json

// 400 Bad Request
{ "error": "symbol is required" }

// 404 Not Found
{ "error": "signal not found" }

// 429 Too Many Requests
{ "error": "rate limit exceeded", "retryAfter": 60 }

// 500 Internal Server Error
{ "error": "internal server error" }

PreviousStrategy Builder NextWebhooks

Edit this page on GitHub