Nexus API Documentation

Overview

TrainFlow Nexus is an autonomous trading intelligence engine that organisations license to embed AI-powered market analysis, signal generation, risk management, and execution into their own trading products — under their own brand.

Nexus operates continuously. It evaluates markets on a defined cycle, forms a structured view per instrument, and when conditions are met, generates a signal with a full reasoning chain. In autonomous mode it then executes, manages, and closes positions — calibrating size and risk independently for every connected account. In intelligence mode it delivers the signal and reasoning directly to the provider's UI.

What is Nexus

Nexus is not a signal subscription service. It is a production-grade autonomous system that:

• Monitors markets 24/7 across Forex, indices, crypto, and volatility instruments
• Generates one AI decision per instrument per cycle, fanned out to all subscribed accounts
• Calculates per-account position size deterministically based on balance, risk policy, and signal levels
• Executes, monitors, and actively manages positions — not just places orders
• Exits proactively when the market thesis changes, before SL or TP is reached
• Tracks equity performance per instrument and continuously refines through live observation

Integration Modes

All integrations fall into one of two modes.

Authentication

Nexus uses two credential types: organisation API keys for server-to-server calls from your backend, and user tokens for calls made in the context of a specific end user. Both are passed as Bearer tokens in the Authorization header.

Overview

API Keys

Organisation API keys are issued per environment. Keys are prefixed to indicate their environment — tf_live_ for production and tf_sandbox_ for testing. The key itself is only shown once at creation — store it securely.

// All API requests from your backend
Authorization: Bearer tf_live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

// Key scopes
// intelligence.read    — read pair states, signals, opportunities
// execution.write      — connect accounts, approve/dismiss signals
// risk.write           — configure risk profiles
// admin                — manage org settings, webhooks, users

User Tokens

When a provider's end user interacts with Nexus through your frontend, requests are made with a short-lived user token. Your backend obtains this token by exchanging the user's authenticated session with Nexus — Nexus maps your internal user ID to a scoped Nexus identity.

// Your backend — exchange user session for a scoped Nexus user token
POST /v1/auth/sessions
Authorization: Bearer tf_live_xxxx   (your org API key)
{
  "external_user_id": "your_internal_user_id_456",
  "permissions": ["intelligence.read", "execution.write"],
  "expires_in": 3600
}

// Response
{
  "user_token": "tf_usr_xxxxxxxxxxxx",
  "expires_at": "2026-09-24T15:00:00Z"
}

// Your frontend uses this token for per-user calls
Authorization: Bearer tf_usr_xxxxxxxxxxxx

Architecture

Nexus is built around one core principle: the intelligence layer makes one decision per instrument per cycle, then a deterministic execution and risk system fans that decision out to all interested accounts concurrently. The intelligence never scales with user count — only execution does.

System Layers

┌─────────────────────────────────────────────────┐
│              MARKET DATA LAYER                  │
│  Continuous ingestion from connected broker     │
│  feeds across all watched instruments           │
└────────────────────┬────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────┐
│           FEATURE COMPUTATION ENGINE            │
│  Pre-computed market state per instrument and   │
│  timeframe — updated incrementally on candle    │
│  close. Multi-timeframe confluence computed     │
│  before the intelligence layer ever runs.       │
│  Hot state served from cache.                   │
└────────────────────┬────────────────────────────┘
                     │  candle close event
                     ▼
┌─────────────────────────────────────────────────┐
│          NEXUS INTELLIGENCE ENGINE              │
│  One AI decision per instrument per cycle       │
│  Structured reasoning → constrained JSON output │
│  Decision validator enforces geometry rules     │
└────────────────────┬────────────────────────────┘
                     │  validated signal
                     ▼
┌─────────────────────────────────────────────────┐
│               SIGNAL ROUTER                     │
│  Fans signal to all subscribed accounts         │
│  Parallel dispatch — one job per account        │
│  Idempotency key per signal + account pair      │
└────────────────────┬────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────┐
│          NEXUS RISK INTELLIGENCE                │
│  Per-account: validates, sizes, approves        │
│  12-check deterministic policy enforcement      │
│  Human approval gates available per plan        │
└────────────────────┬────────────────────────────┘
                     │  approved execution job
                     ▼
┌─────────────────────────────────────────────────┐
│          EXECUTION ADAPTER LAYER                │
│  Broker-agnostic interface                      │
│  MT4 · MT5 · cTrader · Crypto · Custom API     │
└─────────────────────────────────────────────────┘

