BitFrog Signal Strategy Alert Specifications

Automated trading strategies rely on precise communication between analytical platforms and execution systems. BitFrog ensures seamless integration with TradingView through well-defined alert message formats, enabling traders to automate their strategies with confidence and accuracy. This guide outlines the standardized alert specifications for both PineScript™ strategy users and universal configurations, ensuring compatibility, security, and timely execution.

Whether you're using advanced PineScript strategies or setting up manual alerts, understanding these protocols is essential for reliable signal transmission. Below, we break down each component of the alert structure, explain its function, and provide best practices for implementation.

Understanding PineScript: Strategy vs. Indicator

Before diving into alert configurations, it's crucial to distinguish between PineScript strategies and indicators, as they serve different purposes:

• PineScript Strategies: Designed for backtesting and live trading, these scripts use strategy.*() functions to send simulated orders to a broker emulator. Execution results appear in the "Strategy Tester" tab beneath the chart.
• PineScript Indicators: Used solely for calculations and visualizations, indicators do not support order execution or backtesting. They are faster and consume fewer resources.

👉 Discover how to turn your trading logic into actionable signals with real-time execution.

Both types can trigger alerts, but only strategies generate position-based data like market_position or prev_market_position. The alert format you choose depends on your use case.

Section A: PineScript Strategy Users

This section is tailored for users leveraging PineScript’s strategy.entry, strategy.exit, or strategy.order functions. The following JSON structure supports dynamic placeholders that automatically populate when an alert fires.

1. Alert Message – Order ID (id)

{
 "action": "{{strategy.order.action}}",
 "amount": "{{strategy.order.contracts}}",
 "id": "{{strategy.order.id}}",
 "instrument": "{{ticker}}",
 "investmentType": "base",
 "marketPosition": "{{strategy.market_position}}",
 "marketPositionSize": "{{strategy.market_position_size}}",
 "maxLag": "60",
 "orderType": "limit",
 "orderPriceOffset": "0",
 "prevMarketPosition": "{{strategy.prev_market_position}}",
 "prevMarketPositionSize": "{{strategy.prev_market_position_size}}",
 "signalToken": "fb16aaeb4d5e2e5d36a6eacd66d06635",
 "timestamp": "{{timenow}}"
}

The id field captures the unique identifier of the executed order, defined in your PineScript code (e.g., "BuySignal" in strategy.entry("BuySignal", ...)).

2. Alert Message – Action (action)

The action value returns "buy" or "sell" based on the triggered order. This determines whether the system opens or adjusts a long or short position.

3. Alert Message – Current Market Position (marketPosition)

This field reflects the expected state after order execution:

• "long" — Long position active
• "short" — Short position active
• "flat" — No open position

It helps synchronize external systems with your strategy’s current stance.

4. Alert Message – Previous Market Position (prevMarketPosition)

Tracks the position state before the new order:

• Useful for detecting reversals (e.g., switching from long to short)
• Supports risk management by validating transitions

5. Alert Message – Instrument (ticker)

The {{ticker}} placeholder dynamically inserts the trading pair (e.g., BTCUSDT.P, ETHUSDT.P). Ensuring consistency between your chart data source and target exchange prevents mismatches.

6. Alert Message – Signal Token (signalToken)

A unique authentication key generated by BitFrog upon signal creation. This token verifies that incoming alerts are authorized, preventing spoofing or unauthorized trades.

🔐 Always keep your signal token private. Exposure could lead to unauthorized trading activity.

7. Alert Message – Timestamp (timestamp)

Uses {{timenow}} to record the exact UTC time the alert was fired in ISO 8601 format:

• Example: "2023-06-01T17:38:10Z"

This timestamp is critical for latency checks and chronological validation.

8. Alert Message – Maximum Lag (maxLag)

Defines the maximum allowable delay (in seconds) before a signal is rejected. The default is 60 seconds, ensuring only fresh, relevant signals are processed.

High-frequency strategies may require lower values (e.g., 10–30 seconds), while swing trading can tolerate longer delays.

9. Alert Message – Investment Type & Amount

• investmentType: Set to "base" to match PineScript contract counts directly.
• amount: Use {{strategy.order.contracts}} to reflect the exact quantity from your strategy.

This ensures perfect alignment between backtested results and live execution.

👉 Maximize your strategy’s potential with precise, low-latency trade execution.

Section B: Universal Compatibility

For non-strategy scripts or manual alert setups, BitFrog offers a flexible format compatible with any PineScript indicator or user-defined logic.

Supported Actions

Ideal for reversal strategies, where a buy signal closes a short and opens a long.

Example: Reversal Strategy Setup

{
 "action": "open_short",
 "amount": "5",
 "instrument": "{{ticker}}",
 "investmentType": "base",
 "maxLag": "60",
 "orderType": "limit",
 "orderPriceOffset": "0.01",
 "signalToken": "70b6498ea82de2b2e35fa3988c09c3e2",
 "timestamp": "{{timenow}}"
}

When this alert triggers:

• Any existing long position is closed
• A new short position of 5 units is opened

Order Configuration Deep Dive

Order Types

• market: Immediate execution at current market price.
• limit: Places a limit order; requires orderPriceOffset.

⚠️ For market orders, set "orderPriceOffset": "0" or omit it entirely.

Order Price Offset

Only used with limit orders. Defines how far from the current price the order should be placed:

Example: With "orderPriceOffset": "0.01", a long entry will place the order 1% below the current bid.

Investment Types Explained

Choose how order size is interpreted:

• "base": Number of base coins (e.g., BTC, ETH)
• "usdt": Quote currency value (e.g., $100 worth of BTC)
• "percent": Percentage of account balance (range: 0.01–100%)

For consistency with PineScript strategies, "base" is recommended.

Frequently Asked Questions

Q: Can I use the same signal token across multiple strategies?
A: No. Each signal must have a unique token for security and tracking purposes.

Q: What happens if my signal exceeds maxLag?
A: The signal is automatically rejected to prevent outdated trades.

Q: How do I find my signal token in BitFrog?
A: Go to your signal settings page—your token appears under “Signal Configuration.”

Q: Can I mix PineScript strategies and manual alerts?
A: Yes, but ensure consistent formatting to avoid parsing errors.

Q: Is there a minimum order size requirement?
A: Yes. Orders below the exchange’s minimum lot size will fail.

Q: Does BitFrog support partial close orders?
A: Currently, only full closure (action: close) is supported natively.

Best Practices for Reliable Signal Execution

• Always verify your chart’s data source matches your target exchange.
• Use "base" investment type for accurate strategy replication.
• Monitor latency; adjust maxLag based on your strategy’s speed.
• Regularly rotate signal tokens if sharing environments.
• Test alerts in simulation mode before going live.

👉 Start executing your automated signals with precision and confidence today.

Core Keywords: BitFrog signal strategy, TradingView alert format, PineScript strategy alerts, automated trading integration, crypto trading bot setup, signal token authentication, maxLag configuration