Algo Trade Analytics Webhook API

Overview

This standard provides:

• 🎯 Enhanced Analytics - Precise cost attribution with market price context
• 🏗️ Multi-Platform Support - Works with Alpaca, Interactive Brokers, TD Ameritrade
• 📊 Order Type Intelligence - Automatic detection and validation
• 🔄 Broker Transformation - Universal format converts to broker-specific APIs
• 📈 Risk Management - Built-in take profit and stop loss support
• 🚀 Future-Proof Design - Extensible for new brokers and features

Standard Structure

Required Fields

{
  "ticker": "AAPL",           // Symbol to trade (required)
  "direction": "long",        // Trade direction: "long" or "short" (required)
  "auth_key": "your_key"      // Authentication key (required)
}

Complete Universal Format

{
  // REQUIRED FIELDS
  "ticker": "AAPL",
  "direction": "long",
  "auth_key": "your_auth_key",

  // MARKET CONTEXT (For Enhanced Analytics)
  "marketPrice": 150.25,

  // ENTRY ORDER CONFIGURATION
  "orderType": "stop_limit",
  "qty": 100,

  // ENTRY PRICES (Simplified)
  "stopPrice": 150.50,
  "limitPrice": 151.00,

  // EXIT TARGETS (Simplified)
  "profitTarget": 155.00,
  "stopLossTarget": 145.00,

  // TRAILING STOP (Alpaca Compatible)
  "trailPrice": 2.00,
  "trailPercent": 1.5,

  // EXECUTION SETTINGS
  "timeInForce": "gtc",
  "extendedHours": false,

  // METADATA (Grouped)
  "metadata": {
    "strategy": "Breakout Strategy",
    "signal": "Volume Surge",
    "timestamp": "2024-01-15T14:30:00Z",
    "comment": "Breaking above resistance",
    "alertMessage": "Long entry triggered",
    "signalPlatform": "tradingview",
    "brokerPlatform": "alpaca",
    "confidence": "high"
  }
}

Field Reference

Core Fields

Field	Type	Required	Description	Alpaca Mapping
ticker	string	✅	Symbol to trade	symbol
direction	’long’ | ‘short’	✅	Trade direction	side (‘buy’/‘sell’)
auth_key	string	✅	Authentication key	-
qty	number	🔧	Quantity to trade (shares)	qty
notional	number	🔧	Dollar amount to trade (alternative to qty)	notional
orderType	UniversalOrderType	⚠️	Entry order type	type + conditional fields
stopPrice	number	⚠️	Stop trigger price	stop_price
limitPrice	number	⚠️	Limit price	limit_price
takeProfit	TakeProfitConfig	❌	Take profit configuration	take_profit
stopLoss	StopLossConfig	❌	Stop loss configuration	stop_loss
timeInForce	TimeInForce	❌	Order duration: day, gtc, opg, cls, ioc, fok	time_in_force
extendedHours	boolean	❌	Extended hours trading	extended_hours
clientOrderId	string	❌	Custom order identifier (≤128 chars)	client_order_id
positionIntent	string	❌	Strategy intent description (see Position Intent below)	position_intent
accountId	string	❌	Account identifier	-
metadata	WebhookMetadata	❌	Strategy and signal information	-

🔧 Either qty OR notional is required - use qty for share-based trading or notional for dollar-based trading

Position Intent Values

Algo Trade Analytics supports Alpaca’s official position intent values:

Value	Description	Use Case
buy_to_open	Opening a long position	Initial buy to establish position
buy_to_close	Closing a short position	Buy to cover short position
sell_to_open	Opening a short position	Initial short sale
sell_to_close	Closing a long position	Sell to close long position

You can also use custom string values for strategy identification:

• "swing_trade_breakout"
• "dollar_cost_averaging"
• "risk_management_exit"
• "momentum_scalp"

Order Configuration

Field	Type	Description
orderType	string	"market", "limit", "stop", "stop_limit", "trailing_stop"
qty	number	Quantity to trade (shares/contracts)
notional	number	Dollar amount to trade (alternative to qty)
timeInForce	string	Order duration - see Time In Force options below
extendedHours	boolean	Allow extended hours trading
clientOrderId	string	Custom order identifier (≤128 characters, optional)