Full Autonomous Flow

CANDLE CLOSE
      │
      ▼
Pre-computed market state loaded from cache
      │
      ▼
Nexus Intelligence evaluates instrument
  → signal: { action, entry, sl, tp, confidence, reasoning, valid_until }
      │
  [hold] ─────────────────────── Updates pair state · no execution
      │
  [entry signal]
      │
      ▼
Signal Router fans out to all subscribed accounts (concurrent)
      │
      ▼  per account
Nexus Risk Intelligence
  → 12-check pre-trade validation
  → Position size calculation per account balance and policy
  → APPROVED or REJECTED (machine-readable reason code)
      │
  [REJECTED] ──────────────────── Activity log · push notification
      │
  [APPROVED]
      │
      ▼
Execution Adapter places order at broker
      │
      ▼
Nexus begins active position management
  → Evaluates market structure on each cycle while position is open
  → Exits proactively if conditions invalidate the original thesis
  → Closes at configured levels if the market moves as expected
      │
      ▼
Position closed → P&L recorded → Equity snapshot updated
      │
      ▼  (async — does not block the execution path)
  Push notification · Telegram alert · Activity event · Webhook delivery

Active Position Management

Nexus does not place a trade and walk away. Once a position is open, the same intelligence engine that entered the trade continues evaluating market conditions on every cycle. If the thesis that generated the entry is no longer valid — due to a structural shift, opposing momentum, or regime change — Nexus can exit before configured levels are reached.

This is a core differentiator from traditional signal services. Active management behaviour is governed by the user's trading profile and risk configuration. Providers can expose these controls to their end users or enforce platform-level defaults.

Continuous Learning

Nexus reasoning is not static. TrainFlow continuously evaluates engine performance against real trade outcomes — tracking R:R realised versus projected, signal quality by instrument and regime, and thesis consistency across cycles. This feeds periodic model refinements before they reach production.

The evaluation pipeline includes a controlled testing environment where candidate changes run against real-time market conditions on paper accounts before any production promotion. Regressions on any tracked dimension block deployment automatically.

Intelligence Layer

The Intelligence Layer is the foundation of both integration modes. Users select the instruments they want Nexus to watch and a trading profile that governs how the engine interprets market conditions. Nexus then monitors continuously and delivers structured intelligence to the provider's UI.

Pair Selection

Configure the watchlist and trading profile with a single call. The engine begins monitoring from the next cycle. Instrument limits start at 100 and scale with the organisation's plan — custom expansion is available.

{
  "watchlist": ["XAUUSD", "EURUSD", "NAS100", "BTCUSDT"],
  "trading_profile": "day_trader",
  "account_id": "acc_abc",
  "auto_execute": false,
  "sizing_override": { "mode": "risk", "value": 1.0 },
  "notify_realtime": true,
  "notify_push": true
}

// Response
{
  "success": true,
  "subscription": {
    "watchlist": ["XAUUSD", "EURUSD", "NAS100", "BTCUSDT"],
    "trading_profile": "day_trader",
    "auto_execute": false
  },
  "active_account_id": "acc_abc",
  "max_pairs": 100
}

Trader Profiles

The profile shapes how Nexus reasons — timeframe priority, patience before signalling, and expected holding period. Risk is governed separately.

Nexus Mind Response

After each cycle, the full intelligence state for every monitored instrument is available. This is the payload your UI renders — signal, confidence, structural context, zone state, and the reasoning chain.

{
  "success": true,
  "items": [
    {
      "symbol": "XAUUSD",
      "primary_tf": "30m",
      "bias": "bullish",
      "confidence": 87,
      "expected_path": "Continuation after retest of structural support — target above",
      "invalidation": "Hourly close below the most recent swing low",
      "zones": [
        {
          "type": "demand",
          "side": "buy",
          "low": 3648.2,
          "high": 3651.0,
          "freshness": "fresh",
          "invalid_if": "Hourly close below zone origin"
        }
      ],
      "nexus": {
        "signal": "hold",
        "brief": "XAUUSD · hold · Bullish structure intact. Watching for retest of support zone.",
        "at_utc": "2026-09-24T09:30:00Z",
        "reasonings": [
          {
            "at_gmt": "2026-09-24 10:30 WAT",
            "signal": "hold",
            "justification": "Structure remains bullish on the primary timeframe. Price is mid-air above the demand zone — no valid entry without a confirmed retest and pattern confirmation at the level. Watching for the setup to form.",
            "levels": null,
            "wait_for": "Confirmed retest of demand zone with directional confirmation"
          }
        ]
      },
      "updated_at": "2026-09-24T09:30:12Z"
    }
  ],
  "nexus_trades_today": 1,
  "nexus_trade_cap": 5
}

