Signal automation: publishing through the Provider API and Telegram

Before you start

What signal automation does

Instead of typing every signal into the composer, your own system publishes it into Sigrah through an API key. The signal that arrives is a completely normal Sigrah signal: your followers see it, copy-trade bots evaluate it, and every rule that applies to a hand-written signal applies to it too.

Which plans have it

Signal automation is a Level 3 and Level 4 capability. Level 3 providers can publish up to 30 automated signals in each monthly cycle; Level 4 is unlimited. Levels 1 and 2 see the cards in Professional tools with the level they unlock at.

Tip: Only signals that are actually accepted and published count toward the monthly quota. Rejected requests, validation errors and duplicates cost nothing.

Where to find it

Open Professional tools in your provider panel. The Signal API card manages your keys and shows your automation quota for the current cycle; the Telegram card describes the upcoming channel integration.

Your API key

Create a key

On the Signal API card choose a name and create a key. The full key is shown exactly once, in that moment. Copy it into your system's secret storage right away — Sigrah keeps only a fingerprint and can never show it again.

Important: Treat the key like a password. Anyone holding it can publish signals as you. If it ever leaks, contact support to disable it and create a new one.

How to send it

Every request carries the key in a header: either x-sigrah-provider-key with the key as the value, or a standard Authorization header as Bearer followed by the key.

Publishing a signal

The endpoint

Send an HTTP POST to https://api.sigrah.ir/api/v1/provider-api/signals with a JSON body and your key header. A GET to https://api.sigrah.ir/api/v1/provider-api/status with the same header returns your plan, quota and remaining count, which is the easiest first call to test a new key.

The signal body

The JSON fields are the composer’s own. Required: externalSignalId (your unique id, up to 120 characters), pair, action (BUY or SELL), entryPrice and riskLevel (LOW, MEDIUM or HIGH). Optional: orderType (MARKET by default, or LIMIT, STOP, STOP_LIMIT), stopLimitPrice (required for STOP_LIMIT), expiresAt (a future ISO date, for a pending order), stopLossLevels and takeProfitLevels, stopLoss and takeProfit, timeframe (M1, M5, M15, M30, H1, H4, D1 or W1), suggestedLot, audienceType (PUBLIC or VIP), copyTradeEnabled and note (up to 2000 characters).

Tip: There is no riskPercent field any more. The signal carries a declared risk LEVEL — LOW, MEDIUM or HIGH — and that is what subscribers filter on. A request that still sends riskPercent is accepted; the field is simply ignored.

The exit plan

stopLossLevels and takeProfitLevels are the exit plan. Each takes up to three levels, and each level is a price and a closePercent — the share of the position it closes.

• closePercent is above 0 and at most 100, with two decimals, and each ladder totals exactly 100: 33.33, 33.33 and 33.34 pass; 99.99 and 100.01 are refused.
• On a BUY every stop is below entryPrice and every target above it; on a SELL, the reverse. A price equal to entry is refused.
• Send levels in any order. Each ladder is stored nearest to entry first, so level 1 is the nearest. Two levels at one price are refused.
• stopLoss and takeProfit are optional. Sent alone, each is one level closing 100%. Sent beside a ladder, it must equal one of that ladder’s prices — normally level 1 — or the request is refused. Sending the ladders only is simplest.
• In copy trade each level closes its share of the copied position when price reaches it. The broker holds the farthest stop for whatever is left, and a subscriber who sizes by risk percent is sized against that farthest stop.

A complete request

A BUY with three stops and three targets, each ladder totalling 100:

{"externalSignalId": "my-system-2026-000123", "pair": "EURUSD", "action": "BUY", "orderType": "MARKET", "entryPrice": 1.0850, "stopLossLevels": [{"price": 1.0830, "closePercent": 50}, {"price": 1.0815, "closePercent": 30}, {"price": 1.0800, "closePercent": 20}], "takeProfitLevels": [{"price": 1.0900, "closePercent": 50}, {"price": 1.0950, "closePercent": 30}, {"price": 1.1000, "closePercent": 20}], "riskLevel": "MEDIUM", "timeframe": "H1", "note": "London session breakout"}

