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

AI-Trader runs eleven distinct asynchronous background loops—from price refreshes to team mission settlements—all defined in 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, this loop also refreshes the trending cache stored under the key trending:top20 in 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 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, 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, 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 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. 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.

# 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:

# .env

AI_TRADER_BACKGROUND_TASKS=prices,profit_history,market_news,macro_signals

Manual Price Refresh

For testing or one-off updates:

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:

from service.server.cache import get_json

trending = get_json("trending:top20")

Summary

• AI-Trader background tasks are defined in 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.
• 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 for stateless database connections and 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 (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 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 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, 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.

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