# Agents

The shape of this API is the reason it works natively with coding agents. Flat SQL WHERE clauses over named columns and flags. No joins, no window functions, no schema introspection round-trip. Hand the schema to your agent once and it can compose, replay, and subscribe queries on its own.

## Why this works with agents

- **The grammar is small.** A WHERE clause over named columns. No JOIN, no GROUP BY, no OVER.
- **The schema fits in a prompt.** 265 numeric/string columns + 148 pre-thresholded boolean flags. Paste it into a system prompt and the agent has the vocabulary.
- **No surprise dialect.** Identifiers are the customer-facing names; the API doesn't rewrite, alias, or coerce them.
- **One grammar, every endpoint that takes a clause.** The same SQL WHERE grammar drives `/scan` (as `q=`), `/scan?asof=` (as `q=`), `/scan/subscribe` (as `q`), and per-resource subscribe paths `/tickers/{T}/subscribe` and `/signals/{X}/subscribe` (as `condition`).

## The typical agent loop

1. User asks in English ("find oversold semis bouncing on volume").
2. Agent translates to a `q` clause, calls `/v2/scan` for live matches.
3. Agent calls `/v2/scan?asof=YYYY-MM-DD` across past dates to sanity-check.
4. Agent registers the same `q` as a webhook so future matches push.

State lives in the API; the agent stays stateless across turns.

## What to put in the system prompt

1. The list of column and flag names. Fetch https://tickerbot.io/docs/schema.json for the machine-readable dump.
2. The grammar bounds ("flat WHERE clause; bare identifiers; numeric literals fully specified, not `1.5B`").
3. The asset-symbol prefix rules (`X:BTCUSD` for crypto, etc. — see https://tickerbot.io/docs/symbols).

## Tool definitions

The page at https://tickerbot.io/docs/agents has interactive tool-definition JSON for Claude, OpenAI, Gemini, and MCP runtimes, auto-generated from the endpoint catalog. Pick a runtime, copy the JSON, paste it into your integration. Definitions never drift from the API because they share the same source as the rest of these docs.

Or fetch the catalog at runtime instead of pasting a static blob: `GET https://api.tickerbot.io/mcp/tools` returns the live tool array (`{ asOf, serverInfo, protocolVersion, tools }`) — the same source the `@tickerbot/mcp-server` npm package uses — so your runtime always reflects the latest surface.

## How to wire it up

When the LLM decides to call a tool, your code receives the tool name and arguments. Route the call to the matching Tickerbot endpoint, forward the bearer token, and return the JSON response to the LLM. See https://tickerbot.io/openapi.yaml for anything generator-driven.