Time In Force Options

Algo Trade Analytics supports all Alpaca time-in-force values:

Value	Description	Use Case
day	Day order - valid only during regular trading hours	Default for most strategies
gtc	Good Till Canceled - valid until explicitly canceled	Long-term orders
opg	Market/Limit on Open - executes only in opening auction	Opening bell strategies
cls	Market/Limit on Close - executes only in closing auction	End-of-day strategies
ioc	Immediate or Cancel - execute immediately, cancel remainder	Quick execution with partial fills
fok	Fill or Kill - execute completely or cancel entirely	All-or-nothing execution

📝 Alpaca Platform Notes:

• Equity trading: Supports all TIF options (day, gtc, opg, cls, ioc, fok)
• Options trading: Only supports day
• Crypto trading: Only supports gtc and ioc

Entry Prices

Field	Type	Description
stopPrice	number	Stop trigger price for entry
limitPrice	number	Limit price for entry

Exit Targets (Simple)

Field	Type	Description
profitTarget	number	Take profit price
stopLossTarget	number	Stop loss trigger price

Exit Targets (Advanced - for enhanced stop-limit exits)

Field	Type	Description
profitTargetType	string	"limit" or "stop_limit"
profitTargetStopPrice	number	Stop trigger for stop-limit profit exit
profitTargetLimitPrice	number	Limit price for stop-limit profit exit
stopLossType	string	"stop" or "stop_limit"
stopLossStopPrice	number	Stop trigger for stop loss
stopLossLimitPrice	number	Limit price for stop-limit stop loss

Trailing Stop (Alpaca Compatible)

Field	Type	Description
trailPrice	number	Dollar amount trail (maps to Alpaca trail_price)
trailPercent	number	Percent trail (maps to Alpaca trail_percent)

Metadata Object

Field	Type	Description
strategy	string	Strategy name
signal	string	Signal description
timestamp	string	Signal generation time (ISO-8601)
comment	string	Order description
alertMessage	string	Custom alert text
signalPlatform	string	Signal source: "tradingview", "trendspider", "custom"
brokerPlatform	string	Target broker: "alpaca", "interactive_brokers", "td_ameritrade"

Order Types

Market Order

Execute immediately at best available price.

{
  "ticker": "AAPL",
  "direction": "long",
  "auth_key": "your_key",
  "orderType": "market",
  "qty": 100,
  "marketPrice": 150.25
}

Limit Order

Execute only at specified price or better.

{
  "ticker": "TSLA",
  "direction": "long",
  "auth_key": "your_key",
  "orderType": "limit",
  "qty": 50,
  "limitPrice": 200.00,
  "marketPrice": 201.50
}

Stop Order

Market order triggered when price reaches stop level.

{
  "ticker": "NVDA",
  "direction": "short",
  "auth_key": "your_key",
  "orderType": "stop",
  "qty": 10,
  "stopPrice": 450.00,
  "marketPrice": 452.30
}

Stop-Limit Order

Limit order triggered when price reaches stop level.

{
  "ticker": "SPY",
  "direction": "long",
  "auth_key": "your_key",
  "orderType": "stop_limit",
  "qty": 200,
  "stopPrice": 450.50,
  "limitPrice": 451.00,
  "marketPrice": 449.85
}

Trailing Stop Order

Dynamic stop that follows favorable price movement.

{
  "ticker": "QQQ",
  "direction": "short",
  "auth_key": "your_key",
  "orderType": "trailing_stop",
  "qty": 100,
  "trailPercent": 2.5,
  "marketPrice": 380.20
}

Risk Management Examples

Bracket Order (Entry + Exit)

{
  "ticker": "MSFT",
  "direction": "long",
  "auth_key": "your_key",
  "orderType": "market",
  "qty": 50,
  "marketPrice": 350.00,
  "profitTarget": 360.00,
  "stopLossTarget": 345.00,
  "metadata": {
    "strategy": "Earnings Play",
    "signal": "Bullish Guidance"
  }
}

Stop-Limit with Risk Management

