Introduction

Welcome to the Bitcoin.Tax API (version 3).

You can use our API to access Bitcoin.tax endpoints, which can add transaction information, calculate capital gains and download reports.

You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Host

The server host used in this documentation will be shown as api.bitcoin.tax, however, development and test servers have different host names and you should check you are accessing the correct one.

The current development server is:

coins31.bitcoin.tax

The version of the API must be prefixed before any paths, which is /api.v3. A request would be:

https://coins31.bitcoin.tax/api.v3/<path>

The current API definition can also be viewed online directly at

https://coins31.bitcoin.tax/ui

Clients and Types

An example client referencing and calling the API using types:

<script type="module">
import { JsonApiClient } from 'https://unpkg.com/@servicestack/client@2/dist/servicestack-client.min.mjs'
import { Hello } from 'https://api.bitcoin.tax/types/mjs'

const client = JsonApiClient.create()

const api = client.api(new Hello({ name:'World' }))
if (api.succeeded) {
    console.log(api.response)
}
</script>

The API can be called in two ways:

using a standard URL with GETs and POSTs, e.g. GET https://api.bitcoin.tax/api.v3/transactions?count=10
using the client module with typed requests, e.g. const txs = jsonclient.get(new GetTransactions({count:10}))

Javascript based clients should use the servicestack cli that is setup to use the DTO types definied in the system.

A Typescript client can be retrieved from https://api.bitcoin.tax/js/servicestack-client.mjs and then imported

import { JsonApiClient } from '/js/servicestack-client.mjs'

For more information on usign TypeScript, review the ServiceStack TypeSCript documentation

Javascript clients should use the servicestack client module that is setup to use the DTO types definied in the system. this can be retrived from the ServiceStack CDN or by installing locally.

import { JsonApiClient } from 'https://unpkg.com/@servicestack/client@2/dist/servicestack-client.min.mjs'

or, install and reference the client module

import { JsonApiClient } from '@servicestack/client

For more information on usign the javascript client, review the ServiceStack Javascript documentation

Strongly typed DTOs can be retrieved for the current API host or stored locally.

import { JsonApiClient } from 'https://coins31.bitcoin.tax/types/mjs'

or, download the DTO file and reference

import { JsonApiClient } from 'types/mjs

An example ES3 client referencing and calling the API

<script src="https://api.bitcoin.tax/js/require.js"></script>
<script src="https://api.bitcoin.tax/js/servicestack-client.js"></script>
<script src="https://api.bitcoin.tax/types/js"></script>
<script>
var { JsonServiceClient, Hello } = exports

var client = new JsonServiceClient('https://api.bitcoin.tax')
client.get(new Hello({ name }))
        .then(function(r) {
                console.log(r.result)
        })
</script>

ES3 clients can use references to the UMD @servicestack/client

<script src='https://api.bitcoin.tax/js/require.js"></script>
<script src='https://api.bitcoin.tax/js/servicestack-client.js"></script>
<script src='https://api.bitcoin.tax/types/js"></script>

Pagination

Some requests and responses can be paginated, returning transactions for example, and all of these accept and return some common properties.

All paging request will accept start, count and sort parameters that allow the client to step through the returned data.

Request	Type	Description
start	integer	The index of the first item to return, defaults of 0
count	integer	Number of items to return, defaults to null. 0 will return all items.
sort	string	Requested comma, or pipe, seperated sorting fields. A preceeding '-' means descending, e.g. "date,-type"

Response	Type	Description
total	integer	Total number of items in the result set
start	integer	The index of the first item returned
count	integer	Number of items requested
sort	string	The sorted fields

Error Responses

Most error responses will return soft errors, where the return code is 200 but the reponse will include a responseStatus object. The presence of a responseStatus object indicates an error in the operation.

The ErrorResponse object has an errorCode with a shortform uppercase code for the error and a message that can be displayed to the user.

All successful responses will have this form:

    {
        _v: "3.1.x.x."
    }

All error responses will have this form:

    {
        responseStatus: {
          errorCode: "string",
            message: "string",
            stackTrace: "string",
            errors: [ResponseError]
        },

        _v: "3.1.x.x"
    }

Authentication

Authentication is be done by initially passing an email and password pair.

A successful authentication request will return session identifier cookies that should be included in all subsequent API calls. Cookies are marked as HttpOnly and Secure, so cannot be retrieved or manipulated within the client code.

