AlphaFin 🤖

中文文档 | English

AlphaFin 是一个自主金融研究智能体，能够思考、规划并在工作中不断学习。它通过任务规划、自我反思和实时市场数据进行分析。可以理解为专为金融研究而生的 Claude Code。

Note: 本项目基于 dexter (v2026.2.21) Fork 而来，在此基础上新增了 A 股市场支持、命令联想等功能。

目录

• 👋 概述
• ✅ 环境要求
• 💻 安装方法
• 🚀 运行方式
• 📊 评估系统
• 🐛 调试方法
• 📱 WhatsApp 集成
• 🤝 参与贡献
• 📄 许可证

👋 概述

AlphaFin 将复杂的金融问题转化为清晰的逐步研究计划。它使用实时市场数据执行任务，自我检查工作成果，并不断优化结果，直到得出有数据支撑的可靠结论。

核心能力：

• 智能任务规划：自动将复杂查询分解为结构化的研究步骤
• 自主执行：选择并执行正确的工具来收集金融数据
• 自我验证：检查自身工作并迭代直到任务完成
• 实时金融数据：访问利润表、资产负债表和现金流量表
• 安全机制：内置循环检测和步骤限制，防止无限执行

✅ 环境要求

• Bun 运行时（v1.0 或更高版本）
• OpenAI API 密钥（获取地址）
• Financial Datasets API 密钥（获取地址）
• Exa API 密钥（获取地址）- 可选，用于网页搜索

安装 Bun

如果您尚未安装 Bun，可以使用以下命令安装：

macOS/Linux:

curl -fsSL https://bun.com/install | bash

Windows:

powershell -c "irm bun.sh/install.ps1|iex"

安装完成后，重启终端并验证 Bun 是否安装成功：

bun --version

💻 安装方法

1. 克隆仓库：

git clone https://github.com/0xByteBard404/AlphaFin.git
cd AlphaFin

2. 使用 Bun 安装依赖：

bun install

3. 配置环境变量：

# 复制示例环境文件
cp env.example .env

# 编辑 .env 文件并添加您的 API 密钥
# OPENAI_API_KEY=您的-openai-api-密钥
# ANTHROPIC_API_KEY=您的-anthropic-api-密钥（可选）
# GOOGLE_API_KEY=您的-google-api-密钥（可选）
# XAI_API_KEY=您的-xai-api-密钥（可选）
# OPENROUTER_API_KEY=您的-openrouter-api-密钥（可选）

# 机构级市场数据；AAPL、NVDA、MSFT 免费使用
# FINANCIAL_DATASETS_API_KEY=您的-financial-datasets-api-密钥

# （可选）如果本地使用 Ollama
# OLLAMA_BASE_URL=http://127.0.0.1:11434

# 网页搜索（推荐 Exa，Tavily 作为备选）
# EXASEARCH_API_KEY=您的-exa-api-密钥
# TAVILY_API_KEY=您的-tavily-api-密钥

# 国内镜像源（可选）
# NPM_CONFIG_REGISTRY=https://registry.npmmirror.com
# BUN_INSTALL_REGISTRY=https://registry.npmmirror.com

# GitHub 代理（可选）
# GITHUB_PROXY=https://ghproxy.com/

🚀 运行方式

以交互模式运行 AlphaFin：

bun start

或使用监视模式进行开发：

bun dev

📊 评估系统

AlphaFin 包含一个评估套件，用于测试智能体对金融问题数据集的处理能力。评估系统使用 LangSmith 进行追踪，并采用 LLM-as-judge 方法进行正确性评分。

运行所有问题：

bun run src/evals/run.ts

运行随机抽样数据：

bun run src/evals/run.ts --sample 10

评估运行器会显示实时 UI，展示进度、当前问题和准确率统计。结果会记录到 LangSmith 以供分析。

🐛 调试方法

AlphaFin 将所有工具调用记录到暂存板文件中，用于调试和历史追踪。每次查询都会在 .alphafin/scratchpad/ 目录下创建一个新的 JSONL 文件。

暂存板位置：

.alphafin/scratchpad/
├── 2026-01-30-111400_9a8f10723f79.jsonl
├── 2026-01-30-143022_a1b2c3d4e5f6.jsonl
└── ...

每个文件包含换行分隔的 JSON 条目，记录：

• init：原始查询
• tool_result：每次工具调用的参数、原始结果和 LLM 摘要
• thinking：智能体推理步骤

示例暂存板条目：

{"type":"tool_result","timestamp":"2026-01-30T11:14:05.123Z","toolName":"get_income_statements","args":{"ticker":"AAPL","period":"annual","limit":5},"result":{...},"llmSummary":"获取了苹果公司5年的年度利润表，显示营收从2740亿美元增长到3940亿美元"}

这样可以方便地检查智能体收集了哪些数据以及如何解读结果。

📱 WhatsApp 集成

通过将手机链接到网关，可以在 WhatsApp 中与 AlphaFin 聊天。发送给自己的消息会被 AlphaFin 处理，回复会发送到同一个聊天中。

快速开始：

# 链接您的 WhatsApp 账号（扫描二维码）
bun run gateway:login

# 启动网关
bun run gateway

然后打开 WhatsApp，进入自己的聊天（给自己发消息），向 AlphaFin 提问即可。

详细的设置说明、配置选项和故障排除，请参阅 WhatsApp 网关 README。

🤝 参与贡献

