Webhook API Reference

Complete reference for the TradeStaq webhook API used to trigger Signal Bot trades.

Overview

The Webhook API allows external services (like TradingView) to send trading signals to your Signal Bots.

┌──────────────┐     POST      ┌──────────────┐     Execute     ┌──────────────┐
│  TradingView │──────────────▶│   TradeStaq     │────────────────▶│   Exchange   │
│   or Script  │   /webhooks   │   Server     │    Trade        │    (API)     │
└──────────────┘               └──────────────┘                 └──────────────┘

Endpoint

POST https://www.tradestaq.com/api/webhooks/trade/{webhookId}

Finding Your Webhook ID

1. Go to Signal Bots
2. Select your bot
3. Click Settings → Webhook
4. Copy the webhook URL
5. The ID is the last segment of the URL

Request Format

Basic Signal

{
  "action": "buy",
  "symbol": "BTCUSDT"
}

Full Signal (All Options)

{
  "action": "buy",
  "symbol": "BTCUSDT",
  "price": "50000",
  "size": "100%",
  "leverage": "10",
  "stopLoss": "48000",
  "takeProfit": "55000",
  "comment": "RSI oversold entry"
}

DCA Signal

{
  "action": "buy",
  "symbol": "BTCUSDT",
  "dca": true,
  "dcaLevel": 2,
  "size": "25%",
  "comment": "DCA Level 2 entry"
}

Request Fields

action (required)

The trading action to execute.

symbol (conditional)

The trading pair symbol.

Note: Symbol is required for buy/sell actions unless the bot is configured for a fixed pair.

price (optional)

Limit order price. If omitted, a market order is placed.

size (optional)

Position size for the trade.

Default: Uses bot's configured position size.

leverage (optional)

Leverage for futures trading.

Default: Uses bot's configured leverage.

Note: Only applies to futures exchanges. Ignored for spot trading.

stopLoss (optional)

Stop loss price.

takeProfit (optional)

Take profit price.

comment (optional)

Optional note for logging purposes.

DCA Fields

These fields enable Dollar Cost Averaging functionality. DCA must be enabled in bot settings before using these fields.

dca (optional)

Enable DCA for this signal.

Note: DCA must be enabled in bot settings. Signals with dca: true will be rejected if DCA is disabled.

dcaLevel (optional)

Specify which DCA level this entry represents.

Rules:

• Levels must be sequential (can't send level 3 before level 2)
• Level 1 creates the position, levels 2+ add to it
• Cannot exceed bot's configured max levels

DCA Example Flow

// Level 1 - Initial entry
{"action": "buy", "symbol": "BTCUSDT", "dca": true, "dcaLevel": 1, "size": "25%"}

// Level 2 - Price dropped 3%, add more
{"action": "buy", "symbol": "BTCUSDT", "dca": true, "dcaLevel": 2, "size": "25%"}

// Level 3 - Price dropped 6%, add more
{"action": "buy", "symbol": "BTCUSDT", "dca": true, "dcaLevel": 3, "size": "25%"}

// Close - Exit full position
{"action": "close", "symbol": "BTCUSDT"}

DCA Error Responses

Response Codes

Success (200)

Signal received and queued for processing.

{
  "success": true,
  "message": "Signal received",
  "signalId": "sig_abc123",
  "timestamp": 1704067200000
}

Client Errors (4xx)

Example Error Response:

{
  "success": false,
  "error": "Invalid action specified",
  "code": "INVALID_ACTION"
}

Server Errors (5xx)

TradingView Integration

Alert Message Format

In TradingView, set your alert message to JSON:

{
  "action": "{{strategy.order.action}}",
  "symbol": "{{ticker}}",
  "price": "{{close}}"
}

Using TradingView Variables

Pine Script Example

//@version=5
strategy("My Strategy", overlay=true)

// Your strategy logic
longCondition = ta.crossover(ta.sma(close, 10), ta.sma(close, 20))
shortCondition = ta.crossunder(ta.sma(close, 10), ta.sma(close, 20))

if longCondition
    strategy.entry("Long", strategy.long,
        alert_message='{"action":"buy","symbol":"{{ticker}}","size":"100%"}')

if shortCondition
    strategy.close("Long",
        alert_message='{"action":"close","symbol":"{{ticker}}"}')

Setting Up the Alert

1. Create alert on your strategy/indicator
2. Set Webhook URL to your TradeStaq webhook URL
3. Set Message to your JSON payload
4. Enable the alert

Code Examples

cURL

curl -X POST https://www.tradestaq.com/api/webhooks/trade/your-webhook-id \
  -H "Content-Type: application/json" \
  -d '{"action":"buy","symbol":"BTCUSDT","size":"100%"}'

Python

import requests

webhook_url = "https://www.tradestaq.com/api/webhooks/trade/your-webhook-id"

signal = {
    "action": "buy",
    "symbol": "BTCUSDT",
    "size": "100%",
    "stopLoss": "2%",
    "takeProfit": "4%"
}

response = requests.post(webhook_url, json=signal)
print(response.json())

JavaScript/Node.js

const axios = require('axios');

const webhookUrl = 'https://www.tradestaq.com/api/webhooks/trade/your-webhook-id';

const signal = {
  action: 'buy',
  symbol: 'BTCUSDT',
  size: '100%',
  stopLoss: '2%',
  takeProfit: '4%'
    openGraph: { title: 'Webhooks API', description: 'Webhook endpoint reference and payload formats.' },
};

axios.post(webhookUrl, signal)
  .then(response => console.log(response.data))
  .catch(error => console.error(error.response.data));

Signal Processing

Execution Flow

1. Receive - Webhook receives the signal
2. Validate - Check format and permissions
3. Queue - Add to processing queue
4. Execute - Send order to exchange
5. Confirm - Return execution result

Processing Time

Note: Actual execution time depends on exchange API latency.

Error Codes

Best Practices

Security

• Keep your webhook URL private
• Regenerate URL if compromised
• Use HTTPS only (HTTP not supported)

Reliability

• Implement retry logic for 5xx errors
• Log all signals and responses
• Monitor webhook health in dashboard

Performance

• Send only necessary fields
• Avoid duplicate signals
• Respect rate limits

Next Steps

• Authentication - API authentication methods
• Rate Limits - Understanding limits
• TradingView Integration - Detailed setup guide