{
  "ticker": "GOOGL",
  "direction": "long",
  "auth_key": "your_key",
  "orderType": "stop_limit",
  "qty": 5,
  "stopPrice": 2800.50,
  "limitPrice": 2801.00,
  "profitTarget": 2850.00,
  "stopLossTarget": 2780.00,
  "stopLossLimit": 2779.00,
  "marketPrice": 2799.25,
  "metadata": {
    "strategy": "Resistance Breakout",
    "riskRewardRatio": 1.75
  }
}

Enhanced Analytics

Three-Tier Price Analysis

The universal standard provides precise cost attribution:

{
  "marketPrice": 150.25,        // Market when signal fired
  "limitPrice": 151.00,        // Intended entry price
  "actualFillPrice": 151.12,    // Actual execution price

  "analytics": {
    "setupCost": 0.75,          // $151.00 - $150.25 (strategy choice)
    "executionSlippage": 0.12,  // $151.12 - $151.00 (broker performance)
    "totalCost": 0.87,          // Complete cost picture
    "executionQuality": "good"  // Performance rating
  }
}

Quality Assessment

• Excellent: < 0.1% total cost
• Good: 0.1% - 0.25% total cost
• Fair: 0.25% - 0.5% total cost
• Poor: > 0.5% total cost

Platform Transformation

Universal → Alpaca API

Universal Format:

{
  "ticker": "AAPL",
  "direction": "long",
  "orderType": "stop_limit",
  "qty": 10,
  "stopPrice": 105.00,
  "limitPrice": 106.00,
  "timeInForce": "gtc"
}

Alpaca API Format:

{
  "symbol": "AAPL",
  "side": "buy",
  "type": "limit",
  "qty": "10",
  "stop_price": "105",
  "limit_price": "106",
  "time_in_force": "gtc"
}

💡 Note: Alpaca uses type: "limit" with both stop_price and limit_price fields for stop-limit orders.

Universal → Interactive Brokers

Universal Format:

{
  "ticker": "TSLA",
  "direction": "short",
  "orderType": "stop_limit",
  "qty": 50,
  "stopPrice": 200.50,
  "limitPrice": 200.25
}

Interactive Brokers Format:

{
  "symbol": "TSLA",
  "action": "SELL",
  "orderType": "STP LMT",
  "totalQuantity": 50,
  "auxPrice": 200.50,
  "lmtPrice": 200.25
}

TradingView Integration

Pine Script Examples

Basic Market Order

strategy.entry("Long Entry", strategy.long,
    alert_message='{"ticker":"' + syminfo.ticker + '","direction":"long","auth_key":"your_key","orderType":"market","qty":10,"marketPrice":' + str.tostring(close) + ',"metadata":{"strategy":"Simple Trend","timestamp":"' + str.tostring(time) + '"}}')

Stop-Limit Breakout

stopPrice = high[1]
limitPrice = stopPrice * 1.002

strategy.entry("Breakout Long", strategy.long, stop=stopPrice, limit=limitPrice,
    alert_message='{"ticker":"' + syminfo.ticker + '","direction":"long","auth_key":"your_key","orderType":"stop_limit","qty":10,"stopPrice":' + str.tostring(stopPrice) + ',"limitPrice":' + str.tostring(limitPrice) + ',"marketPrice":' + str.tostring(close) + ',"metadata":{"strategy":"Breakout","signal":"High Break","timestamp":"' + str.tostring(time) + '"}}')

Risk-Managed Entry

entryPrice = close
profitTarget = entryPrice * 1.05
stopLoss = entryPrice * 0.98

strategy.entry("Risk Managed", strategy.long,
    alert_message='{"ticker":"' + syminfo.ticker + '","direction":"long","auth_key":"your_key","orderType":"market","qty":10,"marketPrice":' + str.tostring(close) + ',"profitTarget":' + str.tostring(profitTarget) + ',"stopLossTarget":' + str.tostring(stopLoss) + ',"metadata":{"strategy":"Risk Managed","riskReward":"2.5:1","timestamp":"' + str.tostring(time) + '"}}')

Validation

Required Field Validation

