Trading volume and rewards

Build trading rewards from immutable source facts, a stable customer mapping, and an approved calculation. This page uses synthetic data to show one trader with two accounts, separate FX and metals units, and a separately defined comparable USD turnover input.

Canonical user and account lineage

A trading account is not the loyalty user. Use a durable account key made from platform, server, and account login, then map each account to the canonical broker customer and its enrolled Returning.AI user.CUSTOMER_1001 is the broker's external identifier, not the platform user ID returned by enrollment. Keep both IDs and the mapping version and effective dates when ownership can change. See the enrollment guide.

Hold an unmapped account without awarding points. Resolve the mapping and replay through the approved process. Do not merge users because an email or display name happens to match.

Processing model

This worked example chooses raw close-deal activity as the source model and a user/window aggregate as the delivery model. The collector first stores the raw facts, then groups all eligible rows for one canonical user and UTC window before sending one aggregate row. A field such asaggregate_id keeps the derived row tied to its source set.

Worked input: two accounts and two asset classes

Every row below is individual closed-deal activity in the UTC window from 2026-09-07T00:00:00Z inclusive to2026-09-08T00:00:00Z exclusive. Adjacent windows share no boundary event. The USD amount is a separately defined comparable turnover input for this example. It is not a conversion of the FX and metals lot columns, and it is not used by the illustrative lot-rate calculation below.

The two FX rows total 2.00 standard lots. The metals row totals 0.50 metal lots. Do not report one combined lot total: the units and contract rules are different. The USD turnover total is valid here only because it was separately defined as a comparable USD measure and supplied for every included row. Eachsource_event_id is the stable replay identity for its raw row; the aggregate has its own stable aggregate_id.

One canonical-user and window aggregate

Retain the full account list, class totals, source IDs, and aggregate version in one canonical-user/window row. The exact field names below are a synthetic mapping for the example. The configured workflow decides the actual payload contract.

{
  "aggregate_id": "agg:CUSTOMER_1001:2026-09-07:v1",
  "canonical_customer_id": "CUSTOMER_1001",
  "window_start": "2026-09-07T00:00:00Z",
  "window_end": "2026-09-08T00:00:00Z",
  "accounts": [
    { "platform": "mt5", "server": "broker-live-1", "account_login": "ACCOUNT_2001" },
    { "platform": "mt5", "server": "broker-live-1", "account_login": "ACCOUNT_2002" }
  ],
  "volumes": [
    {
      "asset_class": "fx",
      "normalized_volume": 2.0,
      "volume_unit": "standard_lot",
      "source_event_ids": ["deal-2001-fx-001", "deal-2002-fx-002"]
    },
    {
      "asset_class": "metals",
      "normalized_volume": 0.5,
      "volume_unit": "metal_lot",
      "source_event_ids": ["deal-2001-metals-003"]
    }
  ],
  "comparable_turnover_usd": 250000,
  "aggregation_version": "trading-aggregate-v1"
}

Illustrative points calculation

Assume the approved example configuration says 10 points per FX standard lot and 20 points per metal lot. Round half-up to the nearest whole point after each class calculation. These rates are synthetic and do not claim a Returning.AI or client default.

Trading volume is a measurement. Points are an illustrative reward output. Coins, XP, points, and a custom volume field are separate destinations; a configured workflow must say which one is written. The 250,000 USD turnover input is also separate and must not be silently converted into points or combined with lot totals.

Eligibility, launch cutoff, and history

Use the close time and the approved UTC launch cutoff, not the time a poller happened to see a row. In this synthetic example the cutoff is2026-09-07T00:00:00Z; the integration owner must replace it with the approved value for the real campaign.

Snapshot or delta

Decide whether the delivery represents a complete snapshot or a new delta before choosing retry behavior. Do not alternate between them for the same aggregate identity.

Partial success, corrections, and readback

1. Record the baseline authoritative value, aggregate ID, source count, and expected class totals before delivery.
2. Check transport acceptance, Event Ingest persistence, and workflow execution as separate checkpoints. A queue acknowledgement is not a reward result.
3. If a queued user update has per-row results, preserve successful users and retry only failed users through the approved path. Do not replay the whole additive batch to repair one failure.
4. Read back the authoritative field, points, coins, or ledger value using the operation and permission supplied for the environment. Then compare it with the expected aggregate and source lineage.
5. Replay the same aggregate identity and verify that it does not add a second reward when the configured contract promises that behavior.
6. For a changed fact, pause and use the approved correction or compensation flow. A new batch or aggregate ID alone is not a safe financial correction.
7. Refresh the widget for CUSTOMER_1001 only after the saved state is authoritative. A stale widget does not prove the workflow failed.

Next step

Use the SQS data feed guide to package bounded JSON messages or review a provisioned file contract. Use the workflow webhook guidefor registration, KYC, and other lifecycle events. Once enrollment and readback are complete, open the widget quickstart.

For onboarding progress, connect custom fields and milestones. Before enabling real rewards, complete the launch checklist.