Automating TradingView Strategies with Superhook

Here, we’ll show you how to connect your strategies to Bonsai’s trading bots, whether you’re using TradingView or another application. With just one POST request, Superhook can turn any market signal

Introduction to Superhook

Superhook is Bonsai’s solution that links a variety of external tools—like TradingView, third-party services, or your own custom software—to your trading bot. By using webhooks (HTTP POST requests), Superhook receives incoming JSON payloads and instantly executes trades based on the instructions you provide. This flexible design means you can integrate with almost any platform or programming language.

Note: While our examples use TradingView, you can use Superhook from any source as long as you can generate a valid JSON payload and send it to https://api.superhook.io via an HTTP POST request.

Step-by-Step Integration Guide

Step 1: Prepare Your Strategy

• TradingView Users

  1. You’ll need a strategy (e.g., a PineScript strategy or indicator) applied to your chart.

  2. If you haven’t already, browse TradingView’s public library or use Bonsai's tools for TradingView.

• Other Platforms or Apps

  1. Make sure you have some logic that decides when to buy or sell.

  2. When your logic signals a trade, you’ll send a POST request to Superhook.

Step 2: Create or Configure Your Webhook / POST Request

• TradingView Alerts

  1. In TradingView, create an alert.

  2. Specify the condition that triggers the alert (e.g., “Order fills only” if you want alerts only upon filled orders).

• Other Sources

  1. Use your application’s method for making HTTP POST requests (e.g., fetch in JavaScript, requests in Python, or cURL on the command line).

  2. Point it to https://api.superhook.io.

Step 3: Craft the JSON Payload

Superhook reads a JSON payload that tells your Bonsai Bot how to execute a trade. Below is an overview of each key field:

• token (string, required) Your private authentication token for Superhook. Keep this secret at all times.

• bot_id (string, required) The unique identifier of the Bonsai Bot you want to control.

• symbol (string, required) The market you want to trade (e.g., "BTC/USDC").

• market_position (string, optional) Accepts "long", "short", or "flat". Sending "flat" instructs Superhook to close any open positions for the given symbol. This field is especially convenient for TradingView strategies because TradingView automatically outputs these exact values (long, short, or flat) in its strategy alerts. As a result, you can use the same JSON template on multiple charts or strategies without needing to adjust your payload for each new setup—TradingView handles the position state for you.

• side (string, conditionally required) The trade direction: "buy" or "sell".

  • Required if you are not using the command field.

• amount (number, conditionally required) How many units/contracts to buy or sell.

  • Required if you are not using the command field.

• command (string, optional) A direct instruction to the bot. If this is provided, side and amount are not used.

  • Possible values:

    • "cancel_all_orders": Cancels all open orders for the given symbol.

    • "close_all_at_market": Closes all open positions for the given symbol immediately at market.

  • Useful for implementing custom stop-loss behavior or quick position management from any external trigger.

TradingView Placeholder Example

If you’re using TradingView, you can take advantage of placeholder variables that TradingView replaces with live data:

{
  "token": "your_private_token",
  "bot_id": "your_bot_id",
  "symbol": "{{syminfo.basecurrency}}/{{syminfo.currency}}",
  "market_position": "{{strategy.market_position}}",
  "side": "{{strategy.order.action}}",
  "amount": {{strategy.order.contracts}}
}

Hard-Coded or Custom Values

If you want to use fixed values or send data from your own software, simply include the fields you need:

{
  "token": "your_private_token",
  "bot_id": "your_bot_id",
  "symbol": "BTC/USDC",
  "market_position": "long",
  "side": "buy",
  "amount": 1
}

Command-Only Payload Example

If you want to close all current positions at market price (for instance, to implement a stop-loss), you can use the command field without side or amount:

{
  "token": "your_private_token",
  "bot_id": "your_bot_id",
  "symbol": "BTC/USDC",
  "command": "close_all_at_market"
}

Why It Works

Superhook doesn’t care where your data comes from—it only requires a valid JSON structure. For TradingView, placeholders are replaced automatically. For other apps, you can dynamically generate or hard‑code the payload. Just make sure each required field (or the command field) is present.

Overriding the Chart Symbol Because the symbol field is just text in your JSON payload, you can specify any symbol—even if it doesn’t match the chart you’re currently viewing in TradingView. For example, you could be on a chart showing BTC/USDT but still use "symbol": "{{syminfo.basecurrency}}/USDC" in your payload, causing the trade to execute on BTC/USDC. This flexibility allows you to analyze one market while executing trades on another.

Step 4: Enable the Webhook URL

• TradingView

  1. In the alert settings, check “Webhook URL.”

  2. Set it to https://api.superhook.io.

• Other Applications

  1. Confirm your code sends HTTP POST requests to https://api.superhook.io.

Step 5: Send the Request

• TradingView When your alert condition triggers, TradingView automatically sends the JSON payload to Superhook.

• Other Sources Whenever your application or script decides to trade, it should POST the JSON payload to Superhook. That will be processed and passed on to your Bot for execution.

---

Troubleshooting

1. No Alerts or No Trades

   • Verify you’re sending an HTTP POST to https://api.superhook.io.

   • Double-check that the JSON payload is properly formatted.

   • Ensure the minimal required fields are present (token, bot_id, symbol, plus either side/amount or command).

2. Incorrect Trades

   • Make sure token and bot_id are correct.

   • If you’re using placeholders, confirm they match TradingView’s syntax or your own variables.

   • Check the symbol field to ensure it corresponds to the market you want to trade.

3. Authentication Failures

   • Double-check your token value. It must match the private token assigned to your Bonsai Bot. Never share this token publicly.