Автоматичний розрахунок податків: інтеграція криптобіржі з 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;        // "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. Нижче таблиця відповідності:

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

Чому 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.

Типові помилки при інтеграції та їх рішення

Ці кейси ми відпрацьовуємо на етапі тестування з тестовим набором з 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 архітектури, потім переробляють її під тиском — це дорожче, болючіше та загрожує даунтаймами. Ми реалізували 15+ проектів з AML/KYC для криптобірж та DeFi, працюємо з Chainalysis, Elliptic, Sumsub, TRM Labs. Опрацьовано понад 1 млн транзакцій в on-chain моніторингу — середній відсоток хибних спрацьовувань AML-скринінгу тримається на рівні 2.3%. Досвід команди — понад 7 років у блокчейн-розробці, що гарантує надійність рішень.

Чому 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-тікетів забезпечений.

Приклад gRPC-запиту для передачі Travel Rule даних:

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

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

Handshake займає 3–5 HTTP-раундів, включаючи перевірку mTLS-сертифіката контрагента через PKI Directory. Наш AML-скринінг з Chainalysis обробляє транзакцію за 1.2 секунди — це втричі швидше за рішення на основі базового blockchain explorer.

Як обрати 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

MiCA (Regulation (EU) 2023/1114) — чинний регламент, докладніше див. Wikipedia: Markets in Crypto-Assets Regulation. Він вимагає від 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.

Як MiCA змінює архітектуру DeFi?

Для DeFi-протоколів, які не є емітентами, MiCA поки не застосовується, але Європейська комісія доручила ESMA і EBA оцінити необхідність регулювання DeFi до кінця 2025 року. Ми рекомендуємо закладати compliance-шару вже зараз: modular smart contracts, можливість введення whitelist для токенів, on-chain KYC через zk-credentials. Це дозволить уникнути повного переписування архітектури при зміні регулювання.

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

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

Gap analysis — аудит поточної архітектури та data flow (1–2 тижні). Ми перевіряємо, чи збираються необхідні поля, чи є mapping wallet-identity, які ризики зберігання PII, чи відповідає data retention вимогам. На основі цього будується план змін.

Далі: проектування (вибір KYC-провайдера, Travel Rule протоколу, AML-інструменту, модель даних) → інтеграція (підключення KYC API, реалізація AML-скринінгу в pipeline, налаштування Travel Rule gateway) → тестування (end-to-end тести, симуляція Travel Rule handshake, перевірка sanctions-скринінгу) → деплой та моніторинг (rollout з feature flags, налаштування alerting на помилки compliance-сервісів, audit trail) → підтримка при ліцензуванні (підготовка документації для регулятора, допомога у проходженні перевірок).

Що ми здаємо: deliverables

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

У 98% наших клієнтів перевірки регуляторів проходять з першої спроби. Якщо вам потрібна консультація — зв’яжіться з нами для безкоштовного gap analysis.

Орієнтири за термінами

• 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-рішень. Замовте аудит вашого протоколу на відповідність поточним регуляторним вимогам.