# Ask agent API

> POST /v1/ask — Chord's analyst over the Arc index and the router, as an API for other agents. One JSON answer, sources, a route card, tables.

Source: https://getchord.xyz/docs/agents/ask-api/

Ask is the analyst behind the chat on getchord.xyz. It has 40+ tools over the Arc index and the router — trending, a token's flow, holders and risk, support and resistance, top traders on a token, a wallet's PnL and trades, largest prints, launches and launchers, depth, a bridge quote, read-only SQL over the index — and answers in plain language with the sources it read. The same agent is available to your agent.

## Call it

```bash
curl -X POST https://api.getchord.xyz/v1/ask \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{ "question": "Is ARGUS still being bought by real wallets, and where is support?", "stream": false }'
```

- **Auth**: an API key (`X-API-Key`). The browser uses a Google session instead; agents use a key.
- **`stream: false`** returns one JSON answer in 5–40 s. Without it the response is `text/event-stream` (below).
- **`history`**: up to 12 prior turns `{ role, content }` for a conversation.
- **`wallet`**: the agent's wallet, so "my PnL" and "my positions" resolve.
- **`mode`**: `"quick"` or `"deep"`, the chat's answer switch. Quick returns the shortest form of the answer (the verdict, its claim, at most three rows of evidence, 120 words at most) and runs faster. Deep returns a judgement or an explanation as a full research note (`shape: "report"`), and any other answer with a longer `details`. Leave it out for the length the question calls for; any other value is ignored.
- **Limits**: 8 questions a minute per key, metered per key per day against the deployment's token budget (`GET /v1/ask/status`).

## The answer

```json
{
  "text": "**ARGUS is still being bought by real wallets: 59.8% of the last hour's buying is not bots or routers.** Confidence: medium (…)\n\n| Level | Price | vs now % | Why |\n| --- | --- | --- | --- |\n| Support | 0.0181 | … | … |\n\n**Against:** …\n\n*… UTC. Chord's Arc index.*",
  "shape": "brief",
  "parts": [
    { "t": "md", "text": "**ARGUS is still being bought by real wallets: 59.8% of the last hour's buying is not bots or routers.** Confidence: medium (…)" },
    { "t": "viz", "i": 0 },
    { "t": "md", "text": "**Against:** …\n\n*… UTC. Chord's Arc index.*" }
  ],
  "details": null,
  "viz": [ { "kind": "table", "title": "ARGUS · key levels on the tape", "columns": [ "Level", "Price", "vs now %", "Why" ], "rows": [ … ] } ],
  "followUps": [ "Who are the top buyers of $ARGUS this hour?", "…", "Alert me if ARGUS closes below 0.0176" ],
  "followUpKinds": [ "deeper", "ask", "alert" ],
  "assets": [ { "symbol": "ARGUS", "label": "…", "price": …, "change24hPct": 12.7 } ],
  "focus": 0,
  "citations": [ { "label": "ARGUS on Arc", "href": "/arc/token/0xece5…" } ],
  "quote": null,
  "artifact": { "kind": "token", "token": { "address": "0xece5…", "symbol": "ARGUS" }, "stats": { … }, "analysis": { … }, "report": null },
  "toolsUsed": ["arc_token", "arc_price_analysis", "arc_token_traders"],
  "tokens": 9120
}
```

| Field | Meaning |
| --- | --- |
| `text` | The answer, Markdown, complete on its own. A table the answer placed is written out here as a Markdown table (its first 8 rows and 6 columns), so a client that reads only `text` shows the whole answer. |
| `shape` | The kind of answer the question got: `fact` · `explain` · `brief` (a call with its evidence) · `board` (a ranked list) · `why` · `overview` · `compare` · `post` (something to paste or a chart) · `do` (steps on Chord) · `report` · `auto`. |
| `parts` | The same answer in order, for a client that draws blocks: `{ "t": "md", "text" }` is text, `{ "t": "viz", "i" }` is the table or chart `viz[i]` placed at that point. |
| `details` | `{ text, parts }` or `null`: further depth (a per-venue breakdown, a longer history) that the chat folds under "Show full analysis". It is not repeated in `text`. |
| `viz` | Tables and charts from real numbers (`kind`: `table` · `bar` · `line` · `donut`), at most 6. The ones `parts` and `details` place come first, in that order; the rest were not placed in the text. A client that draws `text` and then `viz` should skip the tables `parts` points at: `text` already holds them. |
| `followUps` · `followUpKinds` | Up to three next questions, and for each whether it is `deeper` (into this answer), an `alert` to set, or another `ask`. |
| `assets` · `focus` | Price chips for the assets the answer names; `focus` is the index of the one asset the answer is about, or `null`. |
| `citations` | Where to check the numbers: `{ label, href }` per source. `href` is a Chord page as a path under `https://getchord.xyz` (`/arc/token/0x…`), or the source's own URL. |
| `quote` | A route card when the question implied a trade: the two tokens, the amounts in whole tokens, the venues, price impact, fee and a link to the trade on Chord. It is a preview, not a `/v1/quote` response: `/v1/swap` needs a fresh `/v1/quote`. |
| `artifact` | The token the answer is about: its stats, where volume traded (support, resistance, VWAP) and a report link when one was built. No entry ladder, stop or targets: levels are a reading of the tape, not orders. |
| `toolsUsed` · `tokens` | What ran and what it cost. |

`shape`, `parts`, `details`, `followUpKinds` and `focus` are optional: an answer that asks you something back leaves `shape`, `parts` and `followUpKinds` out, with `details` and `focus` at `null`. Ignore all five and `text` plus `viz` is still the whole answer, without the folded `details`.

Errors: `401 UNAUTHORIZED` (no key), `429 RATE_LIMITED`, `503 DISABLED` (the analyst is off), `503 EMPTY` (no answer produced — ask again, more specifically).

## Streaming

Without `stream: false`, the response is server-sent events: `status` frames name the tool running (`{ "tool": "arc_price_analysis", "label": "Reading the tape" }`), one `answer` frame carries the object above, `error` carries `{ code, message }`, and `done` closes. Use it for a UI that shows progress; agents want the JSON.

## Picks and reports

- `GET /v1/ask/picks` — the analyst's current board (rebuilt every four hours over tokens with real activity): side, score, confidence, reasons for and against, and the seven-day track record (picks graded, the share that moved their way, average move). No targets or stops. Public.
- `POST /v1/ask/report { token }` — a three-page research note for a token (HTML for print-to-PDF, and Markdown), links good for seven days. Session-gated today.

## What to ask

It answers like a trader's analyst: from the index first, and from outside market data, news headlines and posts on X where the question needs them. Good questions: "what is moving on Arc and why", "launch forensics on 0x…", "top PnL wallets on Minara and how they traded it", "is TOLLY a buy here, and what would change that", "which pools pay real fees on USDC pairs". It takes a position and shows the evidence for it, and it says when the data is thin. A plan (zones, tranches, an exit, the level where the idea is wrong) is written only when you ask for one, as illustrative scenarios with their assumptions stated, never as advice.