CryptoTax API

Download OpenAPI specification:Download

Blockpit: sales@blockpit.io URL: https://blockpit.io/

Introduction

The CryptoTax API gives you the ability to create legislation- and standards-compliant tax reportings for you and your customers.

Creating tax report

In essence, creating a single tax report can be accomplished in two steps:

You post transaction information to the /requestReportCalculation API endpoint, also specifying information such as the tax country and tax year, and the format of the tax reportings.
You poll the /checkResult API endpoint until the calculation has been completed and your tax report is ready for download.

This is the base URL of the CryptoTax API:
https://api.cryptotax.io/

Authentication

The CryptoTax API is secured using JWT tokens. You must pass your individual token for each request using the HTTP header parameter Authorization.

Example:
Authorization: Bearer <token>

If you haven't requested your API token yet, please reach out to us at sales@blockpit.io for more details, or visit the Blockpit.io website.

Demo

You find a simple demo application in our GitHub repository here. It shows you how to use the CryptoTax API to create a tax report.

White Labeling

There are three options for white labeling reports created through the CryptoTax API:

only use the CryptoTax logo,
co-label the report with your own logo
only use your logo.

If you want to opt for option (2) or (3), please send us your logo image when requesting API access.

Also, please provide your address information to include on the report cover letter.

Reporting Base Currency

The tax report calculations are always based on a country's (fiat) currency.

For Austria (country code AT) the base currency must always be EUR (i.e. basket id 203).
For Belgium (country code BE) the base currency must always be EUR (i.e. basket id 203).
For Switzerland (country code CH) the base currency must always be CHF (i.e. basket id 231).
For Germany (country code DE) the base currency must always be EUR (i.e. basket id 203).
For Spain (country code ES) the base currency must always be EUR (i.e. basket id 203).
For France (country code FR) the base currency must always be EUR (i.e. basket id 203).
For the United Kingdom (country code GB) the base currency must always be GBP (i.e. basket id 205).
For the Netherlands (country code NL) the base currency must always be EUR (i.e. basket id 203).
For the USA (country code US) the base currency must always be USD (i.e. basket id 227).

For all other tax countries you can choose one of the following supported fiat currencies as a base:

Fiat currency	Basket id	Code
Swiss Franc	231	CHF
Euro	203	EUR
Pound Sterling	205	GBP
United States Dollar	227	USD

Country-specific vs. generic tax reports

The CryptoTax API supports country-specific tax reports which comply with the countries' tax legislation and are approved by a Big 4 firm. Additionally, a generic tax report can be created for all other international tax countries.

Below you can find information on the various supported deposit and withdrawal adjustment types (field adjustmentType for a transaction):

Deposit adjustment types

Deposit adjustment	AT	BE	CH	DE	ES	FR	GB	INT	NL	US
airdrop	X	X	X	X	X	X	X	X	X	X
bounties	X	X	X	X	X	X	X	X	X	X
cashback	X	X	X	X	X	X	X	X	X	X
hardfork	X	X	X	X	X	X	X	X	X	X
income	X	X	X	X	X	X	X	X	X	X
lending	X	X	X	X	X	X	X	X	X	X
linkedwithdrawal	X	X	X	X	X	X	X	X	X	X
margin_trading_profit	X	X	X	X	X	X	X	X	X	X
masternodes	X	X	X	X	X	X	X	X	X	X
mining	X	X	X	X	X	X	X	X	X	X
otcbuy	X	X	X	X	X	X	X	X	X	X
security_token_distribution	x	x	not supported	not supported	X	X	X	X	X	X
simple_deposit	X	X	X	X	X	X	X	X	X	X
staking	X	X	X	X	X	X	X	X	X	X
swap	X	X	X	X	X	X	X	X	X	X

Withdrawal adjustment types

Withdrawal adjustment	AT	BE	CH	DE	ES	FR	GB	INT	NL	US
fee	X	X	X	X	X	X	X	X	X	X
gift	X	X	X	X	X	X	X	X	X	X
lost	X	X	X	X	X	X	X	X	X	X
margin_trading_fee	X	X	X	X	X	X	X	X	X	X
margin_trading_loss	X	X	X	X	X	X	X	X	X	X
otcsell	X	X	X	X	X	X	X	X	X	X
simple_withdrawal	X	X	X	X	X	X	X	X	X	X
spending	X	X	X	X	X	X	X	X	X	X

