# Chatito Agent API (Phase 3 + public catalog)

**Host:** https://chatito.ai/agent-api.md  
**Base URL:** `https://app.chatito.com/api/agent/v1`  
**Updated:** 2026-08-06  
**OpenAPI:** https://chatito.ai/openapi-agent-v1.yaml  
**Recipes:** https://chatito.ai/recipes.md  
**Human Docs:** https://chatito.com/docs/ai-agents · in-app Help https://app.chatito.com/help/#agents

## What this is

API for **AI agents** on Chatito:

- **Public (no key):** catalog (plans, scopes, prices, onboarding) + lightweight status  
- **Read:** strategies, equity, stats, fills, heat, health, Lab gates, boards, market context, credits, audit  
- **Paper write (Phase 2):** create from template, enable paper, pause, soft kill, patch allowlisted fields, webhooks  
- **CEX/DEX paper:** list/create + **get / equity / stats / pause / enable / kill** (same strategy paths; crypto via internal service key)  
- **Lab evaluation (Phase 3):** sample tiers, promote/kill evaluation on stats  
- **Boards + context (Phase 3):** sanitized public strategy leaderboard + market context  
- **Lab writes (Phase 3):** credit-gated invent, one-axis A/B, offline score, paper fork  

**Not financial advice.** Paper first. **Never arms live capital** from agent keys.

### Starter paper on mint (soft onboard)

When a key is minted (Settings, claim-code bootstrap, or multi-key mint) and the **owner has no running Predictions paper**, Chatito may **auto-create** one or more **paper** books so the next session already has equity/fills/stats.

| Detail | Value |
|--------|--------|
| Default book | Predictions **Late Edge** (`crypto_endgame`), name `Agent starter · Late Edge` |
| Origin | `agent_starter` |
| Live | **Never** auto-armed |
| Policy | Once if no running paper (operator-tunable) |
| Mint response | `starter_books`: `{ attempted, created[], skipped_reason, count }` |
| Later discovery | `GET /me` → `starter_books` · `GET /strategies` (`source` / lab origin) |

**Agents:** read `starter_books` after mint/claim; **list strategies before** `POST /strategies` to avoid duplicates.  
**Humans:** Settings shows a one-line hint when a starter was created; pause anytime in Predictions.

Operator can change kind or add venues later (`GET/PATCH /api/auth/operator/agent-starter`).

## Before you have a key (public)

