# Ledgy API

> Backend API and Model Context Protocol (MCP) server for Ledgy — a multi-currency expense tracker for iOS where you talk to your money. The MCP server lets Claude, ChatGPT, Cursor, and any MCP-compatible AI assistant read, add, and edit a user's expenses in plain English after they sign in with Apple, Google, or email. The REST API serves the same data to first-party clients (iPhone, Apple Watch, web dashboard) and to third-party integrations via Personal Access Tokens.

## Key facts

- API host: https://api.ledgy.app
- MCP endpoint: https://api.ledgy.app/mcp (HTTP SSE transport, stateless mode)
- REST base: https://api.ledgy.app/api/v1/
- OAuth 2.0 / RFC 7591 Dynamic Client Registration: https://api.ledgy.app/oauth/register
- OAuth Authorization Server metadata (RFC 8414): https://api.ledgy.app/.well-known/oauth-authorization-server
- MCP Protected Resource metadata (RFC 9728): https://api.ledgy.app/.well-known/oauth-protected-resource
- Auth: JWT (web/mobile sessions) or Personal Access Token (`lgpat_` prefix) for REST; OAuth 2.1 + PKCE for MCP
- PKCE: mandatory (code_challenge_method=S256)
- Cloud subscription required for MCP and REST writes ($2.99/mo or $22.99/yr, 7-day free trial)
- Data center: Germany (Hetzner) + Google Cloud Firestore

## MCP server overview

The MCP server exposes 30+ tools across 10 categories:

- **Transactions** — list, get, create, update, delete, bulk operations, aggregate, transfer
- **Accounts** — list, get, create, update, delete, balance, reconcile, adjust
- **Categories** — list (system + user + group), upsert, delete, list category groups, upsert/delete category groups
- **Budgets** — list, upsert, delete
- **Groups** — list, upsert, delete (shared ledgers for households, trips, shared apartments)
- **Tags** — list, upsert, delete
- **Recurring transactions** — list, upsert, delete
- **Receipts** — upload (server-side fetch from public URL), download (signed URL)
- **Currency** — convert with live ECB FX rates
- **Icons** — list supported FontAwesome icon set
- **User** — get profile, update settings

Sharing in Ledgy decides visibility, NOT ownership. Members of a shared group see the same transactions, but ownership stays personal. There is no debt-settlement math (Splitwise-style "who owes whom") — that is intentionally out of scope.

## Connecting from an AI assistant

### Claude (claude.ai and Claude Desktop)
Settings → Connectors → Add custom connector → Name: Ledgy → Server URL: https://api.ledgy.app/mcp → Add → sign in with Apple, Google, or email.

### ChatGPT (Plus / Pro / Business)
Settings → Apps → Advanced settings → Developer mode (on) → Create → Name: Ledgy → MCP Server URL: https://api.ledgy.app/mcp → Authentication: OAuth → Create → sign in.

### Cursor / Windsurf / other MCP clients
Use https://api.ledgy.app/mcp as the server URL with OAuth 2.1 + PKCE. Dynamic Client Registration is supported (no manual client_id needed).

## Public HTML surfaces

- [API status / index](https://api.ledgy.app/) — landing for the API host
- [Invite landing page](https://api.ledgy.app/join/{code}) — fallback page when a Ledgy invite link is opened without the iOS app installed
- [OAuth consent page](https://api.ledgy.app/oauth/authorize?...) — authorization screen for MCP / API clients and the Ledgy Telegram bot

## OpenAPI / Swagger

- Mobile API schema: https://api.ledgy.app/swagger/v1/swagger.json
- Dashboard API schema: https://api.ledgy.app/swagger/dashboard/swagger.json
- Interactive UI: https://api.ledgy.app/swagger

## Sister surfaces

- [Marketing site](https://ledgy.app/) — features, pricing, FAQ
- [Web dashboard](https://dashboard.ledgy.app/) — browser UI for Cloud subscribers
- [MCP / integrations guide](https://ledgy.app/integrations) — step-by-step setup for Claude and ChatGPT
- [REST API reference](https://ledgy.app/api-v1) — endpoint-by-endpoint docs
- [App Store](https://apps.apple.com/app/id6761738170) — iOS app, App ID 6761738170

## Security & legal

- [Privacy Policy](https://ledgy.app/privacy)
- [Terms of Service](https://ledgy.app/terms)
- [Security contact](https://api.ledgy.app/.well-known/security.txt) — RFC 9116
- Voice transcription runs on-device; only the resulting text is sent to the API. No raw audio leaves the user's device.

## Developer / publisher

- Developer: Borys Harholinskyi
- Support: support@ledgy.app
- Security: security@ledgy.app
- API status: https://api.ledgy.app/health