API Reference

Gateway health check

Returns gateway health status including Redis connectivity and idempotency cache stats. Includes `permission_checks_skipped` counter (> 0 = RBAC cache degraded).

{
  "status": "ok",
  "service": "api-gateway",
  "checks": {
    "redis": "ok",
    "idempotency": {
      "hits": 0,
      "misses": 0,
      "hit_rate": 0
    }
  },
  "timestamp": "2026-03-24T10:00:00Z"
}

Aggregated health check for all services

Polls all internal services and returns combined status. Returns `"status": "degraded"` if any service is down or unhealthy. No authentication required.

{
  "status": "ok",
  "services": {
    "api-gateway": {
      "status": "ok",
      "details": {
        "status": "ok",
        "service": "api-gateway"
      }
    },
    "price-feed": {
      "status": "ok",
      "details": {
        "status": "ok",
        "service": "price-feed"
      }
    },
    "order-service": {
      "status": "ok",
      "details": {
        "status": "ok",
        "service": "order-service"
      }
    }
  },
  "timestamp": "2026-03-11T22:00:00Z"
}

Broker staff login

Authenticate as a broker staff user. Returns short-lived access token (15 min) + long-lived refresh token (7 days). If user has 2FA enabled and no `totp_code` is provided, returns `{"requires_2fa": true}` -- re-send with `totp_code` to complete login.

{
  "email": "[email protected]",
  "password": "secret123",
  "totp_code": "123456"
}

{
  "access_token": "eyJ...",
  "refresh_token": "abc123...",
  "expires_in": 900,
  "token_type": "bearer",
  "user": {
    "id": "uuid",
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Smith",
    "full_name": "Jane Smith",
    "team_id": null,
    "role_id": 2,
    "is_active": true,
    "created_at": "2026-03-09T10:00:00Z",
    "last_login_at": "2026-03-09T10:00:00Z"
  }
}

Customer (trader) login

Authenticate as a trader and receive a JWT with `type: "customer"`. JWT payload includes `login` (primary active trading account), `logins` (all active account logins for multi-account switcher), `compliance_status`, and `force_password_change`.

{
  "email": "[email protected]",
  "password": "secret123"
}

{
  "access_token": "eyJ...",
  "refresh_token": "abc123...",
  "expires_in": 900,
  "token_type": "bearer",
  "customer": {
    "id": "uuid",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "force_password_change": false,
    "...": "all CustomerResponse fields"
  }
}

Redeem one-time autologin token

Redeem a one-time autologin token. Returns the same shape as `POST /customers/login`. Token is burned atomically via Redis Lua GET+DEL.

Request password reset link (authenticated)

Request a password reset link. Customer must be logged in -- email is derived from JWT.

{}

{
  "message": "...",
  "reset_url": "https://..."
}

Forgot password (public)

Public. Always returns 200 to prevent email enumeration.

{
  "email": "[email protected]"
}

{
  "message": "If an account exists with that email, a reset link has been generated"
}

Verify password reset token

Public. Verify token validity without burning it. Returns masked email.

{
  "valid": true,
  "email": "tr***@example.com"
}

Confirm password reset

Public. Burns token atomically and updates password.

{
  "token": "<uuid>",
  "new_password": "NewPass123"
}

{
  "message": "Password updated successfully"
}

Set new password

Set a new password. Clears `force_password_change` flag and issues a fresh JWT. Used after affiliate/import registration where password was auto-generated. This endpoint is allowed even when `force_password_change` is `true` (gateway exempts it). Password must be 8-72 characters.

{
  "new_password": "MySecurePass99"
}

{
  "access_token": "eyJ...",
  "message": "Password updated successfully"
}

Generate TOTP secret for 2FA setup

Generate a TOTP secret for the authenticated user. Returns a QR code URI for authenticator apps (Google Authenticator, Authy, etc.).

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qr_uri": "otpauth://totp/JumpTech:[email protected]?secret=...",
  "message": "Scan QR code, then verify"
}

Verify TOTP code to enable 2FA

Verify a TOTP code to enable 2FA. Generates 10 one-time backup codes (shown once -- user must save them).

{
  "code": "123456"
}

{
  "enabled": true,
  "backup_codes": [
    "a1b2c3d4",
    "e5f6g7h8",
    "..."
  ],
  "message": "2FA enabled. Save backup codes."
}

Disable 2FA

Disable 2FA. Requires a valid current TOTP code to confirm.

{
  "code": "123456"
}

{
  "enabled": false,
  "message": "2FA has been disabled"
}

List active sessions

List all active sessions for the authenticated user.

[
  {
    "session_id": "uuid",
    "device": "Mozilla/5.0...",
    "ip": "1.2.3.4",
    "created_at": "2026-03-20T10:00:00Z"
  }
]

Revoke a specific session

Revoke a specific session. The session's JWT becomes invalid immediately.

Revoke all other sessions

