🦍 TradeApe

Open-source agentic charting - Ask questions, query QuestDB, and mark up financial charts with provenance

QuestDB | KLineCharts | BYOK | deterministic tools | inspectable overlays

AGPL-3.0. Hackable, self-hostable, and built for agent-first market analysis.

🍌 🍌 🍌 🍌 🍌 tradeape.org 🍌 🍌 🍌 🍌 🍌

What the agent can do

• Every claim traces back to a tool call; every overlay has a named source and selection method
• Live OHLCV charts — 1m through 1d, candles polling a live QuestDB feed every 1.5s
• Support, resistance, VWAP, volume nodes, multi-timeframe confluence, swing annotations, channel detection
• Indicator snapshots with actual RSI, MACD, and Bollinger values
  • Cited from queries, not inferred from descriptions
• Multi-symbol briefings and normalized return comparisons

---

How it works

Three open-source components, one agent loop:

flowchart TD
    You(["🦍 you"])

    subgraph TradeApe ["TradeApe scaffold · AGPL-3.0"]
        Claude["AI Model\nBYOK · Anthropic API"]
        Tools["deterministic tools\ndetect_key_levels · SAMPLE BY\ndraw_on_chart · provenance"]
        Claude <--> Tools
    end

    You <-->|question / response| TradeApe
    Tools <-->|SQL via REST| QuestDB[("QuestDB\ntime-series store")]
    Tools -->|draw commands| KLine["KLineCharts\ncanvas"]
    KLine -->|chart context| TradeApe

Loading

QuestDB — time-series backbone. SAMPLE BY, LATEST ON, windowed VWAP, price-volume profile. Standard SQL with time-series extensions; the same powerhouse database engine that powers leading financial firms runs terrific on a laptop.

TradeApe — the scaffold. Deterministic tools, system prompt, provenance layer, and the draw command pipeline between the model and the chart. Everything is exposed and forkable.

KLineCharts — the canvas. Interactive OHLCV charts with indicator panes, overlays, and layer controls the agent can mark up directly.

---

Quick start

npm install
npm run dev

Open http://localhost:5173, enter your API key, and start asking questions.

Currently uses the Anthropic API. Other providers welcome — open an issue.

The default data path uses demo data from QuestDB — no local QuestDB needed to explore the full tool surface.

The provenance badge in the app header shows exactly what the demo feed includes and what it doesn't.

---

MCP

TradeApe MCP lets any MCP-compatible coding agent focus and mark up an open TradeApe chart.

claude mcp add --transport stdio tradeape -- npm --silent run mcp

With the app open, MCP sends explicit chart commands through a localhost bridge.

Uses TradeApe's deterministic analysis tools for levels, structure, confluence, volume nodes, and summaries.

MCP can also call those TradeApe analysis tools directly against the configured feed.

See docs/tradeape-mcp.md for setup and verification.

---

Self-hosted

cp .env.example .env
# set QUESTDB_URL=http://localhost:9000
docker compose up

Point QUESTDB_URL at any QuestDB instance with a trades table.

Query surface — SAMPLE BY, LATEST ON, VWAP, etc — is identical regardless of feed.

TradeApe expects raw trade rows by default: trades(timestamp, symbol, price, amount).

If your QuestDB schema uses different names, configure the mapping:

QUESTDB_TABLE=market_ticks
QUESTDB_TIMESTAMP_COLUMN=ts
QUESTDB_SYMBOL_COLUMN=pair
QUESTDB_PRICE_COLUMN=last_price
QUESTDB_AMOUNT_COLUMN=quantity
QUESTDB_VOLUME_SEMANTIC=base_amount
QUESTDB_EXCHANGE=unknown
QUESTDB_TIMEZONE=UTC

For complex schemas, create a QuestDB compatibility view named trades.

See docs/questdb-schema-mapping.md for more information.

To setup QuestDB, see their quick start.

---

Hackable by design

The parts that matter are all exposed:

File	What it is
src/lib/agent/prompt.ts	Full system prompt, confidence vocabulary, tool instructions
src/lib/agent/tools.ts	Every tool schema and execution handler
src/lib/mcp/analysis.ts	MCP tool surface
scripts/tradeapeBridge.ts	Localhost bridge for visible chart control
src/lib/marketConfig.ts	QuestDB URL/schema mapping and SQL identifier validation
src/lib/marketData.ts	QuestDB query layer — all SQL in one place
src/lib/swings.ts	Swing detection, channel test, Fib anchor selection
src/lib/provenance.ts	Provenance object passed to the agent on every call

Fork it, rewrite the prompt, add tools, swap the data source. Go bananas!

---

Security and data notes

• API keys are stored in browser localStorage only — never routed through a server proxy. localStorage is same-origin and never leaves your machine, but it isn't hardened storage; don't use a key you can't rotate.
• The QuestDB demo feed has explicit provenance limits: treat volume and reference VWAP as feed-local context unless you're running a named-exchange feed with session attribution

---

FAQ

See the website for more information: https://tradeape.org.

If still curious, create an issue!

Contributions

Yes, please!

Issues, PRs, stars, it's all good, baby.

---

License

AGPL-3.0. Self-hosted use is free and unrestricted.

If you run a modified version as a hosted service, AGPL requires you to publish your changes.

---

IMPORTANT

Be excellent to each other.

You damned blessed, dirty beautiful apes.

Also: This tool should not be used to make material financial decisions.