---
title: "Ask the analyst"
method: POST
path: "/ask"
tags: ["Ask agent"]
---

# Ask the analyst

`POST /ask`

## Request

- Base URL: `https://api.getchord.xyz/v1`
- URL: `https://api.getchord.xyz/v1/ask`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Chord's analyst over the Arc index and the router — 40+ tools (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, depth, a bridge quote, read-only SQL over the index). Returns the answer, source links, an optional route card, tables and charts the analysis produced, and a report when one was built. It analyses: a plan (zones, tranches, an exit, the level where the idea is wrong) is written only when the question asks for one, and is illustrative, with its assumptions stated.

**Layout**: `text` is the whole answer on its own. The optional fields `shape`, `parts`, `details`, `followUpKinds` and `focus` say how the chat lays it out: `parts` is the same answer in order, with the tables and charts of `viz` placed inside the text (in `text` a placed table is written out as a Markdown table), and `details` is further depth the chat folds, which `text` does not repeat. A client that ignores them loses nothing of the answer.

**Auth**: a developer API key (`X-API-Key`) or a Google session bearer. Metered per key per day against the deployment's token budget; 8 questions a minute per caller.

**Agents**: send `"stream": false` for one JSON answer (5–40 s). Without it the response is `text/event-stream` with `status` events (which tool is running), `step` events (a lookup finished, with the chain it read), one `answer` event, then `done`.

## Request body

- object
  - `question` string, required: May be empty when `images` is set.
  - `stream` boolean: false = one JSON response instead of SSE.
  - `history` object[]: Up to 12 prior turns.
    - `role` 'user' | 'assistant'
    - `content` string
    - `images` string[]: Image ids that user turn carried — their reading comes back as context.
  - `wallet` string: The caller's wallet, so "my PnL" resolves.
  - `mode` 'quick' | 'deep': How long an answer to write. `quick`: the shortest form (the verdict, its claim, at most three rows of evidence, 120 words at most), faster. `deep`: a judgement or an explanation comes back as a full research note (`shape: "report"`), any other answer with a longer folded `details`. Omitted: the length the question calls for. Any other value is ignored.
  - `copilot` object: AI Copilot: the token whose trading screen the chat sits beside. The answer is about that token whatever the question names ("is it a buy?"): Chord reads the token's name itself, checks it, and points a question about something else to the main chat in one line. A value it cannot read (an unknown chain, no token, a 0x contract on Solana or a mint on an EVM chain) is ignored, and the question is answered as any other.
    - `chain` union, required: The token's chain: its key, or its chain id.
      - 'arc' | 'robinhood' | 'monad' | 'avalanche' | 'base' | 'bnb' | 'arbitrum' | 'ethereum' | 'solana'
      - 5042 | 4663 | 143 | 43114 | 8453 | 56 | 42161 | 1
    - `token` string, required: The token: its 0x contract (any case), or a Solana mint exactly as written (base58 is case-sensitive).
  - `images` string[]: Up to 4 ids from `POST /v1/ask/image` (your own, 30 days). The analyst reads each image — chart, positions, a swap or wallet screenshot — before it answers, and can zoom into one.

## Response `200`

With `stream: false`: the whole answer. Otherwise `text/event-stream`.

