Integrations

Plugins

The plugin system lets you extend TradeClaw with custom technical indicators written in plain JavaScript. Each plugin is a single function that receives OHLCV candles and returns a signal value — no build step, no dependencies.

Plugin Interface

A plugin is a JavaScript function assigned to module.exports. It receives an array of candles and an optional parameters object, and must return a PluginResult.

typescript

// Candle shape passed to every plugin
interface Candle {
  time: number;    // Unix timestamp (seconds)
  open: number;
  high: number;
  low: number;
  close: number;
  volume: number;
}

// Return type — all fields required
interface PluginResult {
  value: number;          // Numeric indicator value
  signal: 'BUY' | 'SELL' | 'NEUTRAL';
  strength: number;       // 0–100, feeds into confluence score
  label: string;          // Short human-readable label, e.g. "Williams %R: -23"
}

// Your plugin exports a single function
module.exports = function(candles: Candle[], params: Record<string, number>): PluginResult {
  // … your indicator logic
  return { value, signal, strength, label };
};

Sandboxed Execution

Plugin code runs inside a V8 isolate with a 500ms CPU budget. Network calls, file system access, and require() calls to external modules are blocked. Only pure computation is allowed.

Allowed

Math.*
Array methods
JSON.*
console.log (dev only)
Closures and recursion

Blocked

fetch / XMLHttpRequest
require() / import()
process / Buffer
fs / path
setTimeout / setInterval

CPU budget: Plugins that exceed 500ms are killed and the run is marked as timed out. Test your plugin with GET /api/plugins/test?id=xxx before deploying.

Built-in Plugins

TradeClaw ships four production-ready plugins. They are visible in the plugin panel and can be used as references for custom implementations.

VWAP

Volume

Volume-Weighted Average Price. Calculates intraday VWAP and returns BUY when price is above VWAP, SELL when below. Strength scales with distance from VWAP.

ATR

Volatility

Average True Range with a configurable period (default 14). Returns the ATR value and a NEUTRAL signal — used as a volatility filter by other indicators.

OBV

Volume

On-Balance Volume. Measures buying/selling pressure by accumulating volume. An upward OBV slope with rising price confirms bullish momentum.

Ichimoku

Trend

Ichimoku Cloud (Tenkan-sen 9, Kijun-sen 26, Senkou Span B 52). Returns BUY when price is above the cloud and Tenkan crosses above Kijun.

Plugin Categories

MomentumTrendVolatilityVolumeOscillatorPatternCustom

API Routes

GET/api/plugins

List all installed plugins with metadata.

POST/api/plugins

Install a plugin. Pass name, description, category, and JS code.

name, description, version, category, code, params

GET/api/plugins/[id]

Retrieve full plugin details including source code.

GET/api/plugins/test

Run plugin against 100 dummy candles and return result.

Example: Williams %R Plugin

Williams %R is a momentum oscillator similar to Stochastic but inverted. Values near -100 indicate oversold conditions; values near 0 indicate overbought. This example shows a complete, installable plugin.

williams-r.js — paste into the plugin editor

/**
 * Williams %R — Momentum Oscillator
 * Range: -100 to 0
 * Oversold:  < -80  → BUY signal
 * Overbought: > -20  → SELL signal
 */
module.exports = function williamsR(candles, params) {
  const period = (params && params.period) || 14;

  if (candles.length < period) {
    return { value: -50, signal: 'NEUTRAL', strength: 0, label: 'Williams %R: N/A' };
  }

  const slice = candles.slice(-period);
  const highestHigh = Math.max(...slice.map(c => c.high));
  const lowestLow  = Math.min(...slice.map(c => c.low));
  const currentClose = candles[candles.length - 1].close;

  const range = highestHigh - lowestLow;
  const value = range === 0 ? -50 : ((highestHigh - currentClose) / range) * -100;

  let signal = 'NEUTRAL';
  let strength = 50;

  if (value < -80) {
    signal = 'BUY';
    // Strength scales from 50 at -80 to 100 at -100
    strength = Math.round(50 + ((value + 80) / -20) * 50);
  } else if (value > -20) {
    signal = 'SELL';
    // Strength scales from 50 at -20 to 100 at 0
    strength = Math.round(50 + ((value + 20) / 20) * 50);
  }

  return {
    value: Math.round(value * 100) / 100,
    signal,
    strength: Math.min(100, Math.max(0, strength)),
    label: `Williams %R: ${value.toFixed(1)}`,
  };
};

Install via API

