etherscan

README

etherscan-api

中文文档

Go bindings to the Etherscan.io API, with nearly Full implementation(accounts, transactions, tokens, contracts, blocks, stats), full network support(Mainnet, Ropsten, Kovan, Rinkby, Tobalaba), and only depending on standard library. 😉

Usage

Create a API instance and off you go. 🚀

import (
	"github.com/nanmu42/etherscan-api"
	"fmt"
)

func main() {
	// create a API client for specified ethereum net
	// there are many pre-defined network in package
	client := etherscan.New(etherscan.Mainnet, "[your API key]")

	// (optional) add hooks, e.g. for rate limit
	client.BeforeRequest = func(module, action string, param map[string]interface{}) error {
		// ...
	}
	client.AfterRequest = func(module, action string, param map[string]interface{}, outcome interface{}, requestErr error) {
		// ...
	}

	// check account balance
	balance, err := client.AccountBalance("0x281055afc982d96fab65b3a49cac8b878184cb16")
	if err != nil {
		panic(err)
	}
	// balance in wei, in *big.Int type
	fmt.Println(balance.Int())

	// check token balance
	tokenBalance, err := client.TokenBalance("contractAddress", "holderAddress")

	// check ERC20 transactions from/to a specified address
	transfers, err := client.ERC20Transfers("contractAddress", "address", startBlock, endBlock, page, offset)
}

You may find full method list at GoDoc.

Etherscan API Key

You may apply for an API key on etherscan.

The Etherscan Ethereum Developer APIs are provided as a community service and without warranty, so please just use what you need and no more. They support both GET/POST requests and a rate limit of 5 requests/sec (exceed and you will be blocked).

Paperwork Things

I am not from Etherscan and I just find their service really useful, so I implement this. 😄

License

Use of this work is governed by a MIT License.

You may find a license copy in project root.

Documentation

Overview

Package etherscan provides Go bindings to the Etherscan.io API.

This work is a nearly Full implementation (accounts, transactions, tokens, contracts, blocks, stats), with full network support(Mainnet, Ropsten, Kovan, Rinkby, Tobalaba), and only depending on standard library.

Example can be found at https://github.com/nanmu42/etherscan-api

Index

• Variables
• type AccountBalance
• type BigInt
  • func (b *BigInt) Int() *big.Int
  • func (b *BigInt) MarshalText() (text []byte, err error)
  • func (b *BigInt) UnmarshalText(text []byte) (err error)
• type BlockRewards
• type Client
  • func New(network Network, APIKey string) *Client
  • func (c *Client) AccountBalance(address string) (balance *BigInt, err error)
  • func (c *Client) BlockReward(blockNum int) (rewards BlockRewards, err error)
  • func (c *Client) BlocksMinedByAddress(address string, page int, offset int) (mined []MinedBlock, err error)
  • func (c *Client) ContractABI(address string) (abi string, err error)
  • func (c *Client) ContractSource(address string) (source []ContractSource, err error)
  • func (c *Client) ERC20Transfers(contractAddress, address *string, startBlock *int, endBlock *int, page int, ...) (txs []ERC20Transfer, err error)
  • func (c *Client) EtherLatestPrice() (price LatestPrice, err error)
  • func (c *Client) EtherTotalSupply() (totalSupply *BigInt, err error)
  • func (c *Client) ExecutionStatus(txHash string) (status ExecutionStatus, err error)
  • func (c *Client) InternalTxByAddress(address string, startBlock *int, endBlock *int, page int, offset int, ...) (txs []InternalTx, err error)
  • func (c *Client) MultiAccountBalance(addresses ...string) (balances []AccountBalance, err error)
  • func (c *Client) NormalTxByAddress(address string, startBlock *int, endBlock *int, page int, offset int, ...) (txs []NormalTx, err error)
  • func (c *Client) ReceiptStatus(txHash string) (receiptStatus int, err error)
  • func (c *Client) TokenBalance(contractAddress, address string) (balance *BigInt, err error)
  • func (c *Client) TokenTotalSupply(contractAddress string) (totalSupply *BigInt, err error)
  • func (c *Client) UnclesMinedByAddress(address string, page int, offset int) (mined []MinedBlock, err error)
