# AI-Trader Background Tasks: Price Updates, Profit History, Settlements, and Market Intel Explained

> Explore AI-Trader's background tasks including price updates, profit history, settlements, and market intel. Learn how these tasks ensure accurate trading data and financial consistency.

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

---

**AI-Trader runs eleven distinct asynchronous background loops—from price refreshes to team mission settlements—all defined in [`service/server/tasks.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/tasks.py) and registered in `BACKGROUND_TASK_REGISTRY` to keep trading data accurate and financially consistent.**

The AI-Trader platform relies on a robust task scheduling system to maintain real-time market data and agent portfolios. These **AI-Trader background tasks** handle everything from updating token prices to settling Polymarket contracts, ensuring the system remains stateless and scalable across worker processes.

## Core Financial Tasks

### Position Price Updates

The **`prices`** task pulls the latest market data for every distinct position and updates the `current_price` field in the `positions` table. Implemented in `update_position_prices()` at lines 22–112 of [`service/server/tasks.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/tasks.py), this loop also refreshes the trending cache stored under the key `trending:top20` in [`service/server/cache.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/cache.py).

By default, this runs every `POSITION_REFRESH_INTERVAL` seconds (300 seconds) after an initial 5-second delay. The task utilizes `asyncio.to_thread` to invoke the synchronous `get_price_from_market` helper from [`service/server/price_fetcher.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/price_fetcher.py) without blocking the event loop.

### Profit History Snapshots

The **`profit_history`** task computes each agent’s total value (cash plus position value) and stores a snapshot in the `profit_history` table. Found at lines 124–202 in [`service/server/tasks.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/tasks.py), the `record_profit_history()` function runs on the same interval as price updates by default. After insertion, it prunes historical data according to retention policies defined by environment variables like `PROFIT_HISTORY_DAILY_WINDOW_DAYS`.

## Settlement Operations

### Polymarket Contract Settlement

The **`polymarket_settlement`** task detects resolved Polymarket contracts and handles financial reconciliation. Located at lines 206–286 in [`service/server/tasks.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/tasks.py), `settle_polymarket_positions()` credits settlement proceeds to owning agents, writes an immutable entry to `polymarket_settlements`, and deletes the original position. This runs every `POLYMARKET_SETTLE_INTERVAL` seconds (default 300) after a 10-second startup pause.

### Challenge Resolution

The **`challenge_settlement`** loop checks for challenges whose end times have passed and settles them accordingly. Implemented in `settle_challenges_loop()` at lines 316–332, this task updates winner and loser balances every `CHALLENGE_SETTLE_INTERVAL` seconds (default 120).

### Team Mission Coordination

AI-Trader manages collaborative trading through three coordinated settlement tasks:
- **`team_mission_form`**: Forms teams for pending missions once enough participants join, implemented in `form_team_missions_loop()` at lines 332–354, running every `TEAM_MISSION_FORM_INTERVAL` seconds (default 180).
- **`team_contribution_score`**: Scores new submissions via `score_team_contributions_loop()` (lines 358–382) every `TEAM_CONTRIBUTION_SCORE_INTERVAL` seconds.
- **`team_mission_settlement`**: Settles completed missions and awards rewards through `settle_team_missions_loop()` at lines 386–416 every `TEAM_MISSION_SETTLE_INTERVAL` seconds (default 180).

## Market Intel and External Data

The **market intel** category encompasses four data-fetching tasks that interface with [`service/server/market_intel.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/market_intel.py) to perform external API calls:

- **`market_news`**: Fetches headlines and categories via `refresh_market_news_snapshots_loop()` (lines 142–165), running every `MARKET_NEWS_REFRESH_INTERVAL` seconds (default 3600).
- **`macro_signals`**: Retrieves economic indicators using `refresh_macro_signal_snapshots_loop()` (lines 169–191) on the same hourly interval.
- **`etf_flows`**: Pulls ETF direction and flow data via `refresh_etf_flow_snapshots_loop()` (lines 195–218) every `ETF_FLOW_REFRESH_INTERVAL` seconds (default 3600).
- **`stock_analysis`**: Updates featured analyst reports through `refresh_stock_analysis_snapshots_loop()` (lines 222–250) every `STOCK_ANALYSIS_REFRESH_INTERVAL` seconds (default 7200).

These tasks cache results for quick API consumption and log insert/error counts for monitoring.

## Task Registry and Configuration

All **AI-Trader background tasks** are registered in the `BACKGROUND_TASK_REGISTRY` dictionary at lines 88–100 of [`service/server/tasks.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/tasks.py). The `start_background_tasks()` function (lines 177–184) creates an `asyncio.Task` for each enabled entry when the worker process starts.

