BitcoinTaxes API

Integrate BitcoinTaxes into wallets or exchanges


BitcoinTaxes provides a REST API for wallet providers and exchanges to integrate BitcoinTaxes on behalf of their users.

The API provides the ability to view and modify transactions for each tax year so that they are included when calculating tax liabilities. A wallet or exchange will typically add a call on each successful transaction, such as a Bitcoin BUY or SELL, or buying something using a wallet.

Endpoint

https://api.bitcoin.tax/v1

All API requests should use the application/json content type when appropriate.

Authentication

Each call to the API must include the user's API Key for authorization. API keys are created from within your account. The authorization can be passed within the request header, as basic Authorization or in the query string.

Headers

All API calls must include the UserAgent header that can identify the calling application.

If passing authorization details within the header, the authorization headers should be included as follows:

X-APIKEY: <the user's API Key>
X-APISECRET: <the user's API Secret Key>

Basic Authorization

Alternatively, the api key can be passed within the standard Basic Authorization header in the format:

Authorization: Basic <API Key> + ":" + <API Secret key>)

Query String

The authorization information can also be passed as part of the query string.

?apikey=<API-Key>&apisecret=<API-Secret-Key>

API Reference

Transaction Types

Each transaction can be one of a number of types, as returned in the action field.

  • SELL - Selling crypto-currency to fiat or BTC
  • BUY - Buy crypto-currency for fiat or BTC
  • INCOME - General income
  • GIFTIN - Income received as a gift or tip
  • MINING - Income received from mining
  • SPEND - General spending of crypto-currencies
  • GIFT - Spending as a gift or tip
  • DONATION - Spending to a registered charity

List Transactions

Get a list of the user's current transactions for the current or specified tax year. Transactions are returned in date descending order, i.e. most recent first.

HTTP REQUEST
GET /transactions
PARAMETERS
Parameter Type Required Description Default
taxyear integer no tax year to return data, e.g 2015, 2014, 2013 current year
start integer no starting index for transaction 0
limit integer no maximum number of transactions to return 100
RETURNS
{
  "status": string : "success", "fail" or "error"
  "data": {
    "total": integer : total number of transactions
    "transactions": [ array of objects : array of returned transactions
      {
        "id": string : id value of transaction
        "date": string : date of transaction in ISO 8601 e.g. "2015-04-03T02:01:00+00:00"
        "action": string : type of transaction
        "exchange": string : name of Exchange or Wallet
        "exchangeid": string : Exchange or Wallet's unique reference for transaction
        "symbol": string : crypto-currency symbol, e.g. "BTC" or "LTC"
        "currency": string : fiat ISO 4217 currency code or crypto-currency symbol only "BTC", "LTC" or "XRP"
        "volume": number : volume of symbol units
        "price": number : price of symbol in currency units
        "fee": number : transaction fees
        "feecurrency": string : specific fee currency if not currency
        "memo": string : optional note value
        "txhash": string : Hash of transaction in blockchain
        "sender": string : Address of sender if known
        "recipient": string : Address of recipient if known
      }
    ]
  }
}
EXAMPLE

Get user's transactions

GET https://api.bitcoin.tax/v1/transactions
{
  "status": "success",
  "data": {
    "total": 2,
    "transactions": [
      {
        "id": "54c6c1940a9e66cc34834543",
        "date": "2015-01-26T20:46:59-08:00",
        "action": "SELL",
        "exchange": "Coinbase",
        "exchangeid": "1235",
        "symbol": "BTC",
        "currency": "USD",
        "volume": 1,
        "price": 269.42,
        "fee": 0,
        "feecurrency": "USD"
      },
      {
        "id": "54c6c1940a9e66cc947645394",
        "date": "2015-01-26T20:42:03-08:00",
        "action": "SELL",
        "exchange": "Coinbase",
        "exchangeid": "1234",
        "symbol": "BTC",
        "currency": "USD",
        "volume": 1,
        "price": 269.42,
        "fee": 0,
        "feecurrency": "USD"
      }
    ]
  }
}

Add Transaction

Add a new transaction for the current user.

HTTP REQUEST
POST /transactions
PARAMETERS

None

BODY
Parameter Type Required Description Default
date string or integer yes date of transaction in ISO 8601 or unix timestamp
action string yes type of transaction, e.g. "BUY" or "SELL"
symbol string yes crypto-currency symbol
currency string yes ISO 4217 currency symbol or "BTC", "LTC" or "XRP"
volume number yes number of units of symbol
exchange string no exchange or wallet name, e.g. "Coinbase"
exchangeid string no exchange or wallet's unique transaction id
price number no price of symbol in units of currency (if total is unknown) total/volume or average daily rate
total number no total value of transaction in currency (if price is unknown) price * volume
fee number no fee for transaction in units of currency 0
feecurrency string no currency for transaction fee currency
memo string no note for transaction
txhash string no hash value from symbol's blockchain
sender string no coin address of sender
recipient string no coin address of recipient
EXAMPLES

Add a BUY transaction

POST https://api.bitcoin.tax/v1/transactions

{
  "date": 1423033757,
  "action": "SELL",
  "exchange": "Coinbase",
  "exchangeid": "1234",
  "symbol": "BTC",
  "currency": "USD",
  "volume": 1,
  "price": 269.42
}
{
  "status": "success"
}

Add spending of $65 (0.30240194 BTC). We can either ask the user for the USD value or leave it out, where the daily price would be used. Sender address is added into the user's address list.

POST https://api.bitcoin.tax/v1/transactions

{
  "date": "2015-01-21T08:08:07+0000",
  "action": "SPEND",
  "exchange": "Mycellium",
  "exchangeid": "e34bb4e3c2b651753bb5fe22085936cd77c94238d73657d9d6f7d3f845060c3b",
  "symbol": "BTC",
  "currency": "USD",
  "volume": 0.30240194,
  "txhash": "e34bb4e3c2b651753bb5fe22085936cd77c94238d73657d9d6f7d3f845060c3b",
  "sender": "18YR4ht6APvyo633W3q2dMbKbG2eFDy6bQ",
  "recipient": "1PRT1xXacSaN9U7Pkc5vBKEX7sfcEr9HY",
  "total": 65.00
}
{
  "status": "success"
}

Add multiple transactions

POST https://api.bitcoin.tax/v1/transactions

[
  {
    "date": 1423033757,
    "action": "SELL",
    "exchange": "Coinbase",
    "exchangeid": "1234",
    "symbol": "BTC",
    "currency": "USD",
    "volume": 1,
    "price": 269.42
  },
  {
    "date": 1423033767,
    "action": "BUY",
    "exchange": "Coinbase",
    "exchangeid": "1235",
    "symbol": "BTC",
    "currency": "USD",
    "volume": 1,
    "price": 267.23
  }
]
{
  "status": "success"
}