Koinly First Tax Report Setup: Wallet Inventory, API and CSV Imports, Balance Checks and Data Review

A useful Koinly tax report begins before any report is downloaded. The first job is to identify every exchange, wallet, address and network that forms part of your transaction history. The second is to import that history without duplicates or dangerous permissions. Only then should you review balances, transfers, missing purchase history and transaction labels. This guide explains that complete first-time setup workflow so the result is based on records rather than assumptions.

Last reviewed: October 13, 2026. Koinly integrations, plan limits, report formats and interface labels can change. Tax rules depend on jurisdiction, year and individual facts. This independent guide provides general educational information and is not tax, legal, accounting or investment advice. Confirm current product details in Koinly and consult a qualified tax professional about your return.

1. What Koinly does with imported data

Koinly brings activity from exchanges, blockchains and other crypto services into one transaction ledger. It can retrieve market rates, identify likely trades and transfers, track acquisition costs and calculate capital gains and income under the settings selected for an account. It can also highlight potential problems, including assets that appear to leave an account without a known acquisition.

Those calculations depend on the inputs. Koinly cannot import an exchange you forgot, infer ownership of an unknown address, recover records that an API does not provide or decide the legal character of an unusual transaction from intention alone. Treat the software as a structured calculation and review environment—not as an automatic guarantee that a return is correct.

2. Define the report you are preparing

Before connecting anything, identify the taxpayer, jurisdiction and tax year for the intended report. A personal account should not silently combine a spouse’s, company’s or client’s assets. Country settings affect available calculations and reports, while a base currency determines how imported market values are displayed.

Write down the intended scope: for example, “individual records for the 2025 calendar year, reported in USD.” This simple note makes it easier to detect an account created with the wrong country, year or currency. If residence changed, a business is involved or more than one jurisdiction may apply, obtain professional guidance rather than guessing which profile setting resolves the issue.

3. Build a wallet and exchange inventory first

Start with a source inventory rather than the Koinly dashboard. List every centralized exchange, broker, custodial platform, software wallet, hardware wallet account, public address, blockchain, Layer 2 network, DeFi protocol and crypto payment service used. Include accounts that are empty, closed, restricted or no longer used if they contain part of the acquisition or transfer history.

Search old email receipts, password-manager entries, bank statements and prior exports to find forgotten services. For each source, record its name, owner, approximate first and last use, available import method and whether original files have been saved. Never enter a recovery phrase or private key into tax software. Public addresses, read-only connections and official transaction exports are the relevant tools.

4. Why historical and closed accounts belong in the inventory

A current-year sale can depend on an acquisition from years earlier. If BTC was purchased on an old exchange, moved through a hardware wallet and finally sold elsewhere, importing only the final exchange leaves the original purchase missing. The ending balance can look reasonable while the cost basis and holding period remain unsupported.

Do not import only the year you intend to file unless the complete earlier basis history is already documented in another appropriate way. Add the sources needed to trace assets from acquisition to disposition. If a closed platform no longer provides downloads, preserve bank records, confirmation emails, previous exports and on-chain evidence, then discuss material gaps with a tax professional.

5. Understand what Koinly calls a wallet

Within Koinly, “wallet” is a broad data container. It can represent a centralized exchange account, blockchain address, mobile wallet, hardware-wallet account or custom source. This does not mean Koinly takes custody of the assets. It means transactions from that source are grouped together for calculation and review.

Name each Koinly wallet clearly. “Ethereum Ledger 1,” “Kraken personal” and “Solana Phantom trading” are more useful than several entries called “Wallet.” Consistent names make transfer matching and troubleshooting easier, especially when the same public address is used on multiple compatible networks.

6. Choose API, public address or CSV deliberately

The best import method is the one that retrieves a complete, verifiable history for the specific source. An exchange API can simplify ongoing synchronization. A public blockchain address can retrieve on-chain activity. A CSV can preserve a stable snapshot and may contain records unavailable through an API. None of these methods is universally superior.

