Standardized import / export format for cryptocurrency transaction ledgers.
Harmony takes the guesswork out of creating an export format for account history. This standard enhances interoperability between producers and consumers of these exports, making "CSV wrangling" a simpler task.
The basic requirements of the Harmony format are:
- The source of the data is named somewhere within the file. For a single-source export, such as an exchange, this declaration can be made within the header. For exports containing history from multiple sources, such as from portfolio management tools, each row of the data must contain the venue for that transaction.
- Transactions can be entered as single-entry, which makes trade history exports more readable; or double-entry, specifying the debits and credits in separate columns.
The Harmony standard should be:
- Easily readable by a human
- Adaptable to different languages
- Versatile enough to account for most transactional use cases
Who is this for?
- Wallet providers
- Service providers
The Format, Version 0.1
A contents of a Harmony file are in CSV format as described in RFC 4180. Implementors may look for language-specific CSV libraries that conform this RFC.
The first row of the document must contain one type declaration cell, which specifies the options for the file. The format of this cell is a space-separated list of options, the first being the string
HarmonyCSV. This declaration may be safely placed as the last cell of the first row.
HarmonyCSV (option)(value) (option)(value) ...
The options are as follows:
- v - The Harmony version of the document. Examples:
- h - The 1-indexed number of the column-definition row. The data content starts on the next row. Rows before this row are in the header area. Defaults to
- a - The accounting methodology used in the document. Valid options are either single-entry (
1) or double-entry (
2). Defaults to
- l- - Language of the document, following RFC 5646. Defaults to
0.1 file with column definitions on the third row of the document by default. Single-Entry, English language assumed. This is the minimum required declaration.
1.2 file with column definitions on the tenth row of the document. Single-entry accounting. Definitions in German.
HarmonyCSV v1.2 h10 a1 l-de
The header area of the document is every row up to and including the row of column definitions. Within this area, each data provider may include arbitrary custom data. However, some values within this area are meaningful for this specification.
When a cell within the header area exactly contains one of the following strings, the cell immediately following on the same row will contain the value of the declaration.
- Venue - The source of all rows of data. Must be declared either here in the header or on each data row.
- Exported - The generation time stamp for this document.
Basic Column Definitions
- indicates a required column
- Date & Time* - Time stamp of the entry, in ISO 8601 format.
- Venue* - If not specified in the header declarations, the execution location of the transaction. This value overrides the header declaration if both are present.
- Type* - Transaction type, enumerated. A colon after the trade type indicates a sub-type. Supported types are:
trade:buy- Indicates a bid that was filled
trade:sell- Indicates an ask that was filled
fee- For use in double-entry mode
fee:network- Indicates a fee paid to the network. Example: Gas on an Ethereum transaction.
"stolen, hacked, fraud"
- Asset* - What asset is being transacted. For trades using single-entry mode, this is the trading pair in the format
BASE/QUOTE. For non-trades, the single currency.
- Amount* - How much of the
BASEasset was transacted. Negative values should only be present in double-entry mode.
- Transaction ID* - Some value that will uniquely identify this transaction to the venue.
- Network ID - The on-chain transaction identifier.
- From ID - An identifier indicating from where the transaction originated, possibly an on-chain address.
- To ID - An identifier indicating from where the transaction was sent, possibly an on-chain address.
- Trade Order Type - The type of order execution method utilized for a given transaction. Examples:
- Notes - A general-purpose, unstructured field.
Single-Entry-Specific Column Definitions
- Price* - The execution price for trades, as the amount of the
QUOTEasset paid for each unit of the
- Total - The total value of the
QUOTEasset involved in the transaction.
- Fee Amount - Quantity of the Fee Asset being spent.
- Fee Asset - The asset being spent as payment for the transaction. For on-chain transactions, this may represent the network fee when the Network Fee Asset column is not defined.
- Network Fee Amount - Quantity of the Network Fee Asset being spent.
- Network Fee Asset - The asset being spent as payment for an on-chain transaction.
- Tax Asset - The asset being used to pay taxes on the transaction.
- Tax Amount - Quantity of the Tax Asset being spent.
Double-Entry-Specific Column Definitions
- Account - The name of the account. Example: wallet:BTC.
- Balance Amount - The amount remaining of the Balance Asset
- Balance Asset - The
BASEasset involved in the transaction.
Example Single-Entry File
HarmonyCSV v0.1 a1 h5 Venue, Coinbase Exported, 2018-05-01 00:00:00 UTC Date & Time, Type, Amount, Asset, Price, Fee Amount, Fee Asset, Transaction ID, 2018-05-01 00:00:00 UTC, deposit, 1000, USD, , , , Deposit Wire 100 2018-05-02 00:00:00 UTC, trade:buy, 10, BTC/USD, 91190.10, , , 123456 2018-05-03 00:00:00 UTC, trade:sell, 50, ETH/USD, 673.61, 336.805, USD, 567890 2018-05-04 00:00:00 UTC, withdraw, 10, BTC, , 0.000169453891, BTC, abc123
Example Double-Entry File
Note: This is the same set of transactions as in the single-entry example.
HarmonyCSV v0.1 a2 h5 Venue, Coinbase Exported, 2018-05-01 00:00:00 UTC Date & Time, Type, Amount, Asset, Transaction ID 2018-05-01 00:00:00 UTC, deposit, 1000, USD, Deposit Wire 100 2018-05-02 00:00:00 UTC, trade:buy, 10, BTC, 123456 2018-05-02 00:00:00 UTC, trade:buy, -91190.10, USD, 123456 2018-05-03 00:00:00 UTC, trade:sell, 50, ETH, 567890 2018-05-03 00:00:00 UTC, trade:sell, 33680.50, USD, 567890 2018-05-03 00:00:00 UTC, fee:exchange, 336.805, USD, 567890 2018-05-04 00:00:00 UTC, withdraw, 10, BTC, abc123 2018-05-04 00:00:00 UTC, fee:network, 0.000169453891, BTC, abc123
- Cost-basis reporting - While cost-basis should be included as an optional column, should the identifier of the source funds spent be required alongside? There is an inherent issue with this however, in the event that more than one source, each with a different cost-basis, was used.
- Short & Cover