• type ContractSource
• type ERC20Transfer
• type Envelope
• type ExecutionStatus
• type InternalTx
• type LatestPrice
• type M
• type MinedBlock
• type Network
  • func (n Network) SubDomain() (sub string)
• type NormalTx
• type Time
  • func (t Time) MarshalText() (text []byte, err error)
  • func (t Time) Time() time.Time
  • func (t *Time) UnmarshalText(text []byte) (err error)

Variables

var ErrPreByzantiumTx = errors.New("pre-byzantium transaction does not support receipt status check")

ErrPreByzantiumTx transaction before 4,370,000 does not support receipt status check

Types

type AccountBalance

type AccountBalance struct {
	Account string  `json:"account"`
	Balance *BigInt `json:"balance"`
}

AccountBalance account and its balance in pair

type BigInt

type BigInt big.Int

BigInt is a wrapper over big.Int to implement only unmarshalText for json decoding.

func (*BigInt) Int

func (b *BigInt) Int() *big.Int

Int returns b's *big.Int form

func (*BigInt) MarshalText

func (b *BigInt) MarshalText() (text []byte, err error)

MarshalText implements the encoding.TextMarshaler

func (*BigInt) UnmarshalText

func (b *BigInt) UnmarshalText(text []byte) (err error)

UnmarshalText implements the encoding.TextUnmarshaler interface.

type BlockRewards

type BlockRewards struct {
	BlockNumber int     `json:"blockNumber,string"`
	TimeStamp   Time    `json:"timeStamp"`
	BlockMiner  string  `json:"blockMiner"`
	BlockReward *BigInt `json:"blockReward"`
	Uncles      []struct {
		Miner         string  `json:"miner"`
		UnclePosition int     `json:"unclePosition,string"`
		BlockReward   *BigInt `json:"blockreward"`
	} `json:"uncles"`
	UncleInclusionReward *BigInt `json:"uncleInclusionReward"`
}

BlockRewards holds info from query for block and uncle rewards

type Client

type Client struct {

	// Verbose when true, talks a lot
	Verbose bool

	// BeforeRequest runs before every client request, in the same goroutine.
	// May be used in rate limit.
	// Request will be aborted, if BeforeRequest returns non-nil err.
	BeforeRequest func(module, action string, param map[string]interface{}) error

	// AfterRequest runs after every client request, even when there is an error.
	AfterRequest func(module, action string, param map[string]interface{}, outcome interface{}, requestErr error)
	// contains filtered or unexported fields
}

Client etherscan API client Clients are safe for concurrent use by multiple goroutines.

func New

func New(network Network, APIKey string) *Client

New initialize a new etherscan API client please use pre-defined network value

func (*Client) AccountBalance

func (c *Client) AccountBalance(address string) (balance *BigInt, err error)

AccountBalance gets ether balance for a single address

func (*Client) BlockReward

func (c *Client) BlockReward(blockNum int) (rewards BlockRewards, err error)

BlockReward gets block and uncle rewards by block number

func (*Client) BlocksMinedByAddress

func (c *Client) BlocksMinedByAddress(address string, page int, offset int) (mined []MinedBlock, err error)

BlocksMinedByAddress gets list of blocks mined by address

func (*Client) ContractABI

func (c *Client) ContractABI(address string) (abi string, err error)

ContractABI gets contract abi for verified contract source codes

func (*Client) ContractSource

func (c *Client) ContractSource(address string) (source []ContractSource, err error)

ContractSource gets contract source code for verified contract source codes

func (*Client) ERC20Transfers

func (c *Client) ERC20Transfers(contractAddress, address *string, startBlock *int, endBlock *int, page int, offset int, desc bool) (txs []ERC20Transfer, err error)

ERC20Transfers get a list of "erc20 - token transfer events" by contract address and/or from/to address.

leave undesired condition to nil.

Note on a Etherscan bug: Some ERC20 contract does not have valid decimals information in Etherscan. When that happens, TokenName, TokenSymbol are empty strings, and TokenDecimal is 0.

More information can be found at: https://github.com/nanmu42/etherscan-api/issues/8

