Dexter 🤖

English | 中文

Forked from virattt/dexter. This fork adds A-share (Chinese stock market) support.

Dexter 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.

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

Dexter 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
• A-Share Support: Query Chinese A-share stocks (price history, fundamentals, financials)
• 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) — for US stocks
• Tushare API key (get here) — for A-shares
• East Money MX API key (get here) — for A-shares
• 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/abrclano/dexter-A.git
cd dexter

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
# FINANCIAL_DATASETS_API_KEY=your-financial-datasets-api-key

# Chinese A-share Market Data
# Tushare API Key
# TUSHARE_API_KEY=your-tushare-api-key
# East Money MX API Key
# MX_APIKEY=your-eastmoneymx-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

🇨🇳 A-Share Support

This fork integrates Tushare and EastMoney MX to enable research on Chinese A-share stocks listed on the Shanghai and Shenzhen exchanges.

Tushare - Credit-based Financial Data Platform

Tushare provides standardized historical market data and fundamental data interfaces for stocks, funds, futures, and other markets:

What you can do:

• Query daily/weekly/monthly price history for A-share tickers (e.g. 000001.SZ, 600519.SH)
• Retrieve fundamental data: P/E, P/B, market cap, turnover rate
• Access financial statements: income statement, balance sheet, cash flow
• Look up company profiles and industry classifications

Setup:

1. Register at tushare.pro and get your API key
2. Add it to your .env:

   TUSHARE_API_KEY=your-tushare-api-key
   

3. The tushare_search tool will be automatically enabled when the key is present

Example queries:

• "What are the recent trends in Kweichow Moutai's revenue and net profit over the last year?"
• "Compare the P/E ratio of 600519.SH vs 000858.SZ"
• "What is the current market cap of BYD (002594.SZ)?"

For the full list of supported APIs and developer guide, see the Tushare Module README.

EastMoney MX - Advanced Financial Data

EastMoney MX integrates real-time market data and institutional-grade financial data from East Money's proprietary database:

What you can do:

• Query real-time quote data for stocks, indices, funds, and bonds
• Access comprehensive financial statements and corporate fundamentals
• Retrieve relationship data between companies, shareholders, and executives
• Search for industry analysis and valuation metrics
• Extract business information and financing details

Setup:

1. Get your API Key from EastMoney MX Skills Hub
2. Add it to your .env:

   MX_APIKEY=your-eastmoney-mx-api-key
   

3. The EastMoney MX(data, search, self-select, simulator) skill will be automatically enabled when the key is present

Example queries:

• "Get the latest stock price and market data for 600519.SH"
• "What are the latest financial metrics and PE ratio for major tech companies?"
• "Retrieve balance sheet data for listed companies in the pharmaceutical sector"
• "Find information about executives and shareholders of company 002594.SZ"

Output formats:

• Excel files with multiple sheets for organized data visualization
• JSON format for programmatic access
• Text descriptions summarizing query results

For detailed API documentation and usage examples, see the EastMoney MX Module README.

🚀 How to Run

Run Dexter in interactive mode:

bun start

Or with watch mode for development:

bun dev

📊 How to Evaluate

Dexter 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

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

Scratchpad location:

.dexter/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 Dexter through WhatsApp by linking your phone to the gateway. Messages you send to yourself are processed by Dexter 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 Dexter 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.