Opportunities Feed

When Nexus produces an actionable entry signal it enters the user's opportunity queue. Providers surface this as a trade card the user can review, dismiss, or snooze.

{
  "success": true,
  "items": [
    {
      "queue_id": "q_01HX...",
      "symbol": "XAUUSD",
      "direction": "long",
      "entry": 3652.4,
      "sl": 3647.8,
      "tp1": 3665.0,
      "confidence": 87,
      "signal_kind": "entry",
      "analysis_summary": "Strong structural setup with confluence at the demand zone. Risk/reward above threshold.",
      "status": "pending",
      "detected_at": "2026-09-24T09:31:00Z",
      "expires_at": "2026-09-24T21:31:00Z"
    }
  ]
}

// Intelligence Layer — dismiss after user has noted the levels
POST /v1/market-scout/opportunities/{queue_id}/dismiss
// → marks signal as seen, removes from queue, no order placed

// Autonomous Execution — approve triggers the execution engine
POST /v1/market-scout/opportunities/{queue_id}/approve
{ "mode": "full", "sizing_mode": "risk", "sizing_value": 1.0 }
// → risk engine validates → broker order placed

In Intelligence Layer mode the levels in the signal — entry, sl, tp1 — are the exact levels the user needs to place a trade manually in their own platform. The provider's UI should present these clearly alongside the reasoning so the user can act confidently. No broker account connection is needed to receive and display these signals.

Autonomous Execution

In Autonomous Execution mode, Nexus connects to broker accounts, applies risk controls per account, and manages the full trade lifecycle — entry, active management, and exit — without user intervention.

Account Connection

Nexus supports multiple broker connectivity models. For providers who already operate their own execution infrastructure, Nexus can route execution instructions directly to a custom endpoint — your engine, your execution, Nexus supplies the intelligence and sizing.

Execution Flow

Once a signal passes risk validation, Nexus dispatches to the broker adapter. The response is normalised across all supported platforms.

// Execution result (normalised across all broker types)
{
  "success": true,
  "execution_id": "exe_01HX...",
  "account_id": "acc_abc",
  "symbol": "XAUUSD",
  "action": "BUY",
  "volume_lots": 0.18,
  "executed_price": 3652.6,
  "stop_loss": 3647.8,
  "take_profit": 3665.0,
  "broker_order_id": "44440719",
  "status": "placed",
  "duration_ms": 380
}

Broker Adapters

The execution layer is broker-agnostic. A common adapter interface abstracts all supported platforms.

Nexus Risk Intelligence

Every trade Nexus executes passes through a structured risk evaluation layer before reaching the broker. This system operates independently of the intelligence engine — it does not interpret markets, it enforces policy. The result is a clean boundary: Nexus Intelligence decides what to do; Nexus Risk Intelligence decides whether and how each account can do it.

Overview

The risk layer calibrates position size to each individual account. Two accounts receiving the same signal will receive completely different order sizes based on their balance, equity, configured risk tolerance, and current exposure. As account equity grows or shrinks, sizing adjusts accordingly.

For accounts where a high-confidence signal meets a threshold, and the equity profile warrants it, Nexus can invoke an additional evaluation pass — incorporating broader context before committing. Human approval gates are also available: providers can configure conditions under which a trade is queued for user confirmation rather than auto-executed.

Sizing Modes

Nexus supports multiple position sizing modes to cover the full range of account types — from standard Forex/indices through to crypto spot and perpetuals. The mode is set via sizing_override and can be configured per account.

// Sizing configuration examples
//
// Standard Forex / indices — risk-based
{ "mode": "risk", "value": 1.0 }           // 1% of equity per trade
{ "mode": "risk", "value": 0.5 }           // 0.5% — more conservative
//
// Crypto spot — allocation-based
{ "mode": "allocation", "value": 15.0 }    // 15% of equity as buying power
//
// Crypto spot — fixed USDT amount
{ "mode": "usdt_amount", "value": 200 }    // $200 USDT per trade
//
// Crypto spot — fixed quantity
{ "mode": "quantity", "value": 0.005 }     // 0.005 BTC per trade
//
// Fixed lot — any platform (use carefully)
{ "mode": "fixed_lot", "value": 0.01 }     // 0.01 lots always

