Forex

Forex Integration Guide

Integration guide for Forex brokers connecting trader data, financial transactions, and trading activity to Track360 for IB and affiliate commission management.

Forex Integration Guide

Integration guide for Forex brokers connecting trader data, financial transactions, and trading activity to Track360 for IB and affiliate commission management.

This guide covers the entity schemas, authentication flow, sample payloads, and onboarding checklist needed to connect your forex platform to Track360. All data is exchanged via REST API using JSON payloads over HTTPS.

Integration Patterns

Forex integrations follow a push model where the broker platform sends customer registrations, deposit/withdrawal/rebate events, and daily trading activity summaries to Track360 via REST API. The data flows through three primary entities: Customers (trader accounts with IB attribution and account configuration), Transactions (deposits, withdrawals, IB rebates, bonuses), and Trading Activity (daily aggregated trading volume per instrument). This enables Track360 to calculate lot-based and spread-based IB commissions, trigger CPA events on first deposits, and deliver real-time reporting to introducing brokers and affiliates.

Pull — Track360 Retrieves Your Data

Track360 periodically pulls data from your API or database

Track360

requests data

Your API / DB

returns data

Track360

You expose a REST API (or database replica / DWH view) and Track360 retrieves data on a scheduled cadence. This is the most common pattern — it keeps control on your side and requires no outbound connectivity from your systems.

Best for

Partners with existing internal APIs or reporting endpoints
Stable, batch-oriented data (daily gaming activity, transaction history)
Reconciliation and backfill workflows
Systems behind firewalls with no public webhook endpoint

Not ideal for

—Real-time event delivery (sub-second latency)
—High-frequency updates where polling creates overhead

Push — You Send Data to Track360

Your platform sends events to Track360 endpoints in real time

Your Platform

sends events

Track360 Endpoint

confirms

Your Platform

Your system pushes events (registrations, deposits, conversions) to Track360 ingestion endpoints as they occur. This gives the lowest latency but requires your platform to handle delivery, retries, and idempotency.

Best for

Real-time customer registration and attribution
Instant deposit and conversion tracking
Event-driven architectures with message queues
Platforms that prefer to control outbound data delivery

Not ideal for

—Aggregated daily data (gaming/trading activity summaries)
—Historical data migration or backfill

Hybrid — Combine Both Patterns

Push real-time events + pull batch data for reconciliation

Recommended

Real-time

Your Platform

pushes events

Track360

Scheduled

Track360

pulls batch data

Your API / DWH

The recommended approach for production integrations. Push time-sensitive events (registrations, deposits) for real-time attribution, while Track360 pulls aggregated data (activity, revenue metrics) on a daily schedule. This gives you speed where it matters and reliability everywhere else.

Best for

Production environments that need both speed and accuracy
Different entities with different freshness requirements
Data reconciliation between real-time and batch sources
High-volume integrations with complex data models

Not ideal for

—Simple integrations with a single entity type

Quick Comparison

	Pull	Push	Hybrid
Latency	Minutes to hours	Seconds	Seconds (events) + daily (batch)
Complexity	Low — expose API	Medium — handle retries	Medium — both patterns
Data freshness	Scheduled cadence	Real-time	Real-time + reconciled
Backfill support	Built-in	Requires replay	Built-in
Best entity fit	Activity, reports	Events, registrations	All entity types

Authentication

Track360 uses the OAuth 2.0 Client Credentials grant. Partners authenticate by exchanging their client_id and client_secret for a short-lived Bearer token. The token is included in the Authorization header of every subsequent API request. Tokens expire after 3600 seconds (1 hour); the client must request a new token before expiry.

Token Request

http

POST /oauth/token HTTP/1.1
Host: api.track360.io
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

Token Response

json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write"
}

Authenticated Request

http

GET /api/v1/forex/customers?page=1&per_page=50 HTTP/1.1
Host: api.track360.io
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Important Notes

Store credentials securely. Never expose client_secret in client-side code.
Implement token refresh logic before expiry to avoid request failures.
All API requests must be made over HTTPS.
Failed authentication returns HTTP 401 with a JSON error body.
Rate limits apply per access token. See API design recommendations for details.

