# tokens for thoughts API reference

Self-funding inference for onchain agents. An agent's pump.fun coin pays creator fees into the agent's inference balance; this API spends that balance.

Base URL: `https://tokensforthoughts.com`
Auth: `Authorization: Bearer tft_…` (the agent's key, shown once at launch; rotate it on the agent page).
Network: Solana mainnet.

## OpenAI-compatible HTTP

### POST /v1/chat/completions
OpenAI chat completions. `model` may be any listed model id, or `"default"` for the model the agent launched with.
- The worst-case cost is reserved from the balance before the call and settled to the real cost after it.
- `max_tokens` is capped by the server. `n` is always 1. Provider routing overrides are ignored.
- `stream: true` is supported. If a stream is cancelled before it finishes, the full reservation is kept.
- Every response carries the header `x-tft-balance-usd`.
- Errors: `401` bad key · `402` balance can't cover this request · `413` body too large · `429` over 120 requests per minute.

### GET /v1/balance
`{ agent, name, symbol, model, balance_usd }`

### GET /v1/models
The models this key can call.

## MCP

### POST /mcp
A remote MCP server using Streamable HTTP with JSON responses. It takes the same bearer key.

Tools:
- `chat({ prompt | messages, model?, max_tokens? })`: a chat completion paid from the balance, with the same metering as `/v1`.
- `balance()`: the remaining balance in USD and the default model.
- `agent_info()`: name, ticker, coin mint, fee split and public page.
- `list_models()`: the models the agent can run on.

Client setup:
- Claude Code: `claude mcp add --transport http tokensforthoughts https://tokensforthoughts.com/mcp --header "Authorization: Bearer tft_…"`
- Cursor: add `{ "url": "…/mcp", "headers": { "Authorization": "Bearer tft_…" } }` to `mcp.json`.
- Codex: set `url` and `bearer_token_env_var` in `~/.codex/config.toml`.
- Claude Desktop: run `npx -y mcp-remote …/mcp --header "Authorization:${TFT_AUTH}"`.
- ChatGPT: in developer mode, create a connector with URL `…/mcp` and Authentication set to OAuth. ChatGPT opens our approval page, where you paste the agent key once.

OAuth 2.1 (for clients that sign in): discovery at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`, dynamic registration at `/oauth/register`, PKCE S256 required, and a token endpoint at `/oauth/token`. Tokens cover a single agent and are revoked when its key is rotated.

## Public reads (no key)
- `GET /api/agents/{id}`: the agent's coin, fee split, balance and activity.
- `GET /api/models`: the models an agent can launch with.
- `GET /api/health`: network, database and launch status.

## Fees
Every harvested creator fee goes to the agent's inference balance (100%). This is locked on-chain at launch. These are draft terms.