Task selection is controlled by the **`AI_TRADER_BACKGROUND_TASKS`** environment variable. If unset, the system defaults to `DEFAULT_BACKGROUND_TASKS`. The helper `get_enabled_background_task_names()` (lines 111–115) parses this comma-separated list and validates entries against the registry.

```python

# From service/server/tasks.py

def get_enabled_background_task_names() -> list[str]:
    raw = os.getenv("AI_TRADER_BACKGROUND_TASKS", DEFAULT_BACKGROUND_TASKS)
    names = [item.strip() for item in raw.split(",") if item.strip()]
    return [name for name in names if name in BACKGROUND_TASK_REGISTRY]

```

### Enabling Specific Tasks

To run only price updates, profit history, and market news:

```bash

# .env

AI_TRADER_BACKGROUND_TASKS=prices,profit_history,market_news,macro_signals

```

### Manual Price Refresh

For testing or one-off updates:

```python
import asyncio
from service.server.tasks import update_position_prices

async def one_shot_update():
    # Run a single iteration

    await update_position_prices().__await__()

asyncio.run(one_shot_update())

```

### Accessing Cached Trending Data

After the price task runs, trending data is available via the cache module:

```python
from service.server.cache import get_json

trending = get_json("trending:top20")

```

## Summary

- **AI-Trader background tasks** are defined in [`service/server/tasks.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/tasks.py) and managed through the `BACKGROUND_TASK_REGISTRY` at lines 88–100.
- **Price and profit tasks** update position values and record historical snapshots every 300 seconds by default via `update_position_prices()` and `record_profit_history()`.
- **Settlement tasks** handle Polymarket resolutions, challenge outcomes, and team mission settlements automatically through dedicated loops in [`service/server/tasks.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/tasks.py).
- **Market intel loops** fetch external news, macro signals, ETF flows, and stock analysis on hourly or bi-hourly schedules.
- Configuration is environment-driven via `AI_TRADER_BACKGROUND_TASKS`, allowing selective enablement of specific loops without code changes.
- The system uses [`service/server/database.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/database.py) for stateless database connections and [`service/server/worker.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/worker.py) to orchestrate the async event loop.

## Frequently Asked Questions

### How do I disable specific background tasks in AI-Trader?

Set the `AI_TRADER_BACKGROUND_TASKS` environment variable to a comma-separated list of only the tasks you want to run. For example, `AI_TRADER_BACKGROUND_TASKS=prices,profit_history` will disable all market intel and settlement operations. The `get_enabled_background_task_names()` function in [`service/server/tasks.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/tasks.py) (lines 111–115) validates these entries against the `BACKGROUND_TASK_REGISTRY` at startup.

### Where are the default intervals for these tasks defined?

Default intervals are defined as environment variables with fallback defaults in the task implementations. For instance, `POSITION_REFRESH_INTERVAL` defaults to 300 seconds, `POLYMARKET_SETTLE_INTERVAL` to 300 seconds, and `MARKET_NEWS_REFRESH_INTERVAL` to 3600 seconds. Check [`service/server/config.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/config.py) for the `_env_int` helper used to parse these values.

### Can I run the price update task manually outside the loop?

Yes. Import `update_position_prices` from [`service/server/tasks.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/tasks.py) and await it directly. The function is a coroutine that normally runs indefinitely with a sleep interval, so for one-shot execution you should call it once and handle the iteration logic yourself or break after the first update cycle.

### What happens if a background task fails during execution?

The tasks are designed to be stateless between iterations. Each loop reads fresh data from the database via `get_db_connection()` from [`service/server/database.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/database.py), performs its atomic work, and sleeps. If a task crashes, the worker process can restart it without corrupting state, though specific error handling depends on the async event loop configuration in [`service/server/worker.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/worker.py).