JavaScript SDK

fynxt-referral.js is the browser SDK for the FYNXT Incentive Program. It exposes a global FynxtReferral object that 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.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, immediately after the script tag, before any call to trackEvent.

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

brokerId

string

required

The broker identifier issued to your brand by FYNXT. Scopes every event to your brokerage so conversions are attributed correctly. Contact FYNXT to obtain the broker ID specific to your brokerage — the placeholder YOUR_BROKER_ID in these snippets must be replaced before the SDK will work.

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 alongside the broker ID.

FynxtReferral.trackEvent(eventType, options)

Reports a single conversion event. Your page is responsible for capturing clientId and sessionId from the inbound referral URL (or your own backend) and passing them in on every call — the SDK does not read them from sessionStorage, cookies, or the URL.

eventType

string

required

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

options

object

optional

Event-specific context. Supported keys:

clientId — string. The FYNXT client ID (returned from POST /ib/client). Required for every event so it can be attributed to the correct user.
sessionId — string. The session identifier captured from the sessionId query parameter on the inbound referral URL. Written into metadata.session.
amount — number. Monetary value for deposit events. Defaults to null.
currency — 3-letter ISO code. Defaults to null.
email — string. User's email. Written into metadata.email.
source — string. Identifier for the surface reporting the event (e.g. "zenithfx_web", "zenithfx_mobile", "partner_portal"), written into metadata.source. Defaults to "zenithfx_web".
paymentMethod — string. e.g. "card", "wire", "crypto".
metadata — object. Free-form keys merged into the metadata envelope.

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 "The API Key is missing." 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
`brokerId`	`""`	Broker identifier issued by FYNXT. Required.
`apiKey`	`""`	Brand API key. Required.

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 /referral/events/track directly with the X-API-KEY header and the clientId and sessionId you captured from the referral URL.

← Previous

Postback introduction

REST API reference