Spectr3 - Affiliate Documentation

Overview

This documentation describes the affiliate tracking and postback data currently sent by the platform. Affiliates do not need a portal login. They provide a tracking click id and a postback URL, then receive JSON postbacks when supported user events are recorded.

Email registration, social registration, and wallet-created accounts use the same affiliate attribution flow when the user arrives through an affiliate tracking link.

Tracking link

Each affiliate receives a unique affiliate code. Traffic should be sent to the tracking URL with a required click_id query parameter.

GET https://spectr3.io/r/{AFFILIATE_CODE}?click_id={CLICK_ID}

The click_id is the affiliate network or partner identifier that will be returned in later postbacks. It must be a string and may be up to 255 characters.

Attribution window

When a valid tracking link is opened, the platform stores an encrypted first-party attribution cookie for 90 days. If the visitor creates an account during that window, the account is linked to the affiliate and click id.

The current implementation creates one attribution record per user. If a user is already attributed, later affiliate clicks do not overwrite that attribution.

Postback delivery

Postbacks are sent as JSON over HTTP POST to the affiliate postback URL configured in the admin panel. A 2xx HTTP response is treated as successful delivery.

POST https://affiliate.example/postback
Content-Type: application/json
Accept: application/json

Registration event

The registration event is queued when an attributed user account is created. This includes standard email registration and wallet-created accounts.

{
  "click_id": "partner-click-123",
  "event": "registration",
  "user_id": 2451,
  "reference_id": "2451",
  "timestamp": "2026-06-09T12:30:00+00:00",
  "signature": "optional_hmac_sha256_signature"
}

Deposit event

The deposit event is queued for each successful deposit made by an attributed user. The amount field is the net amount credited to the user balance after any crypto payment or gateway deductions handled by the platform.

{
  "deposit_id": 784,
  "trx": "DEP123456789",
  "method_name": "USDT",
  "method_currency": "USDT",
  "click_id": "partner-click-123",
  "event": "deposit",
  "user_id": 2451,
  "reference_id": "784",
  "timestamp": "2026-06-09T12:30:30+00:00",
  "amount": 100,
  "currency": "USD",
  "signature": "optional_hmac_sha256_signature"
}

Fill events

Fill events are queued only when a user position is actually matched. Opening an unmatched order does not create an affiliate postback. The platform charges a 1% tax per trade side, and the payload includes the tax applied to that user side.

{
  "market_id": 87,
  "outcome_name": "YES",
  "action": "BUY",
  "origin": "OPEN_ORDER_PURCHASE",
  "price": 0.56,
  "quantity": 100,
  "notional_amount": 56,
  "tax": 0.56,
  "amount_spent": 56.56,
  "market_title": "Will Example FC win?",
  "created_at": "2026-06-09 12:30:00",
  "click_id": "partner-click-123",
  "event": "fill_buy_order",
  "user_id": 2451,
  "currency": "USD",
  "reference_id": "market-log-98765",
  "timestamp": "2026-06-09T12:31:00+00:00",
  "signature": "optional_hmac_sha256_signature"
}

{
  "market_id": 87,
  "outcome_name": "YES",
  "action": "SELL",
  "origin": "FILLED_ORDER",
  "price": 0.56,
  "quantity": 100,
  "notional_amount": 56,
  "tax": 0.56,
  "amount_received": 55.44,
  "market_title": "Will Example FC win?",
  "created_at": "2026-06-09 12:30:00",
  "click_id": "partner-click-123",
  "event": "fill_sell_order",
  "user_id": 2451,
  "currency": "USD",
  "reference_id": "market-log-98766",
  "timestamp": "2026-06-09T12:31:00+00:00",
  "signature": "optional_hmac_sha256_signature"
}

Signature

If an affiliate secret is configured, the platform includes a signature field. The signature is an HMAC SHA-256 hash of the JSON payload before the signature field is added, using the affiliate secret as the key.

signature = HMAC_SHA256(
  json_encode(payload_without_signature, JSON_UNESCAPED_SLASHES),
  affiliate_secret
)

Affiliates should recompute the signature on their side and compare it before trusting the postback.

Retries and statuses

Postbacks are attempted up to three times. Retry delays are 60 seconds, 300 seconds, and 900 seconds. Failed responses store the HTTP status code and a shortened error message for admin review.

pending: The postback is waiting to be sent.
processing: The postback is being sent.
sent: The affiliate endpoint returned a successful 2xx response.
failed: The request failed, timed out, or returned a non-2xx response.

What affiliates provide

A postback URL that accepts JSON POST requests.
A click id macro or generated click id to pass as click_id on the tracking link.
An optional shared secret if signed postbacks are required.
A 2xx HTTP response for successful postback processing.

Important notes

The platform currently sends registration, deposit, fill_buy_order, and fill_sell_order postbacks.
Postback payloads may include null values when a field does not apply to the event.
The same affiliate attribution flow applies to wallet-created users, email registrations, and social registrations.
Affiliates should treat reference_id as the idempotency key together with the event name.