# 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, backtest, 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.** ~100 numeric/string columns + ~50 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 language, every endpoint.** The same `q` string drives `/scan`, `/scan?asof=`, `/webhooks`, and the saved-rules surface.

## 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/api/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/api/symbols).

See https://tickerbot.io/agents for a worked example with prompts, an agent transcript, and a starter repo.

## Tool definitions

The page at https://tickerbot.io/api/agents has interactive tool-definition JSON for Claude, OpenAI, 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.

## 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.