bitindex

package module
v0.2.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 10, 2021 License: MIT Imports: 13 Imported by: 0

README

go-bitindex

The unofficial Go implementation for the BitIndex API


Release Build Status Report Go Sponsor Donate


Table of Contents


Installation

go-bitindex requires a supported release of Go.

go get -u github.com/mrz1836/go-bitindex

Documentation

View the generated documentation

GoDoc

You can also view the BitIndex api documentation.

Features
  • Supports >= V3 API requests
  • Client is completely configurable
  • Customize the network per request (main, test or stn)
  • Using heimdall http client with exponential backoff & more
  • Current (V3) coverage for the BitIndex API
    • Address
    • Block
    • Chain Info
    • Transaction
    • Webhooks
    • Xpub
Library Deployment

goreleaser for easy binary or library deployment to Github and can be installed via: brew install goreleaser.

The .goreleaser.yml file is used to configure goreleaser.

Use make release-snap to create a snapshot version of the release, and finally make release to ship to production.

Makefile Commands

View all makefile commands

make help

List of all current commands:

all                  Runs lint, test-short and vet
clean                Remove previous builds and any test cache data
clean-mods           Remove all the Go mod cache
coverage             Shows the test coverage
godocs               Sync the latest tag with GoDocs
help                 Show this help message
install              Install the application
install-go           Install the application (Using Native Go)
lint                 Run the golangci-lint application (install if not found)
release              Full production release (creates release in Github)
release              Runs common.release then runs godocs
release-snap         Test the full release (build binaries)
release-test         Full production test release (everything except deploy)
replace-version      Replaces the version in HTML/JS (pre-deploy)
run-examples         Runs all the examples
tag                  Generate a new tag and push (tag version=0.0.0)
tag-remove           Remove a tag if found (tag-remove version=0.0.0)
tag-update           Update an existing tag to current commit (tag-update version=0.0.0)
test                 Runs vet, lint and ALL tests
test-ci              Runs all tests via CI (exports coverage)
test-ci-no-race      Runs all tests via CI (no race) (exports coverage)
test-ci-short        Runs unit tests via CI (exports coverage)
test-short           Runs vet, lint and tests (excludes integration tests)
uninstall            Uninstall the application (and remove files)
update-linter        Update the golangci-lint package (macOS only)
vet                  Run the Go vet application

Examples & Tests

All unit tests and examples run via Github Actions and uses Go version 1.15.x. View the configuration file.

Examples & Tests by API section:

Run all tests (including integration tests)

make test

Run tests (excluding integration tests)

make test-short

Benchmarks

Run the Go benchmarks:

make bench

Code Standards

Read more about this Go project's code standards.


Usage

View the bitindex examples above

Basic implementation:

package main

import (
	"log"

	"github.com/mrz1836/go-bitindex"
)

func main() {

	// Create a new client
	client, _ := bitindex.NewClient("your-secret-api-key", bitindex.NetworkMain, nil)

	// Get balance for an address
	info, _ := client.AddressInfo("16ZqP5Tb22KJuvSAbjNkoiZs13mmRmexZA")

	// What's the balance?
	log.Println("address balance:", info.Balance)
}

Maintainers

MrZ
MrZ

Contributing

View the contributing guidelines and follow the code of conduct.

How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬. You can also support this project by becoming a sponsor on GitHub 👏 or by making a bitcoin donation to ensure this journey continues indefinitely! 🚀

Credits

@Attila & BitIndex for their hard work on the BitIndex API

Looking for a Javascript version? Check out the BitIndex JS SDK

Looking for MatterCloud? Checkout the go-mattercloud package.


License

License

Documentation

Overview

Package bitindex is the unofficial golang implementation for the bitindex API

Example:

// Create a new client client, _ := bitindex.NewClient("your-secret-api-key", bitindex.NetworkMain, nil)

// Get balance for an address info, _ := client.AddressInfo("16ZqP5Tb22KJuvSAbjNkoiZs13mmRmexZA")

// What's the balance? log.Println("address balance:", info.Balance)

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIErrorResponse 

type APIErrorResponse struct {
	Error        string   `json:"error,omitempty"`
	ErrorCode    int      `json:"code,omitempty"`
	ErrorMessage string   `json:"message,omitempty"`
	Errors       []string `json:"errors,omitempty"`
	Success      bool     `json:"success,omitempty"`
}

APIErrorResponse is from bitindex (broadcast related errors)

type APIInternalError 

