Broker Integrations
Returning.AI integrations have two jobs: identify the trader securely when the widget opens, then keep the loyalty engine fed with the broker events and trading facts that drive rewards.
Recommended baseline
Use Widget SDK + Access Key for the portal experience, Workflow Webhooks for identity and lifecycle events, and SQS/data-ingest for trading facts, aggregates, tier snapshots, and backfills. Read-only DB or API pull is a fallback only when the broker cannot push data.
Source of truth model
| Layer | Owns | Typical key |
|---|---|---|
| Broker portal / CRM | Trader identity, account state, KYC, deposit status | customer_id |
| Trading platform | MT4/MT5 login, deals, lots, symbols, PnL, account groups | trading_account_id / login |
| Returning.AI | Rewards, tiers, missions, coins, redemptions, widget state | returning_user_id plus broker identifiers |
Integration options
| Path | Use when | Timing | Notes |
|---|---|---|---|
| Widget SDK + Access Key | Logged-in client portals where the broker has a backend | On page load and every token refresh | Server signs userIdentifiers into a 15-minute embed token. Browser receives only embed-token. |
| Workflow Webhooks | Registration, KYC, FTD, account-state events, redemptions | Near real time | Handshake first, then send the main webhook with x-session-token. |
| SQS Data Feed | High-volume trading facts, backfills, hourly aggregates, CSV manifests | Queued batch or streaming | Use AWS Simple Queue Service when payloads need buffering, chunking, or retry isolation. |
| Broker DB or API Pull | Fallback for brokers that cannot push trading facts | Scheduled sync | Use only when SQS/data-ingest is not available and the broker can expose a stable read-only source. |
| MetaTrader | MT5 deal/history data or MT4 data through a broker-hosted bridge | Scheduled cursor-based sync | MT5 is a viable source when server access and commands are confirmed. MT4 usually needs Manager API or an export bridge. |
Build order
- 1. Pick the trader identifier. Prefer a stable broker-owned customer ID. Map it to trading account logins separately instead of using email as the primary key.
- 2. Register or sync the trader. Use Workflow Webhooks for signup, KYC, FTD, and account-state events.
- 3. Render the widget. Mint an Access Key embed token server-side with matching userIdentifiers and put only the returned
embed-tokenon the custom element. - 4. Feed trading activity. Use SQS/data-ingest for broker-pushed trading facts, aggregates, tier snapshots, and backfills. Use read-only API/database pull only as a fallback when the broker cannot push reliably.