Skip to content
ChordChordChord Docs

Ask the analyst

POST
/ask
curl --request POST \
  --url https://api.getchord.xyz/v1/ask \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "question": "What is moving on Arc right now, and is ARGUS still being bought by real wallets?", "stream": false }'

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), one answer event, then done.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
question
required

May be empty when images is set.

string
<= 1000 characters
stream

False = one JSON response instead of SSE.

boolean
history

Up to 12 prior turns.

Array<object>
object
role
string
Allowed values: user assistant
content
string
<= 4000 characters
images

Image ids that user turn carried — their reading comes back as context.

Array<string>
wallet

The caller’s wallet, so “my PnL” resolves.

string
/^0x[a-fA-F0-9]{40}$/
mode

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.

string
Allowed values: quick deep
images

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.

Array<string>
Example
{
  "question": "What is moving on Arc right now, and is ARGUS still being bought by real wallets?",
  "stream": false
}

Responses

Section titled “ Responses ”

200

Section titled “200”

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

Media typeapplication/json
object
text

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.

string
citations

Where to check the numbers: the Chord pages and outside sources behind the answer.

Array<object>

A source link.

object
label

What the link is.

string
href

A Chord page as a path under https://getchord.xyz (/arc/token/0x…), or the source’s own URL.

string
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. A preview, not a /v1/quote response: /v1/swap needs a fresh /v1/quote.

object | null
artifact

The token the answer is about: its stats, where volume traded (support, resistance, VWAP), a report link when one was built.

object | null
walletArtifact
object | null
viz
Array<object>

Tables and charts (kind: table · bar · line · donut), at most 6: the ones parts and details place come first, in that order.

object
key
additional properties
any
toolsUsed
Array<string>
tokens

Model tokens spent.

integer
followUps

Up to three next questions: one that goes deeper, one that widens, one action (an alert, a chart, a plan).

Array<string>
assets
Array<object>

Price chips for the assets the answer names (symbol, label, price, 24h change), at most 8.

object
key
additional properties
any
shape

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.

string
Allowed values: fact explain brief board why overview compare post do report auto
parts

The answer body in order: text, and the blocks of viz placed inside it. Absent on a question back (clarify).

Array
One of:

Text.

object
t
required
string
Allowed value: md
text
required

Markdown.

string
details

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.

object
text

The folded part as Markdown, placed tables written out.

string
parts

i indexes the same viz.

Array
One of:

Text.

object
t
required
string
Allowed value: md
text
required

Markdown.

string
followUpKinds

Parallel to followUps: alert = it asks for an alert, deeper = it goes deeper into this answer, ask = any other question.

Array<string>
Allowed values: ask alert deeper
focus

Index into assets of the one asset the answer is about, when there is one.

integer | null
Example
{
  "shape": "fact",
  "parts": [
    {
      "t": "md"
    }
  ],
  "details": {
    "parts": [
      {
        "t": "md"
      }
    ]
  },
  "followUpKinds": [
    "ask"
  ]
}

400

Section titled “400”

Invalid parameters — error names the check that failed (INVALID_PARAMS, BAD_ADDRESS, BAD_LIMIT, BAD_HOURS, …).

Media typeapplication/json

Every non-2xx body.

object
error
required

Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.

string
message

For humans.

string
statusCode

HTTP status, when included.

integer
Example
{
  "error": "INVALID_PARAMS",
  "message": "amount must be an integer string in the token's smallest unit"
}

401

Section titled “401”

Missing or unknown credential (UNAUTHORIZED).

Media typeapplication/json

Every non-2xx body.

object
error
required

Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.

string
message

For humans.

string
statusCode

HTTP status, when included.

integer
Example
{
  "error": "INVALID_PARAMS",
  "message": "amount must be an integer string in the token's smallest unit"
}

429

Section titled “429”

Over the per-minute limit (RATE_LIMIT_EXCEEDED). Read X-RateLimit-Reset and back off.

Media typeapplication/json

Every non-2xx body.

object
error
required

Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.

string
message

For humans.

string
statusCode

HTTP status, when included.

integer
Example
{
  "error": "INVALID_PARAMS",
  "message": "amount must be an integer string in the token's smallest unit"
}

503

Section titled “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.

Media typeapplication/json

Every non-2xx body.

object
error
required

Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.

string
message

For humans.

string
statusCode

HTTP status, when included.

integer
Example
{
  "error": "INVALID_PARAMS",
  "message": "amount must be an integer string in the token's smallest unit"
}