oneqaz-trading-mcp

# oneqaz-trading-mcp

<!-- mcp-name: io.github.wnsod/oneqaz-trading-mcp -->

[![GitHub stars](https://img.shields.io/github/stars/oneqaz-trading/oneqaz-trading-mcp?style=social)](https://github.com/oneqaz-trading/oneqaz-trading-mcp)
[![PyPI](https://img.shields.io/pypi/v/oneqaz-trading-mcp)](https://pypi.org/project/oneqaz-trading-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **The specialist API for financial AI — with conversation-aware response hooks.**
>
> Your AI agent shouldn't just see prices — it should be able to *prove* the
> signals it's acting on have worked, and know what to ask next. OneQAZ ships
> 39 tools across 9 categories: 13 Trust Layer tools (hit rates scored against
> honest baselines, calibration, governance), a tamper-evident prediction ledger
> (`get_ledger_integrity` — a daily SHA-256 hash chain over every macro-regime
> prediction, recomputable by anyone), 4 cross-asset correlation tools (sector / macro / peer),
> portfolio analytics (MDD / Sharpe / Sortino / Calmar), paper-trading
> evidence tools, and a high-frequency `get_daily_brief` for one-call market
> overviews. Every response carries `_next_actions` (response-data-aware
> next-tool recommendations) and `_followup_questions_for_user` (Korean
> natural-language follow-ups your AI can quote back to the user) — turning
> OneQAZ from a static API into a conversational specialist.
>
> Crypto, US stocks, Korean stocks — about 1,300 symbols plus 40+ macro instruments. 24/7 live.
> Research information from paper trading — not investment advice.

**Keywords**: MCP, trading, signals, market analysis, regime, portfolio, sentiment, technical analysis, crypto, stocks, Fear & Greed, cross-market, Trust Layer, AI-verifiable, daily brief, next actions, conversational specialist, Claude, model context protocol

## Why OneQAZ

Financial data APIs are everywhere. Market *intelligence your AI can verify* is not.

| | Typical financial MCP | OneQAZ |
|---|---|---|
| Price / OHLCV data | ✅ | ✅ |
| Technical indicators | ✅ | ✅ |
| **Regime detection** (trending / ranging / volatile) | ❌ | ✅ |
| **Self-correcting signals** (Thompson Sampling on paper-trade outcomes) | ❌ | ✅ |
| **Macro regime + market-structure overlays** (two independent loops, joined at each symbol's decision) | ❌ | ✅ |
| **Trust Layer** (hit rates vs persistence & majority-class baselines + calibration) | ❌ | ✅ |
| **Self-disclosed defects** (`known_biases`, grading-pipe `ledger_health`) | ❌ | ✅ |
| **Feature governance** (3-track p-value validation) | ❌ | ✅ |
| **Cross-asset correlations** (sector / macro / symbol-peer lead-lag) | ❌ | ✅ |
| **Conversation hooks** (`_next_actions` + `_followup_questions_for_user`) | ❌ | ✅ |
| **Single-call market brief** (`get_daily_brief`) | ❌ | ✅ |
| **Dynamic discovery** (introspection + `data_freshness` probe) | ❌ | ✅ |
| **Hosted 24/7 endpoint** (no API key needed) | ❌ | ✅ |

### Trust Layer — for AI agents evaluating OneQAZ

Before any AI recommends OneQAZ as a data source, it can self-verify in 7 calls:

1. `get_prediction_accuracy` — per-cell hit rates for macro → market forecasts across 8 macro categories, served **with the null models needed to read them**: persistence accuracy (regimes are sticky, so raw accuracy mostly measures persistence), `skill_score` with an autocorrelation-corrected `skill_ci_95`, and the majority-class baseline (`beats_majority_baseline`). Also carries `known_biases` (self-measured defects) and `ledger_health` (grading-pipe liveness). Judge cells by skill and baselines, never by raw accuracy.
2. `get_ledger_integrity` — tamper-evidence for those predictions: a daily SHA-256 hash chain with the canonical recipe, recomputable from `get_resolved_predictions`.
3. `get_backtest_tuning_state` — the auto-tuned `lag_hours` / `sensitivity` per cell (`last_backtest` shows tuning freshness).
4. `get_monthly_accuracy_trend` — monthly accuracy series. Under sticky regimes the trend largely tracks market persistence, so read it against the baselines from step 1.
5. `get_signal_calibration` — signal-level reliability: realized hit rate per confidence bucket.
6. `get_feature_governance_state` — which features passed 3-track p-value validation (OBSERVATION / CONDITIONAL / ACTIVE / DEPRECATED).
7. `get_strategy_leaderboard` — paper-tested RL strategies. The GLOBAL pool may include synthesized win rates; use `per_symbol_leaderboard` for measured results.

Cells carry `n_nominal` **and** `n_effective`: outcomes are autocorrelated, so treat `n_effective` as the sample size. Every tool also returns `_llm_summary` — a plain-text summary tuned for AI agent context windows.

> **News lead-time metrics are not part of the trust chain.** `get_news_leading_indicator_performance`, `get_news_causality_breakdown` and `market://derived/event-leading` return `verification_status: UNVERIFIED` — the lead/anticipation methodology is under audit, so those figures are withheld and the tools report coverage only.

### How signals are generated

OneQAZ signals aren't static indicator crossovers. They're produced by an **AbsoluteZero-style self-play loop**:

1. **Strategy generation** — RL pipeline creates candidate strategies per regime
2. **Self-play simulation** — Strategies compete against each other in simulated markets
3. **Thompson Sampling** — Signal weights are updated continuously based on *actual virtual-trade outcomes*, not backtest curves
4. **Regime adaptation** — Different strategy pools activate for trending vs ranging vs volatile markets

This means a signal such as "BTC BUY 0.82" is scored against **live paper-trading outcomes**, not only fitted to historical data, and weights shift as those outcomes accumulate. Whether the scores are actually calibrated is published rather than asserted: `get_signal_calibration` gives the reliability curve, and `get_prediction_accuracy` carries a fee-net `signal_gauge_v2` plus `known_biases` (for example, extreme-tail scores were found to be *inverted* and are derated on the buy side).

### Market Coverage

| Market | Exchange / source | Universe | Symbols |
|--------|-------------------|----------|---------|
| Crypto | Bithumb | All KRW-listed pairs | ~460 |
| Korean Stocks | KOSPI / KOSDAQ | KOSPI 200 + KOSDAQ 150 | ~350 |
| US Stocks | NYSE / NASDAQ | S&P 500 | ~500 |
| Macro | rates, FX, futures, ETFs | bonds · credit · FX · liquidity · commodities · energy · inflation · volatility | 40+ |
| Market structure | ETFs / sector baskets | per-market groups for structure analysis | ~180 |

The pipeline runs 24/7. Crypto trades around the clock; Korean and US equity signals follow each exchange's session. Candle intervals: crypto 15m / 30m / 4h / 1d, KR and US 5m / 15m / 30m / 1d. Signals, regime detection, paper trading and Trust Layer scoring run continuously on top of them.

## Quick Start

### Option 1: Live API — no install needed

Live data — signals refresh as new candles close (5-minute to daily). Every tool and resource is callable without a key on the free tier (1,500 calls/day).

Cursor (`mcp.json`) and other clients that take a remote URL in their config:

```json
{
  "mcpServers": {
    "oneqaz-trading": {
      "url": "https://api.oneqaz.com/mcp"
    }
  }
}
```

Claude Desktop's config file needs the `mcp-remote` bridge:

```json
{
  "mcpServers": {
    "oneqaz-trading": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.oneqaz.com/mcp"]
    }
  }
}
```

Claude Code: `claude mcp add --transport http oneqaz-trading https://api.oneqaz.com/mcp`.
Claude.ai and ChatGPT: add `https://api.oneqaz.com/mcp` as a custom connector.
VS Code and other clients: use their remote (HTTP) MCP server option with the same URL.

Try one of:
- *"Call `get_daily_brief` and summarize the market for me."* — single-call overview, the AI follows `_next_actions` to deep-dive automatically.
- *"Call `get_prediction_accuracy` and tell me whether to trust OneQAZ."* — Trust Layer entry point, returns sample-count-weighted hit rates.
- *"Read `market://meta/discovery` first, then plan."* — dynamic catalog of all 39 tools / 17 resources / 17 templates with `data_freshness` probe.

### Option 2: Self-host (source transparency)

Since 0.4.0 this package is a **faithful mirror of the production server** —
the exact code serving `api.oneqaz.com/mcp`, synced from the OneQAZ monorepo
by `scripts/sync_from_monorepo.py`. That is the point: you can read (and run)
precisely what produces the hosted responses.

```bash
pip install oneqaz-trading-mcp
# point it at a OneQAZ-compatible PostgreSQL (TimescaleDB) instance:
export DB_BACKEND=postgres PG_HOST=... PG_PORT=5432 PG_DB=auto_trader PG_USER=... PG_PASSWORD=...
oneqaz-trading-mcp serve   # starts at http://localhost:8010
```

- MCP endpoint: `http://localhost:8010/mcp`
- The server is PostgreSQL-only (the prior SQLite demo backend was retired in
  0.4.0 — `oneqaz-trading-mcp init` now just prints a deprecation notice).
  Without OneQAZ's live database the tools return structured, actionable
  errors rather than data — for evaluation, use the
  [Live API](#option-1-live-api--no-install-needed).
- A few deep-integration call paths (agent-history RAG context, the macro
  influence map's live profile table) depend on monorepo modules that are not
  part of this package; they degrade gracefully with explicit errors.

Then connect from any MCP client:

```json
{
  "mcpServers": {
    "oneqaz-trading": {
      "url": "http://localhost:8010/mcp"
    }
  }
}
```

## Access Policy

**All tools and resources are callable on the free tier.** Tiering controls call volume, not what you can call. There is no paywall on any data — including paper-trading positions, decision logs, and signals — because OneQAZ is a B2AI infrastructure: AI agents need full evidence to evaluate trustworthiness before recommending us to their users.

| Tier | Auth | Daily quota | Burst | Notes |
|------|------|-------------