// Minimum valid webhook
{
  "ticker": "AAPL",     // Required
  "direction": "long",  // Required
  "auth_key": "your_key" // Required
}

Order Type Validation

The system validates order-specific requirements:

• Limit orders: Must have limitPrice
• Stop orders: Must have stopPrice
• Stop-limit orders: Must have both stopPrice and limitPrice
• Trailing stops: Must have trailPrice OR trailPercent

Price Relationship Validation

For stop-limit orders:

• Long direction: stopPrice < limitPrice
• Short direction: stopPrice > limitPrice

Error Handling

Common Validation Errors

Error	Cause	Solution
ticker is required	Missing symbol	Add "ticker": "AAPL"
direction is required	Missing direction	Add "direction": "long"
limitPrice is required for limit orders	Limit order without price	Add "limitPrice": 150.00
stopPrice must be less than limitPrice	Invalid price relationship	Fix price relationship

Platform Compatibility Warnings

Warning	Meaning	Action
Order type 'trailing_stop' not supported on td_ameritrade	Feature not available	Use supported order type
Entry stop price is 5.2% from market price	Large price gap	Review order setup

Integration Guide

Using the Webhook Processor

import { UniversalWebhookProcessor } from './utils/webhookProcessor';

// Process webhook with analytics
const result = UniversalWebhookProcessor.processWebhook(webhookData, fillPrice);

if (result.response.success) {
  console.log('Webhook processed successfully');
  console.log('Order type:', result.analysis.orderType);
  console.log('Market price:', result.analysis.marketPrice);
  console.log('Setup cost:', result.analysis.setupCost);
  console.log('Execution quality:', result.analysis.executionQuality);
  console.log('Platform order:', result.platformOrder);
} else {
  console.error('Validation errors:', result.response.errors);
}

Validation Only

// Validate webhook format
const normalized = UniversalWebhookProcessor.normalizeWebhook(webhookData);
const validation = UniversalWebhookProcessor.validateWebhook(normalized);

if (!validation.valid) {
  console.error('Errors:', validation.errors);
  console.warn('Warnings:', validation.warnings);
}

Generate Examples

// Generate example webhooks for testing
const marketOrder = UniversalWebhookProcessor.generateExample('market');
const stopLimit = UniversalWebhookProcessor.generateExample('stop_limit');
const trailingStop = UniversalWebhookProcessor.generateExample('trailing_stop');

Best Practices

1. Always Include Market Price

{
  "ticker": "AAPL",
  "direction": "long",
  "marketPrice": 150.25,  // Critical for analytics
  "orderType": "limit",
  "limitPrice": 149.50
}

2. Use Risk Management

{
  "ticker": "TSLA",
  "direction": "long",
  "orderType": "market",
  "profitTarget": 220.00,    // Always set profit target
  "stopLossTarget": 190.00   // Always set stop loss
}

3. Include Rich Metadata

{
  "ticker": "NVDA",
  "direction": "long",
  "metadata": {
    "strategy": "AI Momentum",
    "signal": "Earnings Beat",
    "confidence": "high",
    "riskReward": "3:1",
    "timeframe": "4h"
  }
}

4. Specify Platform Preferences

{
  "ticker": "QQQ",
  "direction": "short",
  "metadata": {
    "signalPlatform": "tradingview",
    "brokerPlatform": "alpaca",
    "preferredExecution": "aggressive"
  }
}

Migration from Legacy Formats

Automatic Compatibility

The processor automatically handles legacy formats:

// Legacy format (still works)
{
  "price": 150.25,
  "action": "buy",
  "ticker": "AAPL",
  "extras": {
    "stop": 150.50,
    "limit": 151.00
  }
}

// Automatically converts to universal format
{
  "ticker": "AAPL",
  "direction": "long",
  "marketPrice": 150.25,
  "orderType": "stop_limit",
  "stopPrice": 150.50,
  "limitPrice": 151.00
}

Future Enhancements

Planned Features

• Multi-leg option strategies - Complex options trading
• Portfolio-level risk management - Account-wide position limits
• Cross-platform arbitrage - Execute across multiple brokers
• Machine learning analytics - AI-powered execution optimization

