Интеграция с Koinly (крипто-налоги)

Интеграция с Koinly (крипто-налоги)

Koinly — популярный крипто-налоговый сервис с поддержкой 700+ бирж и 170+ стран. Интеграция обычно нужна когда платформа хочет предоставить пользователям удобный экспорт транзакций в Koinly без ручного скачивания CSV.

CSV формат Koinly

Koinly принимает данные через Universal 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] || "";
}

Koinly API (для платформ-партнёров)

Koinly предоставляет Partner API для прямой передачи транзакций (без CSV):

// Партнёрская интеграция через 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));
}

Интеграция с Koinly через CSV export или Partner API — 2-5 рабочих дней.