Customers

Represents trader accounts registered with the broker. Each record links a trader to the introducing broker (IB) or affiliate that referred them, along with account configuration details.

Recommended: Near real-time (within 5 minutes of registration or status change)

Field Specification

Field	Type	Description	Validation Notes
customer_id	string	Unique partner-side customer identifier.	Must be unique across all records. Immutable after creation.
signup_date	string	Date and time the customer registered.	ISO 8601 date-time format.
last_modified_date	string	Timestamp of the last update to this record.	ISO 8601 date-time. Recommended for delta sync.
affiliate_id	string	ID of the introducing broker or affiliate that referred this customer.	Must map to the IB/affiliate identifiers configured in Track360.
campaign_id	string	Campaign that drove the registration.	Recommended for granular attribution.
click_id	string	Click identifier from the tracking link.	Recommended for click-level attribution.
lang_id	string	Language preference of the customer.	ISO 639-1 two-letter code.
country_code	string	Country of the customer.	ISO 3166-1 alpha-2. Recommended for geo reporting.
kyc_status_id	string	Know Your Customer verification status.	Enum mapping documented in onboarding.
sales_status_id	string	Internal sales pipeline status.	—
trading_account_type	string	Type of trading account (e.g. standard, ECN, micro, demo).	Recommended. Used for segmentation and commission tier assignment.
leverage	string	Account leverage setting (e.g. "1:100", "1:500").	Optional. Useful for risk segmentation and regulatory reporting.
first_name	string	Customer first name.	Subject to privacy and data protection policies.
last_name	string	Customer last name.	Subject to privacy and data protection policies.
email	string	Customer email address.	Subject to privacy policy. Must be valid email format if provided.

Sample Payload

json

{
  "customer_id": "tdr_50321",
  "signup_date": "2026-03-10T14:30:00Z",
  "last_modified_date": "2026-03-12T08:22:15Z",
  "first_name": "Maria",
  "last_name": "S",
  "email": "[email protected]",
  "affiliate_id": "ib_1045",
  "campaign_id": "cmp_fx_202",
  "click_id": "clk_fx_789",
  "lang_id": "es",
  "country_code": "MX",
  "kyc_status_id": "approved",
  "sales_status_id": "converted",
  "trading_account_type": "ECN",
  "leverage": "1:200"
}

JSON Schema

json

