bitcointax

README

Bitcoin.Tax REST API Client

A Client implementation for the bitcoin.tax REST API in Golang.

See GoDoc for complete documentation.

Documentation

Overview

Package bitcointax implements a Transaction type which properly Marshals and Unmarshals into the valid JSON format for the bitcoin.tax REST API, as well as a Client with methods for listing and adding Transactions.

The bitcoin.tax REST API is documented here: https://www.bitcoin.tax/api

Index

• Constants
• type Client
  • func NewClient(key, secret string) *Client
  • func (c Client) AddTransactions(txs []Transaction) error
  • func (c Client) ListTransactions(taxyear time.Time, start, limit uint64) ([]Transaction, uint64, error)
• type Transaction
  • func (t Transaction) MarshalJSON() ([]byte, error)
• type TxType

Examples

• Client.AddTransactions
• Client.ListTransactions

Constants

const (
	SellTx       TxType = "SELL"     // Selling crypto-currency to fiat or BTC
	BuyTx               = "BUY"      // Buy crypto-currency for fiat or BTC
	IncomeTx            = "INCOME"   // General income
	GiftIncomeTx        = "GIFTIN"   // Income received as a gift or tip
	MiningTx            = "MINING"   // Income received from mining
	SpendTx             = "SPEND"    // General spending of crypto-currencies
	GiftTx              = "GIFT"     // Spending as a gift or tip
	DonationTx          = "DONATION" // Spending to a registered charity
)

Valid TxTypes

Types

type Client

type Client struct {
	URL    string
	Key    string
	Secret string
	http.Client
}

Client stores API credentials and provides methods for querying the bitcoin.tax REST API. You may set any additional http.Client settings directly on this type.

func NewClient

func NewClient(key, secret string) *Client

NewClient returns a pointer to a new Client with the given key and secret and with the default API endpoint (https://api.bitcoin.tax/v1) as the URL.

func (Client) AddTransactions

func (c Client) AddTransactions(txs []Transaction) error

AddTransactions makes a POST request to the /transactions endpoint adding all Transactions in txs.

Example

package main

import (
	"fmt"
	"time"

	"github.com/canonical-ledgers/bitcointax"
)

func main() {
	key, secret := "API KEY", "API SECRET"
	c := bitcointax.NewClient(key, secret)
	txs := []bitcointax.Transaction{{
		Date:     time.Now(),
		Action:   bitcointax.IncomeTx,
		Symbol:   "FCT",
		Currency: "USD",
		Volume:   5,
		Total:    25,
	}, {
		Date:     time.Now(),
		Action:   bitcointax.IncomeTx,
		Symbol:   "FCT",
		Currency: "USD",
		Volume:   5,
		Total:    25,
	}}
	if err := c.AddTransactions(txs); err != nil {
		fmt.Printf("error: %v\n", err)
		return
	}
}

func (Client) ListTransactions

func (c Client) ListTransactions(taxyear time.Time,
	start, limit uint64) ([]Transaction, uint64, error)

ListTransactions makes a GET request to the /transactions endpoint and returns a slice of transactions for the given taxyear.Year() from the start transaction index and returning no more than limit transactions. If limit is 0 than the limit will not be specified and the API's default limit of 100 will be used.

Example

package main

import (
	"fmt"
	"time"

	"github.com/canonical-ledgers/bitcointax"
)

func main() {
	key, secret := "API KEY", "API SECRET"
	c := bitcointax.NewClient(key, secret)
	txs, total, err := c.ListTransactions(time.Now(), 0, 50)
	if err != nil {
		fmt.Printf("error: %v\n", err)
		return
	}
	fmt.Printf("Total transactions %+v\n", total)
	fmt.Printf("Transactions %+v\n", txs)
}

type Transaction

type Transaction struct {
	Date        time.Time `json:"date"`                  // Date of transaction in ISO 8601 or unix timestamp [required]
	Action      TxType    `json:"action"`                // Type of transaction, e.g. "BUY" or "SELL"         [required]
	Symbol      string    `json:"symbol"`                // Crypto-currency symbol                            [required]
	Currency    string    `json:"currency"`              // ISO 4217 currency symbol or "BTC", "LTC" or "XRP" [required]
	Volume      float64   `json:"volume"`                // Number of units of symbol                         [required]
	Exchange    string    `json:"exchange,omitempty"`    // Exchange or wallet name, e.g. "Coinbase"
	ExchangeID  string    `json:"exchangeid,omitempty"`  // Exchange or wallet's unique transaction id
	Price       float64   `json:"price,omitempty"`       // Price of symbol in units of currency (if total is unknown)   default: total/volume or average daily rate
	Total       float64   `json:"total,omitempty"`       // Total value of transaction in currency (if price is unknown) default: price * volume
	Fee         float64   `json:"fee,omitempty"`         // Fee for transaction in units of currency                     default: 0
	FeeCurrency string    `json:"feecurrency,omitempty"` // Currency for transaction fee                                 default: currency
	Memo        string    `json:"memo,omitempty"`        // Note for transaction
	TxHash      string    `json:"txhash,omitempty"`      // Hash value from symbol's blockchain
	Sender      string    `json:"sender,omitempty"`      // Coin address of sender
	Recipient   string    `json:"recipient,omitempty"`   // Coin address of recipient
	ID          string    `json:"id,omitempty"`          // Unique ID assigned internally by bitcoin.tax
}

Transaction represents the transaction JSON object sent and received by the bitcoin.tax REST API.

func (Transaction) MarshalJSON

func (t Transaction) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface such that it is compatible with what the bitcoin.tax API expects in the Transaction.Date field.

type TxType

type TxType string

TxType represents the valid types of transactions used by bitcoin.tax.