> ## 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.

# API Integration - Deep Dive

> Set up secure, read-only API connections between exchanges and KoinX so your crypto tax reports stay up to date without manual CSV exports or missed transactions.

API integration is the most popular way to connect exchanges to KoinX. You create a read-only API key on your exchange, paste it into KoinX, and fetch your transactions whenever you need. Here's how to set it up — and what to do when things don't work as expected.

<Card icon="sparkles" title="AI Summary">
  * Create a **read-only** API key on your exchange (never enable withdrawal permissions)
  * Paste the API Key, Secret Key, and Passphrase (if required) into KoinX
  * Click **Import Now** to connect
  * KoinX **does not auto-sync** — you need to manually trigger a sync from the Integrations page each time
  * Most exchange APIs have lookback limits (e.g., Bitget = 2 years) — use File Upload to backfill older data
  * Some exchanges offer a **Tax API Key** option (like Bitget) that's simpler to set up
</Card>

***

## Before You Start

Make sure you have:

* An active account on the exchange you want to connect
* Access to the API management section of your exchange (usually under Settings or Account)
* KoinX open in another tab, ready to receive the API key

<Warning>
  When creating your API key, only enable **read-only** (or "view") permissions. Never enable trading, withdrawal, or transfer permissions. KoinX only needs to read your transaction data — nothing more.
</Warning>

***

## How to Connect via API

<Steps>
  <Step title="Click Integrations in the left sidebar, then click Add Integration." />

  <Step title="Search for your exchange name and select it from the results.">
    KoinX opens the integration page with fields for your API credentials. You'll typically see: **API Key** (required), **Secret Key** (required), and sometimes **Password/Passphrase** (required for some exchanges, not for Tax API keys).
  </Step>

  <Step title="Login to your exchange and generate the API Keys">
    Navigate to the API management section and create a new API key with read-only permissions only. Copy the **API Key** and **Secret Key** (and Passphrase if prompted). The Secret is usually shown only once — save it somewhere secure.
  </Step>

  <Step title="Paste them into the corresponding fields in KoinX." />

  <Step title="Click Import Now.">
    KoinX will connect to your exchange and start **fetching** your transaction history. Depending on your trading volume, this can take from a few seconds to several minutes.
  </Step>
</Steps>

<Note>
  Check the right side of the integration page — KoinX shows **built-in instructions** specific to your exchange, including step-by-step guides for generating API keys, Important Notes, and Common Troubleshooting tips.
</Note>

***

## Understanding the Integration Page

Every API integration page in KoinX has two sections:

**Left side — your input:**

* **Add Wallet Name** — KoinX auto-assigns a name (e.g., "Bitget-1", "BigONE-1"). You can change this to something more recognisable.
* **API Key / Secret Key / Passphrase** fields
* **Advanced** section (expandable) for additional configuration
* **Import Now** button

**Right side — built-in help:**

* **Alerts** — important limitations specific to this exchange (shown in yellow)
* **Integration Steps** — step-by-step instructions for generating your API key
* **Important Notes** — data limitations, permissions guidance
* **Common Troubleshooting** — fixes for frequent issues

***

## Troubleshooting API Issues

### **API key shows as invalid**

* Double-check that you copied the full key and secret (no extra spaces or missing characters)
* Always **copy-paste your API key and secret** directly from your exchange — never type them manually. Even a single wrong character will cause the connection to fail.
* Make sure you're using the correct API key pair — some exchanges let you create multiple keys
* Check if the API key has expired on your exchange
* Verify that the API key has the correct permissions enabled
* For Bitget: double-check whether you created the key from the Normal API page or the Tax API page, and used the matching fields in KoinX

### **API integration stopped syncing**

* Your API key may have been revoked or expired on the exchange side. Log into your exchange and check.
* Some exchanges disable API keys after password changes or security events. Re-generate a new key and update it in KoinX.

### **Missing older transactions**

Most exchange APIs have a lookback limit. For example, Bitget only provides the last 2 years. Download your full transaction history from your exchange and import it via File Upload or Custom File.

### **Fewer transactions than expected**

* Check if specific transaction types (staking, futures, P2P, strategy) are included in the exchange's API output
* Bitget's API excludes executed strategy transactions entirely — add these manually
* Some exchanges rate-limit API requests, causing partial syncs — try syncing again after a few hours

***

## Common Issues / Edge Cases

<Accordion title="I have multiple accounts on the same exchange">
  Create a separate API key for each account and add them as separate integrations in KoinX.
</Accordion>

<Accordion title="My exchange requires IP whitelisting for API keys">
  When generating your API key on exchanges that ask about IP whitelisting, always choose the **"no IP whitelisting"** option (or leave it blank/unrestricted). KoinX does not provide specific IP addresses for whitelisting, and enabling IP restrictions will cause the connection to fail.
</Accordion>

<Accordion title="I regenerated my API key — do I need to update KoinX?">
  Yes. If you revoke or regenerate an API key on your exchange, the old key stops working. You'll need to update the key in KoinX under **Integrations → \[Your Exchange]**.
</Accordion>

<Accordion title="My exchange requires a passphrase but I can't remember it">
  If you're on Bitget, switch to the **Tax API Key** method — it removes the passphrase requirement entirely. For other exchanges, you'll need to regenerate a new API key with a new passphrase.
</Accordion>

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Will API automatically sync my future transactions?">
    Not yet — API auto-sync is not available right now. You need to manually trigger a sync by going to **Integrations**, finding your exchange, and clicking **Sync Now**. This will fetch any new transactions since your last sync.
  </Accordion>

  <Accordion title="Does API fetch futures, spot, and deposit transactions?">
    It depends on the exchange. Most major exchanges provide spot trades and deposits/withdrawals via API. Futures, staking rewards, and other transaction types vary. Some types (like Bitget strategy transactions) are excluded entirely.
  </Accordion>

  <Accordion title="Why did my API integration stop working?">
    The most common causes: your API key expired, was revoked, or your exchange disabled it after a security event (like a password change). Log into your exchange, check the API key's status, and generate a new one if needed.
  </Accordion>

  <Accordion title="What's the difference between Normal API Key and Tax API Key?" />
</AccordionGroup>