tokenbalance

README

TokenBalance API

TokenBalance is an easy to use public API and application that will output your ERC20 Token balance without any troubles. You can run TokenBalance on your local computer or you can use api.tokenbalance.com to easily parse your erc20 token balances. Connects to your local geth IPC and prints out a simple JSON response for ethereum token balances. Runs on port 8080 by default if you wish to run locally.

Server Status and Uptime

You can view the current status of Token Balance along with API latency information on our status page. This status page logs the Ethereum Mainnet, Ropsten testnet, and Rinkeby testnet.

https://status.tokenbalance.com

Installing Token Balance

You don't need to compile Token Balance from source anymore! All you need to do is go to Releases in this repo and download the binary that is built for your OS. Once you've downloaded, rename the file to tokenbalance for ease if use. On Mac or Linux move this file with the command mv tokenbalance /usr/local/bin/tokenbalance, you should be able to run the application from anywhere now.

Token Balance and Token Info (/token)

To fetch information about your balance, token details, and ETH balance use the follow API call in a simple HTTP GET or CURL. The response is in JSON so you can easily parse what you need. Replace TOKEN_ADDRESS with the contract address of the ERC20 token, and replace ETH_ADDRESS with your address.

Ethereum Mainnet

https://api.tokenbalance.com/token/TOKEN_ADDRESS/ETH_ADDRESS

Ethereum Ropsten Testnet

https://test.tokenbalance.com/token/TOKEN_ADDRESS/ETH_ADDRESS

Ethereum Rinkeby Testnet

https://rinkeby.tokenbalance.com/token/TOKEN_ADDRESS/ETH_ADDRESS

• Response (JSON)

{
    "name": "Kin",
    "wallet": "0x393c82c7Ae55B48775f4eCcd2523450d291f2418",
    "symbol": "KIN",
    "decimals": 18,
    "balance": "15788648",
    "eth_balance": "0.217960852347180212",
    "block": 4274167
}

Only Token Balance (/balance)

This API response will only show you the ERC20 token balance in plain text. Perfect for ultra simple parsing.

https://api.tokenbalance.com/balance/TOKEN_ADDRESS/ETH_ADDRESS

• Response (PLAIN TEXT)

1022.503000

Examples

• jsFiddle AJAX Example
• Fetch Balance and Token Details for Status Coin
• Fetch Balance and Token Details for Gnosis
• Fetch Balance and Token Details for Storj
• Only Token Balance for Augur
• Only Token Balance for Golem

Run with Docker

You can easily start Token Balance with Docker. Register for a free Infura.io API Key to use Token Balance without downloading the ethereum blockchain.

docker run -p 8080:8080 -e GETH_SERVER=https://mainnet.infura.io/APIKEY -d hunterlong/tokenbalance

Use as Golang Package

You can use Token Balance as a typical Go Language package if you you like to implement ERC20 functionality into your own application.

go get github.com/mobazha/tokenbalance

First you'll want to connect to your Geth server or IPC

import (
    "github.com/mobazha/tokenbalance"
)

func main() {
	// connect to your Geth Server
    configs = &tokenbalance.Config{
         GethLocation: "https://eth.coinapp.io",
         Logs:         true,
    }
    configs.Connect()

    // insert a Token Contract address and Wallet address
    contract := "0x86fa049857e0209aa7d9e616f7eb3b3b78ecfdb0"
    wallet := "0xbfaa1a1ea534d35199e84859975648b59880f639"

    // query the blockchain and wallet details
    token, err := tokenbalance.New(contract, wallet)

    // Token Balance will respond back useful things
    token.BalanceString()  // "600000.0"
    token.ETHString()      // "1.020095885777777767"
    token.Name             // "OmiseGO"
    token.Symbol           // "OMG"
    token.Decimals         // 18
    token.Balance          // big.Int() (token balance)
    token.ETH              // big.Int() (ether balance)
}

Implement in Google Sheets

If your familiar with Google Sheets, you can easily fetch all of your cryptocurrency balances within 1 spreadsheet. All you need to do is make a cell with the value below.

=ImportData("https://api.tokenbalance.com/balance/0xd26114cd6EE289AccF82350c8d8487fedB8A0C07/0xf9578adc61d07671f536d50afc5800232fc9fd86")

Simple as that! Get creative an use Coin Market Cap's API to fetch the price and multiply with your balance to make a portfolio of your cryptocurrencies!

Implement in your App

Feel free to use the TokenBalance API server to fetch ERC20 token balances and details. We do have a header set that will allow you to call the API via AJAX. Access-Control-Allow-Origin "*" The server may limit your requests if you do more than 60 hits per minute.

