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

# Choosing Your Integration Method

> Decide when to use Direct Connect, API, File Upload, blockchain address or custom file so your KoinX integrations stay clean, complete and reliable for crypto tax reports.

You know you need to connect your exchanges and wallets. But KoinX offers multiple ways to do it — and picking the wrong one can mean missing data, duplicates, or unnecessary manual work. This guide helps you choose the right method for each source, based on your specific situation.

<Card icon="sparkles" title="AI Summary">
  * **Direct Connect** is the easiest — use it when available
  * **API** is the best balance of automation and control — works for most major exchanges
  * **File Upload** is the fallback when API has gaps — especially useful for backfilling older history
  * **Blockchain Address** is the only option for DeFi wallets and on-chain activity
  * **Custom File** is the last resort for unsupported exchanges or defunct platforms
  * Don't mix API and File Upload for the **same date range** — use one for current data and the other for historical backfill
</Card>

***

## How to Choose

Here's the simplest way to decide which integration method you should choose:

```mermaid placement="top-left" theme={null}
flowchart TD
    A{DeFi / On-chain?}
    A -- Yes --> B[Use Blockchain Address]
    A -- No --> C{Direct Connect available?}

    C -- Yes --> D[Use Direct Connect]
    C -- No --> E{API available?}

    E -- Yes --> F[Use API]
    F --> G{Full history?}
    G -- No --> H[Upload File for older data]

    E -- No --> I{Exchange listed?}
    I -- Yes --> J[Upload File]
    I -- No --> K[Use Custom File]
```

***

## Comparison Table

|                          | Direct Connect            | API                                    | File Upload                              | Custom File                   | Blockchain Address             |
| :----------------------- | :------------------------ | :------------------------------------- | :--------------------------------------- | :---------------------------- | :----------------------------- |
| **Setup effort**         | Very low                  | Low                                    | Medium                                   | High                          | Low                            |
| **Auto-syncs new data**  | Yes                       | Yes                                    | No                                       | No                            | Yes                            |
| **Full historical data** | Depends on exchange       | Often limited (e.g., Bitget = 2 years) | Full (you control the export)            | Full (you provide the data)   | Full (reads entire chain)      |
| **Best for**             | Exchanges that support it | Most centralised exchanges             | Backfilling old data                     | Unsupported/defunct exchanges | DeFi wallets, hardware wallets |
| **Risk of duplicates**   | Low                       | Low                                    | Medium (if combined with API carelessly) | Low                           | Low                            |

***

## When to Combine Methods

The most effective setup for many users is a **combination** of methods:

### API + File Upload (most common combo)

Use API for **fetching transactions** when you trigger a manual sync. Use File Upload to **backfill historical data** that the API can't reach. Since API doesn't auto-sync, you'll also need to manually trigger a sync from the Integrations page each time you want to pull in new transactions.

1. Connect via API first and let it sync your recent transactions.
2. Go to **Transactions**, filter by that exchange, and check the oldest transaction date.
3. Log into your exchange and download your transaction history as a file, covering the period before your API data starts.
4. Upload the file through KoinX. It will fill in the historical gap while KoinX handles deduplication for any overlap.

<Warning>
  Don't upload a file covering the same date range your API already synced — this will create duplicate transactions.

  Keep your date ranges clean: API for ongoing fetches (triggered manually), File Upload strictly for the historical period before your API data starts.
</Warning>

### Blockchain Address + Manual Adds

For DeFi wallets, the blockchain scan captures most activity. But some complex interactions (multi-step swaps, cross-chain bridges, certain staking protocols) may not import cleanly. Review your imported transactions and manually add anything that's missing.

***

## Method Recommendations by Situation

<Accordion title="I mainly use centralised exchanges">
  Use **API** for your primary exchanges(if available). It auto-syncs and requires minimal maintenance. If any exchange supports **Direct Connect**, use that instead — it's even simpler. Backfill older history with **File Upload** if your API only covers recent months.
</Accordion>

<Accordion title="I'm heavy into DeFi">
  Use **Blockchain Address** for all your wallet addresses across every chain you've used (Ethereum, BSC, Polygon, Solana, etc.). Review the imported transactions carefully — DeFi interactions are complex and may need manual categorisation.
</Accordion>

<Accordion title="I used exchanges that are now shut down">
  Use **Custom File**. Gather whatever records you have (emails, bank statements, CSV exports you saved) and format them into KoinX's template. If you can't create the file yourself, KoinX offers a paid service to build it for you.
</Accordion>

<Accordion title="I want the least effort possible">
  Use **Direct Connect** where available. Use **API** for everything else. Only touch File Upload or Custom File if you're missing historical data. After connecting, let KoinX auto-sync and focus your effort on reviewing and categorising the imported transactions.
</Accordion>

***

## Common Issues / Edge Cases

<Accordion title="Why isn't API available for all exchanges?">
  Not every exchange provides a public API that third-party tools can use. Some smaller or regional exchanges don't offer API access at all. In those cases, File Upload or Custom File is your only option.
</Accordion>

<Accordion title="I connected via API but my exchange shows more transactions">
  This is an API lookback limit. Many exchanges only expose recent data through their API. For example, Bitget's API only provides the last 2 years. Backfill the older period with a File Upload.
</Accordion>

<Accordion title="Can I switch from File Upload to API later?">
  Yes. Adding an API connection for an exchange where you previously uploaded a file is fine. KoinX will sync new data via API going forward. Your previously uploaded data stays intact.
</Accordion>

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Is API integration safe?">
    Yes — as long as you only grant **read-only permissions** when creating your API key. KoinX cannot make trades, withdrawals, or any changes to your exchange account. Only read access is needed.
  </Accordion>

  <Accordion title="Can I use File Upload and API at the same time for the same exchange?">
    Yes, but use them for **strictly different time periods** to avoid duplicate transactions. The recommended approach: File Upload for historical data the API can't reach, then manually sync via API for newer transactions going forward. Do not overlap date ranges — duplicates are a real risk and can skew your tax report.
  </Accordion>

  <Accordion title="What if my exchange exported separate files for spot, futures, and P2P?" />
</AccordionGroup>