Stateless Bearer Tokens

A session can be immediately converted to a stateless bearer token, which can be passed using the Authorization header.

Authorisation: Bearer <Token>

Convert the current session to use a bearer token

import { JsonApiClient, ConvertSessionToToken } from '@servicestack/client'
import { Signin } from './coins31.mjs'
const client = JsonApiClient.create('https://api.bitcoin.tax')
const response = await client.api(new Signin({
  username:"[email protected]",
  password:"mypassword"
}))
client.send(new ConvertSessionToToken());
const token = client.GetTokenCookie();

To convert a session to a Bearer token,

Authenticate

Authenticate with email and password

import { JsonApiClient, Inspect } from '@servicestack/client'
import { Signin } from './coins31.mjs'
const client = JsonApiClient.create('https://api.bitcoin.tax')
const response = await client.api(new Signin({
  username:"[email protected]",
  password:"mypassword"
}))

The above command returns JSON structured like this:

[
  {
    "user": {
          "id": 1,
            "email": "[email protected]",
            "displayname": "My Name",
            "country": "US",
            "currency": "USD",
            "language": "en-US",
            "timezone": "America/Los_Angeles"
        }
  }
]

This endpoint authenticates the credentials and returns session and token information and set cookies for further API calls.

HTTP Request

POST /signin

Parameters

Parameter	Required	Type	Description
username	yes	string	Email address or username
password	yes	string	Provided password
provider	yes	string	Provider for authorisation,
twofa	no	string	2FA code if necessary

Response

Property	Type	Description
user	object	user object

Create a new user

import { JsonApiClient, Inspect } from '@servicestack/client'
import { Signup } from './coins31.mjs'
const client = JsonApiClient.create('https://api.bitcoin.tax')
const response = await client.api(new Signup({
  username:"[email protected]",
  password:"mypassword"
}))

The above command returns JSON structured like this:

[
  {
    "user": {
          "id": 1,
            "email": "[email protected]",
            "displayname": "My Name",
            "country": "US",
            "currency": "USD",
            "language": "en-US",
            "timezone": "America/Los_Angeles"
        }
  }
]

This endpoint creates a new user with the provided credentials and returns their authenticated session and token information and set cookies for further API calls.

HTTP Request

POST /signup

Parameters

Parameter	Required	Type	Description
email	yes	string	Email address or username
password	yes	string	Provided password
displayname	no	string	Name of displaying
country	no	string	Two-letter country code, e.g. US
currency	no	string	Three-letter currency code, e.g. USD
language	no	string	Two-letter (with extension) language, e.g. en-US
timezone	no	string	Timezone identifier, e.g. America/Los_Angeles
costmethod	no	string	Preferred cost method overriding country default, e.g. FIFO
taxyearday	no	integer	day of month that taxyear starts, overriding country default, e.g. 1
taxyearmonth	no	integer	month that taxyear starts, overriding country default, e.g. 1
recaptcharesponse	no	string	Client side recaptcha code

Response

Property	Type	Description
user	object	user object

Logout

import { JsonApiClient, Inspect } from '@servicestack/client'
import { Signout } from './coins31.mjs'
const client = JsonApiClient.create('https://api.bitcoin.tax')
const response = await client.api(new Signout())

This endpoint signs the user out and destroys their authentication tokens.

HTTP Request

POST /signout

Parameters

none

Get the current user

import { JsonApiClient, Inspect } from '@servicestack/client'
import { Signup } from './coins31.mjs'
const client = JsonApiClient.create('https://api.bitcoin.tax')
const response = await client.api(new CurrentUser({
}))

The above command returns JSON structured like this:

[
  {
    "user": {
          "id": 1,
            "email": "[email protected]",
            "displayname": "My Name",
            "country": "US",
            "currency": "USD",
            "language": "en-US",
            "timezone": "America/Los_Angeles"
        }
  }
]

This endpoint get the current user object if they are logged in.

HTTP Request

POST /user

Parameters

Parameter	Required	Type	Description

none

Response

Property	Type	Description
user	object	user object

Update a user

import { JsonApiClient, Inspect } from '@servicestack/client'
import { Signup } from './coins31.mjs'
const client = JsonApiClient.create('https://api.bitcoin.tax')
const response = await client.api(new UpdateCurrentUser({
  email:"[email protected]",
  displayname:"My Name"
}))

The above command returns JSON structured like this:

[
  {
    "user": {
          "id": 1,
            "email": "[email protected]",
            "displayname": "My Name",
            "country": "US",
            "currency": "USD",
            "language": "en-US",
            "timezone": "America/Los_Angeles"
        }
  }
]

This endpoint updates the current user with new properties.

HTTP Request

POST /user

Parameters

Parameter	Required	Type	Description
email	no	string	Email address or username
displayname	no	string	Name of displaying
country	no	string	Two-letter country code, e.g. US
currency	no	string	Three-letter currency code, e.g. USD
language	no	string	Two-letter (with extension) language, e.g. en-US
timezone	no	string	Timezone identifier, e.g. America/Los_Angeles
costmethod	no	string	Preferred cost method overriding country default, e.g. FIFO
taxyearday	no	integer	day of month that taxyear starts, overriding country default, e.g. 1
taxyearmonth	no	integer	month that taxyear starts, overriding country default, e.g. 1
newpassword	no	string	New password - must also provide existingpassword
existingpassword	no	string	User's existing password to update certain information, such as password

Any existing and non-null properties will be updated overwriting the existing values, so you can just update the timezone for example, using {"timezone":"America/Los_Angeles"}

Response

Property	Type	Description
user	object	user object

Reset the user's password

import { JsonApiClient, Inspect } from '@servicestack/client'
import { Signup } from './coins31.mjs'
const client = JsonApiClient.create('https://api.bitcoin.tax')
const response = await client.api(new ResetPassword({
  email:"[email protected]"
}))

The above command returns JSON structured like this:

[
  {
    "token": "abcdefg123456"
  }
]

This endpoint initiates or continues a password reset.

HTTP Request

POST /reset

Parameters

Parameter	Required	Type	Description
email	no	string	Email address of user
user	no	string	Base url to provide for email
token	no	string	Provided token from link
password	no	string	New password
recaptcharesponse	no	string	Client side recaptcha code

Response

Property	Type	Description

none

Resetting a password is initiated with a call passing the "email" and "url" properties. If the user exists they will receive an email containing a link to enter their new password. This link is a combination of the "url" property and "?token=[resettoken]", e.g. you would provide {"url":"https://bitcoin.tax/reset"} and the link in the email will be https://bitcoin.tax/reset?token=abc123

When a token is provided you can call the API again passing in "token" and the new "password". If the token is vaid and and the password is suitable, a non-error will return indicating successs.

Accounts

Get All Accounts

import { JsonApiClient } from '@servicestack/client'
import { GetAccounts } from './dtos'

const client = JsonApiClient.create('https://api.bitcoin.tax')
const response = await client.api(new GetAccounts({count:10}))

The above command returns JSON structured like this:

{
  "accounts": [
        {
            "id": 3,
            "name": "Account 1",
            "exchange": "COINBASE",
            "created": "2022-01-01T12:00:00.0000000Z",
            "lastUpdated": "2022-01-01T12:00:00.0000000Z",
            "apiKey": "someapikeyvalue"
        }
    ],
    "total":1000,
    "start":0,
    "count":10,
    "sort":"name"
}

This endpoint retrieves all accounts for a user, but can be filtered by a partial name.

This endpoint is paginated.

HTTP Request

GET /accounts

Query Parameters

Parameter	Type	Required	Description
name	string	false	Filter accounts that contain this partial name

Response

Property	Type	Description
accounts	array	List of account objects

Get a Specific Account

import { JsonApiClient } from '@servicestack/client'
import { GetAccount } from './dtos'

const client = JsonApiClient.create('https://api.bitcoin.tax')
const response = await client.api(new GetAccount({id:1}))

The request returns JSON structured like this:

{
  "account":
    {
        "id": 3,
        "name": "Account 1",
        "exchange": "COINBASE",
        "created": "2022-01-01T12:00:00.0000000Z",
        "lastUpdated": "2022-01-01T12:00:00.0000000Z",
        "apiKey": "someapikeyvalue"
    }
}

This endpoint retrieves a specific account.

This will return ResponseStatus object with the code of NOTFOUND if the account does not exist.

HTTP Request

GET /accounts/<id>

Request Parameters

Parameter	Description
Id	The id of the account to retrieve

Response

Property	Type	Description
account	object	A account object

Create an Account

import { JsonApiClient } from '@servicestack/client'
import { CreateAccount } from './dtos'