7. Use minimum permissions for an exchange connection

A crypto tax import normally needs transaction-history or read-only access. It should not need permission to trade, withdraw funds or change account security. Follow Koinly’s current instructions for the specific integration because exchanges use different names and authorization flows.

Before saving an API key, confirm that withdrawal and trading permissions are disabled. Store credentials securely and do not paste them into email or support conversations. If an exchange cannot provide an appropriately limited connection, use an official export when practical. Delete obsolete keys from the exchange after they are no longer required, subject to your intended synchronization workflow.

8. Know the limits of API auto-sync

An API connection can succeed while returning incomplete information. Some exchanges limit how far back an endpoint can reach or omit particular products, fees, delisted assets, internal transfers or migrated accounts. Koinly’s integration instructions may describe known limitations and additional CSV requirements.

After the first sync, compare the earliest and latest imported dates with the period in which you used the platform. Compare counts where the exchange provides them. Look for deposits, withdrawals and trades—not merely the current balance. A green connection indicator means the request worked; it does not certify the completeness of the history.

9. Import CSV files without losing the originals

Download files directly from the platform and retain the untouched originals in a dated archive. Use a separate working copy if a format needs adjustment. Record the platform, account, covered dates, time zone and export date in the filename or an accompanying index.

Import a supported Koinly template or the original platform format according to the current instructions. Do not casually delete columns, convert timestamps or combine files, because these changes can remove identifiers used for duplicate detection and matching. If Koinly rejects a file, keep both the original and the corrected version plus a note explaining every change.

10. Update a CSV wallet without duplicating history

A CSV wallet does not automatically gain new activity. To update it, export newer records and import them into the same Koinly wallet. Check whether the new file includes the full account history or only a chosen period. A full-history export can overlap the first upload, while separate monthly exports can leave gaps at their boundaries.

After an update, filter the transaction list around the overlap dates. Compare transaction IDs, order IDs, timestamps, quantities and fees. Do not assume two equal amounts are duplicates: one large order may consist of several legitimate fills. Remove or exclude an entry only when the source evidence demonstrates duplication.

11. Add public blockchain wallets correctly

For supported public chains, add the public address or public key specified by Koinly. Confirm it character by character and label its owner. Never provide a private key, recovery phrase, seed words or hardware-wallet PIN. Tax calculation does not require spending authority.

A wallet application is not the same as a single blockchain account. MetaMask may show the same hexadecimal address across several EVM networks; a hardware wallet can derive many accounts; and Bitcoin can use many addresses. Add the networks and account identifiers needed to represent the actual activity instead of assuming one address entry imports everything.

12. Treat every blockchain and Layer 2 as a separate data source

Activity on Ethereum, Arbitrum, Base, Optimism, BNB Smart Chain and other EVM networks may use the same visible address but reside on separate ledgers. If only Ethereum is added, transactions on another network can remain absent. The same principle applies to non-EVM chains and additional wallet accounts.

Use the inventory to mark each chain as imported and reviewed. For a bridge, identify both the source and destination networks. If only one side is present, Koinly may show an unexplained withdrawal, deposit or missing acquisition. Import both sides before manually changing the classification.

13. Add hardware-wallet history without connecting the device

A hardware wallet protects private keys; it is not itself the tax record. Import its relevant public accounts or addresses according to the blockchain and Koinly integration. You should not need to type the recovery phrase, approve a transaction or expose the private keys.

Keep an offline map showing which public accounts belong to you and how they are labeled in Koinly. If an account used multiple address types or chains, document them separately. This map helps establish that a withdrawal from an exchange and the corresponding deposit belong to the same taxpayer.

14. Create a custom wallet for unsupported sources

If a service is not listed, Koinly allows a custom wallet so its records can still be included. First ask the service for a complete transaction export. Map purchases, sales, deposits, withdrawals, income and fees using Koinly’s current file requirements rather than inventing a structure from memory.

