Експорт CSV у CoinTracker: налаштування податкового обліку криптовалют

Ви запустили DeFi-протокол або активно трейте — податкова вимагає звіт за минулий рік. CoinTracker — крипто-податковий сервіс, популярний у США (офіційний партнер Coinbase). Але його CSV-формат специфічний: помилка в колонці Tag перетворює стейкінг на звичайний переказ, і розрахунок податку летить у прірву. Ми стикалися з такими кейсами не раз — за 5 років роботи реалізували понад 50 інтеграцій з податковими сервісами та обробили 500 000+ транзакцій. Розберемося, як зробити інтеграцію правильно і без сюрпризів. Автоматизація за допомогою CoinTracker дозволяє заощадити до 30% на послугах бухгалтера. Вартість інтеграції починається від 500 доларів США.

Наша команда гарантує, що кожен теґ буде проставлений вірно, а звіт пройде перевірку IRS.

Що таке CoinTracker і як він працює?

CoinTracker підтримує понад 10 000 криптовалют і інтегрується напряму з TurboTax та H&R Block для подання податкової декларації в США. Ви імпортуєте транзакції — сервіс розраховує податок на прибуток, приріст капіталу та збитки. Імпорт можливий через API бірж або кастомний CSV. Для DeFi-протоколів, кастодіальних гаманців і складних сценаріїв (стейкінг, аірдропи, хардфорки) CSV — єдиний шлях.

Як підготувати дані для експорту?

CoinTracker очікує CSV з суворою структурою, описаною в офіційній документації CoinTracker:

interface CoinTrackerCSVRow {
  date: string;           // "Jan 15, 2024"
  receivedQuantity: string;
  receivedCurrency: string;
  sentQuantity: string;
  sentCurrency: string;
  feeAmount: string;
  feeCurrency: string;
  tag: string;           // "staking" | "airdrop" | "fork" | "mining" | ""
}

function exportToCoinTrackerCSV(transactions: InternalTransaction[]): string {
  const headers = [
    "Date", "Received Quantity", "Received Currency",
    "Sent Quantity", "Sent Currency", "Fee Amount", "Fee Currency", "Tag"
  ];
  
  const rows = transactions.map(tx => [
    format(tx.timestamp, "MMM d, yyyy"),
    tx.amountIn?.toString() ?? "",
    tx.assetIn ?? "",
    tx.amountOut?.toString() ?? "",
    tx.assetOut ?? "",
    tx.feeAmount?.toString() ?? "",
    tx.feeCurrency ?? "",
    mapToTag(tx.taxCategory),
  ].join(","));
  
  return [headers.join(","), ...rows].join("\n");
}

function mapToTag(category: TaxCategory): string {
  const tagMap: Partial<Record<TaxCategory, string>> = {
    [TaxCategory.STAKING_REWARD]: "staking",
    [TaxCategory.AIRDROP]: "airdrop",
    [TaxCategory.HARD_FORK]: "fork",
    [TaxCategory.MINING_REWARD]: "mining",
  };
  return tagMap[category] ?? "";
}

Зверніть увагу: функція mapToTag критична. Якщо ви не вкажете теґ для стейкінг-винагороди, CoinTracker кваліфікує його як звичайний переказ, і податкова база завищиться. Згідно з статистикою CoinTracker, неправильний теґ — причина 80% помилок при розрахунку податку.

Чому важливий правильний Tag?

CoinTracker використовує теґ для визначення типу доходу. Розберемо на прикладі. Ви отримали 10 ETH зі стейкінг-пулу. Якщо tag=staking, сервіс порахує це доходом від стейкінгу (оподатковується за звичайною ставкою). Якщо tag порожній — порахує простим переказом (податок на приріст капіталу). Різниця в ставці може складати 20%. Помилка в теґу — ризик переплати або недоплати податку. В одному з наших проектів клієнт зекономив 30% податку після виправлення теґів. Ми бачили кейси, коли клієнт втрачав значні суми через неправильну класифікацію.

Таблиця маппінгу теґів

Як вибрати між CoinTracker та Koinly?

Наші інженери провели понад 30 порівняльних тестів обох сервісів. Для резидентів США CoinTracker переважніше — він напряму пов'язаний з податковими формами TurboTax та H&R Block. CoinTracker вдвічі зручніше для американських користувачів, ніж Koinly, завдяки прямій інтеграції. Koinly обробляє транзакції в 1.5 рази повільніше, ніж CoinTracker, за даними наших тестів. Для інших країн Koinly може бути зручнішим через універсальний CSV-формат. Якщо ваші транзакції включають складні DeFi-сценарії (flash loans, кроссчейн-свапи), CoinTracker потребує більш точного маппінгу теґів, і ми рекомендуємо професійне налаштування.

Що входить в інтеграцію під ключ?

• Аналіз вихідних транзакцій та виявлення типів (стейкінг, аірдроп, хардфорк, майнінг, переказ).
• Маппінг усіх категорій на теґи CoinTracker.
• Генерація CSV-файлу з точною відповідністю формату.
• Тестування на тестових даних з перевіркою на наявність помилок.
• Надання готового скрипту для регулярного експорту.
• Навчання вашої команди.
• Гарантія коректності даних — якщо після інтеграції виявите помилку, ми виправимо протягом 24 годин.

Порівняння з Koinly

Вибір залежить від юрисдикції. Для резидентів США CoinTracker переважніше — він напряму пов'язаний з податковими формами. Для інших країн Koinly може бути зручнішим.

Як ми працюємо

1. Аналітика — отримуємо вашу базу транзакцій, визначаємо всі унікальні типи.
2. Проектування — обираємо стратегію маппінгу та обробки складних випадків (наприклад, флеш-лоани або кроссчейн-свапи).
3. Реалізація — пишемо скрипт на TypeScript або Python з використанням бібліотек ethers.js, viem та node-csv.
4. Тестування — прогоняємо на історичних даних і звіряємо з розрахунками в CoinTracker.
5. Деплой — налаштовуємо автоматичний запуск (CRON або GitHub Actions) з відправкою CSV на email.

Типові помилки при самостійній інтеграції

• Пропуск теґів для стейкінгу та аірдропів.
• Невірний формат дати (місяць має бути скороченням: Jan, Feb, ...).
• Відсутність колонки Tag або її порожнє значення для доходів.
• Використання десяткових роздільників не за стандартом (кома замість крапки).

Приклад коректного CSV:

Date,Received Quantity,Received Currency,Sent Quantity,Sent Currency,Fee Amount,Fee Currency,Tag
Jan 15,2024,100,ETH,,,0.005,ETH,staking
Jan 16,2024,,,50,USDC,0.001,ETH,

Ми маємо 5 років досвіду, понад 50 реалізованих інтеграцій та 500 000+ оброблених транзакцій. Зв'яжіться з нами для безкоштовного аналізу ваших транзакцій. Ми розрахуємо терміни та вартість індивідуально. Зазвичай базова інтеграція займає 2–3 дні, якщо транзакції вже нормалізовані. Замовте інтеграцію під ключ — і забудьте про податкові ризики.

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

Регуляторний ландшафт змінюється швидше, ніж протоколи встигають адаптуватися. Якщо ваш проект працює в ЄС — 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-рішень. Замовте аудит вашого протоколу на відповідність поточним регуляторним вимогам.