type APIInternalError struct {
	Errors       []string `json:"errors,omitempty"`
	ErrorMessage string   `json:"message,omitempty"`
	ErrorName    string   `json:"name,omitempty"`
}

APIInternalError is for internal server errors (most requests)

type AddressInfo 

type AddressInfo struct {
	APIInternalError
	Address                    string   `json:"addrStr"`
	Balance                    float64  `json:"balance"`
	BalanceSatoshis            int64    `json:"balanceSat"`
	TotalReceived              float64  `json:"totalReceived"`
	TotalReceivedSatoshis      int64    `json:"totalReceivedSat"`
	TotalSent                  float64  `json:"totalSent"`
	TotalSentSatoshis          int64    `json:"totalSentSat"`
	Transactions               []string `json:"transactions"`
	TxAppearances              int64    `json:"txApperances"`
	UnconfirmedBalance         float64  `json:"unconfirmedBalance"`
	UnconfirmedBalanceSatoshis int64    `json:"unconfirmedBalanceSat"`
	UnconfirmedTxAppearances   int64    `json:"unconfirmedTxApperances"`
}

AddressInfo is the address info for a returned address request

type BlockHashByHeightResponse 

type BlockHashByHeightResponse struct {
	APIInternalError
	BlockHash string `json:"blockHash"`
}

BlockHashByHeightResponse response struct for block hash by height request

type BlockHeaderResponse 

type BlockHeaderResponse struct {
	APIInternalError
	Bits              string  `json:"bits"`
	ChainWork         string  `json:"chainwork"`
	Confirmations     int64   `json:"confirmations"`
	Difficulty        float64 `json:"difficulty"`
	Hash              string  `json:"hash"`
	Height            int64   `json:"height"`
	MedianTime        int64   `json:"mediantime"`
	MerkleRoot        string  `json:"merkleroot"`
	NextBlockHash     string  `json:"nextblockhash"`
	Nonce             int64   `json:"nonce"`
	PreviousBlockHash string  `json:"previousblockhash"`
	Time              int64   `json:"time"`
	Version           int     `json:"version"`
	VersionHex        string  `json:"versionHex"`
}

BlockHeaderResponse is the block header response

type BlockRawResponse 

type BlockRawResponse struct {
	APIInternalError
	RawBlock string `json:"rawblock"`
}

BlockRawResponse response struct for raw block request

type BlockResponse 

type BlockResponse struct {
	APIInternalError
	Bits              string   `json:"bits"`
	ChainWork         string   `json:"chainwork"`
	Confirmations     int64    `json:"confirmations"`
	Difficulty        float64  `json:"difficulty"`
	Hash              string   `json:"hash"`
	Height            int64    `json:"height"`
	MedianTime        int64    `json:"mediantime"`
	MerkleRoot        string   `json:"merkleroot"`
	NextBlockHash     string   `json:"nextblockhash"`
	Nonce             int64    `json:"nonce"`
	PreviousBlockHash string   `json:"previousblockhash"`
	Size              int64    `json:"size"`
	Time              int64    `json:"time"`
	Tx                []string `json:"tx"`
	Version           int      `json:"version"`
	VersionHex        string   `json:"versionHex"`
}

BlockResponse is the block response

type ChainBestBlockHashResponse 

type ChainBestBlockHashResponse struct {
	BestBlockHash string `json:"bestblockhash"`
}

ChainBestBlockHashResponse response struct for best block hash request

type ChainDifficultyResponse 

type ChainDifficultyResponse struct {
	Difficulty float64 `json:"difficulty"`
}

ChainDifficultyResponse response struct for chain difficulty request

type ChainInfoResponse 

type ChainInfoResponse struct {
	Info chainInfo `json:"info"`
}

ChainInfoResponse response struct for chain info request

type ChainLastBlockHashResponse 

type ChainLastBlockHashResponse struct {
	LastBlockHash string `json:"lastblockhash"`
	SyncTipHash   string `json:"syncTipHash"`
}

ChainLastBlockHashResponse response struct for last block hash request

type Client 

type Client struct {
	LastRequest *LastRequest // is the raw information from the last request
	Parameters  *Parameters  // contains application specific values
	// contains filtered or unexported fields
}

Client is the parent struct that wraps the heimdall client

func NewClient 

func NewClient(apiKey string, network NetworkType, clientOptions *Options) (c *Client, err error)

NewClient creates a new client to submit requests Parameters values are set to the defaults defined by the API documentation.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#Authentication

Example

ExampleNewClient example using NewClient() 

