Integration Errors and Troubleshooting

Documentation Index

Fetch the complete documentation index at: https://guides.koinx.com/llms.txt

Use this file to discover all available pages before exploring further.

Something broke. Maybe your integration has been stuck on “Updating Portfolio” for two hours, maybe you uploaded a file and KoinX spat it back with an error, or maybe your wallet address just won’t connect. Whatever the issue, this page has the fix — or at least tells you exactly what to do next. This guide is organised by error message / symptom so you can find your specific issue fast.

---

​

”Updating Portfolio” — Stuck or Taking Too Long

What it means: After you add or sync an integration, KoinX processes your transactions and recalculates your portfolio, cost basis, and tax figures. During this time, you’ll see “Updating Portfolio” status. How long should it take?

• Small accounts (under 500 transactions): a few minutes
• Medium accounts (500–5,000 transactions): 10–20 minutes
• Large accounts (5,000+ transactions): up to 30 minutes or more

If it’s been more than 2 hours:

1. Refresh the page — sometimes the status indicator doesn’t update in real-time.
2. Check your Transactions page — if transactions are appearing, the processing is still running. Be patient.
3. Try logging out and logging back in.
4. If it’s still stuck after 2+ hours with no new transactions appearing, contact KoinX support with your account email and the integration name.

---

​

”Invalid File Uploaded” Error

What it means: The file you uploaded doesn’t match the expected format for that integration. Common causes and fixes:

• Wrong file for the exchange Each exchange has a specific file format it expects. Uploading a Binance CSV to a WazirX integration (or vice versa) will fail. Make sure you’re uploading to the correct exchange integration.
• Edited or opened CSV before uploading Opening a CSV in Excel or Google Sheets can silently change date formats, number formatting, or encoding. Always upload the original file directly from the exchange without opening it first.
• Wrong file type Some exchanges export as .zip — you may need to extract the CSV inside before uploading. Others export as .xlsx but KoinX expects .csv. Check what the integration page says under “Files Supported.”
• Date format changed by spreadsheet software This is the #1 cause of Custom File upload failures. The expected format is YYYY-MM-DD HH:MM:SS in 24-hour UTC time. Google Sheets loves to auto-convert dates — copy from the example row in the template and edit carefully.
• Empty file If your exchange export has no transactions in the selected date range, the file will be empty. Expand your date range and re-download.
• File too large Some very large exports may hit upload size limits. Try splitting your file into smaller date ranges and uploading them one at a time.

---

​

”Invalid Address” Error for Wallet / Blockchain Integration

What it means: The wallet address you entered isn’t valid for the selected blockchain. Common causes and fixes:

• Wrong blockchain selected An Ethereum address (starts with 0x) won’t work if you selected Bitcoin as the blockchain. Make sure the blockchain type matches your address format.
• Address copied incorrectly Make sure there are no extra spaces before or after the address. Copy-paste directly from your wallet app — don’t type it manually.
• Blockchain domain not resolving If you entered an ENS name (like yourname.eth) or another blockchain domain, it might not resolve if the service is temporarily down. Try using the raw hex address instead.
• Address from an unsupported chain KoinX supports many but not all blockchains. If your address is on a chain that isn’t listed under Blockchains in the Add Integration page, you’ll need to use the Custom File method instead.

---

​

API Key Errors

​

1. “Invalid API Key” or “Authentication Failed”

Common causes:

• The API key was copied with extra spaces or missing characters
• The API key has expired on the exchange side
• The API key was revoked (sometimes exchanges revoke keys after password changes or security events)
• You’re using the wrong key pair — some exchanges let you create multiple API keys
• For exchanges like Bitget: you’re entering a Normal API key but forgot the Passphrase, or entering a Tax API key with a Passphrase when none is needed

Fix: Log into your exchange, check if the API key is still active. If not, generate a new one. Re-enter the credentials in KoinX carefully.

​

2. “Insufficient Permissions”

What it means: The API key doesn’t have the right permissions to read your transaction data. Fix: Go to your exchange’s API management page and check the permissions on your key. KoinX needs at least read/view access to your trading history, deposits, and withdrawals. For BigONE, check all scope boxes except: get deposit address, make withdrawal, create orders, and create futures.

​

3. API Sync Returns Fewer Transactions Than Expected

