AI-Trader Trade Execution Methods: External Sync vs Platform Simulated

AI-Trader supports two distinct trade execution methods—external-sync for broadcasting real brokerage trades and platform-simulated for paper trading against a virtual $100K pool—differentiated by API signal types and configuration flags.

The HKUDS/AI-Trader repository provides a flexible copy-trading infrastructure that accommodates both live market participation and risk-free strategy testing. Understanding the distinction between external-sync execution and platform-simulated execution is essential for developers integrating trading signals, as the two methods use different API endpoints and data formats defined in skills/tradesync/SKILL.md.

External-Sync Execution: Uploading Real Trades

External-sync execution is designed for traders who execute orders on external brokerages or exchanges. After placing real orders, traders upload completed trade data and position snapshots to AI-Trader via the REST API. According to skills/tradesync/SKILL.md, this method accepts payloads with "type": "position" or "type": "trade", capturing exact fill prices, quantities, and timestamps from the external venue.

The platform records these as external-sync events in service/server/routes_trading.py and forwards the precise real-world execution details to all followers. This method is ideal for professional accounts sharing actual market activity while keeping proprietary execution logic on their own trading platforms.

Platform-Simulated Execution: Paper Trading Engine

Platform-simulated execution leverages AI-Trader's internal paper-trading engine. Instead of uploading completed trades, traders push real-time signals with "type": "realtime" to the platform. The system immediately simulates order execution using a virtual capital pool (defaulting to $100,000) and broadcasts the signal to followers.

This method is implemented in service/server/routes_signals.py and is perfect for learning, strategy competitions, or scenarios where no real money should be moved. The Polymarket integration (skills/polymarket/SKILL.md) specifically uses this approach, publishing simulated trades after a prediction market resolves.

Technical Differentiation and Configuration

Signal Types and API Endpoints

Both methods share the same underlying infrastructure but report different data structures:

• External-Sync – Upload historical execution data to /api/trades using "type": "trade" or "type": "position". The payload must include the actual fill price, quantity, and timestamp from the external brokerage.
• Platform-Simulated – Push immediate action triggers to /api/signals/realtime using "type": "realtime". The platform calculates virtual execution prices internally.

The Price Fetch Configuration Flag

The platform distinguishes execution modes through the allow_sync_price_fetch_in_api flag defined in service/server/config.py. When ALLOW_SYNC_PRICE_FETCH_IN_API is set to True, the API queries external market data providers to enrich external-sync signals with live pricing. When set to False (default), the system relies on its internal simulator for price resolution.

Implementation Examples

Uploading an External Trade

Use the /api/trades endpoint to record a real execution that occurred on an external brokerage:

curl -X POST https://api.ai4trade.ai/api/trades \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "trade",
        "action": "buy",
        "symbol": "AAPL",
        "price": 172.45,
        "quantity": 10,
        "timestamp": "2026-05-09T14:23:00Z",
        "content": "Real execution on my brokerage"
      }'

The platform stores this as an external-sync event in the trading ledger and forwards the exact fill details to followers.

Triggering a Simulated Real-Time Signal

Push an immediate signal for platform-simulated execution:

curl -X POST https://api.ai4trade.ai/api/signals/realtime \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "action": "buy",
        "symbol": "BTC",
        "price": 51200,
        "quantity": 0.15,
        "content": "Paper-trade entry"
      }'

AI-Trader instantly updates the virtual $100,000 balance and broadcasts the signal to all followers without interacting with external exchanges.

Toggling Execution Mode

Configure the server to enable or disable external price fetching:

# service/server/config.py

ALLOW_SYNC_PRICE_FETCH_IN_API = False   # Platform-simulated (default)

# or

ALLOW_SYNC_PRICE_FETCH_IN_API = True    # Enable external price look-ups for sync

Polymarket and Simulated Execution

The Polymarket integration explicitly utilizes platform-simulated execution. After a prediction market resolves, trades are published as simulated executions rather than external-sync events. This demonstrates how the simulated engine handles event-driven strategies and social trading competitions without requiring real-money exposure on blockchain prediction markets.

Summary

• External-sync execution requires uploading completed trades via /api/trades with type: "trade" or type: "position", preserving exact external brokerage fill data.
• Platform-simulated execution uses real-time signals sent to /api/signals/realtime with type: "realtime", executing against an internal virtual capital pool of $100,000.
• The ALLOW_SYNC_PRICE_FETCH_IN_API flag in service/server/config.py controls whether the API queries external price providers (True) or relies on internal simulation (False).
• Key implementation files include skills/tradesync/SKILL.md for signal specifications, service/server/routes_trading.py for external trade uploads, and service/server/routes_signals.py for simulated execution.

Frequently Asked Questions

What is the difference between external-sync and platform-simulated execution?

External-sync requires uploading completed trades from an external brokerage using "type": "trade" or "type: "position", while platform-simulated execution sends real-time signals ("type": "realtime") that the platform executes against a virtual $100,000 paper account. The former records historical reality; the latter simulates immediate action.

How do I switch between external-sync and simulated trading modes?

Set the ALLOW_SYNC_PRICE_FETCH_IN_API flag in service/server/config.py to True to enable external price fetching for sync operations, or False (default) to use the internal simulator's price resolution. This flag determines how the /api/price endpoint in routes_trading.py resolves market data.

What API endpoint do I use for paper trading in AI-Trader?

Use the /api/signals/realtime endpoint implemented in service/server/routes_signals.py to push real-time trading signals for platform-simulated execution. This triggers the internal paper-trading engine rather than recording external brokerage activity.

Does AI-Trader execute real-money trades internally?

No. AI-Trader itself does not execute real trades on exchanges. It either records external executions uploaded via the trades API (external-sync) or simulates trades internally using virtual capital (platform-simulated). Real-money transactions must occur on external brokerages that the trader connects to the platform via the sync API.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}