Question

---

OpenBrokerCSV v0.1 — Let’s Standardise Broker CSVs (So Everyone Can Build Better Tools)

Every broker exports a different CSV. That’s fine until you try to import… anything. Let’s fix this together with a small, pragmatic standard and a lightweight CLI.

Why this matters (and why now)

• CSV is still the universal adapter for portfolios.
• Local-first finance tools need clean imports to be reliable, private, and explainable.
• A shared schema unlocks better tools, faster debugging, and safer community samples.

---

Spec v0.1 (minimum that works)

Core file: trades.csv

Column	Type	Notes
timestamp	ISO 8601	Trade time in UTC
side	enum	BUY	SELL
symbol	string	Ticker or ISIN
qty	number	Positive quantity
price	number	Executed price in trade currency
fee	number	Total fees/commissions for the trade
currency	string	ISO 4217 (e.g., USD, GBP, EUR)
fxRate	number	Optional; tradeCCY → portfolioCCY at execution time
note	string	Optional free text (broker ref, venue, etc.)

Optional file: corporate_actions.csv

Column	Type	Notes
timestamp	ISO 8601	Event time in UTC
type	enum	split	dividend	spin
symbol	string	Affected instrument
ratio	number	For splits (e.g., 2 = 2-for-1)
amount	number	For dividends/spins per share

v0.1 goals: be small, unambiguous, and easy to map from any broker export.

---

Fixtures (so you can test fast)

• fixtures/etoro.sample.csv
• fixtures/ibkr.sample.csv
• fixtures/revolut.sample.csv
• fixtures/degiro.sample.csv
• fixtures/yours-redacted.sample.csv ← use the template and redact personally identifying info.

We also ship an error_rows.template.csv that shows exactly how the validator reports broken lines.

---

The CLI (tiny, human-friendly)

Install (local dev):

npx openbrokercsv-cli@latest validate ./my-broker-export.csv \
  --broker revolut \
  --portfolio-ccy GBP \
  --out ./validated/trades.csv \
  --errors ./validated/errors.csv

What it does:

• Detects/uses a mapping for your broker.
• Normalises header names and common formats.
• Writes a clean trades.csv in v0.1 shape and an errors.csv you can fix and re-upload.
• Never uploads data anywhere — runs entirely locally.

---

Broker mappings: YAML, not magic

# mappings/revolut.yaml
headers:
  "Date": timestamp
  "Type": side
  "Ticker": symbol
  "Quantity": qty
  "Price": price
  "Fee": fee
  "Currency": currency
transforms:
  side:
    BUY: BUY
    SELL: SELL
  timestamp:
    parse: "dd/MM/yyyy HH:mm:ss"   # example
  price:
    decimal: "."                   # supports "," too
defaults:
  fxRate: 1

Add one file like this and 80% of imports “just work.”

---

Privacy & safety

• Do not attach real portfolios to issues.
• Use the redaction checklist and sample template.
• Our bot rejects CSVs that look like production data (e.g., contains emails, account IDs).

---

Roadmap to v1.0

• JSON Schema + TypeScript types in @openbrokercsv/types.
• CI validation on PRs (auto-comment with error table).
• Coverage board (which brokers are supported; who’s maintaining the mapping).
• Edge cases: partial fills, DRIPs, lot selection hints (FIFO/LIFO/Avg), multi-currency cash legs.

---

How to contribute in ≤90 minutes

1. Claim a mapping: comment “Taking <broker>” on the issue.
2. Export a redacted sample row and drop it into /fixtures.
3. Add mappings/<broker>.yaml and run the CLI locally.
4. Open a PR with: mapping + fixture + before/after screenshots.
5. (Optional) Add a test case under /tests/mappings/<broker>.test.ts.

We review mappings on Spec Clinic (weekly), merge quickly, and publish a minor release.

---

Starter tasks (pick one today)

• [ ] Add mappings/etoro.yaml (we’ll provide a redacted row).
• [ ] Improve the validator’s error messages (plain English, suggest fixes).
• [ ] Add --date-locale and --decimal flags.
• [ ] Write a doc: “How to redact a CSV safely” (with screenshots).
• [ ] Build a tiny web validator that runs entirely client-side.

---

Where this ships first

This spec powers the import pipeline for Pocket Portfolio — an open, local-first investing dashboard that explains every number. If you care about privacy, explainability, and real-world reliability, you’ll fit right in.

• GitHub: PocketPortfolio/Financialprofilenetwork
• Website: pocketportfolio.app
• DEV post companion: Local-First Finance: Build an Investing Dashboard that Works Offline — and Explains Every Number

---

Join us

Comment below with your broker and we’ll spin up a mapping issue.
Prefer Discord/GitHub? Grab a “good first issue” and say hi — we’re friendly, fast, and very open to RFCs.

Let’s make portfolio imports boringly reliable.

Comments

Really appreciate you laying out such a clear, practical roadmap here—makes the chaos of broker CSVs feel solvable. Could this kind of standardization eventually make it trivial for any new finance tool to support dozens of brokers right out of the box?

---

Thanks, Andrew — that’s exactly the end-state we’re aiming for.

Quick target: v0.1 → one JSON Schema + per-broker YAML mappings so a new app can “import 20+ brokers out-of-the-box” by running a single validator/normalizer step (openbrokercsv validate …) and ingesting the same normalized trades.csv. Our audit bar is: deterministic parsing, explicit timezone/currency handling, and human-readable error rows.

Minimal repro/template: happy to share a tiny starter:

# 1) Clone template
npx degit pocketportfolio/openbrokercsv-min demo && cd demo

# 2) Validate + normalize any broker export
npx openbrokercsv-cli validate ./raw.csv \
  --broker <broker> --portfolio-ccy GBP \
  --out ./normalized/trades.csv --errors ./normalized/errors.csv

# 3) Serve a mini dashboard (loads normalized CSV + shows P/L explain)
npm i && npm run dev

If you’ve got a specific broker in mind, drop a single redacted row and I’ll spin up the mapping PR so it “just works.”