const client = JsonApiClient.create('https://api.bitcoin.tax')
const response = await client.api(new CreateAccount({
 // ....
}))

The request returns JSON structured like this:

{
  "account":
    {
        "id": 3,
        "name": "Account 1",
        "exchange": "COINBASE",
        "created": "2022-01-01T12:00:00.0000000Z",
        "lastUpdated": "2022-01-01T12:00:00.0000000Z",
        "apiKey": "someapikeyvalue"
    }
}

This endpoint creates a new account.

HTTP Request

POST /accounts

Request Parameters

Parameter	Type	Required	Description
name	string	yes	Name of new account, which must be unique to the user
exchange	string	no	Identifier for associated exchange or wallet, e.g. COINBASE
apikey	string	no	External API key for for associated exchange
apisecret	string	no	External API secret for for associated exchange

Response

Property	Type	Description
account	object	The new account object

Update an Account

import { JsonApiClient } from '@servicestack/client'
import { UpdateAccount } from './dtos'

const client = JsonApiClient.create('https://api.bitcoin.tax')
const response = await client.api(new UpdateAccount({
  id: 1,
  // ....
}))

The request returns:

{
  "account":
    {
        "id": 3,
        "name": "Account 1",
        "exchange": "COINBASE",
        "created": "2022-01-01T12:00:00.0000000Z",
        "lastUpdated": "2022-01-01T12:00:00.0000000Z",
        "apiKey": "someapikeyvalue"
    }
}

This endpoint updated an existing account.

HTTP Request

POST /accounts/<id>

Request Parameters

Parameter	Type	Required	Description
id	integer	yes	Id of the account
name	string	no	Name of account, which must be unique to the user
exchange	string	no	Identifier for associated exchange or wallet, e.g. COINBASE
apikey	string	no	External API key for for associated exchange
apisecret	string	no	External API secret for for associated exchange

Only provided properties will update the account values.

Response

Property	Type	Description
account	object	Updated account object

Delete a Specific Account

import { JsonApiClient } from '@servicestack/client'
import { DeleteAccount } from './dtos'

const client = JsonApiClient.create('https://api.bitcoin.tax')
const response = await client.api(new DeleteAccount({id:1}))

This endpoint deletes a specific account.

HTTP Request

DELETE /accounts/<id>

URL Parameters

Parameter	Description
id	The id of the account to delete

Transactions

Get All Transactions

import { JsonApiClient } from '@servicestack/client'
import { GetTransactions } from './dtos'

const client = JsonApiClient.create('https://api.bitcoin.tax')
const response = await client.api(new GetTransactions({count:10}))

The above command returns JSON structured like this:

{
  "transactions": [
        {
            "id": 3,
            "userId": 2,
            "accountId": 1,
            "date": "2022-01-01T12:00:00.0000000Z",
            "batchId": "64fa152a7871bd8a7caf3628",
            "taxyear": 2022,
            "category": "EXCHANGE",
            "action": "SELL",
            "volume": 1.23456,
            "symbol": "BTC:1858",
            "total": 20000,
            "currency": "USD:156",
            "price": 16200,
            "fee": 20,
            "feeCurrency": "USD:156"
        }
    ],
    "total":1000,
    "start":0,
    "count":10,
    "sort":"date"
}

This endpoint retrieves all transactions for all accounts, but can be filtered by account, taxyear, symbol, and type.

This endpoint is paginated.

HTTP Request

GET /transactions

Query Parameters

Parameter	Type	Required	Description
accountId	integer	false	Filter transaction for only this account
taxyear	integer	false	Filter transactions to this taxyear, e.g. 2022
startdate	string	false	Filter transactions for those on or after this date
enddate	string	false	Filter transactions for those before this date
action	string	false	Filter transactions to only this action (or type), e.g. SELL
currency	string	false	Filter transactions to only those that use this currency, e.g. BTC

startdate and enddate should be in ISO8661 format, i.e. "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS". You do not have to include timezone information, as it will be treated in the timezeone defined by the user, but it can be added if needed, e.g. "2022-01-01T12:34:56+0800".

Response

Property	Type	Description
transactions	array	List of transaction objects

Get a Specific Transaction

import { JsonApiClient } from '@servicestack/client'
import { GetTransaction } from './dtos'

const client = JsonApiClient.create('https://api.bitcoin.tax')
const response = await client.api(new GetTransaction({id:1}))

