# Finatic — agent integration notes

## Read next (do not stop here)
This file is an index. Fetch the following before writing integration code:
1. [Quick start](https://finatic.dev/docs/quick-start/quick-start) — token → Connect → grant → accountId.
2. [Client SDK README](https://github.com/FinaticORG/FinaticClientSDK/blob/develop/README.md) — `@finatic/client`, `openPortal({ onEvent })`.
3. [Node SDK README](https://github.com/FinaticORG/FinaticServerSDK-Node/blob/develop/README.md) — `@finatic/server-node`, `v1.getToken()`.
4. [Python SDK README](https://github.com/FinaticORG/FinaticServerSDK-Python/blob/develop/README.md) — `finatic-server-python`, `v1.get_token()`.
5. [API reference](https://finatic.dev/docs/api-reference) — published `finatic.v1` methods.
6. [Public OpenAPI](https://finatic.dev/openapi.json) — `POST /api/v1/session/init`.
7. [SDK method JSON](https://finatic.dev/sdk-api-reference.json) — typed method catalog.
8. [Connecting brokers](https://finatic.dev/docs/quick-start/connecting-brokers) — iframe vs redirect.
9. [Account model](https://finatic.dev/docs/concepts/account-model) — never use companyAccountId as {accountId}.
10. [Error handling](https://finatic.dev/docs/quick-start/error-handling) — SESSION_INVALID_STATE, ACCOUNT_ID_TYPE_MISMATCH, 90s token.
11. [Demo apps](https://github.com/FinaticORG/FinaticDemoApps/blob/develop/README.md) — runnable Client / Node / Python examples.
12. [Embed Connect](https://github.com/FinaticORG/FinaticConnect/blob/develop/docs/embedding.md) — parent_origin and grant events.
Canonical flow: backend `v1.getToken()` / `get_token()` (90 seconds) → `FinaticConnect.init(token)` → `openPortal({ onSuccess, onEvent })` → wait for `account.grant.created` → store financial `accountId`. Server redirect: `startSession` / `start_session` then `getPortalUrl` / `get_portal_url` (URL is secret). Never put the API key in the browser.

## What Finatic does

Finatic is a unified brokerage connectivity platform for fintech companies. Connect end users to multiple brokerages through one standardized, account-first API. Use Finatic SDKs to mint a one-time token on your backend, open Connect, receive account grants, read balances/positions/orders/transactions, place trades, and consume signed webhooks. Tagline: Fast. Secure. Standardized.

## Preferred: v1 account-first SDKs

Implement with **`@finatic/client`**, **`@finatic/server-node`**, or the **Python server SDK** before raw HTTP unless you have a documented exception.

The v1 model is account-first: company session -> end-user Connect grant -> financial `accountId` -> account-scoped reads, trading, and webhooks. Provider connection IDs are internal-only and should not be treated as public customer resources.

## Canonical machine-readable references

- SDK API JSON (methods, params, examples): `https://finatic.dev/sdk-api-reference.json`
- Institutions catalog (brokers, auth_type, auth_kind, sync_path, trading flags): `https://finatic.dev/api/docs/institutions-catalog`
- Pricing JSON (plans and features): `https://finatic.dev/pricing.json`
- Expanded LLM bundle: `https://finatic.dev/llms-full.txt`
- Short LLM index: `https://finatic.dev/llms.txt`

Do not scrape accordion HTML on `/docs/api-reference` as the primary contract.

## Pricing (summary)

- Free tier: live positions, orders, balances, and trading workflows; up to 5 connected users; 1 connection per user; webhook delivery; 1,000 API calls per month.
- Enterprise: production volume, dedicated support, and custom rate limits.
- Machine-readable pricing JSON: /pricing.json
- Full pricing page (human UI): /pricing

Human pricing UI: `https://finatic.dev/pricing`
Machine pricing JSON: `https://finatic.dev/pricing.json`

## Integrations

- Browse UI: `https://finatic.dev/integrations`
- Machine catalog: `https://finatic.dev/api/docs/institutions-catalog`

Use the catalog JSON for auth type, data retrieval/sync path (`sync_path`), trading support, and beta/alpha/disabled status.

## Quick start documentation

- Quick start: `https://finatic.dev/docs/quick-start/quick-start`
- Installation: `https://finatic.dev/docs/quick-start/installation`
- Account-first model: `https://finatic.dev/docs/quick-start/v1-account-first`
- Connect and account grants: `https://finatic.dev/docs/quick-start/account-grants`
- Connecting brokers: `https://finatic.dev/docs/quick-start/connecting-brokers`
- Accounts and data: `https://finatic.dev/docs/quick-start/getting-data`
- Trading: `https://finatic.dev/docs/quick-start/trading`
- Environments: `https://finatic.dev/docs/quick-start/sandbox`
- Portal configuration: `https://finatic.dev/docs/quick-start/portal-configuration`
- Error handling: `https://finatic.dev/docs/quick-start/error-handling`
- Standard response object: `https://finatic.dev/docs/quick-start/standard-response-object`
- Beta to v1 migration: `https://finatic.dev/docs/quick-start/beta-migration`

## Concepts

- Concepts: `https://finatic.dev/docs/concepts/concepts`
- Connections and grants: `https://finatic.dev/docs/concepts/connections-and-grants`
- Account model: `https://finatic.dev/docs/concepts/account-model`

## Webhooks

- `https://finatic.dev/docs/webhooks`

## Public HTTP OpenAPI (`/openapi.json`)

Finatic publishes a vetted **OpenAPI** description of the public REST layer at `https://finatic.dev/openapi.json`. The tracked artifact is limited to approved SDK/Web audiences and carries immutable API commit and version provenance. Use it for direct HTTP tooling; the SDK and SDK JSON remain the default integration contract.

## MCP and tool export

For agent tools, expose the v1 SDK JSON and institutions catalog JSON first. Exclude beta, internal, and admin-only routes from default MCP/tool export. Keep disconnect and grant-revoke actions available because they are end-user account-management actions, not hidden admin operations.

## API keys (authenticated browser or user)

After sign-in, team API keys typically live at:

- `/home/{team_slug}/api-keys` (replace `{team_slug}` with the team account slug).

Use **sandbox** vs **production** keys as documented in the developer portal.

## SDKs

- Browser/client: `@finatic/client` — https://github.com/FinaticORG/FinaticClientSDK/blob/develop/README.md
- Node server: `@finatic/server-node` — https://github.com/FinaticORG/FinaticServerSDK-Node/blob/develop/README.md
- Python: `finatic-server-python` (`from finatic_server_python import FinaticServer`) — https://github.com/FinaticORG/FinaticServerSDK-Python/blob/develop/README.md

## Secrets

Never commit API keys or access tokens into repos or public markdown. Never paste API keys, webhook signing secrets, broker credentials, bearer tokens, or one-time Connect tokens into prompts or agent memory.