The same request, ready to send, is on the Signal API card in Professional tools. Replace every value with your own before you send it.

Safe retries

externalSignalId is what makes retries safe. If your request times out and you send it again with the same externalSignalId, Sigrah recognises it, returns the original signal with idempotent set to true, and charges nothing twice. Never generate a fresh id for a retry of the same signal.

Careful: A brand-new externalSignalId for the same pair, direction, order type and entry within 90 seconds is treated as an accidental duplicate and refused with status 409 and SIGNAL_PUBLISH_DUPLICATE — that protection exists so a bug in your system cannot flood your followers.

What comes back

A successful publish answers with accepted true, the new signalId, and your quota standing after the publish: the limit, how many are used, and how many remain in the cycle. The signal itself appears in your Signals area marked with its API origin.

Closing and adjusting

A signal you published through the API is managed through it too. POST to https://api.sigrah.ir/api/v1/provider-api/signals/:reference/commands, where :reference is your own externalSignalId — or the Sigrah signal id — with an action in the body:

• FULL_CLOSE closes everything still open.
• PARTIAL_CLOSE with closePercent (above 0, at most 100) closes that share of what is still open; closeVolume closes a volume instead.
• MODIFY_STOP_LOSS with stopLoss, or MODIFY_TAKE_PROFIT with takeProfit, replaces that side’s whole ladder with one level for what is still open; null removes it. A new stop must stay on the losing side of entry — at entry (breakeven) or beyond is refused.
• MODIFY_PENDING_PRICE with entryPrice moves a pending order that has not filled; it is refused if a stored stop or target would end up on the wrong side of the new entry. CANCEL_PENDING withdraws one.
• A ladder cannot be changed after publish: a command that carries stopLossLevels or takeProfitLevels is refused. Close the signal and publish again.
• The levels you published close on their own on copied positions. Do not send a PARTIAL_CLOSE for one of them, or that share closes twice.

The vocabulary is the composer’s own, so your system and your hands ask for exactly the same things. Send an idempotencyKey (12 to 180 characters) and a retry replays the command instead of running it twice.

Tip: These commands are never metered and never blocked by your plan standing. A spent quota or a lapsed level must not be able to hold a real position open — only opening new exposure is charged.

Quota and rate limits

The monthly quota

The monthly quota counts accepted publishes only, across every automation source together. When the cycle's quota is exhausted, new publishes are refused with status 403 and code AUTOMATION_QUOTA_EXHAUSTED until the cycle renews — retries of already-accepted signals still succeed.

The technical rate limit

Separately from the quota, the API has a technical requests-per-minute ceiling that protects the infrastructure from bursts. Hitting it answers 429 with a retry-after header; wait and resend. A 429 never consumes quota and never creates a signal.

Tip: Publish when you have a signal, not on a polling loop. Normal automated publishing never comes near the ceiling.

Reading a rejection

Every refusal is JSON: { code, message, details }. A 400 means nothing was published:

• VALIDATION_FAILED — details.fields names the fields that are missing or malformed, such as riskLevel or stopLossLevels.0.closePercent.
• EXIT_CLOSE_SUM_INCOMPLETE or EXIT_CLOSE_SUM_EXCEEDED — a ladder totals under or over 100; details.field names it and details.total gives its total.
• STOP_LOSS_LEVEL_ON_WRONG_SIDE or TAKE_PROFIT_LEVEL_ON_WRONG_SIDE — a level is on the wrong side of entry; details.field, details.level (numbered as you sent them), details.price and details.entryPrice say which. A single stopLoss or takeProfit on the wrong side answers SIGNAL_STOP_LOSS_WRONG_SIDE or SIGNAL_TAKE_PROFIT_WRONG_SIDE.
• EXIT_LEVEL_PRICE_DUPLICATE — two levels of one ladder share a price (details.field, details.price).
• EXIT_SINGLE_PRICE_NOT_IN_LADDER — stopLoss or takeProfit matches none of its ladder’s prices (details.field, details.price).