The request returns JSON structured like this:

{
  "transaction":
    {
        "id": 1,
        "userId": 1,
        "accountId": 1,
        "date": "2022-01-01T12:00:00.0000000Z",
        "batchId": "64fa152a7871bd8a7caf3628",
        "taxyear": 2022,
        "category": "EXCHANGE",
        "action": "SELL",
        "volume": 1.23456,
        "symbol": "BTC:1858",
        "total": 20000,
        "currency": "USD:156",
        "price": 16200,
        "fee": 20,
        "feeCurrency": "USD:156",
        "ledgers": [
            {
                "date": "2022-01-01T12:00:00.0000000Z",
                "amount": -1.23456,
                "currency": "BTC:1858"
            },
            {
                "date": "2022-01-01T12:00:00.0000000Z",
                "amount": 20000,
                "currency": "USD:156"
            }
        ]       
    },
}

This endpoint retrieves a specific transaction.

This will return ResponseStatus object with the code of NOTFOUND if the transaction does not exist.

HTTP Request

GET /transactions/<id>

Request Parameters

Parameter	Description
Id	The id of the transaction to retrieve

Response

Property	Type	Description
transaction	object	A transaction object

Create a Transaction

import { JsonApiClient } from '@servicestack/client'
import { CreateTransaction } from './dtos'

const client = JsonApiClient.create('https://api.bitcoin.tax')
const response = await client.api(new CreateTransaction({
 // ....
}))

The request returns JSON structured like this:

{
  "transaction":
    {
        "id": 1,
        "userId": 1,
        "accountId": 1,
        "date": "2022-01-01T12:00:00.0000000Z",
        "batchId": "64fa152a7871bd8a7caf3628",
        "taxyear": 2022,
        "category": "EXCHANGE",
        "action": "SELL",
        "volume": 1.23456,
        "symbol": "BTC:1858",
        "total": 20000,
        "currency": "USD:156",
        "price": 16200,
        "fee": 20,
        "feeCurrency": "USD:156",
        "ledgers": [
            {
                "date": "2022-01-01T12:00:00.0000000Z",
                "amount": -1.23456,
                "currency": "BTC:1858"
            },
            {
                "date": "2022-01-01T12:00:00.0000000Z",
                "amount": 20000,
                "currency": "USD:156"
            }
        ]       
    },
}

This endpoint creates a new transaction.

HTTP Request

POST /transactions

Request Parameters

Parameter	Type	Required	Description
date	string	yes	ISO 8661 date
action	string	yes	Type of transaction, e.g. BUY, SELL, INCOME, etc
volume	number	yes	Amount of base currency, this is always a positive number
symbol	string	yes	Currency representation of base currency e.g. "BTC:100" or "XYZ"
symbolValue	number	no	Value of the base currency in user's currency (only symbolValue or symbolPrice should be used)
symbolPrice	number	no	Price of the base currency in user's currency
total	number	no	Amount of quote currency, this is always a positive number
currency	string	no	Currency representation of quote currency e.g. "USD:1" or "XYZ"
currencyValue	number	no	Value of the quote currency in user's currency (only currencyValue or currencyPrice should be used)
currencyPrice	number	no	Price of the quote currency in user's currency
price	number	no	Rate between quote currency and base currency if total not provided
fee	number	no	Amount of fee paid for transaction
feecurrency	string	no	Currency representation of fee currency e.g. "BTC:100" or "XYZ"
feeCurrencyValue	number	no	Value of the fee currency in user's currency
feeCurrencyPrice	number	no	Price of the fee currency in user's currency
note	string	no	User provided note
ref	string	no	Exchange or wallet transaction reference, this should be unique per account
txhash	string	no	Blockchain hash values for transaction
sender	string	no	Blockchain address of sender
recipient	string	no	Blockchain address of recipient
accountid	integer	no	The id of an account
accountname	string	no	Name of an existing or new account
ledgers	array	no	List of transaction ledgers to support multiple sub-transactions

If an accountId is not provided, then the account will be found by the accountname. If accountname is not one of the user's accounts, a new account will be created. If accountname is not provided, a "General" account will be used or created.

Response

Property	Type	Description
transaction	object	The new transaction object

Update a Transaction

import { JsonApiClient } from '@servicestack/client'
import { UpdateTransaction } from './dtos'

const client = JsonApiClient.create('https://api.bitcoin.tax')
const response = await client.api(new UpdateTransaction({
  id: 1,
  // ....
}))