Unrealized gains API endpoints

Load transaction data for unrealized gains calculation

This API endpoint is used to request a new unrealized gains data calculation. In addition to information on all transactions (e.g. deposits, withdrawals, trades), you specify the country for which the unrealized gains should be calculated

Request Body schema: application/json

required	Array of objects (ApiTradeDto) [ 1 .. 2147483647 ] items List of transactions
taxCountryCode required	string Enum: "AT" "BE" "CH" "DE" "ES" "FR" "GB" "INT" "NL" "US" Use the mentioned enums except for `INT` for country-specific calculations. Use `INT` for universal calculations that are based on the fiat currency specified in parameter `baseBasketId`.
	Array of objects (ApiRateRequestDto) Rates of assets, which can be used during calculation in the case when we do not have such rates (you got missing_rate error) or you want to use your own rates
baseBasketId required	integer <int32> Base basket id, only fiat is allowed

Responses

Code	Description
NOT_UNIQUE_TRANSACTION_ID	Transaction id should be unique.
NOT_FOUND_LINKED_TRANSACTION	Linked transaction was not found.
WRONG_ASSET	Unknown asset.
WRONG_BASE_BASKET_ID	Wrong base basket id for specified tax country.
WRONG_BUY_ASSET	Buy asset and amount are required or should both be null depending on transaction type.
WRONG_SELL_ASSET	Sell asset and amount are required or should both be null depending on transaction type.
WRONG_TRANSACTION_TYPE	Transaction type is wrong and cannot be applied.
WRONG_ADJUSTMENT_TYPE	Adjustment type is wrong and cannot be applied.
WRONG_ADJUSTMENT_DATA	Wrong or redundant adjustment data.
WRONG_LINKED_TRANSACTION_ADJUSTMENT_DATA	For this type of deposit linked transaction id should be null.
WRONG_HARDFORK_DATA	Some data for 'hardfork' is wrong or violates constraints.
WRONG_TRANSACTIONS_ORDER	Linked 'withdrawal' should not be later than 'deposit' in the same account.
WRONG_ASSET_DATA_IN_LINKED_TRANSACTIONS	Linked 'withdrawal' should have sellAsset the same as buyAsset in 'deposit'.
WRONG_BUY_ASSET_FOR_HARDFORK	Buy asset and hardfork asset should be different for 'hardfork'.
WRONG_FEE_DATA	Both, fee asset and fee amount should exist or be null in transaction.
MISSING_LINKED_TRANSACTION	Missing linked transaction.
MISSING_HARDFORK_ASSET_ID	Missing hardfork asset id for 'hardfork' transaction.
MISSING_HARDFORK_DATE	Missing hardfork date for 'hardfork' transaction.
REDUNDANT_DATA	For this type of deposit one and only one of linked transaction id or clarification data should be present.
RATES_CONSTRAINT_VIOLATION	Rates should contains unique items (assetId, date, transactionId).
RATE_WITH_WRONG_TRANSACTION_ID	If transactionId is provided that there is should be a transaction with that id.
TRANSACTION_SPECIFIC_RATE_WITH_WRONG_ASSET	If transactionId is provided that rate asset should be equal to buy or sell transaction asset.
WRONG_ASSET_ID	Wrong asset id in rate.

Request samples

Payload

Content type

application/json

{"trades": [{"transactionId": 0,
"accountName": "string",
"exchangeName": "string",
"tradeDate": "2015-09-13T23:29:52.123Z",
"type": "trade",
"linkedType": "transfer",
"buyAmount": 0,
"buyAssetId": 0,
"sellAmount": 0,
"sellAssetId": 0,
"feeAmount": 0,
"feeAssetId": 0,
"exchangeOrderId": "string",
"otcAmount": 0,
"hardforkAssetId": 0,
"hardforkExchangeName": "Binance",
"hardforkAccountName": "string",
"hardforkDate": "2015-09-13T23:29:52.123Z",
"linkedTransactionId": 0,
"comment": "string"
}
],
"taxCountryCode": "DE",
"rates": [{"assetId": 23,
"date": "2015-09-13",
"price": 12.05,
"transactionId": 23
}
],
"baseBasketId": 870
}

