Most of the time, Koinly’s API sync just works. But when it does not, or when an exchange no longer exists, CSV import is your fallback, and it gives you complete control over exactly what lands in your account. The catch is that CSV import is less forgiving. One broken header row or a date format Excel quietly mangled, and the whole file bounces.
This walkthrough takes you from export to clean import without breaking your cost basis along the way.
Disclaimer: This guide is for informational purposes only. Always consult a qualified CPA regarding your specific situation.
API vs CSV: Which Should You Use?
API connections are convenient and stay current automatically, but they can fail, lose authorization, or pull partial history. CSV is manual but total: what is in the file is what Koinly gets.
Use API when: the exchange supports it, the connection is stable, and you want hands-off updates. Use CSV when: the API fails, the exchange is defunct, the API pulls incomplete data, or you need to control exactly what imports.
Step-by-Step: Export and Import a Clean CSV
Step 1: Export the Complete History From Your Exchange
In your exchange account, find the transaction or tax export. Set the date range to all time, not the current tax year. Partial history is the number one cause of broken cost basis, because the original buys get left out.
Step 2: Use the Koinly Exchange Template Where It Exists
Koinly supports dedicated CSV formats for major exchanges. In Koinly, choose the specific exchange and follow its import instructions so the columns map correctly. Only fall back to the generic Koinly template when no exchange-specific one exists.
Step 3: Do Not Open and Re-Save the File in Excel
This trips up more people than anything else. Excel can convert dates to a different format, strip leading zeros, and turn long transaction IDs into scientific notation. Any of these breaks the import. If you must inspect the file, use a plain text editor, or import it exactly as exported.
Step 4: Import Into Koinly
Upload the file under the correct wallet or exchange in Koinly. Watch for the import summary: how many transactions were read, and any rows it skipped or flagged.
Step 5: Verify the Totals
After import, check that the balances match what the exchange actually shows, and confirm there are no new $0 cost basis warnings. If balances are off, the export was probably incomplete, so re-export the full range.
Fixing Common CSV Import Errors
- “Invalid format” or rejected file: You likely have an XLSX renamed to CSV, or a broken header row. Re-export a true CSV.
- Dates read wrong: The file was opened and re-saved in Excel. Re-export and import untouched.
- Duplicates after import: You imported twice, or mixed API and CSV. Remove one source.
- New $0 cost basis warnings: The export missed earlier history. Export all-time and re-import.
When Your Exchange Has No Clean Export
Defunct exchanges and obscure platforms are the hard cases. You export whatever transaction detail you can get, then map it to Koinly’s generic template by hand. It is solvable, just tedious, and it is exactly the kind of reconciliation work a crypto CPA does routinely. If you are staring at a messy export from an exchange that no longer exists, that is a reasonable point to hand it off.
Key Takeaways
- CSV is your fallback when API fails or an exchange is gone, and it gives you full control
- Never mix API and CSV on the same account
- Always export the complete history, or cost basis breaks
- Do not let Excel re-format the file. Import it as exported
- Verify balances after import, and re-export all-time if anything looks off
- Messy exports from defunct exchanges are a sensible thing to hand to a CPA