Referral Links · Overview

Track where your traders actually come from.

A referral link is a deep-linked bot URL that encodes a campaign, channel, or partner. When a trader taps it, Trading Layer records first-touch attribution and keeps it attached to every downstream webhook — so your analytics know exactly which source drove every signal execution.

Manage referral links Deep-link format

Why it exists

What is a referral link?

You run a bot. Traders arrive from many places — YouTube reviews, your Telegram channel, affiliate posts, paid ads. A referral link is the shared vocabulary between those sources and Trading Layer's dashboard. One link per source, attached to every trader that opens the bot through it.

One link per source.

Create a link in the dashboard, share its URL, and every trader who taps it is credited to that source on first touch.

Works with a plain Telegram URL.

No tracking pixels, no JS. Just the Telegram deep-link with a ref_XXX token in the start parameter.

Routes through your webhooks.

Every trader and signal event carries referralLinkId so your downstream systems can partition on source.

What's inside

Anatomy of a referral link.

Each link is a small record on the tenant. These fields are set once on the dashboard when you create the link; everything else — attribution, UTM passthrough, event tagging — flows from them.

Internal name: A human-readable label only you see — e.g. 'Q2 YouTube mid-roll'. Never sent to users.
Start payload: The ref_XXX token embedded in the Telegram start parameter. Generated by Trading Layer when the link is created — tenants don't pick it and can't edit it. It uniquely identifies the link at attribution time. See Deep-link format for the exact format.
Destination: Where the link points: straight to your Telegram bot, or a landing page that hands off to the bot. Set on the dashboard.
UTM parameters: Optional utm_source, utm_medium, utm_campaign, utm_term, and utm_content. If you chose a landing-page destination, we append these to the base URL.
Partner code: An optional identifier for the partner / affiliate that owns the link. Useful for reporting by source but has no effect on bot routing.
Status: Either 'active' or archived. Archived links stop accepting new attributions; existing attributions are preserved.

First touch wins

Attribution model.

Attribution is set the first time a trader opens the bot with a matching start payload, and it stays with that trader forever. Later /start links don't overwrite it.

RegEx

The attribution matcher

pattern · /regex/

/^ref_[A-Za-z0-9]{20}(?:_cid[A-Za-z0-9_-]+)?/

The bot only accepts referral payloads that start with our fixed ref_ token. The first 24 characters identify the referral link. If the payload continues with _cid, everything after that marker is stored as Click ID. See Deep-link format for the full rules, examples, and pitfalls.

01
Trader taps the deep link
Telegram opens the bot with the start payload intact, for example ref_03f1500eece04bf9ab5a_cidJOPAPETUHA.
02
The bot parses the fixed prefix
The first 24 characters are looked up in active referral links. If _cid is present, the suffix after it is stored as Click ID.
03
Attribution is pinned first-touch
If the same trader later opens the bot with a different referral link, the attribution row isn't changed. The latest raw payload and latest Click ID are still saved on trader metadata.
04
All later events carry the link id
Every trader-scoped webhook can send the attributed referralLinkId, raw start payload, Click ID, and referral UTM fields when those params are configured.

Why first-touch?

First-touch keeps reporting deterministic: the first campaign to land a trader gets the lifetime credit, and your partner payouts don't shift when the same trader clicks a later campaign. If you need last-touch semantics, configure webhook params for latestStartPayload and latestClickId.

Where attribution shows up

Referrals in webhooks.

Most trader and signal events can be filtered by referral link on an individual endpoint. When filtered, only deliveries whose attributed link matches your filter are sent.

trader.startedCarries referralLinkId and referralAttributed from the very first contact.
trader.onboardedPreserves the original attribution as the trader completes onboarding.
trader.mt5_connectedSame attribution as when the trader first started.
signal.action.executedAttribution is sticky per trader, so signal actions route to the source too.

For the complete event list, see the Webhooks · Event types reference. Events marked referral-filterable pick up attribution automatically.

dataexcerpt from a trader.started delivery

{
  "traderId": "1c027951-63bf-4df0-bcfd-4e47377914b6",
  "telegramId": 1880622198,
  "referralLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "referralAttributed": true,
  "rawStartPayload": "ref_03f1500eece04bf9ab5a_cidJOPAPETUHA",
  "clickId": "JOPAPETUHA"
}

The first 24 characters of rawStartPayload are the token we generated (ref_03f1500eece04bf9ab5a). If the next characters are _cid, the remaining suffix is parsed and stored as Click ID.

Housekeeping

Lifecycle and status.

Links have a simple two-state lifecycle. Archived links preserve history but stop accepting new attributions.

Active

Default state. Appears in the dashboard dropdowns, can be shared publicly, and accepts new attributions.

Archived

Hidden from picker UIs and ignored by attribution parsing. Existing trader attributions remain intact — your historical reporting is unaffected.

PreviousSignature verification NextDeep-link format

{ "traderId": "1c027951-63bf-4df0-bcfd-4e47377914b6", "telegramId": 1880622198, "referralLinkId": "550e8400-e29b-41d4-a716-446655440000", "referralAttributed": true, "rawStartPayload": "ref_03f1500eece04bf9ab5a_cidJOPAPETUHA", "clickId": "JOPAPETUHA" }