Check for finished unrealized gains calculation results

This API endpoint is used to check on the status of a started unrealized gains calculation request. If the status property of the response shows the value COMPLETED, the calculation results can be found on the data property.

query Parameters

request_id

required

string <uuid>

Request id which was fetched during tax data calculation request and should be used for fetching tax data

Responses

Response samples

200

Content type

application/json

{"requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
"status": "NEW",
"calculated": "2019-08-24T14:15:22Z",
"baseAsset": {"id": 343,
"basketId": 343,
"name": "Bitcoin",
"ticker": "BTC",
"taxConfig": {"property1": {"type": "CRYPTO"
},
"property2": {"type": "CRYPTO"
}
}
},
"data": {"unrealisedGains": [{"assetId": 0,
"accountName": "string",
"exchangeName": "string",
"holdingsAcquisitionPart": 0,
"holdingsAcquisitionDate": "2019-08-24T14:15:22Z",
"holdingsAcquisitionPrice": 0,
"salesProceed": 0,
"holdingsGains": 0,
"holdingsTaxRelevance": "string",
"transactionId": 0
}
]
},
"errors": [{ }
],
"warnings": [{ }
],
"issues": {"validationIssues": [{"errorCode": "string",
"message": "string",
"transactionId": 0
}
],
"fallbackIssues": [{"issueType": "missing_rate",
"message": "string",
"transactionId": 0,
"data": { }
}
]
}
}

Report calculation API endpoints

Load transaction data for tax calculation

This API endpoint is used to request a new tax data calculation. In addition to information on all transactions (e.g. deposits, withdrawals, trades), you specify the tax year and country for which the report should be generated, as well as the report format (e.g. PDF).

Request Body schema: application/json

required	Array of objects (ApiTradeDto) [ 1 .. 2147483647 ] items List of transactions
taxCountryCode required	string Enum: "AT" "BE" "CH" "DE" "ES" "FR" "GB" "INT" "NL" "US" Use the mentioned enums except for `INT` for country-specific tax reports. Use `INT` for universal tax reports that are based on the fiat currency specified in parameter `baseBasketId`.
	Array of objects (ApiRateRequestDto) Rates of assets, which can be used during calculation in the case when we do not have such rates (you got missing_rate error) or you want to use your own rates
taxYear required	integer <int32> >= 2013 Year for which tax data should be calculated
format	string Enum: "json" "xlsx" "pdf" Tax data format, default value json
	object (ApiReportUserDataRequestDto) Data that is used to form header for cover letter in reports. If 'null' then default value is provided.
baseBasketId required	integer <int32> Base basket id, only fiat is allowed

Responses

Code	Description
NOT_UNIQUE_TRANSACTION_ID	Transaction id should be unique.
NOT_FOUND_LINKED_TRANSACTION	Linked transaction was not found.
WRONG_ASSET	Unknown asset.
WRONG_BASE_BASKET_ID	Wrong base basket id for specified tax country.
WRONG_BUY_ASSET	Buy asset and amount are required or should both be null depending on transaction type.
WRONG_SELL_ASSET	Sell asset and amount are required or should both be null depending on transaction type.
WRONG_TRANSACTION_TYPE	Transaction type is wrong and cannot be applied.
WRONG_ADJUSTMENT_TYPE	Adjustment type is wrong and cannot be applied.
WRONG_ADJUSTMENT_DATA	Wrong or redundant adjustment data.
WRONG_LINKED_TRANSACTION_ADJUSTMENT_DATA	For this type of deposit linked transaction id should be null.
WRONG_HARDFORK_DATA	Some data for 'hardfork' is wrong or violates constraints.
WRONG_TRANSACTIONS_ORDER	Linked 'withdrawal' should not be later than 'deposit' in the same account.
WRONG_ASSET_DATA_IN_LINKED_TRANSACTIONS	Linked 'withdrawal' should have sellAsset the same as buyAsset in 'deposit'.
WRONG_BUY_ASSET_FOR_HARDFORK	Buy asset and hardfork asset should be different for 'hardfork'.
WRONG_FEE_DATA	Both, fee asset and fee amount should exist or be null in transaction.
MISSING_LINKED_TRANSACTION	Missing linked transaction.
MISSING_HARDFORK_ASSET_ID	Missing hardfork asset id for 'hardfork' transaction.
MISSING_HARDFORK_DATE	Missing hardfork date for 'hardfork' transaction.
REDUNDANT_DATA	For this type of deposit one and only one of linked transaction id or clarification data should be present.
RATES_CONSTRAINT_VIOLATION	Rates should contains unique items (assetId, date, transactionId).
RATE_WITH_WRONG_TRANSACTION_ID	If transactionId is provided that there is should be a transaction with that id.
TRANSACTION_SPECIFIC_RATE_WITH_WRONG_ASSET	If transactionId is provided that rate asset should be equal to buy or sell transaction asset.
WRONG_ASSET_ID	Wrong asset id in rate.

