# Connect TradingView via Webhook
{% hint style="warning" %}
The TradingView integration via Webhook is in beta. Please use it with a demo account to ensure everything works as expected.
{% endhint %}
{% hint style="warning" %}
Webhooks require some technical knowledge of **JSON formatting and general web request concepts**. If you are not familiar with these topics, we recommend using the more straightforward solution of [connecting TradingView with a **supported broker directly**](https://docs.metacopier.io/tutorials/connect-tradingview).
{% endhint %}
TradingView webhooks allow you to send automated trading alerts directly to external systems. By connecting them to MetaCopier, you can automatically execute and copy trades based on TradingView alerts and Pine Scripts without manual intervention. This guide shows how to set up and use TradingView webhooks with MetaCopier.
{% hint style="info" %}
What is webhook? A **webhook** is a way for one platform to automatically send information to another platform in real time.
In the case of **TradingView and MetaCopier**, a webhook allows TradingView to send a message to MetaCopier whenever an alert is triggered. This message can contain trading instructions such as **open a trade, close a trade, or modify a position**. MetaCopier receives the message and executes the action on the connected trading account automatically.
In simple terms, a webhook acts like a **messenger that instantly delivers TradingView alerts to MetaCopier so trades can be executed automatically**.
{% endhint %}
## Requirements
To use TradingView webhooks with MetaCopier, you need the following:
* One trading account connected to MetaCopier
* A TradingView account
## Quick Start
### Enable the Feature
On the trading account where you want positions to be opened or closed, add the **“TradingView Webhook”** feature in MetaCopier:
A new window with the **TradingView Webhook configuration** will open. For now, leave the **default settings** and save them. Each setting is explained in the [**Advanced Guide**](#advanced-guide) below.
### **Configure a New Alert**
Open the TradingView webhook feature (edit button) and select the **Setup Guide** at the top.
A new window will open where you will find all the information required for the TradingView webhook.
In TradingView, open the desired chart (in this example, **XAUUSD**). Then, in the **top-right corner**, open the **Alerts** section and create a new alert with the "+" symbol.
A new window will open. The first step is to define the **Webhook URL**, which is where the alerts will be sent. Open the **Notifications** tab and enter the URL shown in the **MetaCopier Setup Guide** into the **Webhook URL** field.
Switch to the **Message** tab in TradingView, where you can define how the message sent to MetaCopier will be formatted. The message must be formatted as **JSON** and includes the instructions for MetaCopier. Below is a simple example that **opens a** **buy position for XAUUSD with 0.1 lot size.**
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "open",
"symbol": "XAUUSD",
"orderType": "buy",
"volume": 0.1
}
```
In TradingView, it will look like this. Please make sure that the rectangle containing the JSON message is **green**. If it is **orange**, it means the JSON contains formatting errors.
That’s all! Click **Create** to save the alert and make sure it is **active** in TradingView.
Once the alert is triggered, MetaCopier will receive the notification and the defined order will be executed on your trading account.
In the **Log** section in TradingView, you can check the delivery status.
And this is how it looks on the **trading account** after the **webhook** has been received.
## Webhook examples
Below are some **typical JSON messages** to help you set up your alerts correctly. As a starting point, we will use the example shown earlier:
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "open",
"symbol": "XAUUSD",
"orderType": "buy",
"volume": 0.1
}
```
To avoid specifying the **symbol** every time (for example, if you want to reuse the same format on multiple alerts or charts), you can use **TradingView placeholders**. These placeholders act like **variables** that TradingView automatically fills with the correct values when the alert is triggered, so you don’t need to hardcode them.
Let’s use the `{{ticker}}` placeholder to avoid defining the symbol name in every alert:
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "open",
"symbol": "{{ticker}}",
"orderType": "buy",
"volume": 0.1
}
```
When the alert is triggered, the symbol will automatically be replaced based on the chart used to create the alert (in our case, **XAUUSD**).
Now let’s define **take profit (TP)** and **stop loss (SL)** values.
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "open",
"symbol": "{{ticker}}",
"orderType": "buy",
"volume": 0.1,
"stopLoss": 5050,
"takeProfit": 5130
}
```
This works, but as you can imagine, the **TP/SL values are hardcoded** and must be defined each time.
{% hint style="info" %}
**Using Points Instead of Price**
By default, `stopLoss` and `takeProfit` are interpreted as absolute price levels. You can also specify them as a **distance in points** from the fill price by adding `stopLossType` and/or `takeProfitType`:
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "open",
"symbol": "{{ticker}}",
"orderType": "buy",
"volume": 0.1,
"stopLoss": 500,
"stopLossType": "points",
"takeProfit": 1000,
"takeProfitType": "points"
}
```
In this example, the SL is set **500 points below** the fill price and TP is set **1000 points above** (for a buy order). This is useful when you don't know the exact entry price in advance.
{% endhint %}
To make them **dynamic**, you have two options:
* Use the [**MetaCopier TP/SL Management**](https://docs.metacopier.io/features/pro-features#tp-sl-management) feature to set TP/SL values automatically after the order has been placed on the broker.
* Use [**Pine Script in TradingView**](https://www.tradingview.com/pine-script-docs/faq/alerts/#how-do-i-make-an-alert-available-from-my-script) to calculate these values dynamically and include them in the webhook message.
Let’s now see how to manage existing trades. To be able to **modify or close existing trades via webhook**, we first need to define a **unique identifier** when opening a position. This is done using the JSON property **`tradeKey`**. For example:
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "open",
"symbol": "{{ticker}}",
"orderType": "buy",
"volume": 0.1,
"stopLoss": 5050,
"takeProfit": 5130,
"tradeKey": "xauusd_long_001"
}
```
To modify a specific position, you can create an **alert** with the following content:
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "modify",
"tradeKey": "xauusd_long_001",
"stopLoss": 5060,
}
```
And to close it, you can use:
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "close",
"tradeKey": "xauusd_long_001"
}
```
## Webhook URL
MetaCopier operates in four regions: **New York, London, Berlin, and Singapore**. Each region has its own trading API to help minimize latency and improve execution speed.
In the **Setup Guide** described above, the correct **Webhook URL** is automatically generated for your trading account and region.
The Webhook URL has the following structure:
```
https://{region}.metacopier.io/rest/api/v1/webhooks/tradingview/accounts/{your-account-id}
```
| Region | Host |
| --------- | --------------- |
| New York | `api-newyork` |
| London | `api-london` |
| Berlin | `api-berlin` |
| Singapore | `api-singapore` |
| Global | `api` |
***
## Advanced Guide
This section covers all features, configuration options, and advanced usage.
### Feature Configuration
All configuration options for the TradingView Webhook feature:
```json
{
"enableWebhook": true,
"authMethod": "SECRET",
"webhookSecret": "wh_abc123def456xyz789",
"allowedActions": ["open", "close", "modify"],
"allowCloseAll": false,
"allowSymbolOnlyClose": false,
"maxMatchCount": 3,
"ipAllowlist": [],
"requireTimestampForSecret": false,
"timestampToleranceSeconds": 60,
"dataRetentionDays": 30
}
```
#### Configuration Reference
| Option | Type | Default | Description |
| --------------------------- | ------- | -------- | ---------------------------------------------------- |
| `enableWebhook` | boolean | `true` | Enable/disable webhook processing |
| `authMethod` | string | `SECRET` | `SECRET` or `HMAC` |
| `webhookSecret` | string | - | Secret for SECRET auth (min 16, max 64 chars) |
| `hmacSecret` | string | auto | Secret for HMAC auth (auto-generated, read-only) |
| `allowedActions` | array | all | Allowed actions. Empty = all allowed |
| `allowCloseAll` | boolean | `false` | Enable `closeAll` action |
| `allowSymbolOnlyClose` | boolean | `false` | Allow close by symbol without filters |
| `maxMatchCount` | integer | `3` | Max positions before requiring `force: true` (1-100) |
| `ipAllowlist` | array | `[]` | Allowed IPs. Empty = all allowed |
| `requireTimestampForSecret` | boolean | `false` | Require timestamp for SECRET auth |
| `timestampToleranceSeconds` | integer | `60` | Max age of timestamp in seconds (10-300) |
| `dataRetentionDays` | integer | `30` | TTL for stored data (1-90 days) |
### Authentication Methods
#### SECRET Authentication (Recommended)
Simple secret in the request body:
```json
{
"secret": "wh_abc123def456xyz789",
"action": "open",
...
}
```
**Optional Replay Protection**
Enable `requireTimestampForSecret: true` to require timestamp:
```json
{
"secret": "wh_abc123def456xyz789",
"timestamp": 1708771200,
"action": "open",
...
}
```
Requests with timestamps older than `timestampToleranceSeconds` are rejected.
#### HMAC Authentication (Advanced)
For enhanced security using cryptographic signatures:
```json
{
"signature": "a1b2c3d4e5f6...",
"timestamp": 1708771200,
"action": "open",
...
}
```
**Signature Calculation:**
```
HMAC-SHA256(hmacSecret, timestamp + "." + canonicalPayload)
```
Where:
* `timestamp` = Unix seconds (required, must be numeric)
* `canonicalPayload` = JSON with sorted keys, no whitespace, excluding `timestamp` and `signature` fields
{% hint style="info" %}
**Note**: HMAC auth requires a proxy service to compute the signature before sending to MetaCopier.
{% endhint %}
***
### All Actions
| Action | Description |
| ---------- | ---------------------------------------------------- |
| `open` | Open a new position |
| `close` | Close position(s) by matching criteria |
| `modify` | Update SL/TP or partial close |
| `closeAll` | Close all positions (requires `allowCloseAll: true`) |
| `store` | Store custom data in Database |
***
### Open Action
Opens a new position.
```json
{
"secret": "your_secret",
"action": "open",
"symbol": "EURUSD",
"orderType": "buy",
"volume": 0.1,
"stopLoss": 1.0800,
"stopLossType": "price",
"takeProfit": 1.0950,
"takeProfitType": "price",
"openPrice": 1.0870,
"tradeKey": "my_trade",
"magicNumber": "RSI_15M",
"orderId": "Long Entry",
"comment": "TV_Signal"
}
```
#### Open Fields
| Field | Required | Type | Description |
| ---------------- | -------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `symbol` | ✅ | string | Trading pair (e.g., `EURUSD`) |
| `orderType` | ✅ | string | Order type (see below) |
| `volume` | ⚡ | number | Lot size (must be positive). Required unless `riskPercent` is used |
| `riskPercent` | ⚡ | number | Risk as percentage of account balance (e.g., `1.0` = 1%). Requires `stopLoss`. See [Risk Per Trade Sizing](#risk-per-trade-sizing) |
| `stopLoss` | ⬜ | number | Stop loss value (interpretation depends on `stopLossType`) |
| `stopLossType` | ⬜ | string | `price` (default) for absolute price, `points` for relative distance from fill price |
| `takeProfit` | ⬜ | number | Take profit value (interpretation depends on `takeProfitType`) |
| `takeProfitType` | ⬜ | string | `price` (default) for absolute price, `points` for relative distance from fill price |
| `openPrice` | ⬜ | number | Entry price (for pending orders) |
| `tradeKey` | ⬜ | string | Unique identifier for this trade (max 20 chars) |
| `magicNumber` | ⬜ | string | Group identifier for strategy |
| `orderId` | ⬜ | string | Strategy order ID from `{{strategy.order.id}}` |
| `comment` | ⬜ | string | Trade comment (max 23 characters) |
#### Order Types
| Type | Description |
| ----------- | ---------------- |
| `buy` | Market buy |
| `sell` | Market sell |
| `buylimit` | Buy limit order |
| `selllimit` | Sell limit order |
| `buystop` | Buy stop order |
| `sellstop` | Sell stop order |
{% hint style="info" %}
Order types are case-insensitive.
{% endhint %}
### Risk Per Trade Sizing
Instead of specifying a fixed `volume`, you can let MetaCopier automatically calculate the lot size based on a **percentage of your account balance** and the **stop loss distance**.
#### How It Works
When you send `riskPercent` instead of `volume`, MetaCopier calculates the lot size using this formula:
```
lots = (balance × riskPercent / 100) / (stopLossDistance × tickValue)
```
The result is then rounded to the symbol's lot step and clamped to the symbol's min/max volume.
#### Requirements
To use `riskPercent`, the following features must be enabled on your trading account in MetaCopier:
1. **TradingView Webhook** feature
2. **Risk Per Trade** feature (provides tick value configuration and symbol settings)
The Risk Per Trade feature is needed for the **tick value** used in the lot size calculation. Tick values are collected automatically from your trades once both features are active.
{% hint style="warning" %}
**Important**: The tick value service needs data from at least one closed or open trade before it can calculate lot sizes. If no tick value data is available yet, the webhook will return a `RISK_TICK_VALUE_UNAVAILABLE` error. You can also configure a manual tick value per symbol in the [Risk Per Trade](https://docs.metacopier.io/features/pro-features/risk-per-trade-tick-value) feature settings as a fallback.
{% endhint %}
#### Rules
* `volume` and `riskPercent` are **mutually exclusive** — provide one or the other, not both
* `riskPercent` must be greater than `0` and at most `100`
* `stopLoss` is **mandatory** when using `riskPercent` (the SL distance determines the lot size)
* Works with both `stopLossType: "price"` and `stopLossType: "points"`
* Works with all order types (market and pending)
#### Example: Risk 1% of Balance
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "open",
"symbol": "EURUSD",
"orderType": "buy",
"riskPercent": 1.0,
"stopLoss": 50,
"stopLossType": "points",
"takeProfit": 100,
"takeProfitType": "points"
}
```
If your account balance is $10,000, this risks $100 (1%). With a 50-point SL and the current tick value, MetaCopier calculates the appropriate lot size automatically.
#### Example: Risk 2% with Price-Based SL
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "open",
"symbol": "XAUUSD",
"orderType": "buy",
"riskPercent": 2.0,
"stopLoss": 2300.00,
"takeProfit": 2380.00,
"tradeKey": "gold_long_001"
}
```
#### Pine Script Example with Risk Per Trade
```pine
//@version=5
strategy("Risk Managed Strategy", overlay=true)
slPoints = input.int(50, "SL Points")
tpPoints = input.int(100, "TP Points")
riskPct = input.float(1.0, "Risk %", minval=0.1, maxval=100)
if buyCondition
alertMsg = '{"secret": "your_secret_minimum_16_chars", "action": "open", "symbol": "' + syminfo.ticker + '", "orderType": "buy", "riskPercent": ' + str.tostring(riskPct) + ', "stopLoss": ' + str.tostring(slPoints) + ', "stopLossType": "points", "takeProfit": ' + str.tostring(tpPoints) + ', "takeProfitType": "points", "tradeKey": "risk_' + syminfo.ticker + '_' + str.tostring(timenow) + '"}'
strategy.entry("Long", strategy.long, alert_message=alertMsg)
```
***
### Close Action
Closes position(s) based on matching criteria.
#### Match Modes
| Mode | Matches By | Description |
| ------- | -------------------------- | ---------------------------------------------- |
| `EXACT` | `tradeKey` | Close specific position(s) from stored mapping |
| `GROUP` | `magicNumber` or `orderId` | Close positions by strategy group |
| `BULK` | `symbol` | Close all positions for a symbol |
{% hint style="info" %}
If `matchMode` is not provided, it's auto-detected based on which fields you include.
{% endhint %}
#### Close by TradeKey (EXACT)
```json
{
"secret": "your_secret",
"action": "close",
"tradeKey": "my_trade_001"
}
```
#### Close by Magic Number (GROUP)
```json
{
"secret": "your_secret",
"action": "close",
"matchMode": "GROUP",
"magicNumber": "RSI_strategy",
"closeMode": "all"
}
```
#### Close by Symbol (BULK)
```json
{
"secret": "your_secret",
"action": "close",
"matchMode": "BULK",
"symbol": "EURUSD",
"direction": "long",
"closeMode": "first"
}
```
#### Close Fields
| Field | Type | Description |
| ------------- | ------- | ------------------------------------------------------ |
| `matchMode` | string | `EXACT`, `GROUP`, or `BULK` (auto-detected if omitted) |
| `tradeKey` | string | Position identifier (EXACT mode) |
| `magicNumber` | string | Strategy identifier (GROUP mode) |
| `orderId` | string | Strategy order ID (GROUP mode) |
| `symbol` | string | Trading pair (BULK mode) |
| `direction` | string | `long` or `short` filter (BULK mode) |
| `closeMode` | string | `first`, `last`, or `all` (default: `all`) |
| `force` | boolean | Allow closing more than `maxMatchCount` positions |
#### Close Modes
| Value | Description |
| ------- | ---------------------------- |
| `first` | Close oldest position (FIFO) |
| `last` | Close newest position (LIFO) |
| `all` | Close all matching positions |
#### Force Flag
If more than `maxMatchCount` positions match, you must either:
1. Add `force: true` with explicit `matchMode`
2. Add more specific filters
This prevents accidental bulk operations.
***
### Modify Action
Modifies existing position(s).
```json
{
"secret": "your_secret",
"action": "modify",
"tradeKey": "my_trade_001",
"stopLoss": 1.0850,
"takeProfit": 1.0980
}
```
#### Partial Close
```json
{
"secret": "your_secret",
"action": "modify",
"tradeKey": "my_trade_001",
"reduceVolumeBy": 0.05
}
```
{% hint style="info" %}
If `reduceVolumeBy` reduces the position to 0 or below, the position is fully closed.
{% endhint %}
#### Modify Fields
| Field | Type | Description |
| ---------------- | ------- | ------------------------------------------------------- |
| `matchMode` | string | `EXACT`, `GROUP`, or `BULK` (auto-detected) |
| `tradeKey` | string | Position identifier (EXACT mode) |
| `magicNumber` | string | Strategy identifier (GROUP mode) |
| `orderId` | string | Strategy order ID (GROUP mode) |
| `symbol` | string | Trading pair (BULK mode) |
| `force` | boolean | Allow modifying more than `maxMatchCount` positions |
| `stopLoss` | number | New stop loss price (absolute price only, not points) |
| `takeProfit` | number | New take profit price (absolute price only, not points) |
| `openPrice` | number | New price for pending orders |
| `reduceVolumeBy` | number | Volume to reduce (partial close) |
***
### CloseAll Action
Closes ALL positions on the account.
```json
{
"secret": "your_secret",
"action": "closeAll",
"force": true
}
```
**Requirements:**
* Feature must have `allowCloseAll: true`
* Request must have `force: true`
{% hint style="warning" %}
This closes every open position on the account!
{% endhint %}
***
### Store Action
Stores custom data from TradingView strategies/indicators.
```json
{
"secret": "your_secret",
"action": "store",
"data": {
"symbol": "EURUSD",
"rsi": 72.5,
"macd": 0.0012,
"signal": "overbought"
}
}
```
| Field | Required | Type | Description |
| ------ | -------- | ------ | ----------------------------------------- |
| `data` | ✅ | object | Any JSON object to store (max 100KB size) |
Data is stored in Database with TTL based on `dataRetentionDays`.
{% hint style="warning" %}
The `data` object has a maximum size limit of **100KB**. Requests exceeding this limit will be rejected.
{% endhint %}
#### Retrieve Stored Data
Use the REST API to fetch stored data:
**List all stored data (paginated):**
```
GET /rest/api/v1/webhooks/tradingview/accounts/{accountId}/data?limit=50&skip=0
```
Response:
```json
{
"data": [
{
"id": "65abc123...",
"accountId": "your-account-id",
"data": { "symbol": "EURUSD", "rsi": 72.5 },
"receivedAt": "2024-02-24T12:00:00Z"
}
],
"count": 1,
"total": 15,
"limit": 50,
"skip": 0
}
```
**Get specific data by ID:**
```
GET /rest/api/v1/webhooks/tradingview/accounts/{accountId}/data/{dataId}
```
**Delete specific data:**
```
DELETE /rest/api/v1/webhooks/tradingview/accounts/{accountId}/data/{dataId}
```
{% hint style="info" %}
These endpoints require API authentication (not the webhook secret). See REST API documentation for details.
{% endhint %}
***
### Common Request Fields
Fields available on all actions:
| Field | Type | Description |
| ---------------- | ------------- | ----------------------------------- |
| `action` | string | Action type (required) |
| `secret` | string | Webhook secret (for SECRET auth) |
| `signature` | string | HMAC signature (for HMAC auth) |
| `timestamp` | number/string | Unix seconds or ISO-8601 string |
| `idempotencyKey` | string | Prevents duplicate execution |
| `schemaVersion` | integer | Schema version (only `1` supported) |
#### Idempotency
Include an `idempotencyKey` to prevent duplicate executions:
```json
{
"secret": "your_secret",
"idempotencyKey": "open:EURUSD:1708771200000",
"action": "open",
...
}
```
Same key within 5 minutes returns the cached response.
#### Timestamp Format
Timestamp accepts:
* **Number**: Unix seconds (e.g., `1708771200`)
* **String**: ISO-8601 (e.g., `"2024-02-24T12:00:00Z"`)
***
### Error Codes
#### Authentication Errors (401)
| Code | Description |
| ------------------- | ----------------------------------- |
| `INVALID_SECRET` | Webhook secret doesn't match |
| `INVALID_SIGNATURE` | HMAC signature verification failed |
| `TIMESTAMP_EXPIRED` | Timestamp outside valid window |
| `TIMESTAMP_MISSING` | Timestamp required but not provided |
#### Authorization Errors (403)
| Code | Description |
| ---------------------------------- | --------------------------------------------------------- |
| `WEBHOOK_NOT_ENABLED` | Feature not enabled on account |
| `IP_NOT_ALLOWED` | Request IP not in allowlist |
| `ACTION_NOT_ALLOWED` | Action not in allowed actions list |
| `CLOSE_ALL_NOT_ALLOWED` | closeAll requires `allowCloseAll: true` |
| `SYMBOL_ONLY_NOT_ALLOWED` | Symbol-only close requires additional filter |
| `PROFIT_TARGET_HIT` | Order skipped - a profit target is hit |
| `RISK_LIMIT_HIT` | Order skipped - a risk limit is hit |
| `PROFIT_TARGET_AND_RISK_LIMIT_HIT` | Order skipped - both profit target and risk limit are hit |
#### Validation Errors (400)
| Code | Description |
| ------------------------------------ | --------------------------------------------------- |
| `INVALID_ACTION` | Unknown or missing action |
| `INVALID_JSON` | JSON parsing failed |
| `INVALID_CONTENT_TYPE` | Must be application/json |
| `INVALID_ORDER_TYPE` | Unknown order type |
| `INVALID_MATCH_MODE` | Unknown matchMode (must be EXACT/GROUP/BULK) |
| `MISSING_IDENTIFIER` | No position identifier provided |
| `FORCE_REQUIRES_EXPLICIT_MODE` | force:true requires explicit matchMode |
| `UNSUPPORTED_SCHEMA_VERSION` | Only schemaVersion 1 supported |
| `INVALID_TIMESTAMP_TYPE_FOR_HMAC` | HMAC requires numeric timestamp |
| `INVALID_RISK_PERCENT` | `riskPercent` must be > 0 and ≤ 100 |
| `RISK_PERCENT_CONFLICTS_WITH_VOLUME` | Cannot send both `volume` and `riskPercent` |
| `RISK_PERCENT_REQUIRES_STOP_LOSS` | `stopLoss` is mandatory when using `riskPercent` |
| `MISSING_SIZING` | Neither `volume` nor `riskPercent` provided |
| `RISK_PER_TRADE_FEATURE_REQUIRED` | Risk Per Trade feature must be added to the account |
| `RISK_TICK_VALUE_UNAVAILABLE` | No tick value data available yet for the symbol |
#### Not Found Errors (404)
| Code | Description |
| -------------------- | ----------------------------- |
| `TRADEKEY_NOT_FOUND` | TradeKey not found in mapping |
| `POSITION_NOT_FOUND` | No positions match criteria |
| `ACCOUNT_NOT_FOUND` | Account ID not found |
#### Conflict Errors (409)
| Code | Description |
| ----------------- | --------------------------------------------------------- |
| `AMBIGUOUS_MATCH` | Too many matches - add force:true with explicit matchMode |
#### Service Errors (503)
| Code | Description |
| ----------------------- | ------------------------------- |
| `ACCOUNT_NOT_CONNECTED` | Trading account is disconnected |
***
### IP Allowlist (Optional)
Restrict webhook access to specific IPs:
```json
{
"ipAllowlist": ["52.89.214.238", "34.212.75.30"]
}
```
{% hint style="warning" %}
TradingView IPs may change without notice. Empty allowlist (default) allows all IPs.
{% endhint %}
***
### Troubleshooting
When troubleshooting any webhook issue, check the **Logs** and **Audit Logs** sections in MetaCopier. **Logs** show real-time information about trade execution, errors, and broker rejections. **Audit Logs** provide a detailed history of all actions and changes, helping you understand the sequence of events that led to an issue.
**Alert not working?**
1. Check your webhook URL is correct
2. Verify your JSON is valid (use a JSON validator)
3. Confirm your secret matches exactly
4. Make sure your account is connected
**Position not found?**
1. Check the `tradeKey` spelling exactly
2. The position may already be closed
3. Use the exact same `tradeKey` you used when opening
**AMBIGUOUS\_MATCH error?**
* Add `force: true` with explicit `matchMode`
* Or add more specific filters (symbol, direction)
**HMAC signature fails?**
* Ensure timestamp is numeric (Unix seconds)
* Ensure canonical payload excludes timestamp/signature
* Ensure keys are sorted alphabetically
***
## Examples by Use Case
This section provides complete examples for common trading scenarios.
### Close All Positions on Account
Close every open position on the account. Useful for emergency exit or end-of-day cleanup.
**Step 1: Enable closeAll in Feature Settings**
```json
{
"allowCloseAll": true
}
```
**Step 2: Send closeAll Request**
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "closeAll",
"force": true
}
```
{% hint style="warning" %}
This closes ALL positions immediately. Both `allowCloseAll: true` and `force: true` are required as safety guards.
{% endhint %}
***
### Close by Strategy Group (Magic Number)
Close all positions belonging to a specific strategy. Useful when running multiple strategies on the same account.
#### Open with Magic Number
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "open",
"symbol": "EURUSD",
"orderType": "buy",
"volume": 0.1,
"magicNumber": "RSI_Strategy_15M"
}
```
#### Close All Positions with Same Magic Number
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "close",
"matchMode": "GROUP",
"magicNumber": "RSI_Strategy_15M"
}
```
{% hint style="info" %}
This closes ALL positions with `magicNumber: "RSI_Strategy_15M"`, regardless of symbol or direction.
{% endhint %}
#### Close Only Long Positions in Group
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "close",
"matchMode": "GROUP",
"magicNumber": "RSI_Strategy_15M",
"direction": "long"
}
```
***
### Close by Order ID (Pine Script Strategies)
Close positions by strategy entry name. Useful for Pine Script strategies using `strategy.entry()`.
#### Pine Script Strategy Example
```pine
//@version=5
strategy("My Strategy", overlay=true)
if buyCondition
strategy.entry("Long Entry", strategy.long)
if sellCondition
strategy.entry("Short Entry", strategy.short)
```
#### Alert Message (Open)
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "open",
"symbol": "{{ticker}}",
"orderType": "{{strategy.order.action}}",
"volume": 0.1,
"orderId": "{{strategy.order.id}}"
}
```
#### Alert Message (Close All "Long Entry" Positions)
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "close",
"matchMode": "GROUP",
"orderId": "Long Entry"
}
```
{% hint style="info" %}
`orderId` is NOT unique - all positions with the same entry name are closed.
{% endhint %}
***
### Close by Symbol (Bulk Matching)
Close positions for a specific symbol. Requires additional filters by default.
#### Close All EURUSD Long Positions
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "close",
"matchMode": "BULK",
"symbol": "EURUSD",
"direction": "long"
}
```
#### Close All EURUSD Short Positions
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "close",
"matchMode": "BULK",
"symbol": "EURUSD",
"direction": "short"
}
```
#### Close ALL EURUSD Positions (Both Directions)
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "close",
"matchMode": "BULK",
"symbol": "EURUSD",
"force": true
}
```
{% hint style="info" %}
Without `direction`, this matches all EURUSD positions. If more than `maxMatchCount` positions exist, `force: true` is required.
{% endhint %}
***
### Close First or Last Position (FIFO/LIFO)
Close only the oldest or newest position matching your criteria.
#### Close Oldest Position (FIFO)
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "close",
"matchMode": "BULK",
"symbol": "EURUSD",
"direction": "long",
"closeMode": "first"
}
```
#### Close Newest Position (LIFO)
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "close",
"matchMode": "BULK",
"symbol": "EURUSD",
"direction": "long",
"closeMode": "last"
}
```
#### Close Oldest Position in Strategy Group
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "close",
"matchMode": "GROUP",
"magicNumber": "Grid_Strategy",
"closeMode": "first"
}
```
***
### Partial Close (Reduce Position Size)
Reduce position size without fully closing it.
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "modify",
"tradeKey": "my_trade_001",
"reduceVolumeBy": 0.05
}
```
{% hint style="info" %}
**Example**: Position is 0.1 lots → `reduceVolumeBy: 0.05` → Position becomes 0.05 lots
{% endhint %}
#### Partial Close by Magic Number
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "modify",
"matchMode": "GROUP",
"magicNumber": "Scalping_Strategy",
"reduceVolumeBy": 0.01
}
```
{% hint style="info" %}
This reduces ALL positions in the group by 0.01 lots each.
{% endhint %}
***
### Using the Force Flag
The `force` flag allows closing more positions than `maxMatchCount` (default: 3).
#### When Force is Required
| Scenario | Force Required? |
| ----------------------------------- | --------------- |
| 2 positions match, maxMatchCount=3 | No |
| 5 positions match, maxMatchCount=3 | Yes |
| `closeAll` action | Always |
| Symbol-only close without direction | Yes |
#### Force with Explicit matchMode
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "close",
"matchMode": "GROUP",
"magicNumber": "High_Frequency_Strategy",
"force": true
}
```
{% hint style="info" %}
**Important**: `force: true` requires an explicit `matchMode`. Auto-detected matchMode with force will be rejected with `FORCE_REQUIRES_EXPLICIT_MODE`.
{% endhint %}
***
### Real-World Strategy Examples
#### Grid Trading Strategy
Open multiple positions with the same magic number, close oldest first:
**Open (multiple grid levels)**
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "open",
"symbol": "EURUSD",
"orderType": "buy",
"volume": 0.01,
"magicNumber": "Grid_EURUSD",
"tradeKey": "grid_EURUSD_{{timenow}}"
}
```
**Close Oldest Grid Position (Take Profit)**
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "close",
"matchMode": "GROUP",
"magicNumber": "Grid_EURUSD",
"closeMode": "first"
}
```
**Close All Grid Positions (Emergency Exit)**
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "close",
"matchMode": "GROUP",
"magicNumber": "Grid_EURUSD",
"force": true
}
```
***
#### Multi-Symbol Strategy
Trade multiple symbols with the same strategy:
**Open Position**
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "open",
"symbol": "{{ticker}}",
"orderType": "{{strategy.order.action}}",
"volume": 0.1,
"magicNumber": "Trend_Following",
"tradeKey": "trend_{{ticker}}_{{timenow}}"
}
```
**Close Specific Symbol**
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "close",
"matchMode": "BULK",
"symbol": "{{ticker}}",
"direction": "long"
}
```
**Close All Strategy Positions (All Symbols)**
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "close",
"matchMode": "GROUP",
"magicNumber": "Trend_Following",
"force": true
}
```
***
#### Scalping Strategy with Take Profit Levels
Open with tradeKey for precise control:
**Open Position**
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "open",
"symbol": "{{ticker}}",
"orderType": "buy",
"volume": 0.3,
"stopLoss": 1.0850,
"takeProfit": 1.0950,
"tradeKey": "scalp_{{ticker}}_{{timenow}}"
}
```
{% hint style="info" %}
TradingView placeholders don't support math operations. Use fixed prices or calculate SL/TP in your Pine Script using `strategy.order.alert_message`.
{% endhint %}
**Partial Close at First Target (1/3)**
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "modify",
"tradeKey": "scalp_{{ticker}}_{{timenow}}",
"reduceVolumeBy": 0.1
}
```
**Move Stop Loss to Break Even**
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "modify",
"tradeKey": "scalp_{{ticker}}_{{timenow}}",
"stopLoss": 1.0880
}
```
{% hint style="info" %}
**Tip**: For dynamic SL/TP based on entry price, use `strategy.order.alert_message` in your Pine Script to pass calculated values.
{% endhint %}
**Close Remaining Position**
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "close",
"tradeKey": "scalp_{{ticker}}_{{timenow}}"
}
```
***
### Symbol-Only Close (Advanced)
Close all positions for a symbol without direction filter. Requires special permission.
**Step 1: Enable in Feature Settings**
```json
{
"allowSymbolOnlyClose": true
}
```
**Step 2: Close All Symbol Positions**
```json
{
"secret": "your_secret_minimum_16_chars",
"action": "close",
"matchMode": "BULK",
"symbol": "EURUSD",
"closeMode": "all"
}
```
{% hint style="info" %}
**Note**: Without `allowSymbolOnlyClose: true`, you must include `direction` or another filter.
{% endhint %}
***
### Using Dynamic Values (Advanced Pine Script)
TradingView placeholders don't support math operations. To use calculated values (like dynamic SL/TP), use the `alert_message` parameter in your Pine Script.
**Pine Script Example:**
```pine
//@version=5
strategy("Dynamic SL/TP Strategy", overlay=true)
// Calculate dynamic SL and TP
entryPrice = close
stopLoss = entryPrice * 0.998 // 0.2% below entry
takeProfit = entryPrice * 1.005 // 0.5% above entry
// Build the JSON message
alertMsg = '{"secret": "your_secret_minimum_16_chars", "action": "open", "symbol": "' + syminfo.ticker + '", "orderType": "buy", "volume": 0.1, "stopLoss": ' + str.tostring(stopLoss) + ', "takeProfit": ' + str.tostring(takeProfit) + ', "tradeKey": "trade_' + syminfo.ticker + '_' + str.tostring(timenow) + '"}'
if buyCondition
strategy.entry("Long", strategy.long, alert_message=alertMsg)
```
**Alert Message (uses the dynamic values):**
```json
{{strategy.order.alert_message}}
```
When the alert triggers, TradingView replaces `{{strategy.order.alert_message}}` with the complete JSON containing the calculated SL/TP values.
