AI agents and API

The MCP server

Every ftw.trade tool over the Model Context Protocol. Authentication, how calls are checked and refused, conventions every tool shares, and the full tool catalog.

View as Markdown

The server#

One server at two addresses, over Streamable HTTP (JSON-RPC 2.0):

https://ftw.trade/api/mcp: every tool.
https://ftw.trade/api/mcp/essentials: the most-used tools, with search_tools, get_tool and run_tool to reach the rest.

Every tool is a call the site's own pages make, through the same functions, so what an agent builds opens the same on the site.

Authentication#

OAuth: point the client at the address. It discovers the authorization server, registers itself, and sends you to ftw.trade to sign in and approve (PKCE). Access tokens last 30 days; refresh tokens rotate.
API key: make one on the AI & API page (fwb_at_…, shown once) and send Authorization: Bearer fwb_at_…. Keys can be narrowed to projects, tools, paper only, an expiry and a daily spend. See API keys and session keys.

Calls and refusals#

Every tool has a title, a description, annotations (read-only, destructive, open-world) and a closed JSON schema. Arguments are checked before anything runs: an unknown one is refused, naming the ones it takes.

A refusal says exactly what to fix, <status>: <message>, with the field:

Status	Means
400	The arguments are wrong. The field is named
403	Live trading isn't allowed on this connection. The message says where to allow it
404	No such thing (an id from the wrong list, a deleted project)
409	A conflict: a stale version, a name taken, a limit reached. Read the current state and redo the change
422	Understood but not allowed. The message names the fix
500	A fault on ftw.trade's side, with a reference to quote

Conventions#

Ids come from the list_* tools: projects, pools (chain:address), series, deployments (sd_…), automations (au_…).
Guides first: get_project_guide, get_strategy_guide, get_automation_guide and others return the exact shapes their tools take, with working examples.
Dry runs: many tools that change things take apply and only describe what would happen until it's true.
Versions: a save made from an older copy of a document is refused (409), so an agent never undoes your edit.
Mode: every trade answer carries mode: paper | live.
Checks before saves: check_strategy compiles without saving, test_strategy runs cases, backtest_* replay history, previews say what would happen.

Areas#

Area	Examples
Skills and tools	`list_skills`, `get_skill`, `search_tools`, `run_tool`
Projects and dashboards	`create_project`, `save_project`, `update_dashboard`, `check_dashboard`
Sources	`add_pool`, `add_perps_market`, `save_flow_source`, `create_source`
Strategies	`check_strategy`, `save_strategy`, `backtest_strategy`, `run_optimization`, `run_strategy`
Workflows and scripts	`save_workflow`, `control_workflow`, `save_automation`, `run_automation`
Trading	`place_resting_order`, `run_perps_move`, `place_prediction_order`, `get_order_book`
Wallets and funds	`list_account_wallets`, `transfer_funds`, `get_bridge_quote`
Vaults	`list_vaults`, `create_vault`, `place_vault_order`
Account	`get_portfolio`, `get_log`, `get_flow`

The full, generated catalog of every tool is in the MCP skill and its tool reference.

Resources and prompts#

Skills are also MCP resources (ftw://skills/<name>/<file>), and the server offers prompts: start, build-strategy, design-dashboard and check-account.

Pushed sources over HTTP#

Pushed sources receive events at POST /api/sources/<name>/events with the source's own key. See Pushed sources.