JavaScript SDK

fynxt-referral-v1.js is the browser SDK for the FYNXT Incentive Program. It exposes a global FynxtReferral object that automatically captures referral context from inbound URLs, persists it in cookies, and forwards client-side conversion events to the FYNXT API — which then fans them out as postbacks to your downstream systems.

Install

Drop the script tag into every page where you want to report conversions. The SDK is served from FYNXT servers and has no dependencies.

<script src="https://fynxt-incentive-program-referral-links-sdk.s3.ap-south-1.amazonaws.com/fynxt-referral-v1.js"></script>

The script exposes window.FynxtReferral. There is no npm package — use the script tag on every page that needs tracking (sign-up, funding, KYC, etc.).

FynxtReferral.init(config)

Call once per page load, immediately after the script tag and before any call to trackEvent. On initialisation the SDK automatically reads program-id, partner-id, and click-id from the current URL's query string and stores them in cookies (with localStorage as a fallback). If a program-id is found, a REFERRAL_INITIATED event is fired automatically.

<script>
  FynxtReferral.init({
    apiKey: "YOUR_API_KEY"
  });
</script>

apiKey

string

required

The API key issued to your brand by FYNXT. Sent as the X-API-Key header on every tracking request. Contact FYNXT to obtain your API key.

cookieExpiryDays

number

optional

How long the referral cookies (program-id, partner-id, click-id) persist. Defaults to 30 days.

apiEndpoint

string

optional

Override the default API endpoint. Useful for staging environments. Defaults to the FYNXT production URL.

FynxtReferral.trackEvent(eventType, data)

Reports a single conversion event. The SDK automatically attaches the stored clickId, programId, and partnerId from cookies to every request — you do not need to read or pass these values yourself.

eventType

string

required

One of the supported event types — EMAIL_SIGNUP, REGISTRATION, FIRST_DEPOSIT, and so on.

data

object

optional

Event-specific context. Supported keys:

email — string. User's email address. Passed to the backend to identify or create a trader profile.
name — string. User's full name. Used alongside email when creating a new trader profile.
amount — number. Monetary value for deposit or withdrawal events.
currency — string. 3-letter ISO currency code for amount.
paymentMethod — string. e.g. "card", "wire", "crypto".

Returns a Promise. The SDK never throws — network and API errors are logged via console.warn so a failed beacon cannot break your page.

Missing API key? If init was not called (or apiKey was empty), trackEvent will still fire the request and log a warning to the console. The request will be rejected by the API.

Event types

The eventType argument to trackEvent must be one of the values below. Any other value will be rejected.

Event	When to fire	Typical options
`EMAIL_SIGNUP`	Visitor submits their email address on the first step of sign-up, before a full account exists.	`email`
`DEMO_ACCOUNT_CREATION`	Visitor opens a demo / paper-trading account.	`email`, `metadata`
`REGISTRATION`	Full registration form submitted successfully — a live client record now exists.	`email`
`VERIFICATION`	Email or phone verification completed (pre-KYC identity check).	`email`, `metadata`
`FIRST_DEPOSIT`	First funding transaction settles on the live account.	`amount`, `currency`, `paymentMethod`
`RECURRING_DEPOSIT`	Any subsequent deposit after the first one.	`amount`, `currency`, `paymentMethod`
`FIRST_TRADE`	First trade executes on the live account.	`metadata`
`KYC_COMPLETED`	KYC review passes and the client is fully approved.	`email`, `metadata`
`WITHDRAWAL`	Withdrawal request is processed.	`amount`, `currency`, `paymentMethod`
`ACCOUNT_UPGRADE`	Client moves to a higher-tier account (e.g. Standard → Pro ECN).	`metadata`
`SUBSCRIPTION`	Client subscribes to a paid product or service plan.	`amount`, `currency`, `metadata`
`CUSTOM`	Any conversion not covered above. Describe the event via `metadata.name`.	`metadata`
`CONTENT_DOWNLOAD`	Visitor downloads gated content (e-book, report, whitepaper, platform installer).	`email`, `metadata`
`WEBINAR_REGISTRATION`	Visitor registers for a webinar or live event.	`email`, `metadata`
`NEWSLETTER_SUBSCRIPTION`	Visitor opts in to marketing emails / newsletter.	`email`

Configuration reference

Option	Default	Description
`apiKey`	`""`	Brand API key issued by FYNXT. Required.
`cookieExpiryDays`	`30`	Days before referral cookies expire.
`apiEndpoint`	FYNXT production URL	Override for staging or custom deployments.

Server-side alternative. If you prefer zero client-side JS — or if you are reporting events from a backend system — skip the SDK and call POST /api/referral/events/track directly with the X-API-Key header and the clickId captured from the referral redirect URL.

← Previous

Postback introduction

REST API reference