How it works
Five steps connect your platform to a loyalty program your traders see inside your own portal. You send traders and their activity; we run the program and send the results back to you.
Register traders#
Every trader needs an account before activity can count. Choose one path.
Create User API
Call POST /v1/users from your backend when a trader signs up, with externalId set to your broker customer ID. Save the returned userId.
Registration webhook
Your backend calls the handshake URL we give you with your API key, reads data.sessionToken (valid for 300 seconds), then posts the registration to your workflow webhook URL with the x-session-token header.
{
"eventType": "user.registered",
"customerId": "<brokerCustomerId>",
"email": "trader@example.com",
"firstName": "Sample",
"lastName": "Trader",
"occurredAt": "2026-09-26T00:00:00Z"
}
Send activity#
Send what traders do on your platform, such as deposits and closed lots. Pick the channel that fits your data.
SQS queue
Send JSON batches to the queue we set up for you. An accepted send returns HTTP 200 and a MessageId: the batch is queued, then processed.
CSV files
Upload a file to the file ingest endpoint with your x-api-key header and the multipart fields data and metadata. The trigger_id query parameter names your trigger.
Read-only access
Give us read-only credentials and we pull the data ourselves: MT5 Web API or Manager API (Web API enabled and our IPs allowlisted), read-only access to your FXBO SQL database, or your data warehouse such as Databricks.
MetaTrader read-only guide- File ingest
- POST
https://data-workflow.returning.ai/ apis / v1/ data-workflows/ file-ingests? trigger_id= <triggerId> - Header
x-api-key- Multipart
datametadata
{
"trigger_id": "<triggerId>",
"metadata": {
"source": "broker-dwh",
"batch_id": "2026-09-26-009"
},
"data": [
{
"user_id": "<brokerCustomerId>",
"date": "2026-09-26",
"deposit_total": 2500.00,
"closed_lots": 14.25
}
]
}
We calculate coins, tiers and rewards#
The program rules you set in the dashboard turn each batch of activity into coins and XP, move traders through tiers, and unlock rewards in the store. There is nothing to host on your side.
Read the results at any time:
- POSTGet User Data returns a trader's
coins,xpand roles. - GETGet Tiers and XP Settings (
GET /v1/xp-settings/tiers-info) returns your tier configuration.
Show it in your portal#
Traders see their coins, tiers, milestones and store inside your portal through the Widget SDK.
Install the SDK:
npm install @returningai/widget-sdk.On your server, exchange your widget access key for a short-lived embed token. Send
accessId,accessKeyanduserIdentifiers; readdata.embedTokenanddata.expiresIn.- Embed token
- POST
https://api-v2.returning.ai / v2/ api/ widget-access-keys/ token
Pass only the token to the browser. Take the trader's identity from your signed-in session, never from browser input, and never send
accessKeyto the browser.
{
"accessId": "<ACCESS_ID>",
"accessKey": "<ACCESS_KEY>",
"userIdentifiers": {
"data-customer-id": "<brokerCustomerId>"
}
}
<rai-custom-widget
widget-id="<WIDGET_ID>"
embed-token="<EMBED_TOKEN>"
bundle-url="https://prod-widgets.returning.ai/custom-widget/bundle/milestones/widget.js"
domain-key="PROD"
theme="dark">
</rai-custom-widget>
Get the data back#
Every reward, purchase and tier change flows back to you: sent to your systems as it happens, synced to the tools you already use, or read through the API whenever you need it.
As it happens
We send each event to a URL on your side, so your systems can react straight away.
Outgoing webhooksIn your tools
Results are synced to the tools your team already uses.
Whenever you need it
Read a trader's balances and activity from your backend at any time.
API referenceRate limits#
Rate limits are set per community. Your success manager will confirm yours. A request over the limit returns 429 Too Many Requests; wait for the window to reset, then retry.