Triggers

Triggers are webhook-based trade automations. You define a trigger with your trade parameters, then fire it from TradingView alerts, custom bots, or any system that can send an HTTP POST request.

How Triggers Work

1. You create a trigger in the Crodl UI with your desired trade parameters
2. You copy the trigger's JSON payload (which includes your security token) and the webhook URL
3. You configure an external source (e.g., TradingView) to POST the trigger payload to the webhook
4. Crodl validates the payload, resolves your API key via the security token, and queues the trade for execution on your exchange
5. If the payload includes strategy_dashboard_id, Crodl also groups the execution into that strategy journal for dashboard reporting
6. You receive a 202 Accepted response immediately — execution happens asynchronously in the background. Results show up in the Executed Triggers tab and via Discord/Telegram notifications if connected

Webhook Endpoint

All triggers are sent to a single endpoint:

POST https://api.crodl.com/webhooks/trading
Content-Type: application/json

The response is immediate:

{
  "accepted": true,
  "request_id": "a1b2c3d4...",
  "accepted_ms": 45
}

Security Token

Every trigger payload requires a security_token. This is a unique key tied to your exchange API key — it authenticates the webhook without exposing your actual API credentials.

To get it, use Copy JSON on any trigger row on the Automations page — the copied payload includes the security_token for that trigger's API key. MCP clients can retrieve it with the single-trigger payload tool using explicit token reveal.

Open Trigger

An open trigger places a new position. Here's a full example:

{
  "name": "BTC Long",
  "allocation_id": "btc-breakout-a1",
  "strategy_dashboard_id": "btc-momentum-2026",
  "exchange": "blofin",
  "trading_action": "open",
  "security_token": "your_security_token",
  "symbol": "BTC-USDT",
  "side": "long",
  "order_type": "market",
  "margin_mode": "cross",
  "position_mode": "oneway",
  "trading_type": "futures",
  "leverage_amount": "10",
  "quantity_type": "percentage",
  "quantity_amount": "5",
  "quantity_quote": "USDT",
  "opposite_side_close": false
}

Open Trigger Fields

* Send either quantity_type + quantity_amount, or qty. A payload with none of them is rejected with 422.

Optional Trade Guardrails

Open triggers can include optional guard fields to prevent a signal from placing a larger position than expected. They work on every supported exchange: Blofin, Bitunix, Bybit, Bitget, OKX, and Hyperliquid. If these fields are omitted, Crodl keeps the existing behavior and does not enforce a notional cap.

These are payload-only fields — the trigger form does not expose them. Add them to the JSON you send (or paste into TradingView):

"max_notional_usd": "500",
"guard_action": "reject"

max_notional_usd is a position notional cap, not the margin spent. For example, a 10 SOL order at $100 is about $1,000 notional even if the trade uses 10x leverage and only requires about $100 margin.

If guard_action is omitted but max_notional_usd is present, Crodl defaults to reject.

Close Trigger

A close trigger reduces or closes an existing position:

{
  "name": "BTC Close Half",
  "allocation_id": "btc-breakout-a1",
  "strategy_dashboard_id": "btc-momentum-2026",
  "exchange": "blofin",
  "trading_action": "close",
  "security_token": "your_security_token",
  "symbol": "BTC-USDT",
  "side": "close_long",
  "order_type": "market",
  "trading_type": "futures",
  "quantity_type": "percentage",
  "quantity_amount": "50",
  "cancel_unfilled": "disabled"
}

Close Trigger Fields

Flat Trigger (Blofin only)

trading_action: "flat" is a shorthand for "close everything on the opposite side". Crodl rewrites it into a full close before execution:

• side: "buy" or "long" → closes your short (close_short)
• side: "sell" or "short" → closes your long (close_long)
• quantity_type defaults to percentage and quantity_amount to 100 if you omit them

{
  "exchange": "blofin",
  "trading_action": "flat",
  "security_token": "your_security_token",
  "symbol": "BTC-USDT",
  "side": "sell",
  "order_type": "market"
}

allocation_id

allocation_id is an optional strategy bucket ID for running multiple strategies on the same symbol and side without mixing their closes together.

When allocation_id is present:

• Opens are tracked into that allocation bucket
• Multiple opens with the same allocation_id accumulate into the same bucket
• Closes only consume that bucket's remaining size
• Percentage closes are calculated from that allocation's remainder, not the full net exchange position

When allocation_id is omitted, Crodl keeps the legacy behavior and closes against the normal net position on the exchange.

You can review your allocation buckets (opened and remaining size per ID) in the Allocation IDs tab on the Automations page.

Example flow

Open $100 of notional into the btc-breakout-a1 bucket:

{
  "exchange": "blofin",
  "trading_action": "open",
  "security_token": "your_security_token",
  "symbol": "BTC-USDT",
  "side": "long",
  "order_type": "market",
  "allocation_id": "btc-breakout-a1",
  "quantity_type": "amount",
  "quantity_mode": "position",
  "quantity_amount": "100"
}

Then close 10% of that bucket:

{
  "exchange": "blofin",
  "trading_action": "close",
  "security_token": "your_security_token",
  "symbol": "BTC-USDT",
  "side": "close_long",
  "order_type": "market",
  "allocation_id": "btc-breakout-a1",
  "quantity_type": "percentage",
  "quantity_amount": "10"
}