Configuration

Risk is configured per user subscription. All fields are optional — Nexus applies safe defaults where not set.

PUT /v1/market-scout
{
  "sizing_override": { "mode": "risk", "value": 1.0 },
  "auto_execute": true,
  "auto_execute_min_confidence": 80,
  "auto_execute_exits": true,

  // Account-level limits
  "max_drawdown_pct": 8.0,       // halt if overall drawdown exceeds this
  "daily_loss_limit_pct": 2.0,   // halt for the day if daily loss exceeds this
  "max_risk_per_trade_pct": 2.0, // hard cap per trade regardless of sizing mode
  "max_open_positions": 3,       // max concurrent open positions
  "weekend_close_forex": true    // close all forex positions before weekend
}

Pre-Trade Validation

Before every execution the risk layer runs a structured validation sequence. Failed checks return a machine-readable reason code pushed to the activity feed.

1. 01Account active and connected to broker
2. 02Instrument available on this account
3. 03Market currently open
4. 04Signal not already processed for this account (idempotency)
5. 05Daily loss limit not exceeded
6. 06Overall drawdown limit not exceeded
7. 07Available margin sufficient for calculated position
8. 08Open position count below configured maximum
9. 09Current spread within acceptable range
10. 10No high-impact event within the protection window
11. 11Within the configured trading session hours
12. 12Calculated position size above broker minimum

// Rejection event pushed to activity feed
{
  "event": "RISK_REJECTED",
  "reason_code": "DAILY_DRAWDOWN_EXCEEDED",
  "message": "Trading paused for today — the daily loss limit has been reached. Nexus will resume at the next session open.",
  "signal_id": "sig_01HX...",
  "account_id": "acc_abc",
  "timestamp": "2026-09-24T14:22:00Z"
}

Events & Streaming

Nexus delivers real-time updates via a persistent SSE stream. Outbound webhooks are available for Autonomous Execution integrations.

Real-Time Stream

Open a persistent connection to receive signal events, execution confirmations, risk rejections, and Nexus Mind updates as they happen.

// Authorization header only — never a query parameter
GET /v1/orchestrator/status/stream
Authorization: Bearer <user_token>

// Event types:
//   connected          — stream confirmed open
//   orchestrator_state — signal ready, execution update, mind updated
//   heartbeat          — keepalive every ~3s
//   error              — stream-level failure

event: orchestrator_state
data: {
  "type": "orchestrator_state",
  "state": "SIGNAL_READY",
  "message": "XAUUSD — entry signal confirmed. Awaiting execution.",
  "timestamp": "2026-09-24T09:31:00Z"
}

Signal Lifecycle

Webhooks

Register a webhook URL to receive push events. All deliveries include an HMAC signature for verification.

POST https://your-platform.com/webhooks/nexus
Content-Type: application/json
X-Nexus-Signature: sha256=<hmac>

{
  "id": "evt_01HX...",
  "type": "order.executed",
  "created_at": "2026-09-24T09:45:11Z",
  "data": {
    "execution_id": "exe_01HX...",
    "account_id": "acc_abc",
    "symbol": "XAUUSD",
    "action": "BUY",
    "volume_lots": 0.18,
    "executed_price": 3652.6
  }
}

// Available events:
//   signal.created         new entry signal generated
//   signal.expired         validity window passed
//   order.executed         trade placed at broker
//   order.rejected         risk layer rejected (with reason_code)
//   position.closed        exited (with realised P&L)
//   risk.limit_reached     daily or overall drawdown limit hit

Hosting Models

Nexus supports three deployment configurations depending on whether the provider already has execution infrastructure.

Model A — Intelligence Only

Your platform receives Nexus intelligence and renders it in your own UI. No trading account connection required on the Nexus side.

Provider Backend  →  Nexus Intelligence API
                         │
                  Instrument states + Nexus Mind + Signals
                         │
                  Provider UI → your users

Model B — Nexus-Managed Execution

