CSV columns and transaction types
This guide explains every column in NairaTally's CSV template, and every transaction type the calculator accepts. It describes how the tool works. It does not tell you how your own transactions should be taxed. For that, please check with a qualified Nigerian tax professional.
You can download the template from the calculator ("Download generic CSV template"). Its header row is:
date,type,asset,quantity,fiat_currency,fiat_amount,to_asset,to_quantity,usd_value,fee_fiat,exchange,tx_id,wht_withheld,category,noteKeep the header row exactly as it is. Leave a cell empty if it does not apply to that row.
General rules for every row
- Numbers. Write plain numbers, such as
1500000or0.01. The calculator also reads thousands separators (1,500,000), decimal commas (0,5), and strips ₦, $, € and £ signs. A minus sign is ignored, because many exchange exports show sells as negative numbers. - Quantities must be positive. Rows with a zero or unreadable quantity are reported as errors.
- Asset codes are not case-sensitive.
btcandBTCare the same. - Errors are listed, not hidden. If a row cannot be read, the calculator skips it and tells you the row number and the reason.
The columns
| Column | What it means | Required? | Accepted format |
|---|---|---|---|
date | The date of the transaction. | Always. | YYYY-MM-DD (best), for example 2026-01-15. DD/MM/YYYY and MM/DD/YYYY also work if you choose the matching date format in the column mapper. A time after the date is ignored. Years before 2009 or after 2100 are rejected as typos. |
type | What kind of transaction it was. | Always. | One of the transaction types below, for example buy, sell or staking_reward. |
asset | The coin or token involved. For a swap, the coin you gave up. | Always (except transfer, where it is optional). | A ticker, for example BTC, USDT, SOL. |
quantity | How many units. On a buy, the template says this is the net units credited to you after stamp duty. | Always (except transfer). | A positive number, for example 0.01. |
fiat_currency | The ordinary currency the trade was priced in. | Required for buy and sell. Not used for other types. | A currency code, for example NGN or USD. NGN and USD are converted using your rate table. For other currencies (such as GBP or EUR), you must also fill in usd_value. |
fiat_amount | The total amount of that currency paid (on a buy) or received (on a sell). The template says: total NGN paid. | Required for buy and sell. | A positive number, for example 1500000. |
to_asset | For a swap: the coin you received. | Required for swap. | A ticker, for example ETH. |
to_quantity | For a swap: how many units you received. | Required for swap. | A positive number, for example 0.2. |
usd_value | The total US dollar value of the transaction on that date (its fair market value). | Required for rewards, airdrops (with a value), hard forks, other income and gifts, unless you upload a price table that covers that asset and date. Optional for swaps. Needed for buys and sells priced in a currency other than NGN or USD. | A number in US dollars, for example 300. This is the total value, not the price per unit. |
fee_fiat | A trading fee paid in ordinary currency. | Optional. | A number, for example 1500. It is only used if you tick "Include fiat fees in cost base / deduct from proceeds" in the settings, and only for NGN or USD trades. The default is to ignore fees, because the Guidelines do not say whether fees are deductible. |
exchange | Where the transaction happened. | Optional. | Free text, for example ExampleExchange. It is a label for your records. |
tx_id | The exchange's order or transaction ID. | Optional. | Free text, for example tx-001. If you leave it empty, the calculator uses the row number. |
wht_withheld | Whether withholding tax was already deducted on this row. | Optional. | yes or no (also y/n, true/false, 1/0). If empty, the calculator uses your setting for the whole file. |
category | The virtual asset category (1 to 6) from the Guidelines (para 5.0). | Optional. | A whole number from 1 to 6. If empty, the calculator treats known stablecoins as Category 2 and everything else as Category 1. |
note | Your own note. | Optional. | Free text. |
Example rows
These are the example rows from the template and the fictional sample file. They are not real transactions.
date,type,asset,quantity,fiat_currency,fiat_amount,to_asset,to_quantity,usd_value,fee_fiat,exchange,tx_id,wht_withheld,category,note
2026-01-15,buy,BTC,0.01,NGN,1500000,,,,1500,ExampleExchange,tx-001,,,"quantity = NET units credited after stamp duty; fiat_amount = total NGN paid"
2026-03-05,staking_reward,SOL,2,,,,,300,,ExampleExchange,tx-002,,,"usd_value = total USD fair market value on the date received"
2026-04-20,swap,USDT,500,,,ETH,0.2,500,,SampleExchange,s4,,,FICTIONAL
2026-05-12,sell,BTC,0.005,NGN,900000,,,,,SampleExchange,s5,,,FICTIONAL
2026-07-01,airdrop_no_fmv,XYZ,1000,,,,,,,Wallet,s8,,,FICTIONALThe transaction types
The calculator accepts these values in the type column. It also recognises many common exchange words (for example "deposit", "withdraw", "convert", "earn") and maps them to these types. If it does not recognise a value, it reports an error and you can map it in the column mapper.
| Type | What it means in plain words | Columns it needs | How the calculator treats it |
|---|---|---|---|
buy | You bought a coin with ordinary money. | date, asset, quantity, fiat_currency, fiat_amount | Adds the coins to your holdings, with a cost equal to the money paid, converted to US dollars at your rate for that date. It also shows an estimate of the 1.5% stamp duty on the purchase. If the "currency" is actually a coin (for example a BTC/USDT trade), the calculator treats the row as a swap. |
sell | You sold a coin for ordinary money. | date, asset, quantity, fiat_currency, fiat_amount | Treats it as a disposal. It works out the dollar gain (proceeds minus cost, using FIFO or weighted average), then converts that gain to naira at your rate for the sale date. A 1% withholding tax credit is applied for Category 1, 3 and 5 assets if withholding is marked as deducted. |
swap | You exchanged one coin for another, with no ordinary money involved. | date, asset, quantity, to_asset, to_quantity (and usd_value or a price table if the value cannot be worked out) | Treats it as a disposal of the coin you gave up, at its US dollar value on that date. The coin you received gets that value as its cost. Stablecoins are valued at their peg unless you supply prices. |
staking_reward | Coins you received for staking. | date, asset, quantity, usd_value (or a price table) | Records it as income at its US dollar value on the day you received it, converted to naira at your rate for that date. That value also becomes the coins' cost. A 10% withholding credit applies only if you mark it as withheld. |
mining_reward | Coins you received from mining. | Same as staking_reward | Same as staking_reward, labelled as mining income. |
defi_reward | Rewards from DeFi, such as lending, liquidity or yield. | Same as staking_reward | Same as staking_reward, labelled as DeFi income. |
airdrop | Free tokens you received that had a market value when you got them. | Same as staking_reward | Same as staking_reward, labelled as an airdrop. |
hard_fork | New coins you received because a blockchain split. | Same as staking_reward | Same as staking_reward, labelled as a hard fork. |
airdrop_no_fmv | Free tokens you received that had no market value when you got them. | date, asset, quantity | Records them with a nil (zero) cost and no income at receipt. When you later dispose of them, the full proceeds count as gain. The calculator reminds you to keep documents showing there was no market value. |
other_income | Crypto you received as other income, for example payment for work. | Same as staking_reward | Same as staking_reward, labelled as other income. |
gift_received | Coins someone gave you as a gift. | date, asset, quantity, usd_value (or a price table) | Adds the coins to your holdings, with a cost equal to the US dollar value you supplied. It does not record income. The calculator flags these rows for review, because the Guidelines refer to a section of the Nigeria Tax Act that they do not reproduce. |
transfer | You moved your own coins between your own wallets or accounts. | date (asset optional) | Not treated as a disposal and not used in the gain calculation. It still counts towards the price. |
ignore | A row you want the calculator to skip. | None | Skipped completely. |
Counting transactions for pricing
The price of a report depends on the number of transactions dated in the tax year. Every row dated in the tax year counts, including transfers between your own wallets. Rows you mark as ignore, and rows the calculator can't read, don't count.
Transfers are not used in the gain calculation, but they still count towards the price. Rows that cannot be read are listed as errors.
Be careful with overlapping files. The calculator does not spot duplicates, so the same trade uploaded in two files counts twice, for the price and in the calculation. Tip: if you download more than one export from the same exchange, make sure the date ranges do not overlap, or remove the repeated rows before you upload.
What this guide is not
This guide explains how NairaTally reads your file and what the calculator does with each row. It is not tax advice. Choosing the right type for a transaction, the right category, or whether withholding tax was deducted can change your estimate. If you are not sure how a transaction should be treated for your own return, please ask a qualified Nigerian tax professional. Never send your transaction files to NairaTally support. We do not need them.
Information only - not tax or legal advice. NairaTally is an independent software tool. It is NOT affiliated with, endorsed by or connected to the Nigeria Revenue Service or any government body. Results are estimates produced from the data you supply and from our reading of the published "Guidelines on the Taxation of Virtual Assets" (Information Circular No. 2026/21, 31 July 2026). They are information only and are not tax, legal or accounting advice. Some provisions are ambiguous and some inputs (rates, prices, withholding status) are supplied by you. You remain responsible for your own return.