PhoenixPerpetualsDocs API v1
Get an API key

Trading

TradingView alerts⁠.

Turn TradingView alerts into orders on one account, with no code and no server: the link, the message, sizing, exits and the alert log.

View as Markdown

On this page
  1. Create a link
  2. Set up the alert
  3. The message
  4. What each action does
  5. Position modes
  6. Safety built in
  7. Check what happened

An alert link turns your TradingView alerts into orders. TradingView calls the link, the API reads the alert's message and trades one account, within limits you set on the link. No code and no server of yours are needed, and the messages you already use with other signal tools work as they are.

In your dashboard, open Developers, TradingView and choose Create alert link:

  • The account it trades: one link, one account. A live link takes a code we email you.
  • Its limits: the markets it may trade (none chosen: every market), reduce-only, its largest order and largest position in USD, and its own daily loss stop (no new position once today's loss reaches it).
  • The order size: from the alert, or the link's own: a fixed size, a fixed amount in USD, or a share of the account's balance. The link's own size wins over the alert's.
  • When the same signal repeats: ignore it while already in position (the default), add to the position, or treat each alert as the target position (see Position modes).

The link's address, https://hooks.phoenixperpsfunding.com/tv/pptv_..., is shown once. Anyone who has it can trade within the link's limits, so keep it like a password. Lost it? Delete the link and create a new one: the old address stops at once. You can keep 20 links in each environment.

Set up the alert#

  1. In TradingView, open the alert of your chart or strategy.
  2. Under Notifications, tick Webhook URL and paste the link.
  3. In Message, paste the message, then create the alert.

For a strategy, TradingView fills in what the strategy did:

{
  "market": "BTC-USD",
  "action": "{{strategy.order.action}}",
  "size": "{{strategy.order.contracts}}",
  "price": "{{close}}",
  "id": "{{strategy.order.id}}-{{timenow}}"
}

For an indicator or a price alert, write the action yourself, one alert per action:

{ "market": "ETH-USD", "action": "buy", "usd": 500, "tp": "3%", "sl": "1.5%" }

A message that still holds a TradingView placeholder when it arrives (a strategy placeholder in an indicator's alert, for example) is refused with placeholder_unfilled, naming the field.

The message#

The API reads JSON, a PineConnector line (LicenseID,buy,BTCUSD,risk=0.01) or plain text (buy BTC-USD qty 0.01 tp 2% sl 1%). JSON in the shape PickMyTrade or TradersPost teach is read as they write it. Our own fields:

FieldWhat it says
actionbuy (or long), sell (short), close, close_long, close_short, flip, cancel, cancel_long, cancel_short, exits, flatten
marketOur market id (BTC-USD), or a TradingView ticker: an EXCHANGE: prefix, a .P or PERP suffix and a USDT, USDC or USD quote are dropped, so BTCUSDT.P is BTC-USD. ALL, with close or flatten, is every market
order_typemarket (the default), limit, stop or stop_limit, with price and stop_price. buy_limit, sell_stop and the like as the action set it too
size, usd, pct_balanceThe size: in the market's unit, in USD, or as a percent of the account's balance
pct_positionFor a close: the share of the position to close (without it, and without a size, the whole position)
tp, slThe take-profit and the stop-loss: a price, "2%", { "percent": 2 } or { "distance": 150 }; 0 is none, as PickMyTrade writes an unused one
trail_pct, breakeven_pctA stop-loss that trails by that percent, or moves to break-even once the price has gone that percent your way
leverage, margin_modeApplied when the account has no position on that market; kept as they are otherwise
idYour alert's own id: the same id twice within 24 hours runs once
market_position, market_position_sizeThe strategy's position after this order (long, short or flat): see target mode
dry_runtrue: work out what the alert would do, place nothing

A few other common names are read as our markets too, each as name=market: XAUUSD=GOLD-USD / GOLD=GOLD-USD / XAGUSD=SILVER-USD / SILVER=SILVER-USD / USOIL=CL-USD / WTI=CL-USD / UKOIL=BRENTOIL-USD / SPX=SP500-USD / US500=SP500-USD / EURUSD=EUR-USD / XBT=BTC-USD / USDJPY=JPY-USD / USDCAD=CAD-USD / USDCHF=CHF-USD. A market we offer only in a scaled form (1000PEPE-USD for PEPE) is refused with symbol_scaled and the market to use, so a size is never off by a thousand.

Anything in the message that looks like a credential (another tool's token or licence, a key, a password) is masked before the message is kept in your log.

What each action does#

  • **buy, sell** open a position, sized from the link or the alert and rounded down to the market's size step. Their tp, sl, trail_pct and breakeven_pct become the order's exits, measured from the fill price.
  • **close, close_long, close_short** close the position, all of it or the part pct_position or size says; close_long does nothing on a short.
  • **flip** closes the position and opens the same size the other way.
  • **cancel, cancel_long, cancel_short** cancel your resting entry orders on that market (all of them, the buys or the sells). Exits stay.
  • **exits** replaces the position's exits with the message's tp, sl, trail_pct and breakeven_pct, measured from the entry price.
  • **flatten** closes every position on the account and cancels its orders.

An action with nothing to do is kept as skipped with its reason: no_position for a close when flat, for example.

Position modes#

What a buy or a sell does when a position is already open is the link's choice:

ModeSame side openOpposite side open
Ignore while in position (signal, the default)Skipped: already_in_positionClosed, then the new side opened
Add to the position (add)Added to itClosed, then the new side opened
Target position (target)Moved to market_position_sizeMoved to market_position_size

In target mode, each alert says where the position should be (market_position and market_position_size, which TradingView fills for a strategy as {{strategy.market_position}} and {{strategy.market_position_size}}), and the API buys or sells the difference. Sending the same alert twice changes nothing, so a missed or repeated alert never leaves you out of step with your strategy. An alert without those fields acts as in the default mode.

A reduce-only link never opens or adds: an opposite buy or sell only reduces the position, flip only closes it, and an alert that would open or add is refused with link_reduce_only.

Safety built in#

  • Only from TradingView. Alerts from any other address are refused.
  • One at a time. A link runs its alerts in the order they came. An alert that had to wait more than 10 seconds opens nothing (stale_signal); its closes still run.
  • Never twice. The same id within 24 hours, or the same message within 5 seconds, is kept as a duplicate and does nothing.
  • Rates. A link takes 30 alerts a minute and 300 an hour; all your links together, 60 a minute.
  • Every order is checked like an order from the API: the link's limits, the account's rules, the market's size step and price band.

Check what happened#

Every alert is kept in the link's log, in your dashboard and at GET /v1/tradingview/hooks/{hook_id}/alerts: the message as kept, how it was read, what it was to do and what each order did. Its status:

statusMeaning
placedEvery order was placed
partialSome were, some failed: results says which
skippedNothing to do (reason says why)
refusedNot run: reason says why, in a code and in words
failedAn order was refused when placed
duplicate, rate_limitedNot run: a repeat, or too many alerts
dry_runWorked out, nothing placed

Each alert that ran is also an event on your webhooks and the account stream: tradingview.alert_executed (placed, partly placed, or a dry run) or tradingview.alert_refused (refused or failed). When an alert is refused, fails or is only partly placed, we email you too, at most once per link every 6 hours.

To try a message before you trust it with real alerts, ask how it reads, with nothing sent:

POST /v1/tradingview/parse
{ "message": "buy BTC-USD qty 0.01 tp 2% sl 1%", "hook_id": "7Kx2mQ9pLr4A" }

The answer shows the action, sizes, prices, exits and market as read, and, with a hook_id (the link's id, as GET /v1/tradingview/hooks lists it, never its secret address), what the alert would do on that link's account right now. A sandbox link does the rest: point a test alert at it and watch the orders.

Guides, endpoints, fields and error codes.