Автоматический расчёт налогов: интеграция криптобиржи с Koinly

С каждым месяцем объём криптотранзакций на вашей платформе растёт. 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-интерфейс и функция генерации. Этот формат поддерживает все типы операций: трейды, стейкинг, эйрдропы, майнинг, хард-форки, переводы.

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. Ниже таблица соответствия:

Примечание: для нестандартных операций мы адаптируем маппинг индивидуально.

Почему 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.

Типичные ошибки при интеграции и их решения

Эти кейсы мы отрабатываем на этапе тестирования с тестовым набором из 1000+ транзакций.

Как работает сквозной пример на практике?

Один из наших клиентов — биржа с 20 000 транзакций в день. CSV-файл весил 50 МБ. Мы реализовали поточную генерацию: разбили данные на порции по 1000 записей и добавили фоновую задачу для автоматической отправки через их API (реализовали кастомный эндпоинт). Проблем с загрузкой не возникло, пользователи получили возможность экспортировать данные в один клик. Подробнее о формате CSV от Koinly и налогообложении криптовалют.

Процесс реализации под ключ

Мы проходим пять этапов:

1. Анализ — изучаем схему транзакций вашей платформы, типы операций, поля. Выявляем нестандартные кейсы.
2. Проектирование — выбираем CSV, API или комбинированный вариант. Оптимизируем маппинг категорий под требования Koinly.
3. Реализация — пишем код генерации CSV или API-эндпоинта. Подключаем вебхуки для обновлений. Используем стек: TypeScript, Node.js, PostgreSQL.
4. Тестирование — прогоняем тестовый набор из 1000+ транзакций, сверяем с выводом Koinly. Используем автоматические скрипты.
5. Деплой — разворачиваем на продакшн, настраиваем мониторинг через Tenderly и логирование.

Что входит в работу

• Документация формата CSV и API (OpenAPI спецификация).
• Доступы к тестовой среде Koinly.
• Обучение команды: как добавлять новые типы транзакций.
• Поддержка 1 месяц после релиза — исправляем любые несоответствия.

Сроки и гарантия

Базовая интеграция (CSV) — от 1 до 2 дней. Полная с Partner API — от 3 до 5 дней. Мы гарантируем корректное отображение транзакций в Koinly и соответствие всем меткам. Оценим ваш проект бесплатно — напишите нам. Также предоставляем сертификат соответствия после завершения.

Получите бесплатную консультацию по интеграции — наши инженеры проанализируют вашу платформу за 1 день. Свяжитесь с нами, чтобы начать.

Услуги блокчейн комплаенса: почему ваш проект рискует без них

Мы видим, как регуляторный ландшафт для криптоиндустрии меняется быстрее, чем протоколы успевают адаптироваться. Если ваш проект работает в ЕС — MiCA уже не рекомендация, а обязательное требование. FATF Travel Rule применяется несколько лет, но реальное enforcement нарастает. Протоколы, которые запускаются без compliance архитектуры, потом переделывают её под давлением — это дороже, болезненнее и грозит даунтаймами. Услуги блокчейн комплаенса включают полный цикл: от gap analysis до запуска и поддержки при лицензировании. Мы реализовали 15+ проектов по AML/KYC для криптобирж и DeFi, работаем с Chainalysis, Elliptic, Sumsub, TRM Labs. Обработано более 1 млн транзакций в on-chain мониторинге — средний процент ложных срабатываний AML-скрининга держится на уровне 2.3%.

Почему Travel Rule — техническая, а не юридическая задача?

FATF Recommendation 16 (в банковской практике известен как FinCEN Travel Rule) требует, чтобы VASP при переводах от $1 000 (или €1 000 в ЕС) передавали KYC-данные отправителя и получателя от одного VASP другому. Это требование, скопированное из традиционных банковских wire transfers, в блокчейне создаёт технические проблемы, которых не существует в SWIFT.

Первая проблема — определение VASP-to-VASP. Если пользователь отправляет с кастодиального адреса биржи на self-custodial кошелёк — по FATF Travel Rule не нужен, так как один из контрагентов не VASP. Но как VASP автоматически определяет, что destination адрес действительно self-custodial, а не другой VASP? Решение: on-chain аналитика (Chainalysis, Elliptic, TRM Labs) для кластеризации адресов + использование Travel Rule протокола только для VASP-to-VASP.

Вторая проблема — interoperability между VASP. Travel Rule протоколов несколько: TRUST (консорциум под эгидой Coinbase/SWIFT), TRISA (gRPC-based, открытый стандарт), OpenVASP (Ethereum-based), Sygna Bridge. Они несовместимы между собой. Большинство крупных бирж поддерживают несколько одновременно. Техническая реализация — API gateway, который определяет протокол контрагента и маршрутизирует запрос.

TRISA реализация (наиболее открытая): gRPC-сервис, mTLS для аутентификации, PII данные шифруются публичным ключом получателя (envelope encryption, AES-256 + RSA-4096). Для регистрации в TRISA Directory Service нужна верификация через члена TRISA. Код — открытый SDK на Go и Python.

Конкретная грабля: timing. Travel Rule данные должны быть переданы до или одновременно с транзакцией. В Ethereum блокчейне транзакция подтверждается в среднем за 12 секунд — за это время TRISA handshake обязан завершиться. Если контрагент не отвечает — транзакция блокируется или задерживается. UI обязан объяснять это пользователю, иначе поток support-тикетов обеспечен.

service TRISANetwork {
  rpc Transfer(TransferRequest) returns (TransferResponse);
}

