> ## Documentation Index
> Fetch the complete documentation index at: https://docs.routeur.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent workflows

> Four things agents do well with Routeur, with the tool calls each one takes.

Each of these is a sequence an agent can run on its own. The first three are also built in as [prompts](/agents/overview#what-it-exposes), so a client can offer them as commands.

## Find something tradeable, then prove it

```
find_opportunities { category: "Sports", executable_only: true, min_volume_usd: 5000 }
  → rows: leads, cross-venue gaps, strategy matches, each with venue + market ids
explain_relation { a_venue, a_id, b_venue, b_id }     # for the row you care about
  → the proven relation, its evidence, and whether prices respect it
market_snapshot { venue, id }                          # the leg you would buy
  → price, spread, recent fills, 7-day history, what it is linked to
```

Four to ten API requests in total. Report the pair, what it costs, what it pays, the fees, the size the books showed, and what would kill it. `depth.limited_by` names what stopped the fill growing: `price`, `depth`, `minimum`, `fees` or `unavailable`.

## Price one question on both venues

```
search_markets { query: "fed decision december", cross_venue: true }
compare_venues { venue, event_id }
  → each outcome with both venues' asks, the gap in cents, and the cheaper venue
```

Two requests. `compare_venues` matches outcomes across venues by proven equivalence, not by wording, so "Fed cuts 25bps" on one venue lines up with its counterpart on the other. A gap is not a trade: check `find_opportunities` for whether it can be filled after fees.

## Watch one market and say when something happens

```
market_snapshot { venue, id, days: 30 }        # the baseline
list_flow_signals { venue, kind: "one_sided", hours: 6 }
get_tape { min_usd: 10000, hours: 6 }
```

Signals describe trading, not its cause: `burst` is far more trades than the market normally sees, `large_fill` is one fill much larger than its typical trade, `one_sided` is unusual flow almost all one way that moved the price with it. Say what moved and how much money was behind it; do not invent a reason.

For a standing watch, do not poll every minute — subscribe to the [`lead.executable` webhook](/webhooks/overview) and let the agent react to the delivery.

## Test an idea against settled history

```
list_strategies { venue: "all", category: "Politics" }
get_calibration { venue: "all", category: "Politics", horizon_days: 7 }
get_strategy { id }                            # the markets that fit it now
market_snapshot { venue, id }                  # is the ask really in the band?
```

Calibration is the honest version: for each 10-cent band, how many settled markets fell in it, what they averaged, and the share that resolved Yes. A band whose `yes_rate` sits above its `avg_price_usd` is where a strategy's return comes from. Buying Yes at price `p` in a band that resolves Yes at rate `r` returns `100 * (r / p - 1)` per \$100 before fees.

<Warning>
  Returns are historical, before fees, and use each band's average midpoint rather than the ask you would have paid. A rule fitted on the history that selected it is not an out-of-sample test, and a 95% range is not a floor.
</Warning>

## Writing the agent's instructions

Give the agent these rules; they prevent most wrong answers.

```
Prices are asks on a contract that pays $1, as exact decimal strings. Name the venue with every price.
The spread (yes_ask + no_ask - 1) is what crossing costs; a wide spread is a thin book, not an edge.
A relation is proven from contract terms, never guessed. No relation means "not proven", not "unrelated".
A gap between venues is money only if both books have size and fees leave something.
Strategy and calibration numbers are settled history, before fees, and are not a forecast.
Say how fresh the data is: prices are minutes old, the relation graph is rebuilt hourly.
Routeur places no orders. Never give investment advice or size a position.
Budget: at most N Routeur tool calls per answer.
```

## Handling limits

A tool call that runs into your key's limit comes back as a tool error naming `rate_limited` or `daily_quota_exceeded` with the seconds to wait. Teach the agent to wait rather than retry immediately, and remember that one composed call can cost several requests — each tool's description says how many. See [Rate limits](/rate-limits).