Skip to main content
Version: v2

Affiliate & Referral

How orders and quotes are attributed to your partner account, and how partner economics (revenue share, dynamic markup) are applied.

What attribution does​

Attaching your referral identity to a request:

  • credits the order to your account for revenue share,
  • applies your commercial terms (rate TTLs, markup/fees agreed for your integration),
  • makes the order visible in your partner reporting.

The mechanisms​

Full mechanics live in Authentication; in short, attribution is accepted via the x-referral-token header (preferred server-side), the ?ref= link parameter (widget/browser flows), the referral_code body field on order endpoints, or the session. With API-key auth, the referral code must belong to the key's owner.

Referral code formats in ?ref=​

Referral links in the wild carry one of several formats in the ref parameter:

FormatLooks likeMeaning
Plain code?ref=partner123Your referral code used directly
Legacy (v1) link codeolder short codes issued by v1Still accepted; resolved to your account's code
Encoded (v2) tokenlong URL-safe blobCarries the full referral context, including mode-scoped codes

Anything that doesn't parse as one of these is ignored — the order is still created, just without attribution. If attribution matters (it always does), verify your links resolve by checking the order shows up in your partner reporting, and prefer passing the explicit x-referral-token header in server-side flows where you control the request.

Per-mode referral codes​

A partner account can hold separate referral codes per trading mode — e.g. CeFi, CeFi fixed-rate, and DeFi. Consequences:

  • Use the code (and matching API key) for the mode you're operating; a DeFi-scoped code does not attribute CeFi orders and vice versa.
  • An encoded v2 link may contain codes for some modes only. If your integration spans several modes, confirm with your account manager that codes exist for each one, and configure each mode's token explicitly rather than deriving one from another.

Dynamic markup​

Partners with the dynamic-fee capability can adjust their per-request fee:

FieldWhereFormat
markupGET /rate/ query, POST /orders/ bodyinteger basis points, 0–10000 (50 = 0.5%) — preferred
referral_ratesamedeprecated decimal fraction ("0.005")

Rules:

  • The capability must be pre-enabled on your referral code — contact your account manager.
  • Sending both markup and referral_rate in one request → 400.
  • Your account has a partner cap; requested fees above the cap are not applied in full — the excess is split 50-50.
  • The fee actually applied is echoed back as applied_referral_rate (decimal) on rate rows and order responses — always reconcile against it rather than assuming the requested value.
Quote with a 0.75% partner markup
curl -X GET "https://api.n.exchange/en/api/v2/rate/?pairs=BTCETH&markup=75" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "x-referral-token: YOUR_REFERRAL_TOKEN"

Reporting​

Partner reporting is provided via your account manager (periodic CSV exports with the fields you need). For real-time needs, track your own orders by unique_reference — see Order Tracking and Webhooks.

Next steps​