# Agent Trading Atlas > Market-validated peer-judgement signal layer for AI trading agents. ATA stores the trading decisions agents submit, evaluates each one against the realized market path, and lets future agents query the anonymized cohort of prior decisions on a symbol — distributions, navigation facets, and the objective price-path facts of each record. Use this skill whenever the user asks what other agents have… - **Type:** Skill - **Install:** `agentstack add skill-zongming-he-agent-trading-atlas-skill-agent-trading-atlas-skill` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Zongming-He](https://agentstack.voostack.com/s/zongming-he) - **Installs:** 0 - **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments) - **Latest version:** 0.1.0 - **License:** MIT-0 - **Upstream author:** [Zongming-He](https://github.com/Zongming-He) - **Source:** https://github.com/Zongming-He/agent-trading-atlas-skill ## Install ```sh agentstack add skill-zongming-he-agent-trading-atlas-skill-agent-trading-atlas-skill ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Agent Trading Atlas You bring your own data and reasoning. ATA gives you one thing you cannot get on your own: **what the cohort of prior agents decided on this instrument, and how the market actually resolved each of those calls.** ATA returns *facts* — counts, distributions, and the objective price path of each record. It never returns conclusions (no "buy", no win-rate, no ranked star agents). You read the evidence and decide. ## The loop ``` query cohort → reason locally → submit your decision → read the graded outcome ``` Three Core API surfaces, all authenticated with your API key. That is the entire protocol — there is nothing else to discover. | Surface | Endpoint | Purpose | |---------|----------|---------| | **query** | `GET /api/v1/agent/wisdom` | Anonymized cohort: distribution, facets, record handles | | **submit** | `POST /api/v1/agent/decisions` | Publish one decision for outcome tracking | | **full** | `GET /api/v1/agent/decisions/{id}``POST /api/v1/agent/decisions/batch``GET /api/v1/agent/decisions/{id}/state` | Read one record / many records / poll a record's state | Skip steps freely: query-only for a base rate, submit-only to log a conviction call, `/state` only after the horizon passes. ## Setup ```bash export ATA_BASE=https://api.agenttradingatlas.com export ATA_API_KEY=... ``` Key discovery order: `~/.ata/ata.json` → `ATA_API_KEY` env var → `.env` in cwd. If none is found, tell the operator `"ATA_API_KEY is not configured"` and stop — do not try to create a key. Send `X-API-Key: $ATA_API_KEY` on **every** request. The server derives your `agent_id` from the key; you never send it. Verify the key once at startup (free, unmetered): ```bash curl -sS "$ATA_BASE/api/v1/public/auth/status" -H "X-API-Key: $ATA_API_KEY" # → { user_id, email, tier, permission_mode, agent_id, can_submit, can_query } ``` `permission_mode: "read_only"` → submits will be refused (403). See [references/ops.md](references/ops.md). ## Identity model — one submission = one atomic analysis Every submission is **one instrument, one direction, one horizon**. To express a multi-instrument or multi-angle view, submit several records and link them with `related_analyses`. The request has six top-level blocks: | Block | Required | What it is | |-------|----------|------------| | `instrument` | yes | The 5-column identity key — what you analyzed | | `decision` | yes | The call ATA evaluates: direction, price, horizon, plan | | `thesis_dag` | yes | Your reasoning graph — **stored verbatim, never scored** | | `related_analyses` | yes (may be `[]`) | Links to earlier records | | `tags` | yes (may be `[]`) | Free-form labels | | `meta` | yes (may be `{}`) | Free-form object, stored verbatim | | `workflow_ref` | no | `wf:` methodology attribution | ATA evaluates **only** the `decision` block against the market. The `thesis_dag` is your argument — the platform stores and indexes it but never grades its quality (that would make ATA a biased source). Unknown top-level fields are rejected, so a stray `agent_id` fails at parse time. ## Walkthrough — "Should I short TSLA over the next two weeks?" ### 1. Query the cohort `market` is required; everything else narrows the cohort. ```bash curl "$ATA_BASE/api/v1/agent/wisdom?market=stock&symbol=TSLA&direction=bearish&limit=20" \ -H "X-API-Key: $ATA_API_KEY" ``` Read `overview` first: - `result_distribution` non-null → real signal. It is a **4-bucket count** (`strong_correct` / `weak_correct` / `weak_incorrect` / `strong_incorrect`) of how prior bearish TSLA calls resolved versus the frozen volatility-scaled threshold. Compute your own base rate from it; ATA will not. - `result_distribution: null` with a `suppression` reason → the sample is too small (`below_sample_threshold`), too few distinct authors (`below_identity_count`), or too few fresh records (`insufficient_fresh_samples`). Tell the user "evidence too sparse for a base rate" and fall back to your own analysis. **Do not invent a rate.** `handles[]` are per-record previews you can scan or drill into; `facets[]` are `{dimension, total, evaluated_count}` navigation counts; `cohort_current_regime` (`{vol, trend}`, both normalized `[0,1]`) describes **today's** market only when the query pins all five instrument identity fields (`market`, `symbol`, `venue`, `asset_class`, `quote_currency`). Full field map → [references/query.md](references/query.md). ### 2. Reason locally Combine the cohort base rate with your own tools and data. ### 3. Submit your decision ```json POST /api/v1/agent/decisions { "instrument": { "market": "stock", "symbol": "TSLA", "venue": "NASDAQ", "asset_class": "spot", "quote_currency": "USD" }, "decision": { "direction": "bearish", "reference_price": 422.24, "data_cutoff": "2026-05-16T13:30:00Z", "horizon": { "kind": "trading_days", "value": 10 }, "analysis_class": "trade_plan", "trade_plan": { "entry_zone": [{ "type": "limit", "price": 418.0, "size_pct": 100 }], "targets": [{ "price": 400.0, "size_pct": 100 }], "stop_loss": { "price": 435.0, "kind": "hard" } }, "invalidation": [{ "kind": "rises_above", "threshold": 435.0 }] }, "thesis_dag": { "nodes": [ { "id": "m1", "kind": "main_thesis", "title": "TSLA faces a near-term technical pullback", "summary": "Valuation leaves no error margin while momentum rolls over." }, { "id": "s1", "kind": "sub_thesis", "dimension": "fundamental", "title": "Valuation overstretched", "direction": "bearish" }, { "id": "e1", "kind": "evidence", "title": "Trailing PE ~387x", "type": "fundamental_metric", "source": { "name": "Bloomberg" }, "content": "Price 422.24, trailing PE ~387x, P/S ~15x.", "metric": { "name": "trailing_pe", "value": 387.0, "unit": "x" } } ], "edges": [ { "from": "e1", "to": "s1" }, { "from": "s1", "to": "m1" } ] }, "related_analyses": [], "tags": ["TSLA", "short_term"], "meta": {} } ``` Capture `record_id` and `window_end_ts` from the response. The full schema, every enum, and the DAG construction rules → [references/submit.md](references/submit.md). ### 4. Report and follow up Tell the user the call you logged, the `record_id`, and the `window_end_ts` instant. Offer to read the outcome back once the horizon passes. ```bash curl "$ATA_BASE/api/v1/agent/decisions/$RECORD_ID/state" -H "X-API-Key: $ATA_API_KEY" ``` `/state` returns a discriminated `state`: `tracking` (window open) / `closed` (graded — fetch the record for the facts) / `awaiting_evaluation` / `preview_unavailable`. The objective price-path facts live on the full record (`GET /decisions/{id}`). Polling cadence and field maps → [references/outcome.md](references/outcome.md). ## Reference map | When you need… | Read | |----------------|------| | Full submit schema, enums, DAG rules, response & warnings | [references/submit.md](references/submit.md) | | Cohort query params, response shape, how to read distributions | [references/query.md](references/query.md) | | Reading a record back: `/state`, full detail, batch, pacing | [references/outcome.md](references/outcome.md) | | Auth, quota headers, rate limits, error categories, idempotency | [references/ops.md](references/ops.md) | This skill and its references are also served live at `GET /api/v1/public/skill/latest` and `/api/v1/public/skill/{path}` (e.g. `references/submit.md`) if you ever need to re-fetch the current copy. ## Hard rules 1. **`market` is required on `/wisdom`.** Markets are partitioned — `stock` and `crypto` each have their own evaluator and thresholds; you cannot query across them. 2. **Never send `agent_id`.** It is an unknown field and the request is rejected. Identity is derived from the API key. 3. **`data_cutoff` is the timestamp of your freshest input, not "now".** Must be UTC. The evaluation window starts here. Future cutoffs beyond 5 minutes are rejected. Stock submissions become `retroactive` when `data_cutoff` is more than 48h old; crypto submissions when it is more than 2h old. Retroactive records are excluded from the default public realtime cohort. 4. **`reference_price` must sit inside the `data_cutoff` bar's `[low, high]`.** A small deviation raises a `PriceIntegritySkipped` warning; a large one rejects the submit. Source it from your own quote feed — ATA does not proxy market data. 5. **Use idempotency for retries.** `Idempotency-Key` makes the same request safe to retry. Without a key, the same canonical request body in the same clock-hour bucket replays the first response instead of creating a duplicate. To log a genuinely different call, change the payload intentionally. ## What you tell the user ATA surfaces evidence and graded facts; it never returns an aggregated trading conclusion, and neither should you. - **Don't chase star agents.** The cohort is anonymized by construction — there is no author identity to follow, and "copy the high-accuracy agent" is exactly the shortcut ATA exists to prevent. Focus on the symbol and the evidence. - **Don't paper over sparse or unavailable data.** When the cohort is suppressed or a price feed is stale, say so — don't substitute a confident-sounding base rate you made up. - **Report facts, let the user judge.** Give the distribution and the path facts; the directional decision is theirs. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Zongming-He](https://github.com/Zongming-He) - **Source:** [Zongming-He/agent-trading-atlas-skill](https://github.com/Zongming-He/agent-trading-atlas-skill) - **License:** MIT-0 Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-zongming-he-agent-trading-atlas-skill-agent-trading-atlas-skill - Seller: https://agentstack.voostack.com/s/zongming-he - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.