- object
  - `text` string: The answer, Markdown, complete on its own: a table the answer placed is written out in it (its first 8 rows and 6 columns). `details` is not repeated here.
  - `citations` object[]: Where to check the numbers: the Chord pages and outside sources behind the answer. On a deep answer (`mode: "deep"`, or a question that asks for deep research) they are numbered: `[n]` in `text` is `citations[n-1]`.
    - `label` string, required: What the link is.
    - `href` string, required: A Chord page as a path under `https://getchord.xyz` (`/arc/token/0x…`), or the source's own URL.
    - `tier` 1 | 2 | 3 | 4: Deep answers only: 1 primary data (Chord's index, an exchange, an explorer, DefiLlama, CoinGecko, an official page), 2 major media, 3 a blog or another site, 4 social.
    - `kind` 'index' | 'data' | 'official' | 'media' | 'blog' | 'social' | 'other': Deep answers only: the kind of source (`index` = Chord's own index).
  - `quote` object, nullable: 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. A preview, not a `/v1/quote` response: `/v1/swap` needs a fresh `/v1/quote`.
  - `artifact` object, nullable: The token the answer is about: its stats, where volume traded (support, resistance, VWAP), a report link when one was built.
  - `walletArtifact` object, nullable
  - `viz` object[]
  - `toolsUsed` string[]: Every tool called, by name. One tool serves several chains: `steps[].chain` says which chain each lookup read (not on a deep or researched answer, whose steps are its research parts).
  - `tokens` integer: Model tokens spent.
  - `steps` object[]: What ran, in order, one row per lookup. On a deep or researched answer the rows are its research parts instead (`tool` `deep_research`, `detail` "N lookups", no `chain`); `toolsUsed` names every lookup.
    - `tool` string, required: The tool's name.
    - `label` string, required: What the chat showed while it ran.
    - `round` integer, required: The model round it ran in, from 0.
    - `ms` integer, required: How long it took.
    - `detail` string, nullable: What it was asked for: a token, a wallet, a query.
    - `chain` 'arc' | 'robinhood' | 'monad' | 'avalanche' | 'base' | 'bnb' | 'arbitrum' | 'ethereum' | 'solana': The chain this lookup read (`chain_token` reads a token on Arc, Base or Solana alike). Absent when it read no chain or several: a search over every chain, a macro board, a research part of a deep answer.
    - `sources` object[]: The links this lookup read.
      - `label` string
      - `href` string
  - `followUps` string[]: Up to three next questions: one that goes deeper, one that widens, one action (an alert, a chart, a plan).
  - `assets` object[]
  - `revokes` object[]: Only when the answer read a wallet's approvals: the unsigned transaction that revokes each risky one, for the wallet's owner to sign. At most 20.
    - `chainId` integer, required: Chain id.
    - `kind` 'erc20' | 'nft', required: `erc20` = `approve(spender, 0)`, `nft` = `setApprovalForAll(spender, false)`.
    - `token` string, required: EVM address, hex, case-insensitive.
    - `spender` string, required: EVM address, hex, case-insensitive.
    - `to` string, required: Where the revoke is sent: the token or the NFT collection.
    - `data` string, required: The calldata, hex.
    - `value` '0', required
    - `label` string, required: What the button says (`Revoke USDT for 0x… (1inch Aggregation Router v6)`).
  - `shape` 'fact' | 'explain' | 'brief' | 'board' | 'why' | 'overview' | 'compare' | 'post' | 'do' | 'report' | 'auto': The kind of answer the question got: a single fact, an explanation, a call with its evidence (`brief`), a ranked list (`board`), why something moves, a market overview, a comparison, something to post, something to do on Chord, a full report, or `auto` when nothing matched.
  - `parts` union[]: The answer body in order: text, and the blocks of `viz` placed inside it. Absent on a question back (`clarify`).
    - union
      - object: Text.
        - `t` 'md', required
        - `text` string, required: Markdown.
      - object: The table or chart placed at this point.
        - `t` 'viz', required
        - `i` integer, required: Index into `viz`.
  - `details` object, nullable: Further depth (a per-venue breakdown, a longer history) that the chat folds under "Show full analysis". Not part of `text`. Null when the answer has none.
    - `text` string: The folded part as Markdown, placed tables written out.
    - `parts` union[]: `i` indexes the same `viz`.
      - union
        - object: Text.
          - `t` 'md', required
          - `text` string, required: Markdown.
        - object: The table or chart placed at this point.
          - `t` 'viz', required
          - `i` integer, required: Index into `viz`.
  - `followUpKinds` string[]: Parallel to `followUps`: `alert` = it asks for an alert, `deeper` = it goes deeper into this answer, `ask` = any other question.
  - `focus` integer, nullable: Index into `assets` of the one asset the answer is about, when there is one.

## Other responses

- `400`: Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).
- `401`: Missing or unknown credential (`UNAUTHORIZED`).
- `429`: Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.
- `503`: The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.

## Changes

- **2026-10-19** `d3bc4640fea0`: 1 info
  - added the new optional request property `copilot`

[Operation history](https://skmtc.dev/getchord/apis/chord-api/changes/ask/post.md)

---

[API](https://skmtc.dev/getchord/apis/chord-api.md) · [All operations](https://skmtc.dev/getchord/apis/chord-api/llms.txt) · [OpenAPI document](https://skmtc.dev/getchord/apis/chord-api/revisions/d3bc4640fea0?raw)