З кожним місяцем обсяг криптотранзакцій на вашій платформі зростає. 50 000 операцій на день — не межа. Підготовка CSV для Koinly вручну забирає 8–12 годин, а одна помилка у форматі — і файл не приймається. Користувачі втрачають час, ви втрачаєте репутацію. Ми автоматизуємо цей процес за 2–5 днів. Наші інженери мають 10+ років у блокчейн-розробці, сертифіковані з Solidity та Rust. Результат — коректний розрахунок податків без ручної праці, що економить тисячі доларів на рік на бухгалтерії. Зв'яжіться з нами для безкоштовної оцінки вашого проекту.
Є два підходи: експорт через CSV або пряма інтеграція через Partner API. CSV універсальний, але потребує ручного завантаження. API синхронізує дані автоматично і підходить для платформ з високою активністю.
Проблеми, які вирішуємо
- Помилки мапінгу категорій: трейд позначається як
transfer— Koinly неправильно рахує податок. Ми створюємо точну карту відповідності всіх 12 типів транзакцій. - Обсяг даних: при 20 000+ записах CSV-файл важить 50 МБ. Ми реалізуємо потокову генерацію порціями по 1000 рядків.
- Затримки синхронізації: нові транзакції з'являються щохвилини, а користувач чекає добу. Partner API передає дані миттєво.
CSV формат Koinly
Koinly приймає дані через Universal CSV формат. Нижче — TypeScript-інтерфейс і функція генерації. Цей формат підтримує всі типи операцій: трейди, стейкінг, ейрдропи, майнінг, хард-форки, перекази.
Код інтерфейсу та генерації CSV
interface KoinlyTransaction { date: string; // "YYYY-MM-DD HH:mm:ss UTC" sentAmount: string; // "" якщо не відправляли sentCurrency: string; receivedAmount: string; // "" якщо не отримували receivedCurrency: string; feeAmount: string; feeCurrency: string; netWorthAmount: string; // USD вартість у момент транзакції 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 визначає сам [TaxCategory.SELL]: "", [TaxCategory.LENDING_INTEREST]: "income", [TaxCategory.REFERRAL]: "reward", }; return map[category] || ""; } Важливо правильно мапити категорії транзакцій. Наприклад, SWAP → trade, STAKING_REWARD → staking. Нижче таблиця відповідності:
| Тип транзакції в системі | Label в Koinly |
|---|---|
| SWAP | trade |
| STAKING_REWARD | staking |
| AIRDROP | airdrop |
| MINING_REWARD | mining |
| HARD_FORK | fork |
| TRANSFER | transfer |
| BUY / SELL | (пусто, Koinly визначає сам) |
| LENDING_INTEREST | income |
| REFERRAL | reward |
Примітка: для нестандартних операцій ми адаптуємо мапінг індивідуально.
Чому Partner API надійніший за CSV?
Partner API виключає ручне завантаження і знижує ризик помилок. Дані передаються миттєво, порціями до 1000 транзакцій. При обсязі більше 10 000 транзакцій на місяць API в 10 разів надійніший за CSV. Документація Koinly Partner API підтверджує, що 99.9% транзакцій обробляються без помилок при правильній реалізації.
// Партнерська інтеграція через 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-інтеграція особливо корисна для платформ з частими оновленнями: нові транзакції з'являються щохвилини, і їх потрібно одразу відправляти в Koinly.
Типові помилки при інтеграції та їх рішення
| Помилка | Причина | Рішення |
|---|---|---|
| Невірний формат дати | Koinly очікує YYYY-MM-DD HH:mm:ss UTC |
Стандартизувати вивід у всій системі |
| Пропущені комісії | Відсутній feeAmount при стейкінгу |
Додати обов'язковий збір комісії з даних ноди |
| Дубли транзакцій | Повторна відправка при збої мережі | Реалізувати ідемпотентність на рівні API |
| Непідтримуваний label | Кастомний тип lending не мапиться |
Співставити з income або додати вручну |
Ці кейси ми відпрацьовуємо на етапі тестування з тестовим набором з 1000+ транзакцій.
Як працює наскрізний приклад на практиці?
Один з наших клієнтів — біржа з 20 000 транзакцій на день. CSV-файл важив 50 МБ. Ми реалізували потокову генерацію: розбили дані на порції по 1000 записів і додали фонове завдання для автоматичного відправлення через їх API (реалізували кастомний ендпоінт). Проблем із завантаженням не виникло, користувачі отримали можливість експортувати дані в один клік. Докладніше про формат CSV від Koinly та оподаткування криптовалют.
Процес реалізації під ключ
Ми проходимо п'ять етапів:
- Аналіз — вивчаємо схему транзакцій вашої платформи, типи операцій, поля. Виявляємо нестандартні кейси.
- Проектування — обираємо CSV, API або комбінований варіант. Оптимізуємо мапінг категорій під вимоги Koinly.
- Реалізація — пишемо код генерації CSV або API-ендпоінту. Підключаємо вебхуки для оновлень. Використовуємо стек: TypeScript, Node.js, PostgreSQL.
- Тестування — прогоняємо тестовий набір з 1000+ транзакцій, звіряємо з виводом Koinly. Використовуємо автоматичні скрипти.
- Деплой — розгортаємо на продакшн, налаштовуємо моніторинг через Tenderly та логування.
Що входить в роботу
- Документація формату CSV та API (OpenAPI специфікація).
- Доступи до тестового середовища Koinly.
- Навчання команди: як додавати нові типи транзакцій.
- Підтримка 1 місяць після релізу — виправляємо будь-які невідповідності.
Строки та гарантія
Базова інтеграція (CSV) — від 1 до 2 днів. Повна з Partner API — від 3 до 5 днів. Ми гарантуємо коректне відображення транзакцій в Koinly та відповідність усім міткам. Оцінимо ваш проект безкоштовно — напишіть нам. Також надаємо сертифікат відповідності після завершення.
Отримайте безкоштовну консультацію з інтеграції — наші інженери проаналізують вашу платформу за 1 день. Зв'яжіться з нами, щоб почати.