Skip to main content

AI Summary

  • It requires more manual effort, but it works for literally any transaction source.
  • Use Custom File when your exchange or transaction source is not supported in KoinX integrations
  • Download the template from Integrations → Custom File → Download Template File
  • Every row in the file represents one transaction
  • Three fields must always be filled: Date and Time (UTC), Type, and Label
  • Other fields depend on what happened in that transaction
  • Upload the completed template under Integrations → Add Integration → Custom File
  • Only files in KoinX Custom File template format are accepted

​
When Should You Use Custom File?

Not every exchange or transaction source is supported directly in KoinX’s integration library. Maybe you:
  • traded on a smaller regional exchange
  • executed OTC deals
  • used a platform that no longer exists
  • received crypto from an external wallet
  • interacted with DeFi platforms that don’t have a native integration
For situations like these, Custom File is the universal fallback. Instead of connecting an exchange or wallet, you upload your transaction history using KoinX’s standardised template format.
If the exchange is supported in KoinX, always use the native integration or exchange file upload instead.Custom File should be treated as the last resort.

​
How Custom File Works

The Custom File template is a structured spreadsheet. Each row describes one transaction, including:
  • what happened
  • which assets moved
  • how much was sent or received
  • any fees involved
KoinX reads this data and reconstructs the transaction history. Think of it as manually describing your crypto activity to the system.

​
How to Upload a Custom File

1

Click Add Integration.

2

Select Custom File from the integrations list.

You will see a page titled Integrate Custom File with an auto-generated wallet name such as: Custom File-1
3

Click Download Template File.

This downloads the official KoinX Custom File template spreadsheet.
4

Open and Fill the Document

Only files using this exact format can be uploaded. Open the template in Excel or Google Sheets. Each row represents one transaction.Fill the fields according to the guide below.
5

Return to the Custom File integration page.

6

Upload the File

7

Click Submit

KoinX will process the file and import the transactions.
The Custom File upload area only accepts files in KoinX template format.You cannot upload a raw exchange CSV here.If your exchange is supported in KoinX, use the exchange-specific file upload integration instead.

​
Understanding the Template Structure

The template contains multiple columns so it can support every possible crypto transaction type. However, not every column applies to every transaction. We’re dividing this template to two parts:
  1. Required Fields
  2. Transaction Data Fields
This allows the template to represent any crypto activity. Let’s dive deeper to understand these fields and what values are to be entered:

​
Required Fields (Always Needed)

These fields must be filled for every row. If any are missing, the file will fail to upload.
  1. Date and Time (UTC) This is the exact timestamp of the transaction. Format: YYYY-MM-DD HH:MM:SS
    Example: 2023-05-30 14:34:25
    1. Must use 24-hour format
    2. Must be UTC timezone
    3. Avoid letting Excel auto-format dates. A safe approach is to copy the example timestamp from the template and edit it. Spreadsheet software sometimes silently changes date formats, which can break the import.
  2. Type The Type describes the broad category of the transaction. Allowed values:
    TypeDescription
    TradeExchange one asset for another
    DepositReceiving crypto
    WithdrawalSending crypto
    Margin TradeMargin trading transactions
    Futures TradeFutures trading transactions
    ExpenseFees and costs
  3. Label Label adds more detail about the transaction. The allowed labels depend on the Type you selected. For example:
    TypeSupported Labels
    Trade Margin TradeFutures TradeSwap, Buy, Sell, Swap

    Note - Swap is only for Trade type
    DepositExternal Deposit, Collateral Unlock, Refund,
    Reward, Airdrop, Staking Interest, Fixed Deposit Unlock,
    Borrow, Lend Settlement, Receive from Pool, Receive Loan,
    Funding Interest, Futures Realised Profit, Options Realised Profit,
    Salary, Mining Income, Consultancy Income
    WithdrawalExternal Withdraw, Collateral Lock, Lend
    Fixed Deposit Lock,
    Borrow Settlement, Send to Pool, Repay Loan
    Funding Fee, Futures Realised Loss, Options Realised Loss,
    Donation
    ExpenseFutures Fee, Options Fee, Brokerage or Gas Fee,
    Margin Interest Payment,
    Mining Expense, Consultancy Expense
    Labels must match the Type. Using an incompatible label will cause the upload to fail. Example: 
    Deposit → Airdrop
