Environment:HKUDS AI Trader API Credentials

Knowledge Sources	AI-Trader Alpha Vantage API Tushare API
Domains	Infrastructure, Credentials
Last Updated	2026-02-09 14:00 GMT

Overview

API key and credential requirements for the AI-Trader system, including LLM provider keys, market data API tokens, and search service credentials.

Description

The AI-Trader system requires multiple API credentials stored as environment variables (typically in a .env file loaded via python-dotenv). These credentials authenticate against external services for LLM inference, market data retrieval, and web search capabilities. The system uses a layered configuration approach: environment variables can be overridden by per-model settings in the JSON config file.

Usage

Required for any trading workflow. Without the LLM API key, no agent can operate. Without market data keys, no price data can be fetched. Set all required variables in a .env file at the project root before running any commands.

System Requirements

Category	Requirement	Notes
File	`.env` file at project root	Loaded by python-dotenv at startup
Alternative	Per-model config in JSON	`openai_base_url` and `openai_api_key` fields in config

Dependencies

Python Packages

python-dotenv (loads .env file)

Credentials

The following environment variables must be set in .env:

Core (Required)

OPENAI_API_KEY: API key for OpenAI-compatible LLM provider. Validated at agent initialization; raises ValueError if missing.
OPENAI_API_BASE: Base URL for the LLM API endpoint. Optional if using default OpenAI endpoint; required for alternative providers (DeepSeek, Qwen, etc.).

Market Data (Required for data fetching)

ALPHAADVANTAGE_API_KEY: Alpha Vantage API key for US stock and cryptocurrency daily price data. Used in data/get_daily_price.py and data/crypto/get_daily_price_crypto.py.
TUSHARE_TOKEN: Tushare Pro API token for Chinese A-share market data. Only required if using A-stock workflows.

Search (Required for agent reasoning)

JINA_API_KEY: Jina API key for web search tool functionality. Used by agent_tools/tool_jina_search.py.

MCP Service Ports (Optional)

MATH_HTTP_PORT: Port for Math MCP service (default: 8000)
SEARCH_HTTP_PORT: Port for Search MCP service (default: 8001)
TRADE_HTTP_PORT: Port for Trade MCP service (default: 8002)
GETPRICE_HTTP_PORT: Port for Price MCP service (default: 8003)
CRYPTO_HTTP_PORT: Port for Crypto Trade MCP service (default: 8005)

Runtime Configuration (Optional)

RUNTIME_ENV_PATH: Path to runtime environment JSON file (default: data/.runtime_env.json)
AGENT_MAX_STEP: Override maximum agent reasoning steps (default: 30)

Quick Install

# Create .env file at project root
cat > .env << 'ENVEOF'
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_API_BASE=https://api.openai.com/v1
ALPHAADVANTAGE_API_KEY=your_alphavantage_key_here
JINA_API_KEY=your_jina_api_key_here
# Only needed for A-stock market
TUSHARE_TOKEN=your_tushare_token_here
ENVEOF

Code Evidence

API key validation from agent/base_agent/base_agent.py:290-348:

# Set OpenAI configuration
if openai_base_url == None:
    self.openai_base_url = os.getenv("OPENAI_API_BASE")
else:
    self.openai_base_url = openai_base_url
if openai_api_key == None:
    self.openai_api_key = os.getenv("OPENAI_API_KEY")
else:
    self.openai_api_key = openai_api_key

# ... later in initialize():
if not self.openai_api_key:
    raise ValueError(
        "OpenAI API key not set. Please configure OPENAI_API_KEY in environment or config file."
    )

Alpha Vantage key usage from data/get_daily_price.py:117:

APIKEY = os.getenv("ALPHAADVANTAGE_API_KEY")
url = f"https://www.alphavantage.co/query?function={FUNCTION}&symbol={SYMBOL}&outputsize={OUTPUTSIZE}&apikey={APIKEY}"

MCP port configuration from agent_tools/start_mcp_services.py:26-32:

self.ports = {
    "math": int(os.getenv("MATH_HTTP_PORT", "8000")),
    "search": int(os.getenv("SEARCH_HTTP_PORT", "8001")),
    "trade": int(os.getenv("TRADE_HTTP_PORT", "8002")),
    "price": int(os.getenv("GETPRICE_HTTP_PORT", "8003")),
    "crypto": int(os.getenv("CRYPTO_HTTP_PORT", "8005")),
}

Common Errors

Error Message	Cause	Solution
`ValueError: OpenAI API key not set`	OPENAI_API_KEY missing from .env	Add `OPENAI_API_KEY=...` to .env file
`OpenAI base URL not set, using default`	OPENAI_API_BASE not set	Set `OPENAI_API_BASE` if using non-OpenAI provider
Alpha Vantage returns `Note` or `Information` key	API rate limit exceeded or invalid key	Check ALPHAADVANTAGE_API_KEY; free tier is 25 req/day
`RUNTIME_ENV_PATH not set, config value not persisted`	RUNTIME_ENV_PATH env var missing	Set `RUNTIME_ENV_PATH=data/.runtime_env.json` in .env

Compatibility Notes

Per-model overrides: The JSON config supports per-model openai_base_url and openai_api_key fields that override the environment variables.
Provider flexibility: Any OpenAI-compatible API can be used by changing OPENAI_API_BASE. Tested providers include OpenAI, Anthropic (via proxy), DeepSeek, Qwen, and Google Gemini.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment