---
title: "Financier developer portal"
description: "Build on Financier: a versioned REST API, an MCP server for agents, OAuth 2.1 with scopes, self-serve API keys, and a sandbox bank."
canonical: https://financier.sh/developers
updated: 2026-09-22
---

# Financier developer portal

Build on Financier: a versioned REST API, an MCP server for agents, OAuth 2.1 with scopes, self-serve API keys, and a sandbox bank.

## Quickstart

1. Sign in at https://financier.sh/signin. Accounts are invite-only for now; ask at https://financier.sh/contact.
2. Create an API key under Settings, Developer. It is shown once.
3. Link the sandbox bank and build a plan, as below.

```sh
export FINANCIER_KEY=fin_...

# Link the sandbox bank (synthetic household, no real data)
curl -X POST https://financier.sh/api/v1/connections \
  -H "x-api-key: $FINANCIER_KEY" -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"provider":"demo","publicToken":"public-demo","institution":{"id":null,"name":"Sandbox Bank"},"reconnect":null}'

# Build the plan, then read it
curl -X POST https://financier.sh/api/v1/plan -H "x-api-key: $FINANCIER_KEY" -H "content-type: application/json" -d '{}'
curl https://financier.sh/api/v1/plan/view -H "x-api-key: $FINANCIER_KEY"
```

## Reference

- [API reference (Scalar)](https://financier.sh/api/docs)
- [OpenAPI 3.1 document](https://financier.sh/api/openapi.json)
- [API catalog (RFC 9727)](https://financier.sh/.well-known/api-catalog)
- [Authentication guide](https://financier.sh/auth.md)
- [API guide for agents](https://financier.sh/api/llms.txt)
- [Developer guide for agents](https://financier.sh/developers/llms.txt)

## SDK and CLI

| | |
| --- | --- |
| TypeScript SDK | npm install @financier-sh/sdk (https://www.npmjs.com/package/@financier-sh/sdk) |
| CLI | npm install -g @financier-sh/cli, then financier --help (https://www.npmjs.com/package/@financier-sh/cli) |
| Source, agent skill, plugin manifest | https://github.com/financier-sh/financier |

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

const financier = createFinancier({ apiKey: process.env.FINANCIER_API_KEY });
const view = await financier.plan.view();
```

## Authentication

| | |
| --- | --- |
| API key | Header x-api-key. Create and revoke under Settings, Developer. |
| OAuth 2.1 | Authorization code with PKCE. Dynamic client registration at /auth/oauth2/register. |
| Browser session | The first-party app's cookie. Required to manage credentials. |

| | |
| --- | --- |
| financier:read | Read your plan, accounts, categories and tasks |
| financier:write | Answer questions, record decisions, link and sync banks, rebuild the plan |
| openid | Sign in with your Financier identity |
| profile | Your name |
| email | Your email address |
| offline_access | Stay connected with a refresh token |

## MCP

| | |
| --- | --- |
| Product server | https://financier.sh/mcp (Streamable HTTP, OAuth or API key) |
| Docs server | https://financier.sh/mcp/docs (Streamable HTTP, no auth) |
| Server card | https://financier.sh/.well-known/mcp/server-card.json |
| Official MCP registry | sh.financier/financier, sh.financier/financier-docs (https://registry.modelcontextprotocol.io/v0/servers?search=sh.financier) |
| Agent plugin and skill | https://github.com/financier-sh/financier |

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

## Conventions

| | |
| --- | --- |
| Versioning | Paths are versioned: /api/v1. Breaking changes ship as a new version; the old one gets Deprecation and Sunset headers and at least 6 months. |
| Idempotency | Send Idempotency-Key on POST, PUT and DELETE. A retry with the same key within 24 hours returns the first response. |
| Rate limits | 120 requests per minute per credential. RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset on every response; 429 with Retry-After. |
| Errors | JSON: { code, status, message, data? }. Codes are stable; messages are for people. |
| Batch | PUT /categories/rules/batch files up to 100 merchants in one call. |
| Long builds | POST /plan/builds returns 202 Accepted with a Location and Retry-After; poll GET /plan/builds/{id} until succeeded or failed. POST /plan/build streams the same build as server-sent events. |
| Sandbox | Link provider "demo" for a synthetic household. It never touches a real bank. |

## Spending questions

Exact totals from the person's own transactions, after their category rules: filter by dates, category or merchant; group by category, merchant or month. Your model supplies the language; Financier supplies the numbers.

```sh
curl "https://financier.sh/api/v1/spending?from=2026-08-01&to=2026-08-31&groupBy=merchant" -H "x-api-key: $FINANCIER_KEY"
```

Over MCP: the query_spending tool. Over A2A: the query_spending skill.

## Webhooks

| | |
| --- | --- |
| Register | POST https://financier.sh/api/v1/webhooks with an https url and events; the secret (whsec_…) is shown once. |
| Events | plan.built, recurring.detected, bank.reconnect_required, webhook.test. |
| Verify | Standard Webhooks: webhook-signature is v1,base64(HMAC-SHA256(secret, id.timestamp.body)). Every delivery is also signed with Web Bot Auth against financier.sh's key directory. |
| Retries | 5s, 5m, 30m, 2h, 5h, 10h, 14h, 20h, 24h. 2xx is success; 410 disables the endpoint. |

## Agents without an account

An agent can start before any person is involved: it gets a sandbox-only identity, and a person claims it later with a code. See Authentication for agents.

| | |
| --- | --- |
| Identity | POST https://financier.sh/agent/identity {"type":"anonymous"} |
| Claim | POST https://financier.sh/agent/identity/claim; the person enters the code at https://financier.sh/claim |
| Before the claim | Sandbox bank only; no webhooks. |

## Other protocols

| | |
| --- | --- |
| A2A 1.0 | Agent card at https://financier.sh/.well-known/agent-card.json; JSON-RPC at https://financier.sh/a2a (SendMessage, GetTask, ListTasks). |
| NLWeb | POST https://financier.sh/ask searches these docs; results are schema.org items, streamed with prefer.streaming. |
| In-chat UI | MCP Apps views for get_plan, build_plan and list_tasks render in Claude and ChatGPT. |
| Web Bot Auth | Financier's signing keys: https://financier.sh/.well-known/http-message-signatures-directory. Agents that sign their requests are rate-limited by their own origin. |