Extensibility

Easy to extend for new platforms and features:

{
  "ticker": "BTC-USD",
  "direction": "long",
  "auth_key": "your_key",
  "metadata": {
    "brokerPlatform": "coinbase",
    "cryptoFeatures": {
      "stakingEnabled": true,
      "margin": 2
    }
  }
}

This webhook specification provides a solid foundation for automated trading with enhanced analytics while maintaining simplicity and extensibility.

Exit Targets - Profit Taking

{
  // Simple limit profit target (traditional)
  "profitTarget": 155.00,

  // OR: Advanced stop-limit profit target
  "profitTargetType": "stop_limit",
  "profitTargetStopPrice": 155.00,    // Trigger when price hits this level
  "profitTargetLimitPrice": 154.75,   // But sell no lower than this (for long)

  // OR: Simple limit profit target (explicit)
  "profitTargetType": "limit",
  "profitTargetLimitPrice": 155.00
}

Exit Targets - Stop Loss

{
  // Simple stop loss (traditional)
  "stopLossTarget": 145.00,

  // OR: Advanced stop-limit stop loss
  "stopLossType": "stop_limit",
  "stopLossStopPrice": 145.00,        // Trigger when price drops to this level
  "stopLossLimitPrice": 144.75,       // But sell no lower than this (for long)

  // OR: Simple stop loss (explicit)
  "stopLossType": "stop",
  "stopLossStopPrice": 145.00
}

🎯 Advanced Exit Strategy Examples

Example 1: Long Position with Stop-Limit Exits

{
  "auth_key": "your_auth_key",
  "ticker": "NVDA",
  "direction": "long",
  "orderType": "limit",
  "qty": 100,
  "marketPrice": 875.00,
  "limitPrice": 876.50,

  // Stop-limit profit target
  "profitTargetType": "stop_limit",
  "profitTargetStopPrice": 890.00,      // Trigger when price hits $890
  "profitTargetLimitPrice": 889.50,     // But sell no lower than $889.50

  // Stop-limit stop loss
  "stopLossType": "stop_limit",
  "stopLossStopPrice": 865.00,          // Trigger when price drops to $865
  "stopLossLimitPrice": 864.50,         // But sell no lower than $864.50

  "metadata": {
    "strategy": "Earnings Breakout",
    "signal": "Volume Surge + MA Cross"
  }
}

💡 Why Stop-Limit Exits?

• Profit Target: Protects against sudden reversals when taking profits
• Stop Loss: Prevents excessive slippage during market gaps or high volatility
• Control: You set both the trigger point AND the worst acceptable price

Example 2: Short Position with Mixed Exit Types

{
  "auth_key": "your_auth_key",
  "ticker": "AMZN",
  "direction": "short",
  "orderType": "stop_limit",
  "qty": 50,
  "marketPrice": 145.20,
  "stopPrice": 144.80,
  "limitPrice": 144.50,

  // Stop-limit profit target (for short: profit when price drops)
  "profitTargetType": "stop_limit",
  "profitTargetStopPrice": 140.00,      // Trigger when price drops to $140
  "profitTargetLimitPrice": 140.25,     // But buy back no higher than $140.25

  // Regular stop loss (for short: loss when price rises)
  "stopLossType": "stop",
  "stopLossStopPrice": 148.00,          // Stop loss if price rises to $148

  "metadata": {
    "strategy": "Short Squeeze Protection",
    "signal": "Overbought RSI + Resistance"
  }
}

Universal → Alpaca Trailing Stop

Universal Format:

{
  "ticker": "QQQ",
  "direction": "short",
  "orderType": "trailing_stop",
  "qty": 100,
  "trailPercent": 2.5,
  "timeInForce": "gtc"
}

Alpaca API Format:

{
  "symbol": "QQQ",
  "side": "sell",
  "type": "trailing_stop",
  "qty": "100",
  "trail_percent": "2.5",
  "time_in_force": "gtc"
}

🚀 Advanced Examples

Dollar-Based Trading (Alpaca notional)