1. Fork 本仓库
2. 创建功能分支
3. 提交您的更改
4. 推送到分支
5. 创建 Pull Request

重要：请保持您的 Pull Request 小而专注，这样更容易审查和合并。

📄 许可证

本项目采用 MIT 许可证授权。

---

AlphaFin

AlphaFin is an autonomous financial research agent that thinks, plans, and learns as it works. It performs analysis using task planning, self-reflection, and real-time market data. Think Claude Code, but built specifically for financial research.

Note: This project is forked from dexter (v2026.2.21) with additional features including A-share market support, command autocomplete, and more.

Table of Contents

• 👋 Overview
• ✅ Prerequisites
• 💻 How to Install
• 🚀 How to Run
• 📊 How to Evaluate
• 🐛 How to Debug
• 📱 How to Use with WhatsApp
• 🤝 How to Contribute
• 📄 License

👋 Overview

AlphaFin takes complex financial questions and turns them into clear, step-by-step research plans. It runs those tasks using live market data, checks its own work, and refines the results until it has a confident, data-backed answer.

Key Capabilities:

• Intelligent Task Planning: Automatically decomposes complex queries into structured research steps
• Autonomous Execution: Selects and executes the right tools to gather financial data
• Self-Validation: Checks its own work and iterates until tasks are complete
• Real-Time Financial Data: Access to income statements, balance sheets, and cash flow statements
• Safety Features: Built-in loop detection and step limits to prevent runaway execution

✅ Prerequisites

• Bun runtime (v1.0 or higher)
• OpenAI API key (get here)
• Financial Datasets API key (get here)
• Exa API key (get here) - optional, for web search

Installing Bun

If you don't have Bun installed, you can install it using curl:

macOS/Linux:

curl -fsSL https://bun.com/install | bash

Windows:

powershell -c "irm bun.sh/install.ps1|iex"

After installation, restart your terminal and verify Bun is installed:

bun --version

💻 How to Install

1. Clone the repository:

git clone https://github.com/0xByteBard404/AlphaFin.git
cd AlphaFin

2. Install dependencies with Bun:

bun install

3. Set up your environment variables:

# Copy the example environment file
cp env.example .env

# Edit .env and add your API keys (if using cloud providers)
# OPENAI_API_KEY=your-openai-api-key
# ANTHROPIC_API_KEY=your-anthropic-api-key (optional)
# GOOGLE_API_KEY=your-google-api-key (optional)
# XAI_API_KEY=your-xai-api-key (optional)
# OPENROUTER_API_KEY=your-openrouter-api-key (optional)

# Institutional-grade market data for agents; AAPL, NVDA, MSFT are free
# FINANCIAL_DATASETS_API_KEY=your-financial-datasets-api-key

# (Optional) If using Ollama locally
# OLLAMA_BASE_URL=http://127.0.0.1:11434

# Web Search (Exa preferred, Tavily fallback)
# EXASEARCH_API_KEY=your-exa-api-key
# TAVILY_API_KEY=your-tavily-api-key

# China mirror (optional)
# NPM_CONFIG_REGISTRY=https://registry.npmmirror.com
# BUN_INSTALL_REGISTRY=https://registry.npmmirror.com

# GitHub proxy (optional)
# GITHUB_PROXY=https://ghproxy.com/

🚀 How to Run

Run AlphaFin in interactive mode:

bun start

Or with watch mode for development:

bun dev

📊 How to Evaluate

AlphaFin includes an evaluation suite that tests the agent against a dataset of financial questions. Evals use LangSmith for tracking and an LLM-as-judge approach for scoring correctness.

Run on all questions:

bun run src/evals/run.ts

Run on a random sample of data:

bun run src/evals/run.ts --sample 10

The eval runner displays a real-time UI showing progress, current question, and running accuracy statistics. Results are logged to LangSmith for analysis.

🐛 How to Debug

AlphaFin logs all tool calls to a scratchpad file for debugging and history tracking. Each query creates a new JSONL file in .alphafin/scratchpad/.

Scratchpad location:

.alphafin/scratchpad/
├── 2026-01-30-111400_9a8f10723f79.jsonl
├── 2026-01-30-143022_a1b2c3d4e5f6.jsonl
└── ...

Each file contains newline-delimited JSON entries tracking:

• init: The original query
• tool_result: Each tool call with arguments, raw result, and LLM summary
• thinking: Agent reasoning steps

Example scratchpad entry:

{"type":"tool_result","timestamp":"2026-01-30T11:14:05.123Z","toolName":"get_income_statements","args":{"ticker":"AAPL","period":"annual","limit":5},"result":{...},"llmSummary":"Retrieved 5 years of Apple annual income statements showing revenue growth from $274B to $394B"}

This makes it easy to inspect exactly what data the agent gathered and how it interpreted results.

📱 How to Use with WhatsApp

Chat with AlphaFin through WhatsApp by linking your phone to the gateway. Messages you send to yourself are processed by AlphaFin and responses are sent back to the same chat.

Quick start:

# Link your WhatsApp account (scan QR code)
bun run gateway:login

# Start the gateway
bun run gateway

Then open WhatsApp, go to your own chat (message yourself), and ask AlphaFin a question.

For detailed setup instructions, configuration options, and troubleshooting, see the WhatsApp Gateway README.

🤝 How to Contribute

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

Important: Please keep your pull requests small and focused. This will make it easier to review and merge.

📄 License

This project is licensed under the MIT License.