{
  "$schema": "https:">//json-schema.org/draft/2020-12/schema",
  "title": "Forex Customer",
  "type": "object",
  "required": [
    "customer_id",
    "signup_date",
    "affiliate_id"
  ],
  "properties": {
    "customer_id": {
      "type": "string",
      "minLength": 1
    },
    "signup_date": {
      "type": "string",
      "format": "date-time"
    },
    "last_modified_date": {
      "type": "string",
      "format": "date-time"
    },
    "affiliate_id": {
      "type": "string",
      "minLength": 1
    },
    "campaign_id": {
      "type": "string"
    },
    "click_id": {
      "type": "string"
    },
    "lang_id": {
      "type": "string",
      "pattern": "^[a-z]{2}$"
    },
    "country_code": {
      "type": "string",
      "pattern": "^[A-Z]{2}$"
    },
    "kyc_status_id": {
      "type": "string"
    },
    "sales_status_id": {
      "type": "string"
    },
    "trading_account_type": {
      "type": "string"
    },
    "leverage": {
      "type": "string"
    },
    "first_name": {
      "type": "string"
    },
    "last_name": {
      "type": "string"
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "additionalProperties": false
}

Business Notes

customer_id is the primary key. For brokers with multiple trading accounts per client, use the trading account ID.
affiliate_id maps to the introducing broker identifier in Track360. Multi-tier IB structures are configured in the Track360 commission plan.
trading_account_type enables commission differentiation (e.g. higher rebates for ECN accounts).
leverage is informational and can be used for risk-based segmentation.
PII fields are optional and subject to GDPR, MiFID II, and local data protection regulations.

Transactions

Financial events on a trader account: deposits, withdrawals, IB rebates, bonuses, and adjustments. Used for commission calculations and revenue attribution.

Recommended: Near real-time (within 5 minutes of transaction completion)

Field Specification

Field	Type	Description	Validation Notes
transaction_id	string	Unique transaction identifier.	Must be globally unique. Immutable.
customer_id	string	The customer this transaction belongs to.	Must reference an existing customer_id.
transaction_type	string	Category of the transaction.	Enum: deposit, withdrawal, bonus, adjustment, ib_rebate, other.
amount_currency	number	Transaction amount in the original currency.	Decimal precision up to 2 places.
currency	string	Currency of the transaction.	ISO 4217 three-letter code.
transaction_date	string	When the transaction occurred.	ISO 8601 date-time format.
status	string	Current status of the transaction.	Enum values documented per partner (e.g. pending, approved, declined, reversed).
amount_usd	number	Transaction amount converted to USD.	Optional. If not provided, Track360 applies its own FX conversion.
transaction_subtype	string	Further classification within the transaction type.	Examples: "wire", "card", "crypto", "lot_rebate", "spread_rebate".
note	string	Free-text note or internal reference.	Optional. Max 500 characters.

Sample Payload

json

{
  "transaction_id": "txn_fx_440012",
  "customer_id": "tdr_50321",
  "transaction_type": "deposit",
  "transaction_subtype": "wire",
  "amount_currency": 5000,
  "amount_usd": 5000,
  "currency": "USD",
  "transaction_date": "2026-03-12T10:45:00Z",
  "status": "approved",
  "note": "initial funding"
}

JSON Schema

json

{
  "$schema": "https:">//json-schema.org/draft/2020-12/schema",
  "title": "Forex Transaction",
  "type": "object",
  "required": [
    "transaction_id",
    "customer_id",
    "transaction_type",
    "amount_currency",
    "currency",
    "transaction_date",
    "status"
  ],
  "properties": {
    "transaction_id": {
      "type": "string",
      "minLength": 1
    },
    "customer_id": {
      "type": "string",
      "minLength": 1
    },
    "transaction_type": {
      "type": "string",
      "enum": [
        "deposit",
        "withdrawal",
        "bonus",
        "adjustment",
        "ib_rebate",
        "other"
      ]
    },
    "amount_currency": {
      "type": "number"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Z]{3}$"
    },
    "transaction_date": {
      "type": "string",
      "format": "date-time"
    },
    "status": {
      "type": "string"
    },
    "amount_usd": {
      "type": "number"
    },
    "transaction_subtype": {
      "type": "string"
    },
    "note": {
      "type": "string",
      "maxLength": 500
    }
  },
  "additionalProperties": false
}

Business Notes

The ib_rebate transaction type is specific to Forex. It represents rebates paid to introducing brokers based on trading volume.
Deposits trigger FTD (first-time deposit) commission events, similar to iGaming.
IB rebate amounts are typically calculated externally by the broker and pushed as separate transactions.
Multi-currency support is critical for Forex brokers operating across multiple jurisdictions.
Status updates (e.g. pending to approved) should re-send the record with the same transaction_id.

Trading Activity

Aggregated trading metrics per trader, per day, per instrument. Used for lot-based and spread-based commission calculations, IB rebate computation, and trading volume reporting.

Recommended: Daily (end-of-day aggregation, delivered by 06:00 UTC next day)

Field Specification

Field	Type	Description	Validation Notes
date	string	Activity date.	YYYY-MM-DD format.
customer_id	string	The trader this activity belongs to.	Must reference an existing customer_id.
instrument	string	Trading instrument (e.g. EURUSD, XAUUSD, US500).	Symbol as used on the trading platform.
lots_traded	number	Total number of standard lots traded.	Non-negative decimal. Precision up to 2 places.
volume_usd	number	Total notional volume in USD.	Recommended. Enables consistent volume reporting across instruments.
spread_cost	number	Total spread cost incurred by the trader.	Used for spread-based commission models. Non-negative.
commission	number	Trading commission charged by the broker.	Non-negative. Separate from spread cost.
pnl	number	Realized profit and loss for the day.	Can be negative. Represents closed positions only.
currency	string	Currency of the monetary values (spread_cost, commission, pnl).	ISO 4217 three-letter code.

Sample Payload

json

{
  "date": "2026-03-15",
  "customer_id": "tdr_50321",
  "instrument": "EURUSD",
  "lots_traded": 12.5,
  "volume_usd": 1562500,
  "spread_cost": 37.5,
  "commission": 25,
  "pnl": -142.3,
  "currency": "USD"
}

JSON Schema

json

{
  "$schema": "https:">//json-schema.org/draft/2020-12/schema",
  "title": "Forex Trading Activity",
  "type": "object",
  "required": [
    "date",
    "customer_id",
    "instrument",
    "lots_traded",
    "currency"
  ],
  "properties": {
    "date": {
      "type": "string",
      "format": "date"
    },
    "customer_id": {
      "type": "string",
      "minLength": 1
    },
    "instrument": {
      "type": "string",
      "minLength": 1
    },
    "lots_traded": {
      "type": "number",
      "minimum": 0
    },
    "volume_usd": {
      "type": "number",
      "minimum": 0
    },
    "spread_cost": {
      "type": "number",
      "minimum": 0
    },
    "commission": {
      "type": "number",
      "minimum": 0
    },
    "pnl": {
      "type": "number"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Z]{3}$"
    }
  },
  "additionalProperties": false
}

