HQ Wealth ↔ Koinly: The Complete Import & Export Guide

Koinly is one of the most widely used crypto tax calculators, and HQ Wealth is a full double-entry wealth accounting platform. Plenty of people need both, or need to move between them: migrating your history out of Koinly into a proper ledger, keeping Koinly for a country-specific tax report while HQ Wealth runs your books, or handling a client who arrives with three years of Koinly exports. In every case the work lives or dies on file formats — one wrong column header and Koinly rejects the whole upload as an unknown file.

This guide covers both directions: how HQ Wealth exports your data in Koinly's exact custom CSV format so it imports cleanly on the first try, and how HQ Wealth imports a Koinly export and maps every Koinly tag onto its own transaction types. Everything about Koinly's formats below comes from Koinly's own documentation, linked inline, current as of July 2026.

Exporting HQ Wealth → Koinly

Koinly publishes three official custom CSV templates — Simple, Trades, and Universal — each a Google Sheets download with sample rows, documented in Koinly's custom CSV guide. Simple handles one asset movement per row, Trades handles spot trades with a pair column, and Universal handles any transaction type using separate Sent and Received columns.

HQ Wealth generates the Universal template natively. Choose Export → Koinly from any portfolio, journal, or date range and you get a file that matches Koinly's Universal format column for column — no spreadsheet editing, no header renaming. We chose Universal because it is the only template that expresses deposits, withdrawals, and trades in a single file, so your entire history exports as one coherent upload instead of three.

The Universal CSV, column by column

Here is exactly what our exporter writes. The first five columns are the ones Koinly requires in the Universal template; get any of those header names wrong and the file is rejected.

| Column | Required? | Format | Example | |---|---|---|---| | Date | Yes | YYYY-MM-DD HH:mm:ss | 2026-03-14 09:30:00 | | Sent Amount | Yes (header) | Dot-decimal quantity | 0.5 | | Sent Currency | Yes (header) | Ticker, or SYMBOL:CONTRACT_ADDRESS:BLOCKCHAIN | ETH | | Received Amount | Yes (header) | Dot-decimal quantity | 1520.25 | | Received Currency | Yes (header) | Ticker, or extended notation | USDC | | Fee Amount | Optional | Dot-decimal quantity | 0.002 | | Fee Currency | Optional | Ticker | ETH | | Net Worth Amount | Optional | Fiat value at transaction time | 1520.25 | | Net Worth Currency | Optional | Fiat currency only | USD | | Label (tag) | Optional | One Koinly tag, maximum | reward | | Description | Optional | Free text | Uniswap v3 swap | | TxHash | Optional | On-chain transaction hash | 0x9f2c…41ab |

Three details in that table matter more than they look:

The date column is called Date, not Koinly Date. The Simple and Trades templates use a column named Koinly Date, but the Universal template uses plain Date — Koinly's own CSV modification guide calls this out as a common cause of rejected files. Our exporter writes the correct header, so you never hit this.
Row shape follows transaction direction. Deposits fill only the Received pair, withdrawals only the Sent pair, and trades all four amount and currency columns. HQ Wealth's double-entry engine knows which side every movement sits on, so each row comes out in the shape Koinly expects.
Extended currency notation for ambiguous tokens. Koinly accepts SYMBOL:CONTRACT_ADDRESS:BLOCKCHAIN in the currency columns. HQ Wealth stores contract addresses for on-chain assets, so our export uses the extended notation automatically for tokens that would otherwise match the wrong asset.

On timezones: Koinly's documentation shows dates in the YYYY-MM-DD HH:mm:ss pattern and treats them as UTC in practice. HQ Wealth stores and exports every timestamp in UTC — use UTC to be safe if you ever hand-edit a file.

The staking-tag trap — and how our export avoids it

This is the single most important gotcha in the entire Koinly CSV pipeline. Per Koinly's CSV modification guide, rows tagged stake or unstake are skipped entirely during import — they do not error, they do not warn, they simply never appear in your Koinly account. Similarly, the swap tag is ignored in CSV files; swaps can only be marked manually inside Koinly after import.

HQ Wealth tracks staking natively — stake, unstake, and reward are first-class transaction types in our ledger. Exported with the literal stake and unstake tags, Koinly would silently drop them and your balances would drift with no error to tell you why. So our exporter re-maps them:

Stake movements export as plain withdrawals (Sent pair filled, no tag), with the description field noting the staking action.
Unstake movements export as plain deposits (Received pair filled, no tag), likewise described.
Staking rewards export as deposits tagged reward, which Koinly imports and treats as income correctly.

Nothing silently drops, and your Koinly balances reconcile against your on-chain reality.

Koinly enforces at most one tag per row. On the deposit side it accepts tags including other income, reward, mining, airdrop, fork, salary, lending interest, loan, realized gain, futures fee, funding fee, cashback, and fee refund; on the withdrawal side, cost, other fee, margin fee, loan fee, lost, gift, and donation. HQ Wealth's export picks the single best-fit tag per row from that list and never emits more than one.

