etherscan

package module
v1.10.0 Latest Latest
Warning

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

 Go to latest Published: Dec 14, 2022 License: MIT Imports: 13 Imported by: 26

README

English | 中文

etherscan-api

GoDoc CI status codecov Go Report Card

Golang client for the Etherscan.io API(and its families like BscScan), with nearly full implementation(accounts, transactions, tokens, contracts, blocks, stats), full network support(Mainnet, Ropsten, Kovan, Rinkby, Goerli, Tobalaba), and only depending on standard library. 😉

Usage

go get github.com/nanmu42/etherscan-api

Create an 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]")
	
	// or, if you are working with etherscan-family API like BscScan
	//
	// client := etherscan.NewCustomized(etherscan.Customization{
	// Timeout:       15 * time.Second,
	// Key:           "You key here",
	// BaseURL:       "https://api.bscscan.com/api?",
	// Verbose:       false,
	// })

	// (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 an 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 NewCustomized added in v1.2.0 

func NewCustomized(config Customization) *Client

NewCustomized initialize a customized API client, useful when calling against etherscan-family API like BscScan.

func (*Client) AccountBalance 

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

AccountBalance gets ether balance for a single address

func (*Client) BlockNumber added in v1.5.0 

func (c *Client) BlockNumber(timestamp int64, closest string) (blockNumber int, err error)

BlockNumber gets the closest block number by UNIX timestamp

valid closest option: before, after

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) ERC1155Transfers added in v1.10.0 

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

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

leave undesired condition to nil.

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) ERC721Transfers added in v1.6.0 

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

ERC721Transfers get a list of "erc721 - 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) GasEstimate added in v1.9.0 

func (c *Client) GasEstimate(gasPrice int) (confirmationTimeInSec time.Duration, err error)

GasEstiamte gets estiamted confirmation time (in seconds) at the given gas price

func (*Client) GasOracle added in v1.9.0 

func (c *Client) GasOracle() (gasPrices GasPrices, err error)

GasOracle gets suggested gas prices (in Gwei)

func (*Client) GetLogs added in v1.7.0 

func (c *Client) GetLogs(fromBlock, toBlock int, address, topic string) (logs []Log, err error)

GetLogs gets logs that match "topic" emitted by the specified "address" between the "fromBlock" and "toBlock"

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"`
	EVMVersion           string `json:"EVMVersion"`
	Library              string `json:"Library"`
	LicenseType          string `json:"LicenseType"`
	Proxy                string `json:"Proxy"`
	Implementation       string `json:"Implementation"`
	SwarmSource          string `json:"SwarmSource"`
}

ContractSource holds info from query for contract source code

type Customization added in v1.2.0 

type Customization struct {
	// Timeout for API call
	Timeout time.Duration
	// API key applied from Etherscan
	Key string
	// Base URL like `https://api.etherscan.io/api?`
	BaseURL string
	// When true, talks a lot
	Verbose bool
	// HTTP Client to be used. Specifying this value will ignore the Timeout value set
	// Set your own timeout.
	Client *http.Client

	// 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)
}

Customization is used in NewCustomized()

type ERC1155Transfer added in v1.10.0 

type ERC1155Transfer 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"`
	TokenID           *BigInt `json:"tokenID"`
	TokenName         string  `json:"tokenName"`
	TokenSymbol       string  `json:"tokenSymbol"`
	TokenDecimal      uint8   `json:"tokenDecimal,string"`
	TokenValue        uint8   `json:"tokenValue,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"`
}

ERC1155Transfer holds info from ERC1155 token transfer event query

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 ERC721Transfer added in v1.6.0 

type ERC721Transfer 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"`
	TokenID           *BigInt `json:"tokenID"`
	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"`
}

ERC721Transfer holds info from ERC721 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 GasPrices added in v1.9.0 

type GasPrices struct {
	LastBlock            int
	SafeGasPrice         float64
	ProposeGasPrice      float64
	FastGasPrice         float64
	SuggestBaseFeeInGwei float64   `json:"suggestBaseFee"`
	GasUsedRatio         []float64 `json:"gasUsedRatio"`
}

GasPrices holds info for Gas Oracle queries Gas Prices are returned in Gwei

func (*GasPrices) UnmarshalJSON added in v1.9.0 

func (gp *GasPrices) UnmarshalJSON(data []byte) error

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 Log added in v1.7.0 

type Log struct {
	Address         string   `json:"address"`
	Topics          []string `json:"topics"`
	Data            string   `json:"data"`
	BlockNumber     string   `json:"blockNumber"`
	TransactionHash string   `json:"transactionHash"`
	BlockHash       string   `json:"blockHash"`
	LogIndex        string   `json:"logIndex"`
	Removed         bool     `json:"removed"`
}

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"
	// Goerli Testnet(CLIQUE)
	Goerli Network = "api-goerli"
	// 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.