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.

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.
tracking_data	string	Track360 will send it in URL and get it back in API.	Max 50 characters.
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",
  "tracking_data": "2001_1000_abcdefg",
  "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",
    "tracking_data"
  ],
  "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
    },
    "tracking_data": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50
    },
    "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, tracking_data 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