Ask agent 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

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

{
  "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.