client, _ := NewClient("dummy-key", NetworkMain, nil)
log.Println(testAPIKey, client)
fmt.Println(client.Parameters.Network)

Output:
main

func (*Client) AddMonitoredAddresses 

func (c *Client) AddMonitoredAddresses(addAddresses *MonitoredAddresses) (addresses MonitoredAddresses, err error)

AddMonitoredAddresses this endpoint takes new addresses and adds to monitor.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#Webhook

func (*Client) AddressInfo 

func (c *Client) AddressInfo(address string) (addressInfo *AddressInfo, err error)

AddressInfo this endpoint retrieves various address info.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#Address

func (*Client) AddressUnspentTransactions 

func (c *Client) AddressUnspentTransactions(address string) (transactions UnspentTransactions, err error)

AddressUnspentTransactions this endpoint retrieves list of UTXOs.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#Address

func (*Client) ChainBestBlockHash 

func (c *Client) ChainBestBlockHash() (bestBlockHash *ChainBestBlockHashResponse, err error)

ChainBestBlockHash this endpoint retrieves the current best block hash

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#ChainInfo

func (*Client) ChainDifficulty 

func (c *Client) ChainDifficulty() (difficulty *ChainDifficultyResponse, err error)

ChainDifficulty this endpoint retrieves the current chain difficulty.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#ChainInfo

func (*Client) ChainInfo 

func (c *Client) ChainInfo() (chainInfo *ChainInfoResponse, err error)

ChainInfo this endpoint retrieves the current chain info.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#ChainInfo

func (*Client) ChainLastBlockHash 

func (c *Client) ChainLastBlockHash() (lastBlockHash *ChainLastBlockHashResponse, err error)

ChainLastBlockHash this endpoint retrieves the last block hash

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#ChainInfo

func (*Client) GetBlock 

func (c *Client) GetBlock(hash string) (block *BlockResponse, err error)

GetBlock this endpoint retrieves the block by hash.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#Block

func (*Client) GetBlockHashByHeight 

func (c *Client) GetBlockHashByHeight(height int64) (blockHash *BlockHashByHeightResponse, err error)

GetBlockHashByHeight this endpoint retrieves the block hash by height.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#Block

func (*Client) GetBlockHeader 

func (c *Client) GetBlockHeader(hash string) (blockHeader *BlockHeaderResponse, err error)

GetBlockHeader this endpoint retrieves the block header by hash.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#Block

func (*Client) GetBlockRaw 

func (c *Client) GetBlockRaw(hash string) (rawBlock *BlockRawResponse, err error)

GetBlockRaw this endpoint retrieves the raw block by hash.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#Block

func (*Client) GetMonitoredAddresses 

func (c *Client) GetMonitoredAddresses() (addresses MonitoredAddresses, err error)

GetMonitoredAddresses this endpoint retrieves all the addresses being monitored by that API key.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#Webhook

func (*Client) GetTransaction 

func (c *Client) GetTransaction(txID string) (transaction *Transaction, err error)

GetTransaction this endpoint retrieves the transaction info.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#Transactions

func (*Client) GetTransactionRaw 

func (c *Client) GetTransactionRaw(txID string) (rawTx *TransactionRaw, err error)

GetTransactionRaw this endpoint retrieves the transaction in raw format.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#Transactions

func (*Client) GetTransactions 

func (c *Client) GetTransactions(transactionRequest *GetTransactionsRequest) (response *GetTransactionsResponse, err error)

GetTransactions this endpoint retrieves list of transactions.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#Address

func (*Client) GetUnspentTransactions 

func (c *Client) GetUnspentTransactions(transactionRequest *GetUnspentTransactionsRequest) (transactions UnspentTransactions, err error)

GetUnspentTransactions this endpoint retrieves list of unspent transactions.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#Address

func (*Client) GetWebhookConfig 

func (c *Client) GetWebhookConfig() (config *WebhookConfigResponse, err error)

GetWebhookConfig this endpoint retrieves the configuration for the existing webhook.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#Webhook

func (*Client) GetXpubAddresses 

func (c *Client) GetXpubAddresses(xPub string, offset, limit int, order, filterByAddress string) (addresses XpubAddresses, err error)

GetXpubAddresses this endpoint will return addresses for an xpub given the parameters.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#Xpub

func (*Client) GetXpubBalance 

func (c *Client) GetXpubBalance(xPub string) (balance *XpubBalance, err error)

GetXpubBalance this endpoint that gets the total balance for the xpub.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#Xpub

func (*Client) GetXpubNextAddress 