curl -X POST https://your-instance.com/api/plugins \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Williams %R",
    "description": "Momentum oscillator ranging -100 to 0",
    "version": "1.0.0",
    "category": "Momentum",
    "params": [{ "key": "period", "default": 14, "min": 5, "max": 50 }],
    "code": "…paste code here…"
  }'

PreviousTelegram Bot NextEmbedding

Edit this page on GitHub

Plugin Interface

A plugin is a JavaScript function assigned to module.exports. It receives an array of candles and an optional parameters object, and must return a PluginResult.

typescript

// Candle shape passed to every plugin
interface Candle {
  time: number;    // Unix timestamp (seconds)
  open: number;
  high: number;
  low: number;
  close: number;
  volume: number;
}

// Return type — all fields required
interface PluginResult {
  value: number;          // Numeric indicator value
  signal: 'BUY' | 'SELL' | 'NEUTRAL';
  strength: number;       // 0–100, feeds into confluence score
  label: string;          // Short human-readable label, e.g. "Williams %R: -23"
}

// Your plugin exports a single function
module.exports = function(candles: Candle[], params: Record<string, number>): PluginResult {
  // … your indicator logic
  return { value, signal, strength, label };
};

Sandboxed Execution

Plugin code runs inside a V8 isolate with a 500ms CPU budget. Network calls, file system access, and require() calls to external modules are blocked. Only pure computation is allowed.

Allowed

Math.*
Array methods
JSON.*
console.log (dev only)
Closures and recursion

Blocked

fetch / XMLHttpRequest
require() / import()
process / Buffer
fs / path
setTimeout / setInterval

CPU budget: Plugins that exceed 500ms are killed and the run is marked as timed out. Test your plugin with GET /api/plugins/test?id=xxx before deploying.

Built-in Plugins

TradeClaw ships four production-ready plugins. They are visible in the plugin panel and can be used as references for custom implementations.

VWAP

Volume

Volume-Weighted Average Price. Calculates intraday VWAP and returns BUY when price is above VWAP, SELL when below. Strength scales with distance from VWAP.

ATR

Volatility

Average True Range with a configurable period (default 14). Returns the ATR value and a NEUTRAL signal — used as a volatility filter by other indicators.

OBV

Volume

On-Balance Volume. Measures buying/selling pressure by accumulating volume. An upward OBV slope with rising price confirms bullish momentum.

Ichimoku

Trend

Ichimoku Cloud (Tenkan-sen 9, Kijun-sen 26, Senkou Span B 52). Returns BUY when price is above the cloud and Tenkan crosses above Kijun.

API Routes

GET/api/plugins

List all installed plugins with metadata.

POST/api/plugins

Install a plugin. Pass name, description, category, and JS code.

name, description, version, category, code, params

GET/api/plugins/[id]

Retrieve full plugin details including source code.

GET/api/plugins/test

Run plugin against 100 dummy candles and return result.

Example: Williams %R Plugin

williams-r.js — paste into the plugin editor

/**
 * Williams %R — Momentum Oscillator
 * Range: -100 to 0
 * Oversold:  < -80  → BUY signal
 * Overbought: > -20  → SELL signal
 */
module.exports = function williamsR(candles, params) {
  const period = (params && params.period) || 14;

  if (candles.length < period) {
    return { value: -50, signal: 'NEUTRAL', strength: 0, label: 'Williams %R: N/A' };
  }

  const slice = candles.slice(-period);
  const highestHigh = Math.max(...slice.map(c => c.high));
  const lowestLow  = Math.min(...slice.map(c => c.low));
  const currentClose = candles[candles.length - 1].close;

  const range = highestHigh - lowestLow;
  const value = range === 0 ? -50 : ((highestHigh - currentClose) / range) * -100;

  let signal = 'NEUTRAL';
  let strength = 50;

  if (value < -80) {
    signal = 'BUY';
    // Strength scales from 50 at -80 to 100 at -100
    strength = Math.round(50 + ((value + 80) / -20) * 50);
  } else if (value > -20) {
    signal = 'SELL';
    // Strength scales from 50 at -20 to 100 at 0
    strength = Math.round(50 + ((value + 20) / 20) * 50);
  }

  return {
    value: Math.round(value * 100) / 100,
    signal,
    strength: Math.min(100, Math.max(0, strength)),
    label: `Williams %R: ${value.toFixed(1)}`,
  };
};

Install via API

curl -X POST https://your-instance.com/api/plugins \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Williams %R",
    "description": "Momentum oscillator ranging -100 to 0",
    "version": "1.0.0",
    "category": "Momentum",
    "params": [{ "key": "period", "default": 14, "min": 5, "max": 50 }],
    "code": "…paste code here…"
  }'