# Auth.md — how AI agents authenticate to IOST Terminal

IOST Terminal is an AI real-time trading platform (crypto + equities, paper-first).
Agents can read public market data with **no auth**, and act on an account with a
**scoped agent API key** — or an OAuth 2.0 bearer token derived from one.

## Public (no auth) — read-only
`/api/ui-state` · `/api/scores` · `/api/scanner` · `/api/analyze/:symbol` · `/api/news` ·
`/api/onchain` · `/api/probability` · `/api/leaderboard` · `/api/backtest` ·
`/api/signals/feed` · `/api/token-audit` · `/api/smart-money` — all public, no keys.

## Agent API keys (recommended)
1. Human signs in at https://iostcallister.com/app → **Portfolio → AI Agents → Create key**.
2. Key looks like `itk_…`; the full secret is shown **exactly once** (like a wallet seed).
3. Scopes: `read` (always) · `trade-paper` (open/close paper trades) · `trade-live` (owner-only, requests only).
4. Send it: `X-API-Key: itk_…` on every request. Revocable instantly in the UI.

## OAuth 2.0 (client_credentials)
Discovery: `/.well-known/oauth-authorization-server` (RFC 8414) · `/.well-known/oauth-protected-resource` (RFC 9728).
- `client_id` = the key's id (shown in the app), `client_secret` = the full `itk_…` secret.
- `POST /oauth/token` with `grant_type=client_credentials` (form body or HTTP Basic) → a 15-minute opaque bearer session. Only its SHA-256 digest is retained in memory. MCP clients include `resource=https://iostcallister.com/mcp`; tokens are audience-bound and cannot be replayed across resources.
- Optional `scope=read trade-paper` may narrow the source key. It can never add a scope, and MCP sessions always exclude `trade-live`.
- Use `Authorization: Bearer <token>` — resolves to the same identity + scopes as the key.
- Revoke: `POST /oauth/revoke` with `{token}`, or revoke the source agent key to invalidate every bearer derived from it immediately.

## Agent paper execution rail
Agent-key paper opens require the `trade-paper` scope, a positive `entry` and
`size`, a protective `stop`, an owned agent `walletId`, an active
wallet-bound `pactId`, and an allowed server portfolio-risk preflight.
Human-session paper execution remains unchanged.

## MCP 2026-07-28
Endpoint: `POST https://iostcallister.com/mcp`. Public tools are read-only. A user-bound key or
an MCP-resource-bound bearer token adds private evaluation/account tools,
including `paper_execution_receipts` and `paper_execution_intents` with
tamper-evident execution evidence and replay-safe intent status. The read-only
`strategy_promotion_scorecards` tool returns evidence-bound paper lifecycle
recommendations without changing agent authority. The read-only
`paper_position_guardian` tool reports server-enforced bracket/OCO coverage,
fresh-quote watchdog health and automatic risk-reducing exit evidence. The
`agent_runtime_status` and idempotent `agent_runtime_heartbeat` tools add
owner-bound liveness, readiness, exact-checkpoint recovery and fail-closed
mission execution leases without expanding the agent's authority. Optional
version/cadence fields identify the deterministic Runtime Supervisor companion;
they are evidence, not permission. The
read-only `agent_incident_status` tool reports deduplicated runtime incidents,
automatic quarantine, recovery readiness and owner-review requirements without
acknowledging or resolving an incident. The read-only
`agent_safety_slo_status` tool reports honest evidence coverage, mission-readiness
error-budget burn and deterministic recovery playbooks without applying actions. The
read-only `agent_owner_alert_status` tool reports the durable private owner inbox,
signed delivery, bounded retry/dead-letter state and receipt verification without
acknowledging incidents, recovering agents or changing authority. The
`paper_approval_request` and read-only `paper_approval_requests` tools add
short-lived, exact, single-use owner mandates for mission policies that require
human review. Agents cannot approve themselves, and approval never bypasses a
current execution gate. The
`trade-paper` scope adds read-only `paper_trade_preflight` plus
`paper_trade_open` and `paper_trade_close`.
Both require a unique `intentId`; exact retries return the original terminal
outcome and conflicting reuse fails closed. Paper opens still require the wallet
and Pact fields above. No MCP tool can execute a live,
token, conversion, wallet-send, swap, or public-chain action.
Paper closes use a server-observed market price (or the last server observation
if a fresh quote is unavailable); a client cannot select the P&L exit price.

## Live trading — human-in-the-loop
Agents never execute live trades directly. With a `trade-live` key an agent submits a
**proposal** (`POST /api/live/proposals`); the owner approves or rejects it
(`POST /api/live/proposals/:id/approve|reject`) before anything reaches the venue.
No CAPTCHAs, no barriers — keys and rails instead.

## Fail-closed
There are no default/shared platform keys. Unset credentials = no agent identity.