func (c *Client) GetXpubNextAddress(xPub string, reserveTimeSeconds int) (addresses XpubAddresses, err error)

GetXpubNextAddress this endpoint that gets the next address for a xpub and reserve if given.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#Xpub

func (*Client) GetXpubTransactions 

func (c *Client) GetXpubTransactions(xPub string) (transactions XpubAddresses, err error)

GetXpubTransactions this endpoint that gets the the history of transactions for the xpub.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#Xpub

func (*Client) GetXpubUnspentTransactions 

func (c *Client) GetXpubUnspentTransactions(xPub, sort string) (transactions UnspentTransactions, err error)

GetXpubUnspentTransactions this endpoint retrieves list of unspent transactions for a xpub address.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#Xpub

func (*Client) Request 

func (c *Client) Request(endpoint string, method string, payload []byte) (response string, err error)

Request is a generic request wrapper that can be used without constraints

func (*Client) SendTransaction 

func (c *Client) SendTransaction(rawTx string) (response *SendTransactionResponse, err error)

SendTransaction this endpoint broadcasts a raw transaction to the network.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#Transactions

func (*Client) UpdateWebhookConfig 

func (c *Client) UpdateWebhookConfig(updateConfig *WebhookUpdateConfig) (config *WebhookConfigResponse, err error)

UpdateWebhookConfig this endpoint updates the configuration for the existing webhook.

For more information: https://www.bitindex.network/developers/api-documentation-v3.html#Webhook

type GetTransactionsRequest 

type GetTransactionsRequest struct {
	Address        string   `json:"addrs"` // single address or addr1,addr2,addr3
	Addresses      []string `json:"-"`     // (used for multiple)
	AfterBlockHash string   `json:"afterBlockHash,omitempty"`
	AfterHeight    string   `json:"afterHeight,omitempty"`
	FromIndex      int64    `json:"fromIndex,omitempty"`
	IncludeAsm     bool     `json:"includeAsm"`
	IncludeHex     bool     `json:"includeHex"`
	ToIndex        int64    `json:"toIndex,omitempty"`
}

GetTransactionsRequest is for making a POST to get transactions

type GetTransactionsResponse 

type GetTransactionsResponse struct {
	APIInternalError
	TotalItems int64         `json:"totalItems"`
	From       int64         `json:"from"`
	To         int64         `json:"to"`
	Items      []Transaction `json:"items"`
}

GetTransactionsResponse is the response from the POST request

type GetUnspentTransactionsRequest 

type GetUnspentTransactionsRequest struct {
	Address   string   `json:"addrs"` // single address or addr1,addr2,addr3
	Addresses []string `json:"-"`     // (used for multiple)
	Sort      string   `json:"sort"`  // Format is 'field:asc' such as 'value:desc' to sort by value descending
}

GetUnspentTransactionsRequest is for making the GetUnspentTransactions request

type LastRequest 

type LastRequest struct {
	Method     string `json:"method"`      // method is the HTTP method used
	PostData   string `json:"post_data"`   // postData is the post data submitted if POST/PUT request
	StatusCode int    `json:"status_code"` // statusCode is the last code from the request
	URL        string `json:"url"`         // url is the url used for the request
}

LastRequest is used to track what was submitted via the Request()

type MonitoredAddress 

type MonitoredAddress struct {
	Address string `json:"addr"`
}

MonitoredAddress is the address from get monitored addresses

type MonitoredAddresses 

type MonitoredAddresses []MonitoredAddress

MonitoredAddresses is the response from get monitored addresses

type NetworkType 

type NetworkType string

NetworkType is used internally to represent the possible values for network in queries to be submitted: {"main", "test", "stn"} 

const (

	// NetworkMain is for main-net
	NetworkMain NetworkType = "main"

	// NetworkTest is for test-net
	NetworkTest NetworkType = "test"

	// NetworkStn is for the stn-net
	NetworkStn NetworkType = "stn"
)

type Options added in v0.2.0 

type Options struct {
	BackOffExponentFactor          float64       `json:"back_off_exponent_factor"`
	BackOffInitialTimeout          time.Duration `json:"back_off_initial_timeout"`
	BackOffMaximumJitterInterval   time.Duration `json:"back_off_maximum_jitter_interval"`
	BackOffMaxTimeout              time.Duration `json:"back_off_max_timeout"`
	DialerKeepAlive                time.Duration `json:"dialer_keep_alive"`
	DialerTimeout                  time.Duration `json:"dialer_timeout"`
	RequestRetryCount              int           `json:"request_retry_count"`
	RequestTimeout                 time.Duration `json:"request_timeout"`
	TransportExpectContinueTimeout time.Duration `json:"transport_expect_continue_timeout"`
	TransportIdleTimeout           time.Duration `json:"transport_idle_timeout"`
	TransportMaxIdleConnections    int           `json:"transport_max_idle_connections"`
	TransportTLSHandshakeTimeout   time.Duration `json:"transport_tls_handshake_timeout"`
	UserAgent                      string        `json:"user_agent"`
}