In that example, Crodl closes 10% of the btc-breakout-a1 allocation only. The rest of that allocation stays open, and any other allocation on BTC-USDT is untouched.

strategy_dashboard_id

strategy_dashboard_id is an optional reporting-only ID for journaling and dashboarding.

Use it when you want to group open and close triggers into a strategy journal without affecting how the trade is executed.

When strategy_dashboard_id is present:

• Crodl records the value for reporting and dashboard views
• Crodl auto-creates the journal the first time that ID is saved or executed for that exchange and API key
• The trade execution path does not change
• Closes still follow the same allocation_id and position rules as before

You can review those journals in Dashboard → Strategy or directly at /dashboard?view=strategy. In that view, you:

• Pick the exchange first
• Pick the API key
• Choose the exact strategy_dashboard_id journal to review
• Rename, annotate, end, or delete the journal without changing how trades execute

Choosing a good ID

Use an ID that stays stable across the related opens and closes for one strategy run. Good examples:

• btc-breakout-london
• turbo-venom
• eth-mean-revert-apr-2026

If you want a different journal, send a different strategy_dashboard_id.

Limit Order Pricing

For non-market order types (limit, post_only, fok, ioc), two additional fields are required:

Both are fields you add to an open or close payload — not payloads on their own.

Example — limit order at a specific price:

"order_type": "limit",
"limit_price_mode": "price",
"limit_order_price": "95000"

Example — limit order 2% below current price:

"order_type": "limit",
"limit_price_mode": "percentage",
"limit_order_price": "98"

Take-Profit and Stop-Loss

Attach TP/SL to any open trigger. All TP/SL fields are optional — omit them entirely if you don't want TP/SL. TP and SL are independent: you can send either one, or both.

Take-Profit Fields

Stop-Loss Fields

Example with TP/SL

{
  "exchange": "blofin",
  "trading_action": "open",
  "security_token": "your_token",
  "symbol": "ETH-USDT",
  "side": "long",
  "order_type": "market",
  "margin_mode": "cross",
  "position_mode": "oneway",
  "leverage_amount": "5",
  "quantity_type": "percentage",
  "quantity_amount": "10",
  "take_profit_type": "market",
  "take_profit_mode": "price",
  "take_profit_trigger_price": "4000",
  "stop_loss_type": "market",
  "stop_loss_mode": "price",
  "stop_loss_trigger_price": "3200"
}

Trade Policies

opposite_side_close

When true, automatically closes any existing position on the opposite side before opening the new one.

Example: You hold a SHORT on BTC-USDT and send an open LONG trigger with "opposite_side_close": true — the SHORT is closed first, then the LONG is opened.

cancel_unfilled

Controls whether pending unfilled orders are cancelled before the trigger executes:

pyramiding_allowed

Controls whether multiple orders or positions can stack on the same symbol and side:

TradingView Integration

Connect your triggers to TradingView alerts:

1. Create a trigger in Crodl and copy the JSON payload
2. In TradingView, create an alert on your desired condition
3. In the alert's Notifications tab, enable Webhook URL
4. Set the URL to https://api.crodl.com/webhooks/trading
5. Paste your trigger JSON into the Message field
6. Save the alert

When TradingView fires the alert, it POSTs your payload to Crodl, which executes the trade on your exchange.

Execution Flow

When a trigger fires, Crodl processes it in this order:

1. Validate payload and resolve security token
2. Return 202 Accepted immediately
3. Cancel unfilled orders (if cancel_unfilled is set)
4. Close opposite position (if opposite_side_close is true)
5. Check pyramiding rules (if pyramiding_allowed restricts)
6. Apply optional open-trade guardrails (if max_notional_usd is set)
7. Place the order on your exchange
8. Record execution result in your trade history

Because execution is asynchronous, the webhook response never contains a fill result. Track outcomes in the Executed Triggers tab, or connect Discord/Telegram in Settings to get a notification per execution.

Response Codes

Idempotency

Crodl supports idempotent trigger execution to prevent duplicate trades from repeated webhook fires.

How It Works

When you send a trigger with an explicit request key, Crodl checks whether that key has already been accepted.

• Explicit keys use a 1-hour TTL window
• If no explicit key is provided, each webhook request is treated as a new request

If a matching request is found, the original request ID is returned instead of executing a new trade.

Providing an Idempotency Key

You can provide an idempotency key in two ways (checked in this order):

1. HTTP Header

Idempotency-Key: your-unique-key-here

2. Body-level key — include any of these fields in your JSON payload:

{
  "exchange": "blofin",
  "trading_action": "open",
  "security_token": "your_token",
  "idempotency_key": "tv-alert-btc-long-20240115-001",
  "symbol": "BTC-USDT",
  "side": "long",
  "order_type": "market",
  "quantity_type": "percentage",
  "quantity_amount": "5"
}

Response Headers

Responses include idempotency information:

Managing Triggers

On the Automations page (/trading-terminal):

• Create open and close triggers with a visual form
• Edit existing triggers to update parameters
• Delete triggers you no longer need
• Run triggers manually (with a confirmation dialog) before connecting to TradingView
• View execution history in the Executed Triggers tab