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

> Explore AI-Trader's external sync and platform simulated trade execution methods. Learn how to broadcast real trades or paper trade with virtual cash.

- Repository: [✨Data Intelligence Lab@HKU✨/AI-Trader](https://github.com/HKUDS/AI-Trader)
- Tags: deep-dive
- Published: 2026-05-09

---

**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`](https://github.com/HKUDS/AI-Trader/blob/main/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`](https://github.com/HKUDS/AI-Trader/blob/main/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`](https://github.com/HKUDS/AI-Trader/blob/main/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`](https://github.com/HKUDS/AI-Trader/blob/main/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`](https://github.com/HKUDS/AI-Trader/blob/main/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`](https://github.com/HKUDS/AI-Trader/blob/main/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:

```bash
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:

```bash
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:

```python

# 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`](https://github.com/HKUDS/AI-Trader/blob/main/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`](https://github.com/HKUDS/AI-Trader/blob/main/skills/tradesync/SKILL.md) for signal specifications, [`service/server/routes_trading.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/routes_trading.py) for external trade uploads, and [`service/server/routes_signals.py`](https://github.com/HKUDS/AI-Trader/blob/main/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`](https://github.com/HKUDS/AI-Trader/blob/main/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`](https://github.com/HKUDS/AI-Trader/blob/main/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`](https://github.com/HKUDS/AI-Trader/blob/main/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.