Revoke all sessions except the current one (identified by the JWT's `session_id` claim).

{
  "revoked": 3
}

Refresh access token

Exchange a valid refresh token for a new short-lived access token. No JWT required -- auth via the refresh token itself. Works for both CRM users and customers.

{
  "refresh_token": "abc123..."
}

{
  "access_token": "eyJ...",
  "expires_in": 900,
  "token_type": "bearer"
}

Customer registration

Public customer registration. Creates a Customer record and a linked TradingAccount in one transaction. Runs fraud checks: disposable email block -> affiliate_lead_id duplicate -> email duplicate -> phone duplicate -> jurisdiction gate. Supports four registration paths: Organic (password required, country->group), Affiliate (auto-generated password, 72h autologin link, force_password_change=true), Import (auto-generated password, CSV group or default), Promo (password required, promo code's group).

{
  "email": "[email protected]",
  "password": "TestPass1234",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+447700900000",
  "country": "GB",
  "gender": "male",
  "source": "organic",
  "promo_code": null,
  "affiliate_id": "aff_123",
  "campaign_id": "camp_spring2026",
  "funnel": "lp-gold-v3",
  "affiliate_lead_id": "portal_lead_99871"
}

{
  "id": "uuid",
  "email": "[email protected]",
  "phone": "+447700900000",
  "country": "GB",
  "gender": "male",
  "owner_id": null,
  "ftd_sales_agent_id": null,
  "sales_status_id": null,
  "kyc_status_id": null,
  "affiliate_id": "aff_123",
  "campaign_id": "camp_spring2026",
  "funnel": "lp-gold-v3",
  "affiliate_lead_id": "portal_lead_99871",
  "manager_counter": 0,
  "reg_time": "2026-03-09T10:00:00Z",
  "is_deposited": false,
  "is_active": true,
  "retention_status": null,
  "risk_classification": "normal",
  "registration_source": "organic",
  "force_password_change": false,
  "trading_accounts": [
    {
      "id": "uuid",
      "login": "10007",
      "currency": "USD",
      "account_type": "real",
      "balance": 0,
      "credit": 0,
      "is_active": true,
      "created_at": "2026-03-09T10:00:00Z"
    }
  ],
  "autologin_token": null,
  "autologin_url": null,
  "source": "organic"
}

List customers with CRM filters

List customers with CRM filters. Results are scoped by the caller's `customer_view_scope` (own/team/all). Ordered by `reg_time DESC`. Customer responses are PII-masked based on the caller's role -- `email` and `phone` fields may be masked or hidden depending on the role's `pii_email` and `pii_phone` settings.

Get single customer profile

Single customer profile with embedded agent names and trading accounts.

Update customer details

CRM agent update. Scoped by caller's `customer_edit_scope`.

{
  "phone": "+44...",
  "country": "DE",
  "owner_id": "uuid",
  "sales_status_id": 3,
  "kyc_status_id": 1
}

Check for duplicate customers

Check for potential duplicate customers using scoring-based matching. Scoring: `affiliate_lead_id` = 10, `email` = 4, `phone` = 3, `country` = 1.

{
  "email": "[email protected]",
  "phone": "+447700900000",
  "country": "GB",
  "affiliate_lead_id": "portal_lead_99871"
}

{
  "duplicates": [
    {
      "customer_id": "uuid",
      "email": "[email protected]",
      "phone": "+447700900000",
      "country": "GB",
      "score": 8,
      "matched_fields": [
        "email",
        "phone",
        "country"
      ]
    }
  ]
}

Customer heartbeat

Heartbeat -- refresh Redis online presence TTL (300s). Returns 204 No Content.

Check customer online status

Check Redis online status.

{
  "customer_id": "uuid",
  "online": true
}

Create a promo code

Create a promo code that assigns registering customers to a specific group.

{
  "code": "SPRING2026",
  "group_id": "uuid",
  "expires_at": "2026-06-30T23:59:59Z",
  "max_uses": 500
}

List all promo codes

List all promo codes, ordered by `created_at DESC`.

Get single promo code

Single promo code by ID.

Update promo code

Update promo code fields: `is_active`, `expires_at`, `max_uses`.

Deactivate promo code

Soft-deactivate (sets `is_active=false`). Returns 204 No Content.

Download CSV import template

Download CSV template for customer import. Returns a CSV file with headers: `email,phone,first_name,last_name,country,group_name,assigned_to_email,comment`.

Upload CSV to import customers

Upload a CSV to import customers. Creates an async job and processes rows in the background at a drip rate of ~10/sec. Each row is registered with `source=import`, auto-generated password, and `force_password_change=true`. Duplicate emails produce a rejection row (not an HTTP error).

multipart form with `file` field (UTF-8 CSV, max 50,000 rows)

{
  "job_id": "uuid",
  "status": "pending",
  "total_rows": 1500,
  "message": "Import job created. Processing 1500 rows."
}

Get import job progress

Job progress for a customer import.

{
  "id": "uuid",
  "status": "processing",
  "filename": "leads_march.csv",
  "total_rows": 1500,
  "processed_rows": 750,
  "success_count": 740,
  "rejection_count": 10,
  "created_at": "2026-03-24T10:00:00Z"
}

Download rejection report

Download rejection report as CSV. Each row includes the original data and the rejection reason.

Live account equity, PnL, and margin

Live equity, PnL, and margin data from Redis. Includes staleness indicators for frontend display. Falls back to Postgres balance/credit when Redis state is missing (e.g., after Redis restart).

{
  "login": "10007",
  "equity": 10250.5,
  "pnl": 250.5,
  "free_margin": 9750.5,
  "margin_level": 1025.05,
  "margin_used": 500,
  "max_withdrawable": 9750.5,
  "gross_exposure": 10854.2,
  "net_exposure": 5427.1,
  "currency": "USD",
  "stale": false,
  "age_s": 0.2
}

Get derived account balance

Derived balance: `SUM(amount) WHERE status='APPROVED'`.

List account transactions

All transactions for a trading account.

Reassign account to a different group

Reassign a trading account to a different group. Open positions retain their snapshotted terms from the original group.

{
  "group_id": "uuid"
}

Close a trading account

Close a trading account. Pre-checks: no open positions, no pending transactions. Pending orders are auto-cancelled on closure. `force=true` allows closure with remaining balance (broker acknowledges offline handling). Sets `closure_status='closed'`, `is_active=false`. Deactivates customer if no other active accounts.

{
  "reason": "Customer requested closure",
  "force": false
}

{
  "login": 10007,
  "status": "closed",
  "reason": "Customer requested closure",
  "balance_at_closure": 0
}

Query financial ledger events

Query the financial ledger for a trading account. Returns atomic financial events in reverse chronological order.

[
  {
    "id": "uuid",
    "account_id": 10007,
    "event_type": "deposit",
    "reference_type": "transaction",
    "reference_id": "uuid",
    "balance_delta": 500,
    "credit_delta": 0,
    "margin_delta": 0,
    "balance_after": 10500,
    "credit_after": 0,
    "margin_after": 500,
    "sequence_num": 42,
    "description": "Deposit approved",
    "idempotency_key": "deposit:tx-uuid",
    "created_at": "2026-03-24T10:00:00Z"
  }
]

Aggregated ledger summary

Aggregated ledger summary -- total deposits, withdrawals, P&L, commissions, swaps.

{
  "account_id": 10007,
  "total_deposits": 5000,
  "total_withdrawals": -1000,
  "net_trading_pnl": 250.5,
  "total_commissions": -45,
  "total_swaps": -12.3,
  "total_chargebacks": 0,
  "total_nbp": 0,
  "net_credit": 0,
  "net_balance_change": 4193.2,
  "total_events": 87
}

Create a manual transaction

Create a manual transaction.

{
  "type": "DEPOSIT",
  "account_id": "uuid",
  "amount": "500.00",
  "currency": "USD",
  "account_amount": "500.00",
  "usd_amount": "500.00",
  "exchange_rate_usd": "1.0",
  "gate_name": "Bank Wire",
  "proof_reference": "WIRE-REF-20260309",
  "comment": "Bank wire confirmed",
  "status": "PENDING"
}

Approve a pending transaction

Approve a pending manual transaction.

Decline a pending transaction

Decline a pending manual transaction.

Soft-delete a transaction

Soft-delete -- excluded from balance computation, preserved for audit.

Create a cashier (Praxis) transaction

Create a cashier (Praxis) transaction. Idempotent on `cashier_id`.

Praxis webhook

Legacy path -- routes to integration-service for HMAC verification and forwarding.

Process a chargeback

Process a chargeback against an approved deposit. Creates a negative CHARGEBACK transaction.

{
  "reason": "Card dispute by cardholder"
}

{
  "chargeback_id": "uuid",
  "original_transaction_id": "uuid",
  "amount": -500,
  "balance_after": -200,
  "account_frozen": true
}

List transactions awaiting approval

List transactions awaiting approval (status `PENDING` or `PENDING_APPROVAL`). Max 200.

List transactions

List transactions with filters.

Get single transaction

Single transaction by UUID.

Provider payment callback (internal)

Provider-agnostic internal endpoint. Called by integration-service after webhook verification.

{
  "cashier_id": "...",
  "status": "APPROVED",
  "gateway_payload": {}
}

List available payment gateways

List all known payment gateways with their enabled status. A gateway is "enabled" only if activated in integration-service with credentials configured.

[
  {
    "id": "praxis",
    "name": "Praxis",
    "type": "redirect",
    "enabled": true
  },
  {
    "id": "bridgerpay",
    "name": "BridgerPay",
    "type": "embed",
    "enabled": false
  }
]

List payment routing rules

List all per-country payment gateway routing rules.

[
  {
    "country": "BR",
    "deposit_gateway": "bridgerpay",
    "withdrawal_gateway": "praxis",
    "is_active": true,
    "note": "Brazil uses BridgerPay",
    "updated_at": "2026-03-19T10:00:00"
  }
]

Create or update country routing

Create or update payment routing for a country (ISO 3166-1 alpha-2). Rejects if gateway is not enabled.

{
  "deposit_gateway": "bridgerpay",
  "withdrawal_gateway": "praxis",
  "is_active": true,
  "note": "Brazil uses BridgerPay for deposits"
}

Delete country routing

Delete routing -- country reverts to default gateway. Returns 204.

Resolve payment gateway for country

Resolve which payment gateway to use for a customer's country. Public (no auth) -- called by the frontend before initializing the cashier.

{
  "gateway": "bridgerpay",
  "country": "BR",
  "direction": "deposit",
  "type": "embed",
  "script_url": "https://embed.bridgerpay.com/connector.min.js",
  "cashier_key": "..."
}

Create BridgerPay cashier session

Create a BridgerPay cashier session. Requires customer JWT. Creates a PENDING transaction and returns the cashier token for frontend iframe initialization.

{
  "amount": 500,
  "currency": "USD"
}

{
  "transaction_id": "uuid",
  "cashier_token": "abc123...",
  "cashier_session_id": "...",
  "cashier_key": "...",
  "script_url": "https://embed.bridgerpay.com/connector.min.js"
}

BridgerPay payment webhook

BridgerPay payment webhook. Public (no auth). Handled by integration-service -- connector verifies HMAC, maps status, and forwards to `POST /transactions/payment-callback` on account-service.

List withdrawal approval rules

List all active rules, ordered by `min_amount_usd`.

Create a withdrawal approval rule

Create a new rule. Returns 201 Created.

{
  "min_amount_usd": 0,
  "max_amount_usd": 1000,
  "required_role": "agent",
  "is_active": true
}

Update a withdrawal approval rule

Update an existing rule (same fields as POST).

Delete a withdrawal approval rule

Soft-delete (sets `is_active=false`). Returns 204 No Content.

Place a market order (async)

Place a market order -- async execution. Poll `GET /orders/request/{request_id}` for execution result.

{
  "login": 10007,
  "symbol": "EURUSD",
  "cmd": 0,
  "volume": 0.1
}

{
  "request_id": "uuid",
  "status": "queued"
}

Poll async order execution status

Poll async execution status. Key expires after 5 minutes.

{
  "request_id": "uuid",
  "status": "executed",
  "order": 100001
}

List open positions

List open positions.

Get single open position

Single open position with live profit.

Close a position

Close a position. Supports partial close.

Modify stop-loss / take-profit

Modify stop-loss / take-profit on an open position.

{
  "sl": 1.08,
  "tp": 1.12
}

Place a pending order

Place a pending order.

{
  "login": 10007,
  "symbol": "EURUSD",
  "cmd": 2,
  "volume": 0.1,
  "trigger_price": 1.085,
  "limit_price": null,
  "sl": 1.08,
  "tp": 1.09,
  "expiry_at": "2026-03-15T00:00:00Z",
  "comment": "Buy limit on EUR"
}

Modify a pending order

Modify an active pending order.

{
  "sl": 1.075,
  "tp": 1.095,
  "trigger_price": 1.086,
  "limit_price": 1.087
}

List pending orders

List pending orders.

Cancel a pending order

Cancel a pending order. Only active orders.

List closed trades

List closed trades. Response includes `open_fx_rate` and `close_fx_rate` for margin/profit currency conversion.

Get single closed trade

Single closed trade.

Get all latest prices

Returns latest cached price for every active symbol.

{
  "prices": [
    {
      "symbol": "BTCUSDT",
      "bid": 67152.53,
      "ask": 67152.54,
      "mid": 67152.535,
      "timestamp_ms": 1773033231279,
      "provider": "platform"
    }
  ],
  "count": 3
}

Get single symbol price

Single symbol lookup. URL-encode slashes for forex: `EUR%2FUSD`.

OHLC bars for charting

OHLC bars for charting (TradingView Charting Library datafeed).

{
  "symbol": "EURUSD",
  "timeframe": "H1",
  "bars": [
    {
      "time": 1711234567,
      "open": 1.085,
      "high": 1.086,
      "low": 1.084,
      "close": 1.0855,
      "volume": 147
    }
  ],
  "count": 500
}

Get all USD-based FX rates

Returns all USD-based exchange rates from the in-memory cache (refreshed hourly).

{
  "base": "USD",
  "rates": {
    "EUR": 0.92,
    "GBP": 0.79,
    "JPY": 149.5
  },
  "last_updated": 1710000000,
  "count": 161
}

Get single currency FX rate

Single currency rate lookup.

{
  "currency": "GBP",
  "rate": 0.79,
  "base": "USD"
}

Per-symbol price freshness check

Per-symbol price freshness check. Each symbol reports its last tick age against its configured `stale_threshold_ms` (default 10000ms). Status is `"ok"` when no symbols are stale, `"degraded"` when at least one is stale.

{
  "status": "ok",
  "symbols": {
    "EURUSD": {
      "last_tick_ms": 1773033231279,
      "age_ms": 312,
      "stale": false,
      "threshold_ms": 10000
    },
    "BTCUSDT": {
      "last_tick_ms": 1773033230100,
      "age_ms": 1491,
      "stale": false,
      "threshold_ms": 5000
    }
  },
  "summary": {
    "total": 2,
    "stale": 0,
    "healthy": 2
  },
  "timestamp": "2026-03-12T10:00:31Z"
}

Historical price outage log

Historical price outage log. Each row represents a detected staleness window for a symbol. `ended_at` is `null` for ongoing outages.

{
  "outages": [
    {
      "id": "uuid",
      "symbol": "XAUUSD",
      "started_at": "2026-03-12T09:55:00Z",
      "ended_at": "2026-03-12T09:57:12Z",
      "duration_ms": 132000,
      "threshold_ms": 10000,
      "last_tick_at": "2026-03-12T09:54:50Z"
    }
  ],
  "count": 1
}

WebSocket price streaming

WebSocket endpoint for real-time price streaming.

List price providers

List configured price data providers.

List all price symbols

List all symbols available in the price feed.

List all active instruments

List all active instruments.

[
  {
    "id": "uuid",
    "symbol": "EURUSD",
    "display_name": "Euro / US Dollar",
    "category": "forex",
    "asset_class": "forex_majors",
    "base_currency": "EUR",
    "quote_currency": "USD",
    "digits": 5,
    "pip_size": 0.0001,
    "contract_size": 100000,
    "min_lot": 0.01,
    "max_lot": 100,
    "lot_step": 0.01,
    "margin_rate": 0.01,
    "spread": 0.2,
    "stale_threshold_ms": 10000,
    "is_active": true,
    "provider": "none",
    "last_bid": 1.08542,
    "last_ask": 1.08556,
    "last_tick_at": "2026-03-12T10:30:00Z"
  }
]

List active asset classes

Active asset classes for frontend tabs.

Get single instrument

Single instrument by symbol.

Add a new instrument

Add a new instrument.

List broker-level instrument config

List broker-level configuration for all instruments.

List broker-enabled instruments

Instruments enabled at broker level and active in master catalog. Use for trading UI.

Update broker-level instrument config

Update broker-level config: `is_enabled`, `tradeability` (`close_only`, `null` to clear).

List all trading groups

List all active trading groups (public).

Create a trading group

Create a trading group.

{
  "name": "vip",
  "description": "VIP clients",
  "currency": "USD",
  "default_leverage": 200,
  "margin_call_level": 50,
  "stopout_level": 20,
  "commission_type": "per_lot",
  "commission_value": 5,
  "swap_free": false,
  "swap_enabled": true,
  "swap_multiplier": 1,
  "swap_free_days": 0,
  "is_islamic": false,
  "is_default": false,
  "max_exposure": 500000,
  "net_max_exposure": false
}

Get single group

Single group by ID.

Update group fields

Update group fields. All fields optional.

Soft-delete a group

Soft-delete (sets `is_active=false`).

Create or update per-group instrument config

Create or update per-group instrument config. All fields optional and nullable -- `null` = inherit from master catalog.

{
  "spread": 2,
  "margin_rate": 0.015,
  "tradeability": "close_only",
  "commission_type": "per_lot",
  "commission_value": 5,
  "min_lot": 0.01,
  "max_lot": 50
}

List group instrument configs

List all instrument configs for a group.

Bulk upsert swap rates

Bulk upsert swap rates for multiple instruments on a group.

{
  "instruments": {
    "BTCUSDT": {
      "swap_type": "percent",
      "swap_long": -0.05,
      "swap_short": -0.05
    },
    "EURUSD": {
      "swap_type": "points",
      "swap_long": -5.5,
      "swap_short": -3.2
    }
  }
}

{
  "group_id": "uuid",
  "instruments_updated": 1,
  "instruments_created": 1
}

Get resolved swap rates

Resolved swap rates for all active instruments in a group. Shows source and effective rates after applying `swap_multiplier`.

Create a broker staff account

{
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Smith",
  "password": "secret123",
  "team_id": "uuid-or-null",
  "role_id": 2
}

UserResponse

Current user profile from JWT

Returns the profile of the currently authenticated user. No special permission required -- any authenticated user can call this.

List broker staff with filters

Single user profile

Update user fields

{
  "first_name": "Jane",
  "last_name": "Smith",
  "team_id": "uuid",
  "role_id": 3,
  "is_active": false
}

Heartbeat -- refresh online presence

Refresh Redis online presence TTL (300s) and stamp `last_login_at`. Any authenticated user can call this.

Check Redis online status

{
  "user_id": "uuid",
  "online": true
}

Create a team

`path` and `depth` are computed automatically.

{
  "name": "Europe",
  "parent_team_id": "root-uuid-or-null"
}

Flat list of teams

Full hierarchy as nested JSON

Returns the complete team hierarchy as nested JSON for UI rendering.

Single team by ID

Direct children only (one level down)

All descendants at any depth

Uses `path LIKE` -- one index scan.

All active users directly in this team

All active users in this team and all descendants

Update a team

If `parent_team_id` changes, all descendant paths are recomputed atomically.

List permission overrides for a team

Set a permission override for a team

Remove a permission override (reverts to role default)

List all roles

Create a role

{
  "name": "retention_agent",
  "display_name": "Retention Agent",
  "description": "Handles churning customers",
  "customer_view_scope": "own",
  "customer_edit_scope": "none",
  "pii_email": "masked",
  "pii_phone": "masked",
  "can_export_pii": false,
  "level": 0
}

Single role by ID

Update role fields

Updatable fields: `display_name`, `description`, `customer_view_scope`, `customer_edit_scope`, `pii_email`, `pii_phone`, `can_export_pii`, `level`, `is_active`.

List all permissions with granted status for a role

Grant or revoke a permission

{
  "granted": true
}

Remove a permission grant

List all defined permissions

Create a new permission definition

Create a status

`type` is normalised to lowercase.

{
  "type": "finance",
  "name": "Deposited"
}

List statuses

All active statuses grouped by type

Call once on page load.

Single status

Update name or soft-delete

{
  "name": "Funded",
  "is_active": false
}

Hard delete a status

Assign customers to an agent

{
  "customer_ids": [
    "uuid1",
    "uuid2"
  ],
  "role": "sales",
  "new_agent_id": "agent-uuid",
  "source": "rotation",
  "note": "Round-robin batch"
}

Full assignment history

Current agent per role

Move a user to a new team

{
  "new_team_id": "uuid-or-null",
  "note": "Q2 restructure"
}

Full team membership history

Activity feed with keyset pagination

{
  "items": [
    "..."
  ],
  "next_cursor": "1187"
}

Create a note

{
  "body": "Called customer, interested in gold trading"
}

Edit a note body

Only the author may edit. Previous body saved to `note_edits`.

Soft-delete a note

Only the author may delete.

Full edit history for a note

Create a task

{
  "title": "Follow up call Friday 3pm",
  "due_at": "2026-03-13T13:00:00Z",
  "assigned_to": "user-uuid"
}

List tasks for a customer

Update a task

Status transitions: `-> done` (sets `completed_at`), `-> cancelled` (sets `cancelled_at`).

Tasks assigned to current user

Tasks for all users in caller's team

List all broker settings

[
  {
    "key": "maker_checker_enabled",
    "value": "true",
    "description": "Require different user for tx approval",
    "updated_at": "2026-03-20T10:00:00Z"
  },
  {
    "key": "platform_name",
    "value": "MyBroker",
    "description": "Broker display name",
    "updated_at": "2026-03-19T08:00:00Z"
  }
]

Create or update a broker setting

Upserts on key.

{
  "value": "true",
  "description": "Require different user for transaction approval"
}

{
  "key": "maker_checker_enabled",
  "value": "true"
}

List all available placeholders for email templates

Returns available placeholders (e.g., `{{customer.first_name}}`, `{{transaction.amount}}`).

Create a new email template

Creates the parent record with no translations yet.

{
  "name": "Welcome Email",
  "event_type": "customer.registered",
  "description": "Sent on signup",
  "default_locale": "en"
}

List all email templates with their translation locales

Single template with all translations

Update template metadata

Update name, description, default_locale.

Soft-delete an email template

Create or update a locale-specific translation

{
  "subject": "Welcome, {{customer.first_name}}!",
  "body_html": "<p>Hello {{customer.first_name}}</p>",
  "body_text": "Hello {{customer.first_name}}"
}

Remove a translation

Preview a rendered template with sample data

Returns resolved HTML with placeholders filled.

Analyze SMS content

Returns encoding (GSM-7 or UCS-2), character count, and segment count.

{
  "body": "Your code is {{code}}"
}

Create a new SMS template

{
  "name": "Verification Code",
  "event_type": "verification",
  "description": "OTP SMS",
  "default_locale": "en"
}

List all SMS templates with translation locales

Single SMS template with all translations

Update SMS template metadata

Soft-delete an SMS template

Create or update a locale-specific SMS translation

{
  "body": "Your verification code is {{code}}"
}

Remove an SMS translation

Preview a rendered SMS with sample data

Create a workflow rule

{
  "name": "Auto-assign new deposits to retention",
  "description": "When a customer deposits, assign to retention team",
  "trigger_event": "customer.deposited",
  "trigger_config": {},
  "conditions": {
    "match": "all",
    "rules": [
      {
        "field": "event.amount",
        "operator": "gte",
        "value": 1000
      },
      {
        "field": "customer.retention_status",
        "operator": "eq",
        "value": "churning"
      }
    ]
  },
  "actions": [
    {
      "type": "handover_to_retention",
      "params": {}
    },
    {
      "type": "add_note",
      "params": {
        "body": "Auto-assigned: high-value deposit from churning customer"
      }
    },
    {
      "type": "send_email",
      "params": {
        "subject": "Welcome back!",
        "body_html": "<p>We noticed your deposit...</p>"
      }
    }
  ],
  "priority": 10,
  "stop_after": false
}

List all workflows

Single workflow with execution stats

Full replace of workflow definition

Toggle is_active on/off

{
  "id": "uuid",
  "is_active": true
}

Soft-delete a workflow

Sets `is_active=false`.

Duplicate workflow

Clones the workflow with "(copy)" appended to name.

Execution log for a specific workflow

[
  {
    "id": "uuid",
    "workflow_id": "uuid",
    "workflow_name": "Auto-assign new deposits to retention",
    "trigger_event": "customer.deposited",
    "customer_id": "uuid",
    "customer_email": "[email protected]",
    "status": "completed",
    "actions_executed": 3,
    "error_message": null,
    "started_at": "2026-03-19T10:00:00Z",
    "completed_at": "2026-03-19T10:00:01Z"
  }
]

Available trigger event types

Returns trigger event types with descriptions and field categories. Trigger events: `customer.registered`, `customer.deposited`, `customer.ftd`, `customer.withdrew`, `customer.traded`, `customer.status_changed`, `customer.retention_changed`, `call.no_answer`, `call.completed`, `task.overdue`, `customer.inactive_days`.

[
  {
    "event": "customer.deposited",
    "description": "Customer deposit approved",
    "available_categories": [
      "customer",
      "event",
      "transaction"
    ]
  },
  {
    "event": "customer.traded",
    "description": "Customer opened a trade",
    "available_categories": [
      "customer",
      "event",
      "order"
    ]
  }
]

All fields available in workflow conditions

Returns fields with value source metadata for UI rendering. Field categories: `customer.*`, `event.*`, `transaction.*`, `order.*`. Custom status types auto-discovered from the `statuses` table -- broker-created statuses appear without code changes.

[
  {
    "path": "customer.country",
    "type": "string",
    "description": "Customer country (ISO 3166-1)",
    "category": "customer",
    "value_source": null
  },
  {
    "path": "customer.sales_status_id",
    "type": "integer",
    "description": "Sales status",
    "category": "customer",
    "value_source": {
      "type": "status",
      "status_type": "sales"
    }
  }
]

Registered action types with parameter schemas

Available actions (14): `assign_to_team`, `assign_to_agent`, `reassign_round_robin`, `handover_to_retention`, `set_status`, `send_email`, `send_sms`, `create_task`, `add_note`, `increment_manager_counter`, `set_customer_active`, `freeze_account`, `delay`, `webhook`.

[
  {
    "type": "send_email",
    "description": "Send email via integration service",
    "params": {
      "subject": {
        "type": "string",
        "required": true
      },
      "body_html": {
        "type": "string",
        "required": true
      }
    }
  }
]

All condition operators

16 operators: `eq`, `ne`, `gt`, `lt`, `gte`, `lte`, `in`, `not_in`, `is_null`, `is_not_null`, `contains`, `not_contains`, `starts_with`, `ends_with`, `between`, `regex`.

Return current risk rule config

Returns the current risk rule configuration, or null.

Update risk classification thresholds

Triggers full batch recompute.

List risk profiles

Single customer risk profile

Create or replace the retention classification rule

Triggers full recompute.

{
  "signals": [
    "last_deposit_at",
    "last_trade_at"
  ],
  "operator": "OR",
  "thresholds": {
    "active": {
      "max_days": 35
    },
    "churning": {
      "min_days": 35,
      "max_days": 60
    },
    "dormant": {
      "min_days": 60
    }
  }
}

Return the current retention rule

Returns the current rule, or null if not yet configured.

Set a new per-country minimum deposit threshold

Append-only.

{
  "country": "BR",
  "minimum_usd": 300,
  "effective_from": "2026-03-11T00:00:00Z",
  "note": "Q2 Brazil campaign"
}

Full FTD minimum history

Currently active minimum per country

Confirmed FTDs

In-progress FTDs (deposited but not reached minimum)

FTD status for a specific customer

Customer trading activity calendar

Returns dates when the customer opened at least one order.

{
  "customer_id": "uuid",
  "from": "2026-03-01",
  "to": "2026-03-31",
  "total_days": 12,
  "days": [
    {
      "date": "2026-03-01",
      "first_order_at": "2026-03-01T09:14:22Z",
      "symbol": "BTCUSDT",
      "login": "10007"
    }
  ]
}

Aggregated trader counts per agent and team

For a date range. Respects `customer_view_scope`.

{
  "from": "2026-03-01",
  "to": "2026-03-31",
  "total_trader_days": 4520,
  "unique_traders": 890,
  "by_owner": [
    {
      "owner_id": "uuid",
      "owner_name": "John Smith",
      "trader_days": 320,
      "unique_traders": 45
    }
  ],
  "by_team": [
    {
      "team_id": "uuid",
      "team_name": "Sales Team A",
      "trader_days": 1200,
      "unique_traders": 150
    }
  ]
}

Day-by-day breakdown for charting engagement trends

Respects `customer_view_scope`.

{
  "from": "2026-03-01",
  "to": "2026-03-31",
  "days": [
    {
      "date": "2026-03-01",
      "trader_days": 145,
      "unique_traders": 145
    }
  ]
}

Provider-agnostic KYC webhook

Accepts results from SumSub, Shufti, Jumio, or manual verification. Public endpoint, HMAC-verified.

{
  "customer_id": "uuid",
  "provider": "sumsub",
  "provider_id": "ext-ref-123",
  "status": "approved",
  "doc_type": "passport",
  "doc_country": "US",
  "raw_result": {}
}

List restricted jurisdictions

Add a restricted jurisdiction

Update tier, reason, or is_active

Compliance events

Login audit trail

Manually freeze a customer account

{
  "reason": "Suspicious activity"
}

Manually unfreeze a customer account

{
  "reason": "KYC verified",
  "new_status": null
}

List all blocked disposable email domains

Add a domain to the blocklist

{
  "domain": "tempmail.com"
}

Remove a domain from the blocklist

Query the fraud audit log

Record customer acceptance of a legal document

Captures IP address and User-Agent automatically. Upserts on `(customer_id, document_type, document_version)`.

{
  "document_type": "terms_and_conditions",
  "document_version": "2.3",
  "accepted": true
}

List all consent records for a customer

Ordered by `accepted_at DESC`. For compliance review.

Communication log -- all emails and SMS sent to this customer

List all per-country group assignments

[
  {
    "country": "DE",
    "group_id": "uuid",
    "group_name": "EU Standard",
    "note": "EU regulation",
    "updated_at": "..."
  }
]

Set or update the default group for a country

ISO 3166-1 alpha-2 (2 chars). Validates group exists. Upserts on country code.

{
  "group_id": "uuid",
  "note": "EU regulation"
}

Remove mapping -- country reverts to platform default group

List all available integrations in the platform catalog

[
  {
    "slug": "sendgrid",
    "category": "email",
    "display_name": "SendGrid",
    "description": "Transactional email via SendGrid API",
    "credential_schema": {
      "api_key": {
        "type": "string",
        "required": true
      }
    },
    "config_schema": {},
    "is_available": true
  }
]

Single catalog entry by slug

List all activated integrations for this broker

Credentials are masked in the response.

Single active integration with masked credentials and health status

{
  "id": "uuid",
  "slug": "sendgrid",
  "category": "email",
  "display_name": "SendGrid",
  "is_active": true,
  "health_status": "healthy",
  "health_message": "OK",
  "last_health_check": "2026-03-19T10:00:00Z",
  "config": {},
  "credentials_summary": {
    "api_key": "SG.***redacted***"
  },
  "activated_at": "2026-03-10T12:00:00Z"
}

Activate an integration with credentials

One provider per category -- activating a second email provider returns 409.

{
  "credentials": {
    "api_key": "SG.xxx"
  },
  "config": {}
}

{
  "slug": "sendgrid",
  "category": "email",
  "is_active": true,
  "activated_at": "..."
}

Deactivate an integration

Update credentials for an active integration

Re-encrypts at rest, resets health status, invalidates connector pool cache.

{
  "credentials": {}
}

Update configuration for an active integration

Non-credential settings.

{
  "config": {}
}

Test connector health

If credentials provided in body, tests with those temporarily (no storage). Otherwise tests with stored credentials.

{
  "credentials": {}
}

{
  "status": "success",
  "message": "..."
}

Execute an action through the active provider for a category

Send an email via the active email provider

Provider-agnostic send endpoint. All fields except `to`, `subject` are optional. `from_email`/`from_name` fall back to `EMAIL_FROM_ADDRESS`/`EMAIL_FROM_NAME` env vars.

{
  "to": "[email protected]",
  "subject": "Welcome to trading",
  "body_html": "<p>Hello John</p>",
  "body_text": "Hello John",
  "from_email": "[email protected]",
  "from_name": "Broker Support",
  "reply_to": "[email protected]",
  "cc": [],
  "bcc": [],
  "tags": {
    "campaign": "onboarding"
  },
  "customer_id": "uuid",
  "event_type": "welcome"
}

{
  "message_id": "...",
  "status": "sent",
  "provider": "sendgrid"
}

Send an SMS via the active SMS provider

`from_number` falls back to `SMS_FROM_NUMBER` env var.

{
  "to": "+447700900000",
  "body": "Your verification code is 123456",
  "from_number": "+15551234567",
  "tags": {
    "type": "verification"
  },
  "customer_id": "uuid",
  "event_type": "verification"
}

{
  "message_id": "...",
  "status": "sent",
  "provider": "twilio_sms"
}

Initiate a phone call via the active VoIP provider

`from_number` falls back to `CALL_FROM_NUMBER` env var.

{
  "to": "+447700900000",
  "from_number": "+15551234567",
  "from_agent_id": "uuid",
  "customer_id": "uuid",
  "metadata": {
    "reason": "follow_up"
  }
}

{
  "call_id": "...",
  "status": "initiated",
  "provider": "zadarma"
}

Provider names and sender defaults

No credentials exposed. Used by frontend to show current configuration.

{
  "email": {
    "provider": "sendgrid",
    "from_address": "[email protected]",
    "from_name": "Broker"
  },
  "sms": {
    "provider": "twilio_sms",
    "from_number": "+15551234567"
  },
  "call": {
    "provider": "zadarma",
    "from_number": "+15559876543"
  }
}

Inbound delivery status from email provider

Provider delivery status callback (e.g., `sendgrid`). Verified via provider-specific HMAC signatures.

Inbound delivery status from SMS provider

Provider delivery status callback (e.g., `twilio_sms`). Verified via provider-specific HMAC signatures.

Inbound call completion status from VoIP provider

Provider callback (e.g., `zadarma`, `voiso`). Verified via provider-specific HMAC signatures.

Generic webhook handler for payment and KYC providers

Connector verifies HMAC, processes payload, forwards to account-service. - **Payment flow**: Verifies -> forwards to `POST /transactions/payment-callback` with `{cashier_id, status, gateway_payload}` - **KYC flow (sumsub)**: Verifies `x-payload-digest` -> maps status -> fetches doc details -> signs and forwards to `POST /webhooks/kyc`

Create a BridgerPay cashier session

Called internally by account-service during `POST /payments/bridgerpay/session`. Requires active BridgerPay integration.

{
  "order_id": "bp_abc123",
  "amount": 500,
  "currency": "USD",
  "email": "[email protected]",
  "first_name": "Omar",
  "last_name": "Al-Rashid",
  "country": "AE",
  "phone": "+971501234567",
  "customer_id": "uuid"
}

{
  "cashier_token": "abc123...",
  "cashier_session_id": "...",
  "cashier_key": "..."
}

Integration activity log

Actions: `activated`, `deactivated`, `credentials_updated`, `config_updated`, `health_check_passed`, `health_check_failed`, `execute_success`, `execute_failure`, `webhook_received`.

Register a new affiliate webhook endpoint

{
  "affiliate_id": "partner_acme",
  "endpoint_url": "https://acme-affiliates.com/api/webhook",
  "secret": "hmac-secret-key",
  "batch_size_max": 500
}

List all registered webhooks

Single webhook

Update a webhook

Updatable fields: `endpoint_url`, `secret`, `is_active`, `batch_size_max`.

Delete a webhook

Delivery attempts (most recent first)

Aggregate delivery statistics

Upcoming economic events

[
  {
    "id": 1,
    "event_name": "Business NZ PMI",
    "country": "New Zealand",
    "currency": "NZD",
    "category": "Manufacturing PMI",
    "impact": "medium",
    "event_date": "2026-03-13T03:30:00Z",
    "actual": null,
    "forecast": null,
    "previous": 55.2
  }
]

List recent stopout force-close events

For dealing room / risk monitoring.

{
  "id": 1,
  "login": 10001,
  "order_ticket": 100042,
  "symbol": "EURUSD",
  "margin_level_at_trigger": 18.5,
  "margin_level_after_close": 45.2,
  "equity_at_trigger": 450.2,
  "profit_realized": -125.3,
  "close_price": 1.08542,
  "stopout_level": 20,
  "positions_remaining": 2,
  "created_at": "2026-03-11T14:30:00Z"
}

Immutable audit trail of financial state changes

{
  "id": 1,
  "entity_type": "order",
  "entity_id": "100042",
  "action": "open",
  "login": "10001",
  "details": {
    "symbol": "EURUSD",
    "volume": 0.1,
    "cmd": 0
  },
  "balance_before": 10000,
  "balance_after": 10000,
  "credit_before": 0,
  "credit_after": 0,
  "margin_used_before": 0,
  "margin_used_after": 108.54,
  "source_service": "order-service",
  "created_at": "2026-03-11T14:30:00Z"
}

Live account state via Server-Sent Events

Opens an SSE stream for real-time account state updates. Connect using `EventSource` in the browser. **Event format:** ``` event: state data: {"balance": 10000.0, "credit": 0.0, "equity": 10250.5, "pnl": 250.5, "margin_used": 500.0, "free_margin": 9750.5, "margin_level": 2050.1, "gross_exposure": 10854.2, "net_exposure": 5427.1, "currency": "USD"} ```

{
  "balance": 10000,
  "credit": 0,
  "equity": 10250.5,
  "pnl": 250.5,
  "margin_used": 500,
  "free_margin": 9750.5,
  "margin_level": 2050.1,
  "gross_exposure": 10854.2,
  "net_exposure": 5427.1,
  "currency": "USD"
}