Crypto perpetuals

Prerequisites

• A Nyria Paper account, which is free on every plan. If you're new to Nyria, do the quick start first.
• An alert source that sends entry and exit alerts for longs and shorts. This guide uses TradingView, and any source in alert sources works the same way.

Long and short on a perpetual

A perpetual future follows the coin's spot price and never expires. You can hold a long or a short as long as you want. The cost of holding it is the funding rate, covered below.

You configure long and short separately on the strategy. The common setups are:

• Long and short entries both on, for a two-way strategy.
• One direction only, for example a long-only BTC momentum strategy.
• One direction's entry alert closing the other direction, using the Exit long position or Exit short position entry behavior. Use this when your alert source sends one flip alert instead of a separate close alert.

Exits arrive from your alert source as their own alerts. If you want a stop, your alert source has to send it.

Funding rate: the cost of holding

Funding is a payment between longs and shorts that keeps the perpetual's price close to spot. Binance settles it every 8 hours on most perpetuals. Other exchanges, Coinbase included, set their own schedule, so check the contract page.

• When the rate is positive, longs pay shorts. This is the usual case in a rising market.
• When the rate is negative, shorts pay longs. This happens most often in sharp sell-offs.
• Each payment is position_notional * funding_rate. For example, $100 notional at 0.01% funding costs $0.01 every 8 hours; three $100 entries held for a month cost about $2.70.

Funding is charged on the position size and taken from your margin. Nyria doesn't set aside a buffer for it. If funding pushes your margin below the maintenance level, the exchange liquidates the position.

Position sizing for perpetuals

A perpetual position has two sizes:

1. Notional exposure, the market value of the position (quantity * mark_price). It moves with the price.
2. Margin, the collateral the exchange holds against the position (notional / leverage). This is what you lose in a liquidation.

The bot's budget sets the notional. Each entry buys budget ÷ price of the coin. The strategy's leverage does not change the quantity. On an exchange it only sets how much margin is held. Nyria Paper holds no margin and never liquidates. The strategy's record is the exception: it states each return at the strategy's leverage, capped at -100% of the entry.

Worked example (BTC at $64,000, 5x leverage, $100 budget per entry):

• Quantity: $100 / $64,000 ≈ 0.00156 BTC.
• Notional exposure: $100.
• Margin an exchange would hold at 5x: $20.
• Approximate distance to liquidation: a 20% move against you, minus fees and the exchange's maintenance margin. The exchange shows the exact liquidation price after the order fills.

Raising leverage buys the same quantity with less margin behind it, so the liquidation price moves closer. On a $100 position, going from 5x to 10x cuts the margin from $20 to $10 and the buffer from about 20% to about 10%. Funding is charged on the notional, so it costs the same in dollars, but it eats twice the share of your margin.

Margin warnings

• Insufficient margin. The order needs more margin than the account has free after its open positions. The rejection appears in your bot logs with the exchange's reason. Nyria drops the order and doesn't retry the alert.
• Auto-deleveraging (ADL). If the exchange's insurance fund can't cover a liquidation, the exchange closes profitable positions on the other side at the bankruptcy price. It is rare, but it has happened on Binance perpetuals in extreme markets.
• Maintenance margin tiers. Both exchanges raise the maintenance margin as the notional grows. If repeated entries push a position into a higher tier, its liquidation price gets worse than the first entry suggested. Check the exchange's tier table before you scale in.

Step 1: Decide the contract before you create the strategy

Start with one pair. A strategy can trade several, but one pair is easier to debug.

Write down these values before you start:

Step 2: Create the strategy in Nyria

Step 3: Check the alert format

Give Nyria a sample alert for each direction you turned on, so you can confirm it reads the symbol and direction the way you intend.

Sample long entry (JSON payload):

{
  "ticker": "BTCUSDT",
  "action": "buy",
  "direction": "long"
}

Sample short entry (JSON payload):

{
  "ticker": "BTCUSDT",
  "action": "sell",
  "direction": "short"
}

Sample long exit (JSON payload):