Run Your Own Server

TokenBalance isn't just an API, it's an opensource HTTP server that you can run on your own computer or server.

Installation

Ubuntu 16.04

git clone https://github.com/mobazha/tokenbalance
cd tokenbalance
go get && go build ./cmd

Start TokenBalance Server

tokenbalance start --geth="/ethereum/geth.ipc"

This will create a light weight HTTP server will respond balance information about a ethereum contract token.

Optional Config

tokenbalance start --geth="/ethereum/geth.ipc" --port 8080 --ip 127.0.0.1

CURL Request

CONTRACT=0xa74476443119A942dE498590Fe1f2454d7D4aC0d
ETH_ADDRESS=0xda0aed568d9a2dbdcbafc1576fedc633d28eee9a

curl https://api.tokenbalance.com/token/$CONTRACT/$ETH_ADDRESS

Response

{
    "name": "Kin",
    "wallet": "0x393c82c7Ae55B48775f4eCcd2523450d291f2418",
    "symbol": "KIN",
    "decimals": 18,
    "balance": "15788648",
    "eth_balance": "0.217960852347180212",
    "block": 4274167
}

Documentation

Overview

Package tokenbalance is used to fetch the latest token balance for any Ethereum address and ERC20 token. You can install this package/CLI or you can use basic HTTP GET on the public TokenBalance server.

Mainnet API Endpoint: https://api.tokenbalance.com

Example: https://api.tokenbalance.com/balance/0xa74476443119A942dE498590Fe1f2454d7D4aC0d/0xda0aed568d9a2dbdcbafc1576fedc633d28eee9a Response: `5401731.086778292432427406`

Example: https://api.tokenbalance.com/token/0xa74476443119A942dE498590Fe1f2454d7D4aC0d/0xda0aed568d9a2dbdcbafc1576fedc633d28eee9a Response: ``` { "token": "0xa74476443119A942dE498590Fe1f2454d7D4aC0d", "wallet": "0xda0AEd568D9A2dbDcBAFC1576fedc633d28EEE9a", "name": "Golem Network token", "symbol": "GNT", "balance": "5401731.086778292432427406", "eth_balance": "0.985735366999999973", "decimals": 18, "block": 6461672 } ```

Ropsten Testnet API Endpoint: https://test.tokenbalance.com

Rinkeby Testnet API Endpoint: https://rinkeby.tokenbalance.com

More info on: https://github.com/mobazha/tokenbalance

Index

• Variables
• type Config
  • func (c *Config) Connect() error
• type TokenBalance
  • func New(contract, wallet string) (*TokenBalance, error)
  • func (tb *TokenBalance) BalanceString() string
  • func (tb *TokenBalance) ETHString() string
  • func (tb *TokenBalance) ToJSON() string

Examples

• New
• TokenBalance.BalanceString
• TokenBalance.ETHString
• TokenBalance.ToJSON

Variables

var (
	Geth *ethclient.Client

	VERSION string
)

Types

type Config

type Config struct {
	GethLocation string
	Logs         bool
}

func (*Config) Connect

func (c *Config) Connect() error

type TokenBalance

type TokenBalance struct {
	Contract common.Address
	Wallet   common.Address
	Name     string
	Symbol   string
	Balance  *big.Int
	ETH      *big.Int
	Decimals int64
	Block    int64
	// contains filtered or unexported fields
}

func New

func New(contract, wallet string) (*TokenBalance, error)

Example

Create a New Token Balance request with the ERC20 contract address and a wallet address

token := "0xb64ef51c888972c908cfacf59b47c1afbc0ab8ac"
wallet := "0x9ea0c535b3eb166454c8ccbaba86850c8df3ee57"
example, _ = New(token, wallet)
fmt.Printf("This wallet has %v %v tokens", example.BalanceString(), example.Name)

Output:

This wallet has 7.282 StorjToken tokens

func (*TokenBalance) BalanceString

func (tb *TokenBalance) BalanceString() string

Example

Return the Token Balance as a string rather than a *big.Int

tokens := example.BalanceString()
fmt.Printf("This wallet has %v %v tokens", tokens, example.Name)

Output:

This wallet has 7.282 StorjToken tokens

func (*TokenBalance) ETHString

func (tb *TokenBalance) ETHString() string

Example

Return the ETH Balance as a string rather than a *big.Int

eth := example.ETHString()
fmt.Printf("This wallet has %v ETH", eth)

Output:

This wallet has 0.277525175999999985 ETH

func (*TokenBalance) ToJSON

func (tb *TokenBalance) ToJSON() string

Example

View all token information as JSON

data := example.ToJSON()
fmt.Println(data)