financier

# Financier

Official agent and developer tooling for [Financier](https://financier.sh): a personal finance plan built from a person's own bank data. Financier is API-first. Everything a person can do in the app, an agent can do over MCP, the REST API, this SDK or this CLI.

| | |
| --- | --- |
| MCP server | `https://financier.sh/mcp` (Streamable HTTP; OAuth 2.1 or `x-api-key`) |
| Docs MCP server | `https://financier.sh/mcp/docs` (no credentials) |
| REST API | `https://financier.sh/api/v1`, [OpenAPI](https://financier.sh/api/openapi.json), [reference](https://financier.sh/api/docs) |
| TypeScript SDK | [`@financier-sh/sdk`](packages/sdk) |
| CLI | [`@financier-sh/cli`](packages/cli) (`financier`) |
| Agent skill | [`skills/financier/SKILL.md`](skills/financier/SKILL.md) |
| Agent plugin | [`plugin.json`](plugin.json) + [`mcp.json`](mcp.json) |
| MCP registry | `sh.financier/financier`, `sh.financier/financier-docs` |
| A2A 1.0 | [agent card](https://financier.sh/.well-known/agent-card.json), JSON-RPC at `https://financier.sh/a2a` |
| Ask the docs (NLWeb) | `POST https://financier.sh/ask` |
| Agent identity, no account | `POST https://financier.sh/agent/identity` (sandbox-only until a person claims it) |
| Webhooks | Standard Webhooks + Web Bot Auth ([keys](https://financier.sh/.well-known/http-message-signatures-directory)) |
| Agent index | [llms.txt](https://financier.sh/llms.txt), [auth.md](https://financier.sh/auth.md) |

Accounts are invite-only for now. The sandbox bank (provider `demo`) gives any account a synthetic household to try everything on.

## MCP

```json
{
  "mcpServers": {
    "financier": { "type": "http", "url": "https://financier.sh/mcp" }
  }
}
```

Claude Code: `claude mcp add --transport http financier https://financier.sh/mcp`

## SDK

```sh
npm install @financier-sh/sdk
```

```ts
import { createFinancier } from "@financier-sh/sdk";

const financier = createFinancier({ apiKey: process.env.FINANCIER_API_KEY });
await financier.connections.linkSandbox();
for await (const event of financier.plan.buildStream()) console.log(event.stage);
const view = await financier.plan.view();
console.log(view?.stages[view.current]?.name, view?.plan.monthly.surplus);
```

### Webhooks

```ts
import { verifyWebhook } from "@financier-sh/sdk";

// In your handler: the raw body, the request headers, and the secret from webhooks.create.
if (!(await verifyWebhook(rawBody, request.headers, process.env.FINANCIER_WEBHOOK_SECRET!)))
  return new Response("bad signature", { status: 401 });
```

Events: `plan.built`, `recurring.detected`, `bank.reconnect_required`, `webhook.test`. Every delivery is also signed with Web Bot Auth, verifiable against financier.sh's key directory without a shared secret.

## Agents without an account

An agent can start before any person is involved: `POST /agent/identity {"type":"anonymous"}` returns a sandbox-only identity and a claim token. When a person wants the agent to work on their real account, the agent starts a claim with their email, shows them the code, and the person approves it at `financier.sh/claim`. The full flow, with requests, is in [auth.md](https://financier.sh/auth.md).

## CLI

```sh
npm install -g @financier-sh/cli
financier login          # paste an API key from Settings, Developer
financier sandbox        # link the synthetic household
financier build          # sync, categorise, build the plan
financier plan           # stage, monthly figures, actions
financier plan --json    # the same, for scripts and agents
financier spending --from 2026-08-01 --by merchant
financier webhooks add https://example.com/hooks/financier --events plan.built
```

## This repository

The Financier app itself is private. This repository holds the public surface: the SDK, the CLI, the agent skill, the plugin manifest and the MCP registry entries. The SDK's types are generated from the live OpenAPI document (`bun run generate`).

## License

MIT