Request samples

Payload

Content type

application/json

{"trades": [{"transactionId": 0,
"accountName": "string",
"exchangeName": "string",
"tradeDate": "2015-09-13T23:29:52.123Z",
"type": "trade",
"linkedType": "transfer",
"buyAmount": 0,
"buyAssetId": 0,
"sellAmount": 0,
"sellAssetId": 0,
"feeAmount": 0,
"feeAssetId": 0,
"exchangeOrderId": "string",
"otcAmount": 0,
"hardforkAssetId": 0,
"hardforkExchangeName": "Binance",
"hardforkAccountName": "string",
"hardforkDate": "2015-09-13T23:29:52.123Z",
"linkedTransactionId": 0,
"comment": "string"
}
],
"taxCountryCode": "DE",
"rates": [{"assetId": 23,
"date": "2015-09-13",
"price": 12.05,
"transactionId": 23
}
],
"taxYear": 2018,
"format": "pdf",
"reportUserData": {"name": "John Doe",
"address": "Khreshchatyk str",
"addressSupplement": "apt. 10",
"postcode": "01001",
"city": "Kyiv",
"state": "Kyiv district",
"country": "Ukraine"
},
"baseBasketId": 870
}

Check for finished tax calculation results

This API endpoint is used to check on the status of a started calculation request.

Status property:

Value	Description
NEW	the request has been received
PROCESSING	the request is being processed
COMPLETED	the calculation results can be found in the `data` property
WARNING	check the `warnings` property to get the details
ERROR	the calculation is failed. Find the result in the `errors` property

Errors and warnings contain array of objects with properties type, message, and data:

	type	message	data
ERROR	missing_rate	Amount of missing rates - {}	Array of objects [1]
ERROR	linkedwithdrawal_loop	There is a loop detected in your linked withdrawal clarifications	Array of objects [2]
ERROR	missing_fork_asset	Forked asset {} is missing in account {} at provided fork date ({})	`transactionId`
WARNING	missing_asset	Number of missing assets: {}	Array of objects [3]
WARNING	empty_report	There is not any assets to calculate report	`null`

Data property [1] object for ERROR status missing_rate type:

field	type
`assetId`	`number`
`assetCode`	`string`
`date`	`string <date-time>`
`transactionIds`	`Array of numbers`

Data property [2] object for ERROR status linkedwithdrawal_loop type:

field	type
`id`	`number`
`exchangeName`	`string`
`accountName`	`string`
`date`	`string <date-time>`
`type`	`Enum: 'deposit', 'withdrawal', 'trade'`
`amount`	`number`
`asset`	`string`
`depositAdjustmentType`	`linkedwithdrawal` \ `null`

Data property [3] object for WARNING status missing_asset type:

field	type
`transactionId`	`number`
`assetId`	`number`
`assetCode`	`string`
`exchange`	`string`
`account`	`string`
`date`	`string <date-time>`
`amount`	`number`

query Parameters

request_id

required

string <uuid>

Request id which was fetched during tax data calculation request and should be used for fetching tax data

Responses

Response samples

200

Content type

application/json