Manual entries are appropriate only when supported by evidence. Retain order confirmations, statements, bank records and transaction hashes. A manually balanced account can still be wrong if values were entered merely to make a warning disappear.

15. Wait for calculations before judging the result

After imports, Koinly processes market values, transfer candidates, cost basis, gains and detected issues. Large or complex histories can take time. Do not begin changing transactions while calculation is still in progress, because intermediate balances and warnings may not reflect the completed ledger.

When processing finishes, note the wallet count and overall transaction count. Save a screenshot or review note as a checkpoint. This gives you a baseline if a later sync unexpectedly changes results.

16. Reconcile calculated balances with real balances

Compare Koinly’s calculated ending balance for each wallet with the balance shown by the exchange or blockchain at the same point in time. A difference can indicate missing transactions, duplicate imports, an incorrect address, an unsupported asset, a migration or a manual entry problem.

Do not correct a discrepancy with a balancing transaction until you understand its cause. Work chronologically from the first date where the running balance diverges. Check whether the source records contain an event that Koinly omitted or interpreted differently. Small differences may come from fees or rounding; large differences usually require a traceable explanation.

17. Investigate missing purchase history

A missing-purchase-history warning generally means an asset was disposed of or transferred out without enough earlier acquisition data. It does not prove that the asset had zero cost. Common causes include an old exchange not being imported, a deposit whose sending wallet is missing, an API date limitation, a token migration or a symbol that was mapped incorrectly.

Begin with the warned transaction. Record the asset, quantity, wallet and date, then trace backward. Search for the corresponding deposit and the previous withdrawal. Follow the chain until reaching a documented purchase, trade, gift, income event or other acquisition. If the origin cannot be reconstructed, preserve the search record and seek advice instead of entering a convenient basis.

18. Match transfers between accounts you control

A transfer between your own accounts ordinarily differs from a sale to another person, but Koinly needs both sides to recognize the relationship. Match the asset, amount, time, network and transaction hash. The received quantity can be smaller because of an exchange withdrawal fee or on-chain network fee.

Confirm ownership before applying a transfer label. A payment, gift, loan, bridge or transfer to someone else should not be relabeled as an internal movement simply to remove a gain. Where a bridge changes the technical representation of an asset, preserve the full on-chain path and obtain jurisdiction-specific advice if the treatment is uncertain.

19. Find duplicate transactions systematically

Duplicates often arise when the same exchange is imported through both API and CSV, the same public address is added twice, or a refreshed export overlaps an earlier file. They can double acquisitions, disposals, income and fees. The final balance alone may not reveal every duplicate because offsetting records can hide the effect.

Filter by wallet and date, then compare transaction hashes, order IDs, timestamps and quantities. Review repeated events around the same time. Preserve multiple fills when the source order history confirms them. Document the reason for removing any imported item so another reviewer can reproduce the decision.

20. Review deposits, withdrawals, trades and transfers

Start with high-value transactions and unusual labels. A deposit should have an identifiable source or reason. A withdrawal should have a destination. A trade should show what was disposed of, what was received and which fees applied. A transfer should connect two accounts under the same ownership.

Then sample ordinary transactions from each wallet and year. Compare them with original statements or block explorers. Sampling cannot replace a complete reconciliation, but it can reveal systemic errors such as reversed buy and sell columns, incorrect time zones or an API that omitted a product category.

21. Review staking, mining, rewards and airdrops separately

Assets received from staking, mining, referrals, promotions or airdrops should not automatically be treated as purchases or internal transfers. Their tax treatment and valuation timing differ by jurisdiction and facts. Koinly can suggest classifications, but the imported data may not describe why an asset was received.

Retain reward statements, payout schedules, wallet receipts and a description of the activity. Confirm the quantity and market-value source. If a reward is restaked automatically or paid through a changing token, ensure the later transaction does not hide the original receipt.

22. Review DeFi transactions as complete workflows