{
  "ticker": "BTCUSDT",
  "action": "exit",
  "direction": "long"
}

Sample short exit (JSON payload):

{
  "ticker": "BTCUSDT",
  "action": "exit",
  "direction": "short"
}

For every payload field, see the webhook reference.

Step 4: Connect the alert source

Start from this Pine Script template. Each order it places sends its comment, which holds one of the JSON payloads above, as the alert message. Replace the longCondition and shortCondition lines with your own entry logic. Keep the strategy.entry and strategy.close lines, since they carry the JSON.

//@version=5
strategy("Nyria Perp Long/Short Template", overlay=true)

// --- your entry logic goes here ---
longCondition = ta.crossover(ta.sma(close, 9), ta.sma(close, 21))
shortCondition = ta.crossunder(ta.sma(close, 9), ta.sma(close, 21))

if longCondition
    strategy.close("short", comment='{"ticker":"BTCUSDT","action":"exit","direction":"short"}')
    strategy.entry("long",  strategy.long,  comment='{"ticker":"BTCUSDT","action":"buy","direction":"long"}')

if shortCondition
    strategy.close("long",  comment='{"ticker":"BTCUSDT","action":"exit","direction":"long"}')
    strategy.entry("short", strategy.short, comment='{"ticker":"BTCUSDT","action":"sell","direction":"short"}')

// In your TradingView alert: set "Message" to {{strategy.order.comment}}
// and tick "Webhook URL" in Notifications, with your strategy's https://trades.nyria.io/webhooks/... URL.

To set it up:

1. Paste it into the Pine editor and select Add to chart.
2. Select Alert on the top toolbar and set Condition to your strategy. In the second dropdown under it, choose Order fills only. Open Message, set it to {{strategy.order.comment}} and select Apply. Open Notifications, tick Webhook URL, paste your Nyria webhook URL and select Apply.
3. Select Create. From then on, TradingView posts the JSON from comment each time the script calls strategy.entry or strategy.close.

To send the same alert without TradingView, use curl:

curl -X POST https://trades.nyria.io/webhooks/REPLACE_WITH_YOUR_STRATEGY_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"ticker":"BTCUSDT","action":"buy","direction":"long"}'

Replace REPLACE_WITH_YOUR_STRATEGY_TOKEN with the token from your strategy's Integration tab.

Step 5: Deploy a bot on Nyria Paper

Step 6: Watch the first round trip

When your first alert reaches the webhook, two logs update. The strategy log, visible only to the strategy's owner, shows how Nyria read the alert. The bot log shows how your bot sized the order and what the broker did with it.

Keep both open for the first entry. These are the usual problems on a first run:

Common pitfalls

• Treating the budget as margin. The budget is the position's notional. A $1,000 budget opens about $1,000 of the coin at any leverage, and at 10x the exchange holds $100 of margin against it. If you want $1,000 of margin at 10x, that's $10,000 of notional, so set the budget to $10,000.
• Forgetting that each entry adds a full budget. Three $100 entries are $300 of notional at any leverage. On an exchange each entry also needs its own margin, and when the free collateral runs out the exchange rejects the next one.
• Ignoring funding on long holds. At 0.01% per 8-hour window, which is Binance's baseline rate, a long pays about 0.03% of notional a day, or about 0.9% a month. At 10x the margin is a tenth of the notional, so that is about 9% of the margin lost to funding alone, before any price move. Nyria Paper charges no funding.
• Expecting an exit alert to close a single entry. Nyria closes by direction. After three long entries, one long exit alert closes all three. A quantity on a CLOSE alert doesn't trim the position, because the webhook has no partial-close field. See the webhook reference.
• Changing leverage on an open position. A new leverage value on the strategy doesn't affect positions that are already open. On Nyria Paper, leverage never changes a bot's position size.

Next steps

• Bots: multiple entries, budget modes and pausing
• Trading behavior: every entry, exit and flip setting
• Risk disclosure: read it before you trade live
• Webhook reference: every field Nyria reads