{"requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
"status": "NEW",
"calculated": "2019-08-24T14:15:22Z",
"format": "json",
"taxReportUrl": "string",
"data": { },
"errors": [{ }
],
"warnings": [{ }
],
"issues": {"validationIssues": [{"errorCode": "string",
"message": "string",
"transactionId": 0
}
],
"fallbackIssues": [{"issueType": "missing_rate",
"message": "string",
"transactionId": 0,
"data": { }
}
]
}
}

Assets API endpoints

Get a paginated list of supported assets

This API endpoint gives you information on all currently available assets and their ids. You need this information when loading transaction data for tax calculation (i.e. /requestReportCalculation API endpoint).

query Parameters

offset	integer <int32> Default: 0 Optional offset of the paginated list of assets to return.
limit	integer <int32> Default: 5000 Optionally specify the number of results to return. Use this parameter and the 'offset' parameter to determine your own pagination size.

Responses

Code	Description
WRONG_LIMIT	Limit is not in allowed range.
WRONG_OFFSET	Offset should be greater than 0.

Response samples

200
400

Content type

application/json

Asset example

[{"id": 7847,
"basketId": 58485,
"name": "HT 3x Long",
"ticker": "HT3L",
"taxConfig": {"DE": {"type": "DERIVATIVE"
},
"AT": {"type": "DERIVATIVE"
},
"DEFAULT": {"type": "CRYPTO"
}
}
},
{"id": 7848,
"basketId": 7893,
"name": "ASD",
"ticker": "ASD",
"taxConfig": {"DEFAULT": {"type": "CRYPTO"
}
}
}
]

Get a paginated list of supported assets with provided tickers, sorted by ticker then by basket_id then by asset_id

This API endpoint gives you information on all currently available assets and their ids with provided tickers. You need this information when loading transaction data for tax calculation (i.e. /requestReportCalculation API endpoint).

query Parameters

tickers

required

Array of strings

Responses

Code	Description
WRONG_PARAMETERS_LIMIT	Number of provided tickers is more than 100 or not present at all.

Response samples

200
400

Content type

application/json

Asset example

[{"id": 7847,
"basketId": 58485,
"name": "HT 3x Long",
"ticker": "HT3L",
"taxConfig": {"DE": {"type": "DERIVATIVE"
},
"AT": {"type": "DERIVATIVE"
},
"DEFAULT": {"type": "CRYPTO"
}
}
},
{"id": 7848,
"basketId": 7893,
"name": "ASD",
"ticker": "ASD",
"taxConfig": {"DEFAULT": {"type": "CRYPTO"
}
}
}
]

Transaction types endpoints

Get a list of supported transaction types

This API endpoint gives you information about all currently supported transaction types.

Note that:

nonTaxableIn and nonTaxableOut will be reflected as Non-Taxable.
deposit and withdrawal will be reflected as Unlabeled.
linkedwithdrawal and withdrawal that are linked to each other will be reflected as Transfer.
Any transaction with a label of type Incoming linked to any transaction with a label of type Outgoing will also be reflected as Transfer.

Responses

Response samples

200

Content type

application/json

[{"type": "security_token_distribution",
"countrySpecificData": {"allowedCountries": ["AT"
]
}
}
]

CryptoTax API

Introduction

Creating tax report

Authentication

Demo

White Labeling

Reporting Base Currency

Country-specific vs. generic tax reports

Deposit adjustment types

Withdrawal adjustment types

Unrealized gains API endpoints

Load transaction data for unrealized gains calculation

Request Body schema: application/json

Responses

Error codes

Request samples

Check for finished unrealized gains calculation results

query Parameters

Responses

Response samples

Report calculation API endpoints

Load transaction data for tax calculation

Request Body schema: application/json

Responses

Error codes

Request samples

Check for finished tax calculation results

query Parameters

Responses

Response samples

Assets API endpoints

Get a paginated list of supported assets

query Parameters

Responses

Error codes

Response samples

Get a paginated list of supported assets with provided tickers, sorted by ticker then by basket_id then by asset_id

query Parameters

Responses

Error codes

Response samples

Transaction types endpoints

Get a list of supported transaction types

Responses

Response samples