A DeFi interface can turn one click into approvals, swaps, deposits, receipt tokens, rewards and fees. Review the entire transaction group rather than assigning meaning from a single token movement. Liquidity positions, lending deposits, wrapped assets and bridges may require facts that an automatic label cannot capture.

Keep the protocol name, network, wallet, transaction hashes and a short explanation of the intended action. Check whether all relevant chains and addresses have been imported. For material or ambiguous activity, ask a qualified professional to review the treatment before finalizing the report.

23. Check settings before comparing tax totals

Confirm the country, base currency, tax year, time zone where applicable and cost-basis method before interpreting gains. Changing a method can alter which acquisition lots are matched to disposals and can affect remaining holdings. Do not switch settings merely because another result looks more favorable.

Save the settings used for each filed year. If a change is necessary, record the previous setting, the new setting, the reason and the professional guidance relied upon. A report should be reproducible after the filing deadline has passed.

24. Understand the Review needed section

The Tax Reports page can identify records that deserve attention. Treat these items as investigation prompts. Resolve missing purchase history, incomplete imports and material valuation problems before relying on the summary. A report may still be technically downloadable while warnings remain, but downloadability is not an accuracy test.

If an issue is genuinely immaterial or cannot be resolved, document the judgment and evidence. Do not clear warnings blindly to produce a cleaner screen. The objective is a supportable record, not a dashboard with no visible alerts.

25. Know what the free plan can establish

Koinly’s current documentation says the free plan can be used to test imports, review transactions and view calculated gains and a tax summary, subject to current transaction limits. Downloadable tax reports require an eligible paid plan. Plan features and limits can change, so confirm them on the live pricing and help pages.

Use the review stage before purchasing to assess whether wallets sync correctly and whether the history can be reconciled. Do not select a plan only from a rough trade count. Koinly applies its current billable-transaction rules, and a complete history may differ from the number of orders remembered.

26. Generate the first report only after reconciliation

Once sources, balances, transfers, warnings and settings have been reviewed, select the correct tax year on the Tax Reports page. Choose the report appropriate for the jurisdiction or filing software. Download all formats needed by the taxpayer or accountant, rather than assuming one summary contains every supporting detail.

Open the generated files and check the taxpayer context, period, currency and totals. Compare capital gains and income figures with the on-screen summary. A corrupted download, wrong-year selection or old cached report should be caught before anything is filed.

27. Create a filing-ready evidence folder

A good archive lets another qualified person reproduce the report. Keep original exchange exports, API setup notes, public-address inventory, transaction hashes for unusual events, Koinly transaction exports, generated reports, settings, warnings reviewed and a log of manual edits.

Use encrypted storage and a separate protected backup. Do not store recovery phrases or private keys with tax files. Name folders by tax year and source, and record the date each report was generated. If data changes later, retain the original filed version as well as the corrected version.

28. Common first-time Koinly mistakes

• Importing only the exchange where assets were sold.
• Omitting old, empty or closed wallets that contain acquisition history.
• Adding an exchange deposit address as though it were a self-custody wallet.
• Assuming one EVM address import covers every network.
• Giving an API key trading or withdrawal permissions.
• Uploading CSV files over an API history without checking overlap.
• Treating a completed sync as proof of complete data.
• Entering zero or an estimated basis only to remove a warning.
• Marking a payment or gift as a transfer between owned wallets.
• Changing the cost-basis method to obtain a preferred total.
• Downloading a report before checking balances and Review needed items.
• Failing to retain the source files and settings behind the report.

29. First Koinly report checklist