File size and decimals

Koinly's import documentation sets a hard 10 MB limit per file, which a long trading history can exceed easily. HQ Wealth's exporter checks the output size and automatically splits the export into chunks under 10 MB, each carrying its own header row so every file uploads independently.

Decimals are the other silent killer: Koinly requires the period as the decimal separator and recommends explicit decimals (write 1.0 rather than 1). If your system locale uses comma decimals, a hand-made spreadsheet export can corrupt every amount. HQ Wealth always writes dot-decimal amounts with explicit decimal points, regardless of locale.

Importing Koinly → HQ Wealth

Migration runs the other way too. Koinly lets you export your transaction history as CSV, and HQ Wealth's importer accepts that export directly — pick Koinly as the source in Import, drop the file, and review the mapping preview before anything posts to your ledger.

Because HQ Wealth is a double-entry platform rather than a tax calculator, every imported row becomes a proper journal entry, and cost basis is rebuilt under your chosen method — FIFO, LIFO, HIFO, or AVCO — rather than inheriting Koinly's computation. Transaction hashes drive duplicate detection, so re-importing an overlapping date range does not double-post.

Here is how our importer maps Koinly's transaction shapes and tags onto HQ Wealth transaction types. This table describes our mapping, not anything Koinly publishes:

| Koinly transaction or tag | HQ Wealth transaction type | |---|---| | Fiat → crypto trade | BUY | | Crypto → fiat trade | SELL | | Crypto → crypto trade | CRYPTO_TRADE | | Untagged deposit | DEPOSIT | | Untagged withdrawal | WITHDRAWAL | | reward | STAKING_REWARD | | lending interest | INCOME (interest subtype) | | mining, airdrop, fork, salary, other income, cashback, fee refund | INCOME (original subtype preserved) | | realized gain | INCOME (derivative P&L) | | futures fee, funding fee, margin fee | FEE (derivative subtype) | | cost, other fee, loan fee | FEE | | gift, donation | GIFT_OUT | | lost | WITHDRAWAL (flagged as loss) |

Every mapped row keeps its original Koinly description and date, and the import preview shows the proposed type per row before you commit — you can override any mapping line by line.

Format quick reference

All three Koinly custom templates at a glance, per Koinly's template documentation:

| Template | Required columns | Best for | |---|---|---| | Simple | Koinly Date, Amount, Currency | Single-asset movements: deposits, withdrawals, rewards, futures closed PnL. Negative Amount = withdrawal; amounts are gross of fees. | | Trades | Koinly Date, Pair, Side, Amount, Total | Spot trades only. Pair as BASE/QUOTE or BASE-QUOTE; Side is Buy or Sell; rows sharing an Order ID merge into one transaction. | | Universal | Date, Sent Amount, Sent Currency, Received Amount, Received Currency | Any transaction type in one file. This is the format HQ Wealth exports. |

And the rejection errors we see most often, with fixes:

| Symptom | Cause | Fix | |---|---|---| | File rejected as unknown file | Header names do not match the template exactly — e.g. Koinly Date in a Universal file, or Date in a Simple file | Copy the headers from Koinly's official template character for character | | Amounts import wrong or rows fail | Comma decimal separators | Use period decimals; write explicit decimals (1.0, not 1) | | Upload fails outright | File over 10 MB | Split into chunks, keeping the header row in each | | Transactions silently missing after import | Rows tagged stake or unstake | Remove those tags and import as plain withdrawals and deposits | | Swaps not recognised | The swap tag is ignored in CSV imports | Import untagged, then mark as swaps manually in Koinly |

FAQ

Do I need a custom CSV to get data into Koinly at all? Usually not. Koinly natively parses export files from more than 500 exchanges and wallets, typically with no editing needed. Custom CSVs are for unsupported sources — or for curated, reconciled data like an HQ Wealth export, where you want one clean file instead of a dozen raw exchange dumps.

Why did my staking transactions disappear after importing a CSV into Koinly? Rows tagged stake or unstake are skipped during CSV import by design. Re-import them as untagged withdrawals and deposits, and tag rewards with the reward tag. HQ Wealth's Koinly export does this remapping automatically.

What date format does a Koinly custom CSV need? YYYY-MM-DD HH:mm:ss — for example, 2026-03-14 09:30:00. Timestamps are treated as UTC in practice, so export in UTC to be safe. The column is named Koinly Date in the Simple and Trades templates but plain Date in the Universal template.

Can I identify a token by contract address instead of ticker? Yes. Koinly's currency columns accept the extended notation SYMBOL:CONTRACT_ADDRESS:BLOCKCHAIN, which disambiguates tokens that share a ticker. HQ Wealth uses this automatically for on-chain assets with stored contract addresses.

---

Ready to run real double-entry books next to your tax tool? Try HQ Wealth and export to Koinly in one click.