• Most exchange APIs have lookback limits — for example, Bitget only provides the last 2 years
• Some transaction types aren’t included in the API (Bitget excludes strategy transactions; some exchanges exclude staking rewards or P2P trades)
• Rate limiting can cause partial syncs — wait a few hours and try again
• Backfill the gap using File Upload or Custom File

---

​

”Please Wait While We Process Your Previous Report”

What it means: KoinX is still processing a previously generated report or a large data import. Until that finishes, certain actions (like generating a new report or adding integrations) may be temporarily blocked. Fix: Wait for the processing to complete. If it’s been more than a few hours, contact KoinX support.

---

​

Bitcoin Address Limit Reached

What it means: Bitcoin wallets can generate many addresses under a single account (due to how HD wallets work). KoinX has a limit on how many addresses it scans per integration. Fix: If you hit this limit, contact KoinX support. They can assist with importing your full Bitcoin transaction history. You may need to provide an XPUB key (extended public key) instead of individual addresses — this lets KoinX scan all addresses derived from your wallet in one go.

---

​

Duplicate Transactions After Integration

What it means: You see the same transaction appearing twice (or more). This inflates your trade volume, income, and tax figures. Common causes:

• You connected via API and uploaded a CSV covering the same time period
• You uploaded the same file twice
• You added the same wallet address under two different integration entries

Fix:

1. Go to Transactions and filter by the suspect integrations using the Wallets dropdown.
2. Compare the transaction lists — look for identical timestamps and amounts.
3. Remove the duplicate integration from the Integrations page (the one with less complete data).
4. Alternatively, if only a few transactions are duplicated, delete the individual duplicate entries from the Transactions page using the three-dot menu → Delete.

---

​

Transactions Showing Cost as 0 or Missing Prices

What it means: KoinX couldn’t determine the market price for a token at the time of the transaction. Common with: obscure tokens, newly launched coins, airdropped spam tokens, and very old transactions. Fix: Click the Add Price link on the transaction card (shown with an orange warning triangle). Enter the market value manually. If you don’t know the price, check a block explorer or price aggregator like CoinGecko for the token’s historical price at that timestamp.

---

​

Transactions Showing “Can’t Find Purchase Transaction” Error

What it means: KoinX found a sale, transfer out, or disposal of an asset — but cannot locate the original acquisition transaction for that asset in your history. This usually happens when historical data for that exchange or wallet was never imported, or the API lookback window didn’t cover older transactions. Fix: Upload historical data for the same exchange or integration using CSV import. Make sure the file covers the period when the asset was originally acquired. Once the missing purchase transactions are added, KoinX will recalculate the correct cost basis automatically.

---

​

Common Issues / Edge Cases

My integration connected successfully but shows 0 transactions

This can happen if: the API key doesn’t have the right permissions, the exchange account has no trading history in the API’s lookback window, or the wallet address is correct but has no on-chain activity. Double-check the address/key and your exchange account.

Transactions appeared then disappeared after re-sync

This usually happens when KoinX re-processes data and reclassifies some transactions (e.g., marking spam tokens). Check your Spam filter on the Transactions page — they may have been auto-hidden.

I can't delete an integration

If the integration is currently syncing or processing, you may need to wait for it to finish before removing it. If it remains stuck, contact support.

My exchange shut down — how do I add that data?

Check your email for trade confirmations or account statements. Use the Custom File integration to manually enter those transactions. Even partial data is better than a gap.

---

​

When to Contact Support

Try the fixes above first. Contact KoinX support if:

• “Updating Portfolio” has been stuck for more than 2 hours with no progress
• You’ve verified your API key is correct and active but KoinX still can’t connect
• You hit the Bitcoin address limit and need XPUB support
• You’re seeing data that looks clearly wrong (negative balances, impossible gains) that doesn’t resolve after re-syncing
• An error message not covered on this page appears

You can reach support via the chat widget (bottom-right corner of KoinX) or by emailing the support team.

---

​

Frequently Asked Questions

---

​

What’s Next?

• Verifying Your Integration Data — Make sure your data looks right after fixing errors
• Managing & Removing Integrations — Remove or re-add problematic integrations
• Custom File Integration — Manual fallback for data that won’t import any other way
• Getting Started with Integrations — Starting fresh? Begin here