The request returns:

{
  "transaction":
    {
        "id": 1,
        "userId": 1,
        "accountId": 1,
        "date": "2022-01-01T12:00:00.0000000Z",
        "batchId": "64fa152a7871bd8a7caf3628",
        "taxyear": 2022,
        "category": "EXCHANGE",
        "action": "SELL",
        "volume": 1.23456,
        "symbol": "BTC:1858",
        "total": 20000,
        "currency": "USD:156",
        "price": 16200,
        "fee": 20,
        "feeCurrency": "USD:156",
        "ledgers": [
            {
                "date": "2022-01-01T12:00:00.0000000Z",
                "amount": -1.23456,
                "currency": "BTC:1858"
            },
            {
                "date": "2022-01-01T12:00:00.0000000Z",
                "amount": 20000,
                "currency": "USD:156"
            }
        ]       
    },
}

This endpoint updated an existing transaction.

HTTP Request

POST /transactions/<id>

Request Parameters

Parameter	Type	Required	Description
id	integer	yes	Id of the transaction
accountid	integer	no	Move this transaction to another account with this id
accountname	string	no	Move this transaction to another account with this name, or create a new account with this name
date	string	no	ISO 8661 date
action	string	no	Type of transaction, e.g. BUY, SELL, INCOME, etc
volume	number	no	Amount of base currency, this is always a positive number
symbol	string	no	Currency representation of base currency e.g. "BTC:100" or "XYZ"
symbolValue	number	no	Value of the base currency in user's currency (only symbolValue or symbolPrice should be used)
symbolPrice	number	no	Price of the base currency in user's currency
total	number	no	Amount of quote currency, this is always a positive number
currency	string	no	Currency representation of quote currency e.g. "USD:1" or "XYZ"
currencyValue	number	no	Value of the quote currency in user's currency (only currencyValue or currencyPrice should be used)
currencyPrice	number	no	Price of the quote currency in user's currency
price	number	no	Rate between quote currency and base currency if total not provided
fee	number	no	Amount of fee paid for transaction
feecurrency	string	no	Currency representation of fee currency e.g. "BTC:100" or "XYZ"
feeCurrencyValue	number	no	Value of the fee currency in user's currency
feeCurrencyPrice	number	no	Price of the fee currency in user's currency
note	string	no	User provided note
ref	string	no	Exchange or wallet transaction reference, this should be unique per account
txhash	string	no	Blockchain hash values for transaction
sender	string	no	Blockchain address of sender
recipient	string	no	Blockchain address of recipient
ledgers	array	no	List of transaction ledgers to support multiple sub-transactions

Only provided properties will update the transaction values.

Response

Property	Type	Description
transaction	object	Updated transaction object

Delete a single Transaction

import { JsonApiClient } from '@servicestack/client'
import { DeleteTransaction } from './dtos'

const client = JsonApiClient.create('https://api.bitcoin.tax')
const response = await client.api(new DeleteTransaction({id:1}))

This endpoint deletes a specific transaction.

HTTP Request

DELETE /transactions/<id>

URL Parameters

Parameter	Description
id	The id of the transaction to delete

Delete multiple Transactions

import { JsonApiClient } from '@servicestack/client'
import { DeleteAllTransactions } from './dtos'

const client = JsonApiClient.create('https://api.bitcoin.tax')
const response = await client.api(new DeleteAllTransactions({accountid:1}))

This endpoint deletes multiple transactions using filters.

HTTP Request

DELETE /transactions

URL Parameters

Parameter	Type	Required	Description
ids	array	no	An array of transaction ids to delete, e.g. [1,2,3,4]
accountid	integer	no	Delete all transactions for this account id
taxyear	integer	no	Delete all transactions for this taxyear, e.g. 2022
startdate	string	no	Delete all transactions from this date, e.g. "2022-01-01T00:00:00"
enddate	string	no	Delete all transactions before this date, e.g. "2022-01-01T00:00:00"
action	string	no	Delete all transactions with this action, e.g. "BUY"
currency	string	no	Delete all transactions using this currency (in either symbol, currency or feecurrency), e.g. "BTC:1234"

Note: dates will be considered to be in the user's timezone unless a timezone is provided

Response

Property	Type	Description
deleted	integer	number of transactions that were deleted
task	object	A task object could be returned instead for this operation