Agents may call these **without** `Authorization` (rate-limited):

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/public/catalog` | Plans (Free · AI Lab), prices, scopes, credit costs, mint steps, billing slice, commerce roadmap |
| GET | `/public/status` | Agent API up/down + bootstrap phase flags |
| POST | `/public/bootstrap` | Create claim-code session (name, scopes, client_hint) |
| GET | `/public/bootstrap/{code}` | Poll status; after human claim, **secret once** |

```bash
curl -sS https://app.chatito.com/api/agent/v1/public/catalog | head
curl -sS https://app.chatito.com/api/agent/v1/public/status
```

Use the catalog to **explain** Chatito to the human owner. Do **not** invent prices from training data when this endpoint is available.

### Claim-code bootstrap (free key)

1. `POST /public/bootstrap` with JSON e.g. `{"name":"hermes","scopes":["read","paper_trade"],"client_hint":"hermes"}`  
2. Show the human `claim_url` (or the `code`)  
3. Human signs in, opens link, clicks **Claim On This Account**  
4. Poll `GET /public/bootstrap/{code}` until `status=claimed` and `secret` appears **once**  
5. Store `chk_…` in host secrets; never log the secret  
6. Check mint/poll payload for `starter_books` (may already have a running Late Edge paper book)

### Wallet pay + Lab mint (Phase 3)

1. `POST /public/bootstrap` with `{"intent":"lab_month","chain":"base","name":"crew","scopes":["read","paper_trade","lab"]}` (or `lab_year`)  
2. **Wallet path:**  
   - `POST .../siwe/prepare` `{ "address": "0x…" }` → sign `message`  
   - `POST .../siwe/verify` `{ "message", "signature" }` → invoice  
   - Pay native amount from that wallet  
   - `POST .../confirm` `{ "tx_hash": "0x…" }` → Lab grant + key mint  
3. **Human path (preferred for newcomers):** send the human to standalone checkout  
   - Catalog field `billing.human_checkout` → **https://app.chatito.com/checkout**  
   - Deep link query (optional): `?chain=polygon|base&sku=lab_month|lab_year&promo=CODE&pay=1`  
   - Page has **no dashboard chrome** (logo + checkout + short “What is Chatito” + Website / Open App)  
   - Hard-open `/checkout` must **not** flash the dashboard shell (standalone SPA route)  
   - Human signs in if needed → **Connect Wallet** → pay onchain from a linked wallet  
   - Optional **Invite code** applies a fixed USD price when configured  
4. Poll until `secret` once  

Also valid for logged-in renew: Settings → Account → Get / Renew AI Lab (same invoice rails).  

Alternative free path: Settings → Agent API → Create key (no pay).

**Commerce shipped (`agent_native_commerce_v1`):** catalog · claim-code · wallet Lab mint · email link · agent billing · multi-key. **Later:** Phase 5 allowances / auto-renew. Details in catalog `commerce` and monorepo `docs/AGENT_PLATFORM.md` §16.

## Auth (after mint)

```http
Authorization: Bearer chk_…
```

## Scopes

| Scope | Allows |
|-------|--------|
| `read` | GET me, health, strategies, equity, stats, lab/gates, lab/credits, boards, markets, templates, keys/me, audit/export, login-methods, billing status |
| `paper_trade` | All of `read` + create / patch / paper enable / pause / kill / fork (also implied by `lab`) |
| `lab` | Invent / A/B / offline score (+ paper mutations) |
| `webhooks:manage` | Register lifecycle / fill webhooks |
| `account:manage` | Link email for dashboard magic-link login |
| `billing:manage` | Create / confirm onchain Lab invoices |
| `keys:manage` | List / mint / revoke additional agent keys |

Live trade scopes are **not** available. WebSocket stream is not shipped (use webhooks).

## Dashboard login (email vs wallet)

Wallet SIWE bootstrap is great for crypto agents, but **not every human has that wallet in MetaMask**. For the dashboard:

1. Pass `email` on `POST /public/bootstrap` (linked at mint), or  
2. `POST /public/bootstrap/{code}/email` before/after claim, or  
3. With a key that has `account:manage`: `POST /account/email` `{ "email": "you@domain.com" }`  

That creates the same invite-style email identity used for Supabase **magic link** login at https://app.chatito.com. Same Chatito user as the wallet and agent keys.

`GET /account/login-methods` (scope `read`) lists masked email / wallet / social links.

**Chatito does not send the magic link from the Agent API** - the human completes Sign in with email in the app.

## Agent billing + multi-key (Phase 4)

| Method | Path | Scope |
|--------|------|-------|
| GET | `/account/login-methods` | read |
| POST | `/account/email` | account:manage |
| GET | `/billing/status` | read |
| POST | `/billing/checkout` | billing:manage |
| POST | `/billing/checkout/{id}/confirm` | billing:manage |
| GET | `/keys` | keys:manage |
| POST | `/keys` | keys:manage |
| DELETE | `/keys/{id}` | keys:manage |

## Read endpoints

| Method | Path | Scope |
|--------|------|-------|
| GET | `/me` | read |
| GET | `/health` | read |
| GET | `/strategies` | read |
| GET | `/strategies/{id}` | read |
| GET | `/strategies/{id}/equity` | read |
| GET | `/strategies/{id}/stats` | read |
| GET | `/strategies/{id}/fills` | read |
| GET | `/lab/gates` | read |
| GET | `/lab/credits` | read |
| GET | `/boards/strategies` | read |
| GET | `/markets/context` | read |
| GET | `/markets/heat?venue=cex\|dex` | read |
| GET | `/keys/me` | read |
| GET | `/templates` · `?venue=cex\|dex` | read |
| GET | `/audit/export` | read |

### Stats + Lab evaluation

`GET /strategies/{id}/stats` includes `sample_tier`, `evidence`, `evaluation` (promote/kill), `lab`, `gates`.

### Public strategy board

`GET /boards/strategies?book=paper&sort=score&limit=25` — sanitized arena (no cash/bot fields).

### Market context

`GET /markets/context` — assets, windows, exchanges, template defaults. Not OHLCV.

## Paper write endpoints (Phase 2)

| Method | Path | Scope |
|--------|------|-------|
| POST | `/strategies` (PM kinds or `venue=cex\|dex` + dca/limit) | paper_trade |
| PATCH | `/strategies/{id}` | paper_trade |
| POST | `/strategies/{id}/paper/enable` | paper_trade |
| POST | `/strategies/{id}/pause` | paper_trade |
| POST | `/strategies/{id}/kill` | paper_trade |
| POST | `/strategies/{id}/fork` | paper_trade or lab |

Optional header: `Idempotency-Key` on create.

## Lab write endpoints (Phase 3)

| Method | Path | Scope | Credits |
|--------|------|-------|---------|
| POST | `/lab/invent` | lab | invent cost (see `/lab/credits`) |
| POST | `/lab/ab` | lab | none (capacity still applies) |
| POST | `/lab/score` | lab | none |

### Invent body

```json
{
  "prompt": "Late edge BTC/ETH 5m conservative paper",
  "accept": true,
  "activate": true
}
```

Safe invent kinds only (same as product AI Lab): endgame, monte carlo, dual tilt, hybrid. Not HFT pair / invented DSL.

### A/B body

```json
{
  "parent_id": "lab_…",
  "axis": "min_edge",
  "value": 0.04,
  "activate": true
}
```

Axes: `GET /lab/gates` → `ab_axes`.

### Offline score body

```json
{ "kind": "crypto_endgame", "params": { "assets": ["btc", "eth"], "min_edge": 0.03 } }
```

## Metrics (do not invent)

| Metric | Meaning |
|--------|---------|
| Volume / fill counts | **BUY** fills |
| Win% / sample n | **Settled** reviews only |
| PnL | Trading PnL (realized + unrealized) |
| ROI | PnL ÷ BUY notional; null if BUY volume under $1 |

## Errors

```json
{
  "error": {
    "code": "scope_required",
    "message": "…",
    "docs_url": "https://chatito.ai/errors.md#scope_required",
    "request_id": "req_…"
  }
}
```

Codes: `unauthorized` · `forbidden` · `scope_required` · `not_found` · `rate_limited` · `capacity_exceeded` · `validation_error` · `insufficient_credits` · `credits_error` · `venue_unavailable` · `internal_error`

## Limits (defaults)

- ~60 requests / minute per key  
- Monthly call budget (default 100k)  
- Max 10 active keys per account  
- Plan capacity applies to paper create / invent / A/B  
- Invent spends AI Lab credits (same catalog as product Lab; Free plan monthly drip is 0)  
- **Predictions** strategy list/create is default (`GET/POST /strategies` without venue).
- **CEX/DEX list/create shipped:** `GET /strategies?venue=cex|dex`, `GET /templates?venue=cex`, `POST /strategies` with `venue=cex|dex` and kind `dca_in|dca_out|limit` (params: `symbol`, `quote_amount_usd`, …). Never arms live. Requires `CHATITO_INTERNAL_SERVICE_KEY` on platform + crypto services.
- CEX/DEX detail equity/stats/pause via Agent API still Predictions-first (use app UI or future residual).

## Phase map

| Phase | Status |
|-------|--------|
| 1 Read API | Shipped |
| 2 Paper create / pause / webhooks | **Shipped** |
| 3 Lab + boards + invent/A/B + SDKs | **Shipped** |
| 4 Live scopes | Planned (human arm still required) |

## MCP

### Hosted remote

```
POST https://app.chatito.com/api/agent/mcp
Authorization: Bearer chk_…
```

Tools include: `get_me` · `get_health` · `list_strategies` · `get_strategy` · `get_equity` · `get_stats` · `get_lab_gates` · `get_lab_credits` · `get_strategy_board` · `get_market_context` · `list_fills` · `get_heat` · `create_paper_strategy` · `enable_paper` · `pause_strategy` · `kill_strategy` · `invent_strategy` · `ab_spawn` · `score_strategy` · `fork_strategy`.

## SDKs

| Lang | Path | Notes |
|------|------|-------|
| Python | `sdk/python` (`chatito-agent` **0.4.0**) | `invent`, `ab_spawn`, `score`, `fork`, `lab_credits` |
| TypeScript | `sdk/typescript` (`@chatito/agent` **0.4.0**) | same surface |

```bash
# Python
cd sdk/python && pip install -e .
export CHATITO_AGENT_KEY='chk_…'
python -c "from chatito_agent import Client; print(Client().me()['phase'])"

# TypeScript
cd sdk/typescript && npm install && npm run build
```

## Recipes

See https://chatito.ai/recipes.md for heat→paper, lab eval, invent, A/B walkthroughs.