In most cases, you should not need to create a custom file as Koinly can handle almost every csv and excel file out there. However, if your exchange or wallet does not have export functionality then you can follow these instructions to create your own.
Instructions
Select one of the templates below and click on the link to go to the Google Sheets page for it.
Click on File > Make a Copy in the top right corner (you will need a google account for this - if you don't have one then click on File > Download > CSV to download the file and edit it using Excel or another tool)
Remove the sample data rows once you understand how to enter your own data.
When you have finished entering the data click on File > Download > Comma-separated values (CSV) to download the file and import it into Koinly.
1. For importing deposits/withdrawals/mining
This format is ideal for importing deposits and withdrawals from wallets/blockchains/mining pools etc. Basically, anywhere you have incoming and outgoing transactions.
If you also need to import trades then you can use the second file format that we have created specifically for trades. You can also look at the Universal file format which will allow you to import all deposits/withdrawals/trades using a single file.
Sample data explained:
The first sample row in this file contains an incoming transaction of 20 BTC which is tagged as mining income.
The second row contains an outgoing/send transaction of 20 BTC.
Required fields:
Koinly Date, Amount, Currency
Optional fields:
Net Worth Amount, Net Worth Currency, Tag, Description, TxHash
2. For importing Trades
This file is ideal for importing trades that are displayed using their market pair/side, instead of the amount you sent/received.
If your exchange shows you the amount you have sent and the amount you have received separately then you should look at the universal import format instead.
Sample data explained:
The first sample row in this file contains a trade of 1000 USD to 1 BTC with a fee of 5 USD on top. In other words: you are buying 1 BTC for 1000 USD + fee.
The second row contains a sale of 1 BTC for 900 USD with a fee of 3 USD on top. In other words, you sold 1 BTC for 900 USD + fee.
Required fields:
Koinly Date, Pair, Side, Amount, Total
Optional fields:
Fee Amount, Fee Currency, Order ID, Trade ID
3. Universal format
This format can be used for importing any kind of data. You have to specify the amount you are sending and the amount you are receiving in separate fields. This means you can use the file for deposits/withdrawals and even trades.
Sample data explained:
The first sample row in this file contains a trade of 1000 USD to 1 BTC with a fee of 5 USD on top. In other words, you are buying 1 BTC for 1000 USD + fee.
The second row contains an outgoing/send transaction of 0.5 BTC.
The third row contains an incoming transaction of 1 BTC from mining.
Required fields:
Date, Sent Amount, Sent Currency, Received Amount, Received Currency
Optional fields:
Fee Amount, Fee Currency, Net Worth Amount, Net Worth Currency, Tag, Description, TxHash
Fields explained:
Decimal separators
Always use the dot as a decimals separator in your files. We do not support comma separators. Ex: 0.55 BTC is good and 0,55 BTC is bad. A decimal separator (Ex: #.00) is required for all amounts.
Dates (timestamps)
All date fields must be formatted like this: YYYY-MM-DD HH:mm:ss. For example, if you want to enter 5th Jan 2019 the date will be 2019-01-05. It's best for timestamps to be in UTC but if they aren't, you don't have to edit them in the file - see How to import a CSV file using a different timezone
Order ID / Trade ID
Entering both an order ID and a Trade ID will allow Koinly to group trades for the same Order (Avalanche Trades).
Net worth amount & currency
You can set these if you know what the market rate of the transaction was at the time of the transaction. If it is empty Koinly will determine the market rate automatically. Read more about market prices on Koinly here.
The Net worth amount/currency is ignored if you bought or sold some coins using a fiat currency, in such cases Koinly will use the fiat as the market value instead.
The Net worth currency must be a fiat currency like USD, EUR, GBP, etc. The net worth amount should NOT include the value of the fee. If you have paid fees in a different cryptocurrency and want to specify the exact worth of the fee as well, you can use the Fee Worth and Fee Worth Currency columns instead.
Fee amount & currency
These are the fees you paid when trading and can be in any fiat or cryptocurrency. Fees can not be added to incoming or outgoing transactions. If you paid a transfer fee, Koinly will calculate it automatically when it matches an outgoing txn to an incoming txn on another wallet. Only use this field for entering trading fees.
Ex. if you bought 1 BTC for 100 USD and paid a 10 USD fee enter this as:
100 USD Sent
10 USD Fee
1 BTC Received
or as
110 USD Sent
1 BTC Received
(no fee)
Both are the same. Just don't enter the fee if it's already included.
Tags
Tags can be added as appropriate. For regular deposits/withdrawals/trades, no tag is required.
Koinly allows the following tags for outgoing transactions:
gift
lost
donation
cost
loan fee
margin fee
loan repayment
margin repayment
stake
realized gain
The following tags are allowed for incoming transactions:
airdrop
fork
mining
reward
income
lending interest
cashback
salary
fee refund
loan
margin loan
stake
realized gain
If you are unsure about what a tag does then you should refer to the below guide:
FAQ
How can I import a Transfer?
Since Koinly follows a double-ledger model, you can't import a "transfer" between wallets.
Instead, you need to:
Add an incoming transaction into the "receiving" wallet (deposit)
Add an outgoing transaction into the "sending" wallet (withdrawal)
Koinly will then match these two transactions and turn them into a single Transfer transaction automatically. See How Koinly handles transfers between your own wallets
Can I import the same file again without duplicates?
If you need to import the same file again, this can be done without worrying about duplicates.
Can I import Excel (XLS, XLSX) files or does it have to be CSV?
Koinly can handle these files too but if you encounter some errors (due to encoding etc) just export the file to csv (make sure it is comma delimited!).
Error: "Zip end of central directory signature not found"
If you are getting this error when trying to import a file to Koinly, follow these steps:
Open the file in a text editor (not excel!) and remove any invalid lines or quotes.
Then go to Google Sheets > create a Blank document > paste the csv data into the first column "A".
Then click on the "A" column to select all rows. Next click on Data > Split text to columns in the menu.
Your data should now be displayed in separate columns unless the file still contains bad data/quotes.
Now click on File > Download > Comma separated values (csv) and upload the downloaded file to Koinly.
How to fix a token that is imported as the wrong token?
If you try to import a token that shares its symbol with another token then Koinly will import the token that is more common.
If this is not the token that you were intending to import then you can fix this in your file. The way to do this is to replace the token symbol with the Koinly ID.
This is how:
Go to the Markets tab on Koinly and search for the token you want to import.
Let's say that I wanted to import the BitTorrent (old) token but Koinly is only importing the Bittorrent (new) token when I import BTT.
After clicking on the token you want, you will see the Koinly ID in the URL:
https://app.koinly.io/p/markets/3361
In this URL, we can see that the ID is 3361You can now replace the symbols in your file. The easiest way to do this would be to use the Find & Replace feature that most editors have. In this example, I would replace all instances of BTT with the text ID:3361.
Note that it's important to include the "ID:" in front of the number and there should be no space in between.
After all instances of BTT have been replaced with the ID, the file will import the correct token!