# FillRoute
# Execution rails for AI trading agents.

## What it is

FillRoute takes a trading signal (from TradingView, a custom model, or a
Centinela champion strategy) and turns it into an audited fill across
Binance, MT4, or MT5. One versioned API, one typed error envelope, one
Ed25519-signed audit trail — regardless of venue.

Every capability is reachable by an agent with a scoped API key. The human
Console is a supervisor view; it is not the control plane.

## Base URL

https://api.fillroute.com (prod) / http://localhost:3050 (dev)

## Authentication

Bearer fr_live_<key> on every call. Mint at https://fillroute.com/keys.
For the canonical quickstart below, mint the key with `signals:submit`,
`research:read`, and `audit:read`. Because `signals:submit` is a trade scope,
the owner must confirm trade scope during key creation.

## Canonical quickstart

```bash
KEY=fr_live_your_key_here
curl -X POST https://api.fillroute.com/api/v1/agent/signals \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "BUY",
    "symbol": "BTCUSDT",
    "venue": "sandbox",
    "strategy_id": "double7-btc-4h-v3",
    "notional_usd": 100
  }'
```

```bash
# After the signal response, fetch + verify the receipt
FILL_ID=<from signal response .fill_id>
curl -X POST https://api.fillroute.com/api/v1/agent/audit/export \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"fill_ids\": [\"$FILL_ID\"], \"format\": \"json\" }"
```

Verify the returned `signature` (Ed25519, base64) against the public key
published at `/.well-known/fillroute-keys.json`.

## Endpoints (Sprint 1 surface)

GET  /v1/agent/openapi.json
GET  /v1/agent/me
POST /v1/agent/signals              (requires Idempotency-Key)
GET  /v1/agent/routes
GET  /v1/agent/fills
GET  /v1/agent/audit
POST /v1/agent/audit/export         (Ed25519-signed receipt)
GET  /v1/agent/positions
GET  /v1/agent/risk/status
POST /v1/agent/risk/policies
GET  /v1/agent/research/strategies
GET  /v1/agent/research/strategies/:id
GET  /v1/agent/errors
GET  /.well-known/fillroute-keys.json

Same paths also work under /api/v1/agent/*.

## Error codes

Every mutating endpoint returns a typed error envelope
(`{ error_code, message?, ... }`) instead of prose. See /v1/agent/errors for
the full catalog (key_unknown, scope_missing, spend_cap_exceeded,
rate_limited, idempotency_conflict, guard_rejected, circuit_open,
strategy_below_parity, safe_f_stale, and more).

## belts

Bronze (read-only), Silver (sandbox + caps), Gold (live), Platinum (strategist), Diamond (research).
Bronze + Silver are live. Gold+ ship Sprint 3+.

The canonical Sprint 1 test: prompt E1.3 — "Find best champion strategy for
BTC, sandbox trade with 1% cap, show audit proof." Source:
eval/prompts/silver/E1.3.yaml in the FillRoute repo.

## More

Full docs: https://fillroute.com/agents
OpenAPI (partial, Sprint 1 surface): https://fillroute.com/agents/openapi.json
Source: https://github.com/famlopezmuralles/FillRoute