Why crypto CSV descriptions are not trades: extract candidates without inventing cost basis

An offline-first developer walkthrough · October 2026 · AI-assisted, reproducible examples.

A historical question in r/koinly about Wealthsimple-style exports described an unusually awkward file format. Instead of separate columns for crypto amount and asset, a description can contain text resembling this:

Description,When,Reference
"Purchase of 1.4324467000 SOL","2026-10-01 10:00:00","FICTIONAL-01"
"Sale of 0.250000 BTC","2026-10-02 11:00:00","FICTIONAL-02"
"Purchase of 2 SOL for 99 CAD","2026-10-03 12:00:00","FICTIONAL-03"

All values and IDs in this article are fictional examples. I haven't tested the source exchange's current export schema, and the Reddit post is not an endorsement or a request to buy our tool.

The tempting answer is to split each sentence into side, quantity and asset. That is useful — but insufficient to reconstruct a real trade. It does not tell you whether an actual trade settled, which token contract was involved, what the counter-asset and fee were, or how the exchange timestamps map to the destination importer's expectations.

If a parser silently guesses any of those facts, it may turn an import-cleaning problem into an accounting error.

The safe job: extract candidates, not tax records

For an explicit sentence such as:

Purchase of 1.4324467000 SOL

we can propose three review-required fields:

Candidate	Extracted value	What is still unknown
Direction	BUY_CANDIDATE	Whether a completed trade actually occurred
Quantity	1.4324467000	Whether the amount is gross or net after fees
Asset ticker	SOL	Token identity, chain, exchange listing, and ownership

The quantity stays a decimal string. Converting the source value through JavaScript's Number can erase insignificant-looking trailing zeros or lose precision for very small values. For a review tool, preserving what the source literally said is more useful than pretending to do exchange arithmetic.

What about Purchase of 2 SOL for 99 CAD? A safe parser can still propose BUY_CANDIDATE / 2 / SOL, but it should flag that the suffix was ignored. It must not automatically treat 99 CAD as the transaction's accounting cost basis. The quote might describe a reference estimate, failed payment, correction, or something else.

Conversely, messages about refunds, reversals, cancellation, and a second operation need special caution:

Purchase of 1 ETH for CAD 100 REFUNDED  -> NOT_PARSED
Sale of 0.01 BTC reversed              -> NOT_PARSED
Bought 1 ETH for USD 250 and sold 2 BTC -> NOT_PARSED

A parser that quietly converts the first of these to a buy and forgets the refund is worse than a parser that asks the user to review it.

A bounded local-first implementation

I built a narrow free checker that recognizes only four explicit prefixes: Purchase of, Sale of, Bought, and Sold. It accepts positive ASCII decimal quantities and uppercase candidate tickers, including up to 18 fractional digits. It also permits a small set of clearly labeled suffix prefixes like for or reference.

Conceptually, the flow is:

function classifyDescription(description) {
  // Schematic: the production implementation applies stricter bounds,
  // amount validation, formula filtering, and suffix rejection.
  const match = /^(Purchase of|Sale of|Bought|Sold) (\d+(?:\.\d+)?) ([A-Z][A-Z0-9]+)(?:\s+(.+))?$/.exec(description);
  if (!match) return {status: 'NOT_PARSED'};
  const [, verb, quantity, symbol, suffix] = match;
  return {
    status: 'REVIEW_REQUIRED',
    type: /^(Sale of|Sold)$/.test(verb) ? 'SELL_CANDIDATE' : 'BUY_CANDIDATE',
    quantity, symbol,
    trailingContextIgnored: Boolean(suffix)
  };
}

That illustration is deliberately not presented as production-ready. For safe handling, the real implementation additionally rejects unsupported trailing context, formula-like values, zero quantities, scientific notation, malformed quoting and rows with missing columns. It refuses oversized files rather than attempting to read arbitrary spreadsheet exports.

The actual open-source parser runs on the browser-selected CSV in memory, with a strict Content Security Policy setting connect-src 'none'. No CSV rows need to be uploaded to a server. The optional downloadable candidate file contains only the logical source row number, direction, quantity, ticker and review flag, not original descriptions, wallet references, source dates or account numbers.

The current boundaries are 32 KiB, at most 500 data rows and 40 CSV columns. Those limits are intentional: this is a free reviewer for small, reproducible samples, not an unrestricted exchange import pipeline.

Test the failure paths, not only the happy path

A successful regex match is the easiest test. Real input safety depends on negative cases:

• A Purchase of ... containing REFUNDED, cancellation or a second buy/sell should not be accepted as a completed trade.
• =HYPERLINK(...) in a source cell should be refused as formula-like content, never evaluated.
• A decimal such as 0.000000000000000001 should remain a string with no floating-point conversion.
• Ambiguous ellipses, unknown suffixes, duplicate headers and malformed quoted rows should fail closed.
• Changing the browser input after a scan should invalidate any previously prepared download.

At this writing, the original repository's full Node test suite passes 191 of 191 checks. Tests are reproducible from the linked repository with npm test; the count is an automated regression result, not a guarantee of importer correctness.

Why this does not produce a Koinly tax CSV

According to Koinly's official custom CSV instructions, different templates need correctly populated transaction details. An extracted BUY_CANDIDATE / 1.4324467000 / SOL is not enough. In particular, a user may still need to independently verify:

1. Original date and time zone.
2. Actual sent and received amounts and counter-asset.
3. Transaction fees, refunds, transfers and duplicate records.
4. Token contract/chain identity and exchange-specific mappings.

My tool neither calculates tax nor estimates missing cost basis. The final candidate file is labeled NOT_KOINLY_IMPORT on purpose. You should only import transactions after checking authorized original exchange records and the vendor's current template.

Try a fully fictional four-row sample first

Free browser-local Crypto CSV Narrative Inspector

Click Load FICTIONAL example then Analyze. The four demonstration rows show three review candidates and one formula-like row that is rejected. There is no account, API key, wallet connection, payment, analytics or private file transfer. Review-only extraction is free.

If you already have complete authorized source columns and need format checks, this same owner's separate free local column mapper and format preflight may help. Those are distinct tools, not endorsements by Koinly or Wealthsimple.

One technical question for people who have actually fought with these exports

Which fictional narrative sentence would your CSV workflow need to handle that this strict parser currently rejects? An example with invented data and the expected candidate behavior would be useful. Please do not post original wallet addresses, exchange account IDs, private CSV contents or tax documents.

You can email a made-up sample and reproducible description, or review the source and tests.

Commercial disclosure: The same human owner operates an optional separately agreed, bounded 49 Base Circle USDC technical CSV mapping pilot when an independent customer requests manual help; no payer, customer agreement, or real-world use of this new free tool has yet been verified. This is not a public instant checkout, tax consultancy, wallet recovery, or financial advice. The tool and this article are AI-assisted and are not affiliated with any exchange or tax software.