401 means the key is missing or not recognised. 403 is either a plan without automation or an exhausted quota — the code says which. 409 SIGNAL_PUBLISH_DUPLICATE is the duplicate window, with details.signalId. None of these consume quota.

Telegram channels — coming soon

What it will be

Soon you will be able to connect your own Telegram channel or group to Sigrah. A signal you post there in the Sigrah format is published to your followers exactly as one typed into the composer, and it counts against the same automation quota as the API. The channel is not only for opening trades: the same place closes one, all of it or part, moves a stop loss or a take profit, and cancels a pending order — so a provider who works from their phone never has to open the panel mid-trade.

How connecting will work

You will mint a one-time verification code in Professional tools, add the Sigrah bot to your channel, and post the code there. Ownership is proven inside your own channel — nobody can attach a channel they do not control.

The message format

A message is read only when a Sigrah header sits in its first three lines: SIGRAH SIGNAL to open a position, SIGRAH CLOSE to close all or part of one, SIGRAH MODIFY to move a stop or a target, SIGRAH CANCEL to drop a pending order. Their Persian words — سیگراه سیگنال، بستن، اصلاح، لغو — work the same. Under the header write one item per line: PAIR, ACTION, ENTRY and RISK are required; TYPE, SL, TP, TIMEFRAME, NOTE and REF are optional; a RISK% line is read and ignored. A stop is either one SL, which closes the whole position, or a ladder — SL1: 1.0800 50%, SL2: 1.0780 30%, SL3: 1.0760 20% — or the same on one line: SL: 1.0800 50% / 1.0780 30% / 1.0760 20%. Targets work the same way with TP and TP1 to TP3. In a ladder every step states its percentage, from 1 to 100, and they total exactly 100. Persian key names (نماد، جهت، قیمت ورود، حد ضرر، حد سود، ریسک، شناسه) are read too — a step number may be a Latin or a Persian digit, as in حد سود 1 or حد سود ۱ — as are Persian digits in values, bold and emoji, and a chart posted with the instruction as its caption. Copy the sample in the panel and replace every value before you post.

Tip: Lines that are not instructions — a chart link, a signature, a greeting — are skipped rather than fatal; put comments on a NOTE line, because a line that starts with a key word (stop, target, profit, SL, TP, type) is read as an instruction. A post is refused instead when a key repeats or sits one letter away from a real one, such as SLL for SL, because skipping that would publish a position with no stop loss; and when a ladder’s percentages are missing or do not total 100, because how much of a trade comes off where is the provider’s call, not the machine’s. A refused post publishes nothing: the bot tells you why in a private message, in your language, and your recent attempts are listed in the provider panel.

Closing and changing from the channel

A close, modify or cancel names its signal by replying to the signal post — whether or not that post had a REF — by the same REF, or by the pair while only one signal is open on it. SIGRAH CLOSE closes PERCENT of what is still open; 100, or no percentage, closes all of it. SIGRAH MODIFY takes one price per side: SL or TP replaces that side’s whole ladder with one level for what is still open, and NONE — or حذف — removes it. A new stop must stay on the losing side of entry; moving it to entry or beyond is refused. ENTRY moves a pending order and SIGRAH CANCEL withdraws one. None of these costs quota.

Careful: Levels you published close on their own on copied positions — do not close one again by hand, or that share comes off twice. A ladder cannot be changed after publishing: close the signal and publish a new one.

When something is off

The key stopped working

A 401 on every request means the key is not what Sigrah has: re-check for whitespace or truncation from your secret storage. If the key is right and still refused, it may have been disabled — check the Signal API card for your active keys.

The signal did not appear

If the publish answered accepted true, the signal exists — open your Signals area and look for the API origin mark. If the answer was anything else, the response body says exactly why; the same reason is recorded in your integration history for support.