io.github.Sean-Bravo/taxformatter

📊 TaxFormatter

Crypto CSVs and bank statement PDFs, parsed into tax-ready data.

REST API · MCP Server · Node SDK · Python SDK · Consumer Dashboard

🚀 What It Does

TaxFormatter turns messy financial exports into structured, tax-ready data — for humans and for AI agents.

Drop a CSV from Coinbase, a ZIP from Kraken, a .tar.gz from Binance, or a PDF statement from Chase, and get back a clean, normalized transaction set you can pipe into Koinly, TurboTax, CoinLedger, ZenLedger — or straight into your own software.

   Exchange CSV                        Clean, normalized
   Bank PDF              →             transactions (JSON / CSV)
   XLSX / ZIP / TAR.GZ                 + AI-generated insights

✨ Features

🔌 Developer REST API

Ship a crypto-tax or bank-ingestion feature into your product in an afternoon.

• POST /v1/parse — upload a CSV or PDF, get structured JSON back
• GET /v1/sources — list every supported exchange, bank, and output format, each with a verified / beta status
• GET /v1/usage — monthly quota, RPM limit, current consumption
• GET /v1/health — liveness probe
• Auth: X-API-Key header with tf_live_* keys (SHA-256 hashed at rest)
• Host: https://api.taxformatter.com

🤖 MCP Server for AI Agents

Give Claude, Cursor, Windsurf, or any MCP-compatible agent the ability to parse crypto and bank data directly.

npx @taxformatter/mcp-server

📦 Official SDKs

• Node.js → @taxformatter/sdk — promise-based, fully typed
• Python → taxformatter — idiomatic, type-hinted

🏦 14 Exchanges · 6 Banks · 4 Export Formats

Every public supported-source claim is generated from two registries, and drift tests fail CI if any surface disagrees with them:

• Exchanges — backend/configs/exchanges.yaml, mirrored by lib/exchange-registry.ts
• Banks — backend/configs/banks/*.yaml, mirrored by lib/bank-registry.ts

GET /v1/sources serves the same lists. Every entry carries a status: verified means a fixture-backed parse test runs on every change; beta means the parser exists but has no fixture yet. A new status is earned by a test, never by editing a registry.

Exchanges (verified): Binance · Coinbase · Kraken · KuCoin · Bybit · Cash App · Robinhood · Crypto.com · Gemini · FTX · Bitfinex · OKX

Exchanges (beta): Venmo

Banks (verified): Chase · Mercury · Navy Federal

Banks (beta): Bank of America · Wells Fargo · Citi

Export formats: Koinly · TurboTax (Form 8949) · CoinLedger · ZenLedger

Per-exchange detail: content/docs/getting-started/supported-exchanges.md.

🧠 Tiered AI Insights

Every parsed file comes back with analysis scaled to your plan. Plans expose an insights level; the level → model mapping lives in lib/insights-engine.ts and is published only in the API docs and blog Updates posts.

The insights contract is strict. Model output is validated against a fixed schema, and a refusal, truncation, or unparseable response falls back to the deterministic quick stats with an insights unavailable warning rather than partial flags. Every result is stamped with the model, prompt version, and effort that produced it, and every model call logs tokens, cache-hit rate, latency, and cost.

🖥️ Consumer Dashboard

Not a developer? The web app at taxformatter.com is a full drag-and-drop experience with real-time job status, exchange auto-detection, transformation previews, and one-click downloads.

🏗️ Tech Stack

📁 Repo Layout

trw/
├── app/                 # Next.js App Router (marketing, dashboard, docs, blog)
│   ├── api/             # Internal API routes (NextAuth, uploads, jobs, dev keys, cron/prune)
│   ├── dashboard/       # Authenticated user area + /dashboard/developer
│   ├── docs/ · blog/    # MDX-powered docs site and blog (content in content/)
│   ├── playground/      # API playground
│   ├── samples/         # Sample outputs
│   └── upload/          # Anonymous bank statement → CSV landing page
│
├── backend/             # Python processing layer (AWS Lambda)
│   ├── handlers/        # scanner · processor · webhook · api
│   ├── services/
│   │   ├── engine.py            # CSV parsing (14 exchange parsers)
│   │   ├── format_converter.py  # Koinly → TurboTax/CoinLedger/ZenLedger
│   │   ├── fingerprinting.py    # Exchange auto-detection
│   │   ├── ai_insights.py       # Tiered AI analysis (schema-validated, refusal-safe)
│   │   ├── api_auth.py          # API key validation + rate limiting
│   │   └── bank_statement/      # PDF extraction pipeline
│   ├── configs/
│   │   ├── exchanges.yaml       # Exchange source registry (serves /v1/sources)
│   │   └── banks/*.yaml         # Bank source registry + parser configs
│   ├── tests/                   # pytest suite + parse fixtures
│   └── terraform/               # Infra as code
│
├── packages/
│   ├── mcp-server/      # @taxformatter/mcp-server (npm)
│   ├── sdk-node/        # @taxformatter/sdk (npm)
│   └── sdk-python/      # taxformatter (PyPI)
│
├── components/          # React components (marketing, dashboard, ui)
├── content/             # Docs (.md) and blog (.mdx) sources
├── lib/                 # Business logic (auth, api-keys, stripe, email)
│   ├── exchange-registry.ts # Mirrors backend/configs/exchanges.yaml
│   ├── bank-registry.ts     # Mirrors backend/configs/banks/*.yaml
│   ├── tier-registry.ts     # The one price list (plan, price, quota, RPM, insights level)
│   ├── insights-engine.ts   # The one model list (insights level → model)
│   └── retention.ts         # RETENTION_DAYS = 30
├── db/                  # PostgreSQL schema + migrations
├── __tests__/           # Jest suite, incl. copy and registry drift guards
└── docs/                # Setup guides, plans, build reports

Full architectural reference: ARCHITECTURE.md

⚡ Quick Start

Run the web app

npm install
npm run dev

Open http://localhost:3000.

Try the API

curl -X POST https://api.taxformatter.com/v1/parse \
  -H "X-API-Key: tf_live_..." \
  -F "file=@coinbase.csv"

Use the MCP server with Claude Code

{
  "mcpServers": {
    "taxformatter": {
      "command": "npx",
      "args": ["@taxformatter/mcp-server"],
      "env": { "TAXFORMATTER_API_KEY": "tf_live_..." }
    }
  }
}

Install the Node SDK

npm install @taxformatter/sdk

import { TaxFormatter } from "@taxformatter/sdk";

const tf = new TaxFormatter(process.env.TF_API_KEY!);

// Parse a file by path, or pass a Buffer with a filename
const result = await tf.parse("./coinbase.csv");
const turbotax = await tf.parse(buffer, "coinbase.csv", { outputFormat: "turbotax" });

Install the Python SDK

pip install taxformatter

from taxformatter import TaxFormatter

tf = TaxFormatter("tf_live_...")
result = tf.parse("./coinbase.csv")

🧪 Testing

npm test              # Jest (700+ tests: API routes, MCP, keys, registries, UI)
npm run test:e2e      # Playwright end-to-end tests
npm run typecheck     # TypeScript strict mode
npm run lint          # ESLint
cd backend && pytest  # Python engine, parsers, insights, API Lambda (370+ tests)

Public copy is tested too. Drift guards under __tests__/ fail if any surface hard-codes a price, quota, or model name outside the registries, names an exchange or bank the registries don't list, or carries a superseded retention or marketing claim.

💳 Pricing

One plan, two ways to use it — drop a file in the dashboard or call our API. Same quota, same AI insights.

Source of truth: lib/tier-registry.ts (prices, quotas, limits) and lib/insights-engine.ts (which model serves each insights level). Model names are published in the API docs and blog Updates posts only.

🔒 Security Highlights

• API payloads never stored — request bodies are parsed in memory and never written to S3 or the database
• Metadata-only request log — api_requests stores key id, endpoint, status, bytes, timing, detected source, error code, and caller IP; never file contents
• API keys SHA-256 hashed at rest, prefixed tf_live_ for easy identification
• Uploads only — TaxFormatter never asks for exchange API keys or bank logins
• TLS 1.3 enforced everywhere
• AES-256 encryption on all stored uploads
• AWS WAF in front of the API
• 30-day retention — uploads, outputs, and parsed rows are deleted within 30 days (sooner from the dashboard); enforced by an S3 lifecycle rule and a daily prune cron

Full disclosure at taxformatter.com/security.

📚 Documentation

• ARCHITECTURE.md — Full system design
• content/docs/api/index.md — API reference
• content/docs/getting-started/supported-exchanges.md — per-exchange status, generated from the registry
• packages/mcp-server/README.md — MCP setup guide
• RELIABILITY.md — SLOs, incident playbooks
• docs/PARKED_UNTIL_REVIEW.md — post-launch initiatives frozen until the Oct 28 review
• docs/ — Stripe, Sentry, deployment guides, and build reports

License

Source-available, not open source. Copyright (c) 2026 Quantum Transfer Group, all rights reserved — you may read and audit this code, but not run, copy, or build on it. Full terms in LICENSE; the published npm and PyPI client packages are licensed separately.

Security

Found a vulnerability? Report it privately — see SECURITY.md. Please don't open a public issue.

Contributing

Bug reports are welcome, especially parsing failures against real exchange or bank exports. We don't accept outside pull requests — see CONTRIBUTING.md.