func (*Client) EtherLatestPrice

func (c *Client) EtherLatestPrice() (price LatestPrice, err error)

EtherLatestPrice gets the latest ether price, in BTC and USD

func (*Client) EtherTotalSupply

func (c *Client) EtherTotalSupply() (totalSupply *BigInt, err error)

EtherTotalSupply gets total supply of ether

func (*Client) ExecutionStatus

func (c *Client) ExecutionStatus(txHash string) (status ExecutionStatus, err error)

ExecutionStatus checks contract execution status (if there was an error during contract execution)

note on IsError: 0 = pass, 1 = error

func (*Client) InternalTxByAddress

func (c *Client) InternalTxByAddress(address string, startBlock *int, endBlock *int, page int, offset int, desc bool) (txs []InternalTx, err error)

InternalTxByAddress gets a list of "internal" transactions by address

startBlock and endBlock can be nil

if desc is true, result will be sorted in descendant order.

func (*Client) MultiAccountBalance

func (c *Client) MultiAccountBalance(addresses ...string) (balances []AccountBalance, err error)

MultiAccountBalance gets ether balance for multiple addresses in a single call

func (*Client) NormalTxByAddress

func (c *Client) NormalTxByAddress(address string, startBlock *int, endBlock *int, page int, offset int, desc bool) (txs []NormalTx, err error)

NormalTxByAddress gets a list of "normal" transactions by address

startBlock and endBlock can be nil

if desc is true, result will be sorted in blockNum descendant order.

func (*Client) ReceiptStatus

func (c *Client) ReceiptStatus(txHash string) (receiptStatus int, err error)

ReceiptStatus checks transaction receipt status

only applicable for post byzantium fork transactions, i.e. after block 4,370,000

An special err ErrPreByzantiumTx raises for the transaction before byzantium fork.

Note: receiptStatus: 0 = Fail, 1 = Pass.

func (*Client) TokenBalance

func (c *Client) TokenBalance(contractAddress, address string) (balance *BigInt, err error)

TokenBalance get erc20-token account balance of address for contractAddress

func (*Client) TokenTotalSupply

func (c *Client) TokenTotalSupply(contractAddress string) (totalSupply *BigInt, err error)

TokenTotalSupply gets total supply of token on specified contract address

func (*Client) UnclesMinedByAddress

func (c *Client) UnclesMinedByAddress(address string, page int, offset int) (mined []MinedBlock, err error)

UnclesMinedByAddress gets list of uncles mined by address

type ContractSource

type ContractSource struct {
	SourceCode           string `json:"SourceCode"`
	ABI                  string `json:"ABI"`
	ContractName         string `json:"ContractName"`
	CompilerVersion      string `json:"CompilerVersion"`
	OptimizationUsed     int    `json:"OptimizationUsed,string"`
	Runs                 int    `json:"Runs,string"`
	ConstructorArguments string `json:"ConstructorArguments"`
	Library              string `json:"Library"`
	SwarmSource          string `json:"SwarmSource"`
}

ContractSource holds info from query for contract source code

type ERC20Transfer

type ERC20Transfer struct {
	BlockNumber       int     `json:"blockNumber,string"`
	TimeStamp         Time    `json:"timeStamp"`
	Hash              string  `json:"hash"`
	Nonce             int     `json:"nonce,string"`
	BlockHash         string  `json:"blockHash"`
	From              string  `json:"from"`
	ContractAddress   string  `json:"contractAddress"`
	To                string  `json:"to"`
	Value             *BigInt `json:"value"`
	TokenName         string  `json:"tokenName"`
	TokenSymbol       string  `json:"tokenSymbol"`
	TokenDecimal      uint8   `json:"tokenDecimal,string"`
	TransactionIndex  int     `json:"transactionIndex,string"`
	Gas               int     `json:"gas,string"`
	GasPrice          *BigInt `json:"gasPrice"`
	GasUsed           int     `json:"gasUsed,string"`
	CumulativeGasUsed int     `json:"cumulativeGasUsed,string"`
	Input             string  `json:"input"`
	Confirmations     int     `json:"confirmations,string"`
}

ERC20Transfer holds info from ERC20 token transfer event query