1. Confirm the taxpayer, country, base currency and intended tax year.
2. List every current and historical exchange, wallet, address and network.
3. Archive original CSV files and statements before editing anything.
4. Use read-only API permissions and verify integration limitations.
5. Import all years required to establish acquisition history.
6. Add every relevant blockchain and Layer 2 separately.
7. Wait for calculations to finish before making corrections.
8. Compare each calculated wallet balance with source records.
9. Trace missing purchase history back to documented acquisitions.
10. Match transfers only when both accounts belong to the same owner.
11. Check API and CSV overlaps for duplicates.
12. Review high-value, unusual, reward and DeFi transactions.
13. Confirm tax settings and the applicable calculation method.
14. Investigate material Review needed items.
15. Download the correct report and archive the supporting evidence.

30. When to involve a crypto tax professional

Professional review is particularly useful when ownership is mixed, records are missing, several jurisdictions are involved, prior returns may need correction or the history contains high-value DeFi, NFT, bridge, staking, business or foreign-account activity. Software can organize facts but cannot resolve every legal or accounting judgment.

Give the adviser the source inventory, original exports, unresolved warnings, settings, edit log and draft reports. This is more efficient than sending only a dashboard screenshot. Ask which report format and supporting schedules they require before purchasing or filing.

Frequently asked questions

Can I use Koinly without paying?

Koinly’s current help documentation describes a free plan for importing and reviewing eligible data, viewing calculated gains and seeing a tax summary within current limits. Generating downloadable tax reports requires a paid plan for the relevant year. Confirm live limits before relying on them.

Should I use API or CSV?

Use the method that produces the most complete verifiable history for that service. API auto-sync is convenient for supported exchanges, while CSV may be necessary for historical records, unsupported activity or API gaps. Compare the result with the source account.

Does Koinly need my seed phrase?

No. Never provide a seed phrase, private key or hardware-wallet PIN. Public addresses, appropriately restricted exchange connections and official exports are sufficient import methods.

Why does Koinly show missing purchase history?

The software can see an outgoing asset but cannot locate enough earlier acquisition data. Add missing exchanges, wallets, networks or historical files and trace the asset backward. Do not assume the cost was zero without appropriate evidence and advice.

Why does my Koinly balance differ from the exchange?

Common causes include missing transactions, API limitations, an incomplete CSV period, duplicates, incorrect addresses, fees or unsupported assets. Find the first date where the running balance diverges and compare it with the original source history.

Should I add wallets I no longer use?

Yes, when they contain activity needed to explain later transfers, basis or income. An empty wallet can still be an essential link between an old purchase and a current disposal.

Can I download a report while warnings remain?

Koinly may permit report generation with incomplete data, but that does not make the result reliable. Investigate material warnings, document unresolved items and seek professional help where the impact is uncertain.

Can Koinly file my taxes automatically?

Koinly produces calculations and reports that can support filing through an accountant, tax software or the applicable government process. The taxpayer remains responsible for complete inputs, correct classifications and the return that is filed.

Official Koinly documentation

Use these official resources to confirm the current interface, import methods, plan limits and report workflow:

• Koinly Help Center — Getting started with Koinly — the official four-step workflow for importing, calculating, reviewing and generating reports.
• Koinly Help Center — Import data from exchanges and crypto services — API auto-sync and CSV import instructions.
• Koinly Help Center — How to ensure your Tax Report is accurate — wallet completeness, balance checks and data-review guidance.
• Koinly Help Center — Some transactions are missing — troubleshooting incomplete exchange and wallet imports.
• Koinly Help Center — How to generate tax reports — selecting a tax year and downloading available report types.
• Koinly Help Center — Tax plans — current free-plan capabilities, paid reports and transaction limits.
• Koinly Blog — How to do crypto taxes — an overview of calculation, reporting and filing workflows.

Final takeaway

Koinly setup is not finished when accounts display a successful sync. It is finished when every material asset path can be followed through complete records, wallet balances reconcile, transfers reflect actual ownership, acquisition warnings are investigated and the report settings match the intended filing context.

Begin with the inventory, use the safest suitable import method, review the resulting ledger and preserve the evidence. That workflow makes Koinly more useful while keeping the final responsibility where it belongs: with the taxpayer and the qualified professionals involved in the return.