Business Notes

Aggregation key: date + customer_id + instrument + currency. One record per unique combination.
lots_traded is the primary metric for lot-based IB rebate calculations (e.g. $5 per lot).
spread_cost is used for spread-based commission models where the IB earns a share of the spread.
volume_usd normalizes trading across different instruments for unified reporting.
pnl reflects closed positions only. Open position P&L is not included.
Intra-day updates replace the full day record (upsert on aggregation key).

API Design Recommendations

Recommended Endpoints

POST/api/v1/forex/customersCreate or upsert customer records in bulk.

GET/api/v1/forex/customersRetrieve customers with optional filtering.

POST/api/v1/forex/transactionsPush transaction records in bulk.

GET/api/v1/forex/transactionsQuery transactions with filtering and pagination.

POST/api/v1/forex/trading-activityPush daily aggregated trading activity records.

GET/api/v1/forex/trading-activityQuery trading activity with date range, instrument, and trader filters.

Pagination

Cursor-based pagination is recommended for large datasets. Use the "page" and "per_page" query parameters (default: 50, max: 500). Response includes "total", "page", "per_page", and "next_cursor" fields.

Rate Limiting

1000 requests per minute per access token. Bulk endpoints accept up to 1000 records per request. HTTP 429 is returned when limits are exceeded, with a Retry-After header.

Response Envelope

All list endpoints return data in a standard envelope with pagination metadata.

Response Envelope

json

{
  "data": [
    "..."
  ],
  "meta": {
    "total": 1250,
    "page": 1,
    "per_page": 50,
    "next_cursor": "eyJpZCI6MTMwMH0="
  }
}

Validation Rules

All payloads are validated against JSON Schema before processing. Requests that fail validation receive a 422 response with detailed error messages.

General Rules

All required fields must be present and non-null.
Date and date-time fields must conform to ISO 8601.
Currency codes must be valid ISO 4217 three-letter codes.
Numeric amounts must not exceed 15 significant digits.
String fields must not exceed 500 characters unless documented otherwise.
IDs must be non-empty strings, unique within their entity scope.
Bulk payloads must not exceed 1000 records per request.

Entity-Specific Rules

Customers: customer_id, signup_date, affiliate_id are required fields. See the field specification above for type and format constraints.
Transactions: transaction_id, customer_id, transaction_type, amount_currency, currency, transaction_date, status are required fields. See the field specification above for type and format constraints.
Trading Activity: date, customer_id, instrument, lots_traded, currency are required fields. See the field specification above for type and format constraints.

Onboarding Checklist

Track your progress through the integration onboarding process.

Onboarding Progress0 of 8 completed

Phase: 1 day

Phase: 2-3 days

Phase: 1-2 days

Phase: 3-5 days

Phase: 5-7 days

Ready to begin your forex integration?

Get in touch with our integrations team to receive your API credentials and start onboarding.

Contact Integrations Team