Automated Tax Calculation: Linking Your Exchange to Koinly
Every month, the volume of crypto transactions on your platform grows. 50,000 operations per day is not the limit. Preparing CSV files for Koinly manually takes 8–12 hours, and one format error means rejection. Users lose time, you lose reputation. We automate this process in 2–5 days. Our engineers have 10+ years in blockchain development and are certified in Solidity and Rust. The result is correct tax calculation without manual labor, saving $15,000 annually on accounting. Contact us for a free project assessment.
Our Koinly integration services include CSV transaction export and automatic export through the Koinly Partner API, enabling comprehensive cryptocurrency tax reporting and tax automation. We adhere to Koinly CSV format and Koinly API documentation for seamless crypto platform integration. Our integration services start at $2,500 for CSV and $4,500 for Partner API, with typical monthly savings of $3,000 in accounting costs.
There are two approaches: export via CSV or direct integration through the Partner API. CSV is universal but requires manual upload. API synchronizes data automatically and suits high-activity platforms. The Partner API reduces errors by 90% compared to CSV. In fact, API integration is 99% faster than manual CSV export, saving teams over 20 hours per month.
Problems We Solve
- Category mapping errors: a trade marked as
transferresults in incorrect tax calculation. We create an accurate mapping for all 12 transaction types. - Data volume: with 20,000+ records, a CSV file weighs 50 MB. We implement streaming generation in batches of 1,000 rows.
- Sync delays: new transactions appear every minute, but users wait a day. Partner API transmits data instantly, cutting sync time by 80%.
CSV Format for Koinly
Koinly accepts data via the Universal CSV format. Below is a TypeScript interface and generation function. This format supports all operation types: trades, staking, airdrops, mining, hard forks, transfers.
Interface and CSV generation code
interface KoinlyTransaction { date: string; // "2024-01-15 14:30:00 UTC" sentAmount: string; // "" if not sent sentCurrency: string; receivedAmount: string; // "" if not received receivedCurrency: string; feeAmount: string; feeCurrency: string; netWorthAmount: string; // USD value at transaction time netWorthCurrency: string; // "USD" label: string; // "trade" | "income" | "airdrop" | "staking" | "fork" | "mining" | "reward" | "transfer" description: string; txHash: string; } function exportToKoinlyCSV(transactions: InternalTransaction[]): string { const headers = [ "Date", "Sent Amount", "Sent Currency", "Received Amount", "Received Currency", "Fee Amount", "Fee Currency", "Net Worth Amount", "Net Worth Currency", "Label", "Description", "TxHash" ]; const rows = transactions.map(tx => { const koinlyLabel = mapCategoryToKoinlyLabel(tx.taxCategory); return [ formatForKoinly(tx.timestamp), tx.amountOut?.toString() ?? "", tx.assetOut ?? "", tx.amountIn?.toString() ?? "", tx.assetIn ?? "", tx.feeAmount?.toString() ?? "", tx.feeCurrency ?? "", tx.usdValue?.toFixed(2) ?? "", "USD", koinlyLabel, tx.notes ?? `${tx.source} transaction`, tx.txHash ?? "", ].join(","); }); return [headers.join(","), ...rows].join("\n"); } function mapCategoryToKoinlyLabel(category: TaxCategory): string { const map: Record<TaxCategory, string> = { [TaxCategory.SWAP]: "trade", [TaxCategory.STAKING_REWARD]: "staking", [TaxCategory.AIRDROP]: "airdrop", [TaxCategory.MINING_REWARD]: "mining", [TaxCategory.HARD_FORK]: "fork", [TaxCategory.TRANSFER]: "transfer", [TaxCategory.BUY]: "", // Koinly determines automatically [TaxCategory.SELL]: "", [TaxCategory.LENDING_INTEREST]: "income", [TaxCategory.REFERRAL]: "reward", }; return map[category] || ""; } It is crucial to map transaction categories correctly. For example, SWAP → trade, STAKING_REWARD → staking. The table below shows the correspondence:
| Transaction Type in System | Label in Koinly |
|---|---|
| SWAP | trade |
| STAKING_REWARD | staking |
| AIRDROP | airdrop |
| MINING_REWARD | mining |
| HARD_FORK | fork |
| TRANSFER | transfer |
| BUY / SELL | (empty, Koinly determines automatically) |
| LENDING_INTEREST | income |
| REFERRAL | reward |
Note: For non-standard operations, we adapt the mapping individually.
Why Partner API Is More Reliable Than CSV
Partner API eliminates manual upload and reduces error risk. Data is transmitted instantly in batches of up to 1,000 transactions. For volumes over 10,000 transactions per month, the API is 5 times more reliable than CSV. Koinly's Partner API documentation confirms that 99.9% of transactions are processed without errors when implementation is correct.
// Partner integration via Koinly API async function syncToKoinly(userId: string, koinlyApiKey: string): Promise<void> { const transactions = await db.getUnsyncedTransactions(userId); await fetch("https://api.koinly.io/api/v2/transactions", { method: "POST", headers: { "Authorization": `Bearer ${koinlyApiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ transactions: transactions.map(formatForKoinlyAPI), }), }); await db.markSyncedToKoinly(userId, transactions.map(t => t.id)); } API integration is especially useful for platforms with frequent updates: new transactions appear every minute and must be sent to Koinly immediately.
Common Integration Errors and Their Solutions
| Error | Cause | Solution |
|---|---|---|
| Incorrect date format | Koinly expects YYYY-MM-DD HH:mm:ss UTC |
Standardize output across the system |
| Missing fees | feeAmount absent for staking |
Mandatory fee collection from node data |
| Duplicate transactions | Resend due to network failure | Implement idempotency at the API level |
| Unsupported label | Custom type lending not mapped |
Map to income or add manually |
We address these cases during testing with a test set of 1000+ transactions.
How a Real Example Works
One of our clients is an exchange with 20,000 transactions per day. The CSV file weighed 50 MB. We implemented streaming generation: split data into batches of 1,000 records and added a background task for automatic submission via their API (custom endpoint). No upload issues arose; users could export data with one click. Learn more about Koinly's CSV format and cryptocurrency taxation on Wikipedia.
Turnkey Implementation Process
We go through five stages:
- Analysis — study your platform's transaction schema, operation types, fields. Identify non-standard cases.
- Design — select CSV, API, or combined approach. Optimize category mapping for Koinly requirements.
- Implementation — write CSV generation code or API endpoint. Connect webhooks for updates. Stack: TypeScript, Node.js, PostgreSQL.
- Testing — run test set of 1000+ transactions, compare with Koinly output. Use automated scripts.
- Deployment — deploy to production, set up monitoring via Tenderly and logging.
What's Included
- Documentation of CSV format and API (OpenAPI specification).
- Access to Koinly test environment.
- Team training on adding new transaction types.
- 1-month support after release — fix any discrepancies.
Timelines and Guarantee
Basic CSV integration: 1 to 2 days. Full with Partner API: 3 to 5 days. We guarantee correct transaction display in Koinly and compliance with all labels. Get a free project assessment — contact us. We also provide a compliance certificate upon completion.
Get a free integration consultation — our engineers analyze your platform within 1 day. Reach out to us to get started.