С каждым месяцем объём криптотранзакций на вашей платформе растёт. 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; // "2024-01-15 14:30:00 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 documentation подтверждает, что 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 день. Свяжитесь с нами, чтобы начать.