Options holds all the configuration for connection, dialer and transport

func ClientDefaultOptions added in v0.2.0 

func ClientDefaultOptions() (clientOptions *Options)

ClientDefaultOptions will return an Options struct with the default settings Useful for starting with the default and then modifying as needed

type Parameters added in v0.2.0 

type Parameters struct {
	Network   NetworkType // is the BitcoinSV network to use
	UserAgent string      // (optional for changing user agents)
	// contains filtered or unexported fields
}

Parameters are application specific values for requests

type SendTransactionResponse 

type SendTransactionResponse struct {
	APIErrorResponse
	TxID string `json:"txid"`
}

SendTransactionResponse is the response for the request

type Transaction 

type Transaction struct {
	APIInternalError
	BlockHash     string       `json:"blockhash"`
	BlockHeight   int64        `json:"blockheight"`
	BlockTime     int64        `json:"blocktime"`
	Confirmations int64        `json:"confirmations"`
	Fees          float64      `json:"fees"`
	Hash          string       `json:"hash"`
	LockTime      int64        `json:"locktime"`
	RawTx         string       `json:"rawtx"`
	Size          int64        `json:"size"`
	Time          int64        `json:"time"`
	TxID          string       `json:"txid"`
	ValueIn       float64      `json:"valueIn"`
	ValueOut      float64      `json:"valueOut"`
	Version       int          `json:"version"`
	Vin           []vinObject  `json:"vin"`
	Vout          []voutObject `json:"vout"`
}

Transaction is returned in the GetTransactionsResponse

type TransactionRaw 

type TransactionRaw struct {
	APIInternalError
	RawTx string `json:"rawtx"`
}

TransactionRaw is the response for the raw tx request

type UnspentTransaction 

type UnspentTransaction struct {
	Address       string  `json:"address"`
	Amount        float64 `json:"amount"`
	Chain         int     `json:"chain"`
	Confirmations int64   `json:"confirmations"`
	Height        int64   `json:"height"`
	Num           int     `json:"num"`
	OutputIndex   int64   `json:"outputIndex"`
	Path          string  `json:"path"`
	Satoshis      int64   `json:"satoshis"`
	Script        string  `json:"script"`
	ScriptPubKey  string  `json:"scriptPubKey"`
	TxID          string  `json:"txid"`
	Value         int64   `json:"value"`
	Vout          int     `json:"vout"`
}

UnspentTransaction is a standard UTXO response Also has some fields for xpub data (chain, num, path)

type UnspentTransactions 

type UnspentTransactions []UnspentTransaction

UnspentTransactions is a list of unspent transactions

type WebhookConfigResponse 

type WebhookConfigResponse struct {
	APIInternalError
	Enabled bool   `json:"enabled"`
	ID      string `json:"id"`
	Secret  string `json:"secret"`
	URL     string `json:"url"`
}

WebhookConfigResponse is the response from get config

type WebhookUpdateConfig 

type WebhookUpdateConfig struct {
	Enabled bool   `json:"enabled"`
	Secret  string `json:"secret,omitempty"`
	URL     string `json:"url,omitempty"`
}

WebhookUpdateConfig is for updating a webhook config

type XPubAddress 

type XPubAddress struct {
	Address string `json:"address"`
	Chain   int    `json:"chain"`
	Height  int64  `json:"height"`
	Num     int    `json:"num"`
	Path    string `json:"path"`
	TxID    string `json:"txid"`
}

XPubAddress is an address returned from xpub requests

type XpubAddresses 

type XpubAddresses []XPubAddress

XpubAddresses is the list of next addresses

type XpubBalance 

type XpubBalance struct {
	APIInternalError
	Confirmed   int64 `json:"confirmed"`
	UnConfirmed int64 `json:"unconfirmed"`
}

XpubBalance is the balance returned for a xpub address

Source Files

View all Source files

Directories

Path Synopsis
Package main is an example package that uses go-bitindex
 Package main is an example package that uses go-bitindex

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.