{
  "ticker": "SPY",
  "direction": "long",
  "auth_key": "your_auth_key",
  "orderType": "market",
  "notional": 10000,
  "clientOrderId": "monthly-dca-001",
  "positionIntent": "dollar_cost_averaging",
  "takeProfit": {
    "limitPrice": 460.00
  }
}

Complete Alpaca Integration

{
  "ticker": "AAPL",
  "direction": "long",
  "auth_key": "your_auth_key",
  "orderType": "stop_limit",
  "qty": 100,
  "stopPrice": 150.50,
  "limitPrice": 151.00,
  "clientOrderId": "breakout-strategy-001",
  "positionIntent": "buy_to_open",
  "timeInForce": "gtc",
  "extendedHours": false,
  "takeProfit": {
    "limitPrice": 160.00
  },
  "stopLoss": {
    "stopPrice": 145.00,
    "limitPrice": 144.50
  }
}

Time In Force Examples

Opening Bell Strategy (opg)

{
  "ticker": "SPY",
  "direction": "long",
  "auth_key": "your_key",
  "orderType": "market",
  "qty": 100,
  "timeInForce": "opg",
  "clientOrderId": "opening-momentum-001",
  "metadata": {
    "strategy": "Opening Gap Play",
    "signal": "Pre-market Volume Surge"
  }
}

Closing Bell Strategy (cls)

{
  "ticker": "QQQ",
  "direction": "short",
  "auth_key": "your_key",
  "orderType": "limit",
  "qty": 50,
  "limitPrice": 380.50,
  "timeInForce": "cls",
  "clientOrderId": "close-rebalance-001",
  "metadata": {
    "strategy": "End of Day Rebalancing",
    "signal": "Portfolio Adjustment"
  }
}

Immediate Execution (ioc)

{
  "ticker": "NVDA",
  "direction": "long",
  "auth_key": "your_key",
  "orderType": "limit",
  "qty": 100,
  "limitPrice": 875.25,
  "timeInForce": "ioc",
  "clientOrderId": "scalp-entry-001",
  "metadata": {
    "strategy": "High Frequency Scalping",
    "signal": "Level 2 Opportunity"
  }
}

All-or-Nothing Execution (fok)

{
  "ticker": "TSLA",
  "direction": "long",
  "auth_key": "your_key",
  "orderType": "limit",
  "qty": 1000,
  "limitPrice": 200.00,
  "timeInForce": "fok",
  "clientOrderId": "block-trade-001",
  "metadata": {
    "strategy": "Large Block Trade",
    "signal": "Institutional Order"
  }
}

Position Intent Examples

Opening a Long Position (buy_to_open)

{
  "ticker": "AAPL",
  "direction": "long",
  "auth_key": "your_key",
  "orderType": "market",
  "qty": 100,
  "positionIntent": "buy_to_open",
  "clientOrderId": "long-entry-001",
  "metadata": {
    "strategy": "Momentum Entry",
    "signal": "Breakout Confirmed"
  }
}

Closing a Short Position (buy_to_close)

{
  "ticker": "TSLA",
  "direction": "long",
  "auth_key": "your_key",
  "orderType": "limit",
  "qty": 50,
  "limitPrice": 200.00,
  "positionIntent": "buy_to_close",
  "clientOrderId": "short-cover-001",
  "metadata": {
    "strategy": "Short Cover",
    "signal": "Oversold Bounce"
  }
}

Opening a Short Position (sell_to_open)

{
  "ticker": "SPY",
  "direction": "short",
  "auth_key": "your_key",
  "orderType": "stop_limit",
  "qty": 200,
  "stopPrice": 450.00,
  "limitPrice": 449.50,
  "positionIntent": "sell_to_open",
  "clientOrderId": "short-entry-001",
  "metadata": {
    "strategy": "Market Hedge",
    "signal": "Technical Breakdown"
  }
}

Closing a Long Position (sell_to_close)

{
  "ticker": "NVDA",
  "direction": "short",
  "auth_key": "your_key",
  "orderType": "market",
  "qty": 100,
  "positionIntent": "sell_to_close",
  "clientOrderId": "profit-take-001",
  "metadata": {
    "strategy": "Profit Taking",
    "signal": "Target Reached"
  }
}