# FYN Agent API — Full Reference for AI Agents

> This file is the complete machine-readable reference for consuming FYN financial data from an AI agent. Curated for LLM consumption via https://fyn.fyi/llms-full.txt. Short index: https://fyn.fyi/llms.txt

## What FYN provides

FYN is a personal finance backend: bank transactions (Plaid, read-only), receipts with AI OCR/line items, budgets, subscriptions, portfolio, and AI insights. The Agent API exposes 28 read-only endpoints over plain HTTPS for agents that are not (or are also) MCP clients.

## Decision tree for an agent

1. **You are an MCP client (ChatGPT, Claude, Cursor, …)** → use `https://api.fyn.fyi/v1/mcp`. Self-enrollment is fully machine-driven: OAuth 2.1 + PKCE with dynamic client registration. Discovery metadata is published at:
   - `https://api.fyn.fyi/.well-known/oauth-protected-resource` (RFC 9728; also served at `https://api.fyn.fyi/v1/mcp/.well-known/oauth-protected-resource`)
   - `https://api.fyn.fyi/.well-known/oauth-authorization-server` (RFC 8414, with an `openid-configuration` alias)
   A human signs in once with their FYN account to approve read-only access; that human step cannot be automated and must be requested from the user.
2. **You are not an MCP client** → use the REST Agent API below with a Bearer API key. The key requires a human to: sign up at https://fyn.fyi/register (free tier, no credit card), optionally connect a bank via Plaid, then create a key at https://fyn.fyi/settings (Settings → Agent Access → New Key, shown once). If you are an agent being asked to set this up, stop and ask the user to produce the key.
3. **Got 401** → key invalid or revoked; keys are per-account and read-only. Ask the user to regenerate one and check for whitespace/paste errors.

## REST Agent API

- Base URL: `https://api.fyn.fyi/v1/agent`
- Auth: `Authorization: Bearer <FYN_API_KEY>` on every request.

### Response envelope

All endpoints return:

```json
{
  "success": true,
  "data": { },
  "meta": {
    "plan": "free",
    "rateLimit": { "remaining": 49, "limit": 50 }
  }
}
```

Errors return `success: false` and a `data.error` message with an appropriate HTTP status (401 unauthorized, 400 bad request naming the invalid/missing field, 404 not found, 429 rate limited, 500 server error).

### Quick test

```bash
curl -s https://api.fyn.fyi/v1/agent/accounts/net-worth \
  -H "Authorization: Bearer $FYN_API_KEY"
```

### Rate limits

| Plan | Daily API calls | RAG/days |
| --- | --- | --- |
| Free | 50 | 10 |
| Pro ($9.99/mo) | 2,000 | 500 |

Endpoints marked (Pro) require the Pro plan.

### Endpoints

Data returned is scoped to the authenticated account; no endpoint moves money.

#### Transactions

- `GET /v1/agent/transactions/recent` (default 10) — query params: `limit`, `category`, `merchant`, `start_date`.
- `POST /v1/agent/transactions/sum` — spend totals. Body: `start_date` (`YYYY-MM-DD`), `end_date`, `merchant` (string), `category` (string). All optional; omit for all-time total.

#### Spending

- `POST /v1/agent/spending/breakdown` — Body: `group_by` (required: `"category"` or `"merchant"`), `start_date`, `end_date` (`YYYY-MM-DD`), `limit`.
- `POST /v1/agent/spending/compare` — period-over-period comparison. Body: `period1`, `period2` (required, format `"YYYY-MM"`), optional `category`.
- `POST /v1/agent/spending/discretionary` — discretionary spend analysis. Body: optional `months` (int, lookback window).

#### Accounts

- `GET /v1/agent/accounts/net-worth` — assets, liabilities, net worth, account count.
- `GET /v1/agent/accounts/balances` — all account balances.
- `GET /v1/agent/accounts/balance?account_name=<name>&account_type=checking` — one account. Query params: `account_name`, `account_type`.

#### Budgets

- `GET /v1/agent/budget/status` — per-category budget usage.
- `GET /v1/agent/budget/over` — categories currently over budget.

#### Subscriptions

- `GET /v1/agent/subscriptions` — recurring charges.
- `GET /v1/agent/subscriptions/total` — total monthly subscription spend.

#### Cash flow

- `GET /v1/agent/cashflow` — income vs expenses for the current period.
- `GET /v1/agent/cashflow/savings-rate` — savings rate.

#### Insights

- `GET /v1/agent/insights/daily` — daily financial briefing.
- `GET /v1/agent/insights/weekly` — weekly recap.
- `GET /v1/agent/insights/alerts` — spending alerts (spikes, budget risk, subscription price changes).
- `GET /v1/agent/insights/health` — financial health score (0–100) with savings rate, subscription cost, and top recommendations.
- `GET /v1/agent/insights/opportunities` — saving/optimization opportunities.
- `POST /v1/agent/insights/ask` — natural-language question about the user's finances. Body: `query` (required string).

#### Portfolio

- `GET /v1/agent/portfolio` — portfolio value and allocation.
- `GET /v1/agent/holdings` — individual holdings.

#### Receipts (Pro)

- `POST /v1/agent/receipts/search` — search receipt text/line items. Body: `query` (required), optional `start_date`, `end_date`.
- `POST /v1/agent/receipts/rag` — RAG chat over receipts (counts against RAG daily limit). Body: `query` (required), optional `start_date`, `end_date`.
- `GET /v1/agent/receipts/deals` — deals/price-adjustment opportunities across receipts.
- `POST /v1/agent/receipts/insights` — price insights (cheaper alternatives, shrinkflation, membership ROI). Body: optional `receipt_id`, `category`.

#### Intelligence (Pro)

- `POST /v1/agent/affordability` — "can I afford this?". Body: `amount` (required number), optional `account`.
- `GET /v1/agent/recommendations` — product/subscription recommendations.

#### API key management (session auth, human-side)

Managed in-app (Settings → Agent Access); these endpoints use session/JWT auth, not the agent key:

- `POST /v1/agent/keys` — create a key (optionally named).
- `GET /v1/agent/keys` — list keys (metadata only; plaintext never returned again).
- `DELETE /v1/agent/keys/{keyId}` — revoke a key.
- `POST /v1/agent/keys/{keyId}/rotate` — rotate a key (old key stops working, new one returned once).

### Security notes

- Agent API keys are read-only and instantly revocable; hashed (SHA-256) at rest; plaintext shown exactly once at creation.
- Bank access via Plaid is read-only; FYN cannot move money.
- All data is scoped to the authenticated FYN account.
- Never print or log a full API key; mask it to the last 4 characters.

### MCP alternative

For MCP-capable clients, prefer the MCP server (`https://api.fyn.fyi/v1/mcp`) over raw REST: same data as typed tools with runtime self-documentation via `tools/list`, no static API key to manage, OAuth-scoped. The Agent Skill (README + curl reference) is at https://github.com/fynfyi/agent-skill.