message TransferRequest {
  string identity_payload = 1;  // зашифрованный PII-пакет
  string envelope_public_key = 2;
  string transaction_hash = 3;
}

Как выбрать KYC/AML провайдера для криптопроекта?

KYC-провайдеры для криптовалют делятся на несколько классов:

Tier 1 (enterprise, regulatory grade): Jumio, Onfido, Sumsub, Veriff. Поддерживают 200+ стран, видео-верификацию, liveliness checks, AML-скрининг через Refinitiv/Dow Jones. Интеграция через REST API + webhooks. Sumsub популярен в европейских криптопроектах — качественная документация SDK для мобильных приложений.

Tier 2 (DeFi-native, privacy-focused): Fractal ID, Synaps, Persona. Меньше regulatory overhead, быстрее интеграция, но меньше глобального покрытия для высокорискованных юрисдикций.

On-chain KYC через credentials: Quadrata Passport, Civic, PolygonID — пользователь проходит верификацию один раз, получает on-chain credential, протоколы проверяют его без повторной верификации. Privacy-preserving через ZK. Пока не mainstream, но направление, которое мы закладываем в архитектуру.

Архитектурный принцип: KYC-данные никогда не хранятся on-chain. Персональные данные хранятся у провайдера или в вашей зашифрованной базе, on-chain — только хеш (commitment) или credential (если используется VC/SBT подход). Это соответствие GDPR: право на удаление данных реализуемо, если данные off-chain.

Типичная ошибка: хранить wallet-to-identity mapping в plaintext в PostgreSQL без row-level encryption. Один SQL injection — и вся база KYC-данных скомпрометирована. Минимум: column encryption для PII-полей (PGP или AES через pgcrypto), отдельное управление ключами (AWS KMS, HashiCorp Vault), audit log для всех доступов к PII.

Для AML-скрининга используем Chainalysis, Elliptic или TRM Labs. Интеграция асинхронная через webhook: результат приходит за 1–5 секунд. Threshold-based блокировка: HIGH risk — автоблок, MEDIUM — manual review. Hold-период для подозрительных транзакций — 24–72 часа до manual review. Sanctions-скрининг отдельно: OFAC SDN list обновляется несколько раз в неделю, используем прямую интеграцию OFAC list (бесплатно) с собственной логикой matching для адресов.

Услуги блокчейн комплаенса: как мы реализуем поддержку MiCA

Markets in Crypto-Assets Regulation (EU 2023/1114) — ссылка на Wikipedia — требует от CASP (Crypto-Asset Service Provider) лицензирования в одном государстве ЕС с passporting. Технические требования, влияющие на разработку:

White paper обязателен для эмитентов ART (Asset-Referenced Tokens) и EMT (E-Money Tokens) — не маркетинговый документ, а юридически обязывающий проспект с техническим описанием, правами держателей, механизмами redemption.

Custody requirements: клиентские активы отдельно от операционных. Технически — отдельные кошельки/accounts на клиента (или omnibus с off-chain mapping + регулярная reconciliation), невозможность использовать клиентские средства для операционных нужд.

Transaction monitoring и reporting: CASP обязаны вести запись всех транзакций минимум 5 лет, предоставлять регулятору по запросу.

Travel Rule в MiCA: порог €0 для VASP-to-VASP переводов — не €1 000, как в FATF. Реализация требует Travel Rule endpoint, работающего 24/7.

Процесс внедрения compliance инфраструктуры

Compliance архитектура не добавляется поверх готового продукта без боли. Правильный порядок: compliance requirements → data model → business logic → UI. Если у вас уже есть продукт без compliance слоя — начинаем с gap analysis: какие данные уже собираются, где дыры, что потребует schema migration.

1. Gap analysis — аудит текущей архитектуры и data flow (1–2 недели).
2. Проектирование — выбор KYC-провайдера, Travel Rule протокола, AML-инструмента, модель данных.
3. Интеграция — подключение KYC API, реализация AML-скрининга в pipeline, настройка Travel Rule gateway.
4. Тестирование — end-to-end тесты, симуляция Travel Rule handshake, проверка sanctions-скрининга.
5. Деплой и мониторинг — rollout с feature flags, настройка alerting на ошибки compliance-сервисов, audit trail.
6. Поддержка при лицензировании — подготовка документации для регулятора, помощь в прохождении проверок.

Что включает услуга блокчейн комплаенса?

• Документация compliance-архитектуры (data flow, ER-диаграммы, API-спецификации).
• Интеграция KYC/AML/Travel Rule API с вашим бэкендом.
• Настройка мониторинга и alerting для compliance-сервисов.
• Обучение вашей команды работе с инструментами (Chainalysis, Sumsub и т.д.).
• Поддержка при прохождении лицензирования (MiCA, FATF).

Ориентиры по срокам

• KYC/AML интеграция с Sumsub или Jumio — от 3 до 6 недель.
• Travel Rule (TRISA или Sygna) — от 6 до 10 недель.
• Полная compliance инфраструктура для CASP лицензирования — от 4 до 8 месяцев.
• On-chain compliance через VC/SBT с ZK (MiCA-ready) — от 5 до 9 месяцев.

Scope уточняется после gap analysis. Для оценки вашего проекта свяжитесь с нами — мы проведём бесплатный анализ текущей архитектуры и подберём оптимальный набор инструментов. Получите консультацию по compliance-архитектуре под MiCA или Travel Rule. Опыт команды — более 7 лет в блокчейн-разработке, 15+ внедрённых compliance-решений. Закажите аудит вашего протокола на соответствие текущим регуляторным требованиям.