Nexus manages the full trade lifecycle end-to-end. Users connect accounts, configure risk, and Nexus handles everything under your brand.

Provider Platform  →  Nexus Intelligence + Risk + Execution
                              │
                     Manages broker connections
                              │
                    Fills · Management · Exits · P&L
                              │
                         Provider UI

Model C — Custom Execution

For providers who already operate execution infrastructure. Nexus supplies the intelligence and risk-validated sizing instruction — your systems place the order.

Nexus Intelligence + Risk Intelligence
        │  structured execution instruction
        ▼
Provider Execution Infrastructure
        │
Proprietary Broker / Exchange / Prime Brokerage

// Instruction shape
{
  "instruction_id": "ins_01HX...",
  "signal_id":      "sig_01HX...",
  "account_ref":    "your_internal_account_id",
  "action":         "BUY",
  "symbol":         "XAUUSD",
  "volume_lots":    0.18,
  "stop_loss":      3647.8,
  "take_profit":    3665.0,
  "idempotency_key":"sig_01HX:your_account_ref",
  "expires_at":     "2026-09-24T09:36:00Z"
}

AI Model Benchmarking

TrainFlow operates a structured AI benchmarking programme. Every model considered for production use is evaluated rigorously — not against synthetic prompts, but against the same real market conditions the engine faces live. Financial institutions use these results to make informed decisions about which AI systems can be trusted with real capital.

What We Measure

Live Performance Testing

Beyond static benchmarks, every candidate model is evaluated in a controlled live environment before production consideration. TrainFlow operates an internal testing environment — the Arena — where models run against real-time market data on paper accounts. The Arena provides:

• Real-time signal generation against live market conditions — not historical replays
• Full trade lifecycle tracking: entry, active management, exit, and realised P&L
• R:R performance measured against projected at the moment of signal generation
• Concurrent multi-model comparison across the same instruments and timeframes
• Automated regression detection — degradation on any tracked dimension blocks deployment
• Cross-regime backtests to verify consistency outside current market conditions
• Instrument-family performance profiles — a model strong on indices may underperform on crypto volatility instruments
• Latency profiling under load — decision freshness across burst candle-close events with 100+ instruments running simultaneously

Model Selection

TrainFlow selects the inference model for every Nexus decision cycle. Selection is based on current benchmark standing, cost-efficiency, latency under load, and instrument-specific performance profiles. Model details are not disclosed publicly — this is a core part of how we protect the quality of the intelligence layer.

Enterprise integrations can optionally engage with the benchmarking programme as part of onboarding — receiving a structured performance report for their specific instrument set and trading profile before going live.

Quickstart

From credentials to your first Nexus signal in under 10 minutes.

First Signal — Intelligence Layer

1 — Authenticate

Authorization: Bearer tf_live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

2 — Configure watchlist

{
  "watchlist": ["XAUUSD", "EURUSD", "NAS100"],
  "trading_profile": "day_trader",
  "notify_realtime": true
}

3 — Open the real-time stream

GET /v1/orchestrator/status/stream
Authorization: Bearer <user_token>

// Receive:
//   event: connected — stream open
//   event: orchestrator_state — on every Nexus cycle per instrument
//     state: "SIGNAL_READY"   when entry signal generated
//     state: "MIND_UPDATED"   when thesis updated without entry

4 — Read instrument states

// Returns Nexus Mind state for every instrument in the watchlist:
// signal, confidence, structural context, reasoning chain, wait conditions

First Execution — Autonomous Mode

5 — Connect a broker account

// Choose the connection method for the broker type:
POST /v1/broker/connect/oauth          // OAuth flow (e.g. cTrader)
POST /v1/broker/connect/credentials    // Login + server (e.g. MT5/MT4)
POST /v1/broker/connect/custom         // Custom execution endpoint

// All return a normalised account object:
{
  "account_id": "acc_abc",
  "platform": "mt5",
  "currency": "USD",
  "balance": 10000,
  "equity": 10000,
  "status": "connected"
}

6 — Enable auto-execute

{
  "auto_execute": true,
  "auto_execute_min_confidence": 80,
  "sizing_override": { "mode": "risk", "value": 1.0 }
}

// Nexus now:
//   Monitors watchlist continuously
//   Generates signals when conditions are met
//   Validates risk per account (12-check sequence)
//   Executes at the broker
//   Actively manages the open position
//   Closes when thesis resolves or conditions invalidate