Note: if the system determines this operation could take a long time, it will return a task instead of the deleted property

Import Transactions from a CSV

import { JsonApiClient } from '@servicestack/client'
import { ImportTransactions } from './dtos'

const client = JsonApiClient.create('https://api.bitcoin.tax')
const response = await client.api(new ImportTransactions({
 // ....
}))

The request returns JSON structured like this:

{
  "task":
    {
        "id": 1,
        "created": "2023-01-01T12:34:56Z",
        "type": "ImportTransactions",
        "status": "New",
    },
}

This endpoint imports one or more CSV files. The format of the CSV can be determined by the exchange property, otherwise will default to our standard CSV format.

HTTP Request

POST /transactions/import

Request Parameters

Parameter	Type	Required	Description
file	file	yes	one or more files POSTed to the request
accountid	integer	no	The id of an existing account
accountname	string	no	Name of an existing or new account
taxyear	integer	no	Only import transactions within this taxyear
exchange	string	no	CSV format for this exchange
clear	boolean	no	Clear all transactions for account(s) before import

Response

Property	Type	Description
task	object	The task object created for thgis import

Object Definitions

User

Property	Type	Description
id	integer	Id of user
email	string	Email address
displayname	string	Name of displaying
country	string	Two-letter country code, e.g. US
currency	string	Three-letter currency code, e.g. USD
language	string	Two-letter (with extension) language, e.g. en-US
timezone	string	Timezone identifier, e.g. America/Los_Angeles

Account

Property	Type	Description
id	integer	Id of account
name	string	name, unique to user
exchange	string	Identified for Exchange or Wallet
created	date	ISO8661 date when account was created
lastUpdated	date	ISO8661 date when account was last updated
apikey	string	External API key for exchange

Transaction

Property	Type	Description
id	integer	Id of the transaction
userid	integer	Id of the owning user
accountid	integer	Id of the owning account
date	string	ISO 8661 date
batchid	string	identifier for batch in which transaction was added
taxyear	int	Taxyer for transaction date, e.g. 2022
action	string	Type of tranasction, e.g. BUY, SELL, INCOME, etc
volume	number	Amount of base currency, this is always a positive number
symbol	string	Currency representation of base currency e.g. "BTC:100" or "XYZ"
total	number	Amount of quote currency, this is always a positive number
currency	string	Currency representation of quote currency e.g. "USD:1" or "XYZ"
price	number	Rate between quote currency and base currency
fee	number	Amount of fee paid for transaction
feecurrency	string	Currency representation of fee currency e.g. "BTC:100" or "XYZ"
note	string	User provided note
ref	string	Exchange or wallet transaction reference, this should be unique per account
txhash	string	Blockchain hash values for transaction
sender	string	Blockchain address of sender
recipient	string	Blockchain address of recipient
ledgers	array	List of TransactionLedger objects showing amount deltas

Transaction Ledger

Property	Type	Description
date	string	ISO 8661 date
amount	number	Amount of base currency, positive for incoming and negative for outgoing
currency	string	Currency representation e.g. "BTC:100" or "XYZ"
nativeamount	number	Amount of user's native currency
nativecurrency	string	User's native currency representation e.g. "USD:1"
sender	string	Blockchain address of sender
recipient	string	Blockchain address of recipient

Task

Property	Type	Description
id	integer	Id of task
created	string	Datetime when task was created
expires	string	Datetime when task will expire if not completed
scheduled	string	Datetime when task will run if not immediately
retry	integer	Number of times task has been retried
name	string	User friendly name for task
tasktype	string	Type of task action
isunique	boolean	If task is unique, i.e. only one of this type can exist per user
metadata	object	Extra task information
status	integer	Status of task: 0-new , 1=running, 2=finished, 3=error, 4=cancelling, 5=cancelled
started	string	Datetime when task was started
ended	string	Datetime when task finished or errored
percent	integer	Percentage value of task completion
error	string	Message if task failed with an error
result	string	Success message or JSON string of task result

Errors

The API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid
403	Forbidden -- Your Authorization credentials are invalid
404	Not Found -- The specified resource could not be found
405	Method Not Allowed -- You tried to access an API with an invalid method
406	Not Acceptable -- You requested a format that isn't json.
429	Too Many Requests -- Too many API calss within a window
500	Internal Server Error -- a server error
503	Service Unavailable -- temporarily offline for maintenance, try again later