Trade → Buy
Expense → Gas Fee

​
Transaction Data Fields

The remaining fields describe what assets moved in the transaction. You only fill the fields relevant to that transaction.
  1. Received Asset Fields Use these when crypto was received.
    FieldDescription
    Received CoinThe asset received (BTC, ETH, USDT, etc.)
    Received Coin AmountQuantity received
    Received Coin Amount in
    Base Currency    		Value in your base currency for entire quantity
    (USD, EUR, INR etc.)
    Example: I received 1.5 ETH and the price during the transaction was 3000 USD. 
    Received Coin: ETH
Received Coin Amount: 1.5
Received Coin Amount in Base Currency: 4500 USD
  2. Sent Asset Fields Use these when crypto was sent.
    FieldDescription
    Sent CoinThe asset sent
    Sent Coin AmountQuantity sent
    Sent Coin Amount in Base CurrencyValue in base currency
    Example: 
    Sent Coin: USDT
Sent Coin Amount: 2500
  3. Fee Fields Use these when a transaction fee was paid.
    FieldDescription
    Fee CoinAsset used to pay the fee
    Fee Coin AmountFee amount
    Fee Coin Amount in Base CurrencyFee value in base currency
    Example: 
    Fee Coin: ETH
Fee Coin Amount: 0.002
  4. TDS Fields These apply only when tax was deducted at source. Primarily relevant for Indian exchanges.
    FieldDescription
    TDS CoinAsset in which TDS was deducted
    TDS Coin AmountQuantity deducted
    TDS Coin Amount in Base CurrencyValue of TDS
    If no TDS applies: 
    TDS Coin = -
TDS Coin Amount = 0
  5. Address and Hash Fields These are useful for blockchain transactions.
    FieldDescription
    From AddressSource wallet address
    To AddressDestination wallet address
    Transaction HashBlockchain transaction ID
    If unknown: -
  6. Token Contract Fields These identify tokens on EVM chains.
    FieldDescription
    Received Coin Contract AddressToken contract for received asset
    Sent Coin Contract AddressToken contract for sent asset
    Only required for less common tokens.

​
Rules for Empty Fields

Do not leave cells blank. Use placeholders.
Field TypeValue to Enter
Coin fields-
Amount fields0
Address / hash fields-
Example: 
No coin received → Received Coin = -
No amount received → Received Coin Amount = 0

​
Sample Scenarios:

Type: Trade
Label: BuyExample: Received 1.5 ETH and Sent 2850 USDT
2023-05-30 14:34:25 | Trade | Buy | ETH | 1.5 | 0 | USDT | 2850 | 0
Type: Deposit
Label: AirdropExample - Received 500 ARB tokens
2023-06-15 09:00:00 | Deposit | Airdrop | ARB | 500 | 0
Type: Withdrawal
Label: External WithdrawExample - Sent 0.1 BTC
2023-06-20 10:00:00 | Withdrawal | External Withdraw | - | 0 | BTC | 0.1
Type: Expense
Label: Brokerage or Gas FeeExample - Paid gas fee of 0.003 ETH
2023-07-01 18:22:10 | Expense | Brokerage or Gas Fee | - | 0 | ETH | 0.003

​
Common Issues and Fixes

Most common cause:
  1. Incorrect timestamp format.
    Make sure the format is: YYYY-MM-DD HH:MM:SS. And that the timezone is UTC.
  2. Label does not match Type
    Example mistake: Type: Trade and Label: Airdrop
    This will fail because Airdrop is only allowed for Deposit.
If you don’t know certain values:
  • Use 0 for amounts
  • Use - for coin names or addresses
Even partial data can still be processed.
You can upload multiple files to the same Custom File integration.Each upload will add new transactions.

​
Frequently Asked Questions

No. The Custom File integration only accepts KoinX template format.Use the exchange-specific integration if available.
KoinX will try to determine the market price at that timestamp using its pricing data.Providing values manually may improve accuracy for obscure tokens.
Only if TDS was actually deducted.Otherwise:
TDS Coin = -
TDS Coin Amount = 0
Last modified on March 13, 2026