etherscan

package module
v1.0.3 Latest Latest
Warning

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

 Go to latest Published: Sep 24, 2018 License: MIT Imports: 12 Imported by: 0

README

etherscan-api

Build Status Go Report Card codecov GoDoc 中文文档

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

Constants

This section is empty.

Variables

View Source 
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

Functions

This section is empty.

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) (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.

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.

Source Files

View all Source files

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.