type Envelope

type Envelope struct {
	// 1 for good, 0 for error
	Status int `json:"status,string"`
	// OK for good, other words when Status equals 0
	Message string `json:"message"`
	// where response lies
	Result json.RawMessage `json:"result"`
}

Envelope is the carrier of nearly every response

type ExecutionStatus

type ExecutionStatus struct {
	// 0 = pass, 1 = error
	IsError        int    `json:"isError,string"`
	ErrDescription string `json:"errDescription"`
}

ExecutionStatus holds info from query for transaction execution status

type InternalTx

type InternalTx struct {
	BlockNumber     int     `json:"blockNumber,string"`
	TimeStamp       Time    `json:"timeStamp"`
	Hash            string  `json:"hash"`
	From            string  `json:"from"`
	To              string  `json:"to"`
	Value           *BigInt `json:"value"`
	ContractAddress string  `json:"contractAddress"`
	Input           string  `json:"input"`
	Type            string  `json:"type"`
	Gas             int     `json:"gas,string"`
	GasUsed         int     `json:"gasUsed,string"`
	TraceID         string  `json:"traceId"`
	IsError         int     `json:"isError,string"`
	ErrCode         string  `json:"errCode"`
}

InternalTx holds info from internal tx query

type LatestPrice

type LatestPrice struct {
	ETHBTC          float64 `json:"ethbtc,string"`
	ETHBTCTimestamp Time    `json:"ethbtc_timestamp"`
	ETHUSD          float64 `json:"ethusd,string"`
	ETHUSDTimestamp Time    `json:"ethusd_timestamp"`
}

LatestPrice holds info from query for latest ether price

type M

type M map[string]interface{}

M is a type shorthand for param input

type MinedBlock

type MinedBlock struct {
	BlockNumber int     `json:"blockNumber,string"`
	TimeStamp   Time    `json:"timeStamp"`
	BlockReward *BigInt `json:"blockReward"`
}

MinedBlock holds info from query for mined block by address

type Network

type Network string

Network is ethereum network type (mainnet, ropsten, etc)

const (

	// Mainnet Ethereum mainnet for production
	Mainnet Network = "api"
	// Ropsten Testnet(POW)
	Ropsten Network = "api-ropsten"
	// Kovan Testnet(POA)
	Kovan Network = "api-kovan"
	// Rinkby Testnet(CLIQUE)
	Rinkby Network = "api-rinkeby"
	// Tobalaba Testnet
	Tobalaba Network = "api-tobalaba"
)

func (Network) SubDomain

func (n Network) SubDomain() (sub string)

SubDomain returns the subdomain of etherscan API via n provided.

type NormalTx

type NormalTx struct {
	BlockNumber       int     `json:"blockNumber,string"`
	TimeStamp         Time    `json:"timeStamp"`
	Hash              string  `json:"hash"`
	Nonce             int     `json:"nonce,string"`
	BlockHash         string  `json:"blockHash"`
	TransactionIndex  int     `json:"transactionIndex,string"`
	From              string  `json:"from"`
	To                string  `json:"to"`
	Value             *BigInt `json:"value"`
	Gas               int     `json:"gas,string"`
	GasPrice          *BigInt `json:"gasPrice"`
	IsError           int     `json:"isError,string"`
	TxReceiptStatus   string  `json:"txreceipt_status"`
	Input             string  `json:"input"`
	ContractAddress   string  `json:"contractAddress"`
	CumulativeGasUsed int     `json:"cumulativeGasUsed,string"`
	GasUsed           int     `json:"gasUsed,string"`
	Confirmations     int     `json:"confirmations,string"`
}

NormalTx holds info from normal tx query

type Time

type Time time.Time

Time is a wrapper over big.Int to implement only unmarshalText for json decoding.

func (Time) MarshalText

func (t Time) MarshalText() (text []byte, err error)

MarshalText implements the encoding.TextMarshaler

func (Time) Time

func (t Time) Time() time.Time

Time returns t's time.Time form

func (*Time) UnmarshalText

func (t *Time) UnmarshalText(text []byte) (err error)

UnmarshalText implements the encoding.TextUnmarshaler interface.