{"id":15292380,"url":"https://github.com/hunterlong/tokenbalance","last_synced_at":"2025-07-20T11:32:16.822Z","repository":{"id":44760505,"uuid":"86408270","full_name":"hunterlong/tokenbalance","owner":"hunterlong","description":"Simple Ethereum API to get your ERC20 Token Balance along with useful information","archived":false,"fork":false,"pushed_at":"2019-11-05T17:02:08.000Z","size":14853,"stargazers_count":191,"open_issues_count":15,"forks_count":59,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-05-11T13:55:54.165Z","etag":null,"topics":["cryptocurrency","erc20","ethereum","ethereum-contract","ethereum-token","geth","json-api"],"latest_commit_sha":null,"homepage":"https://tokenbalance.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hunterlong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"hunterlong","custom":["https://www.buymeacoffee.com/hunterlong"]}},"created_at":"2017-03-28T02:57:36.000Z","updated_at":"2024-08-23T21:24:24.000Z","dependencies_parsed_at":"2022-09-26T17:50:36.751Z","dependency_job_id":null,"html_url":"https://github.com/hunterlong/tokenbalance","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/hunterlong/tokenbalance","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunterlong%2Ftokenbalance","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunterlong%2Ftokenbalance/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunterlong%2Ftokenbalance/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunterlong%2Ftokenbalance/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hunterlong","download_url":"https://codeload.github.com/hunterlong/tokenbalance/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunterlong%2Ftokenbalance/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266117400,"owners_count":23879060,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cryptocurrency","erc20","ethereum","ethereum-contract","ethereum-token","geth","json-api"],"created_at":"2024-09-30T16:17:39.664Z","updated_at":"2025-07-20T11:32:16.644Z","avatar_url":"https://github.com/hunterlong.png","language":"Go","funding_links":["https://github.com/sponsors/hunterlong","https://www.buymeacoffee.com/hunterlong"],"categories":[],"sub_categories":[],"readme":"![TokenBalance](http://i.imgur.com/43Blvht.jpg)\n\n\n# TokenBalance API [![Build Status](https://travis-ci.org/hunterlong/tokenbalance.svg?branch=master)](https://travis-ci.org/hunterlong/tokenbalance) [![Docker Build Status](https://img.shields.io/docker/build/hunterlong/tokenbalance.svg)](https://hub.docker.com/r/hunterlong/tokenbalance/) [![Coverage Status](https://coveralls.io/repos/github/hunterlong/tokenbalance/badge.svg?branch=master)](https://coveralls.io/github/hunterlong/tokenbalance?branch=master) [![GoDoc](https://godoc.org/github.com/golang/gddo?status.svg)](https://godoc.org/github.com/hunterlong/tokenbalance)\nTokenBalance is an easy to use public API and application that will output your [ERC20 Token](https://github.com/ConsenSys/Tokens/blob/master/Token_Contracts/contracts/Token.sol) 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.\nConnects 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.\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://github.com/hunterlong/balancebadge\"\u003e\u003cimg src=\"https://img.balancebadge.io/eth/0x004F3E7fFA2F06EA78e14ED2B13E87d710e8013F.svg?color=green\"\u003e\u003c/a\u003e \u003ca href=\"https://github.com/hunterlong/balancebadge\"\u003e\u003cimg src=\"https://img.balancebadge.io/token/0x86fa049857e0209aa7d9e616f7eb3b3b78ecfdb0/0x3bf19a5b8b8cacda07c0ad46c18b27d999c15d0f.svg?color=purple\"\u003e\u003c/a\u003e \u003ca href=\"https://github.com/hunterlong/balancebadge\"\u003e\u003cimg src=\"https://img.balancebadge.io/token/0xd26114cd6EE289AccF82350c8d8487fedB8A0C07/0x12a99eb147af05a68ff900d8e9f55d855a41dda7.svg?color=cyan\"\u003e\u003c/a\u003e \u003ca href=\"https://github.com/hunterlong/balancebadge\"\u003e\u003cimg src=\"https://img.balancebadge.io/token/0xe41d2489571d322189246dafa5ebde1f4699f498/0xb15bb8a5c133aeb874c2b61252b7f01128574332.svg?color=red\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Server Status and Uptime\nYou 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.\n\n[https://status.tokenbalance.com](https://status.tokenbalance.com)\n\n## Installing Token Balance\nYou don't need to compile Token Balance from source anymore! All you need to do is go to [Releases](https://github.com/hunterlong/tokenbalance/releases/latest) in this repo and download the binary that is built for your OS.\nOnce 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.\n\n## Token Balance and Token Info (/token)\nTo 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.\n\n###### Ethereum Mainnet\n```bash\nhttps://api.tokenbalance.com/token/TOKEN_ADDRESS/ETH_ADDRESS\n```\n\n###### Ethereum Ropsten Testnet\n```bash\nhttps://test.tokenbalance.com/token/TOKEN_ADDRESS/ETH_ADDRESS\n```\n\n###### Ethereum Rinkeby Testnet\n```bash\nhttps://rinkeby.tokenbalance.com/token/TOKEN_ADDRESS/ETH_ADDRESS\n```\n\n- ###### Response (JSON)\n```bash\n{\n    \"name\": \"Kin\",\n    \"wallet\": \"0x393c82c7Ae55B48775f4eCcd2523450d291f2418\",\n    \"symbol\": \"KIN\",\n    \"decimals\": 18,\n    \"balance\": \"15788648\",\n    \"eth_balance\": \"0.217960852347180212\",\n    \"block\": 4274167\n}\n```\n\n## Only Token Balance (/balance)\nThis API response will only show you the ERC20 token balance in plain text. Perfect for ultra simple parsing.\n\n```bash\nhttps://api.tokenbalance.com/balance/TOKEN_ADDRESS/ETH_ADDRESS\n```\n- ###### Response (PLAIN TEXT)\n```bash\n1022.503000\n```\n\n## Examples\n\n- [jsFiddle AJAX Example](https://jsfiddle.net/hunterlong/nkqr6064/)\n- [Fetch Balance and Token Details for Status Coin](https://api.tokenbalance.com/token/0x744d70FDBE2Ba4CF95131626614a1763DF805B9E/0x242f3f8cffecc870bdb30165a0cb3c1f06f32949)\n- [Fetch Balance and Token Details for Gnosis](https://api.tokenbalance.com/token/0x6810e776880c02933d47db1b9fc05908e5386b96/0x97b47ffde901107303a53630d28105c6a7af1c3e)\n- [Fetch Balance and Token Details for Storj](https://api.tokenbalance.com/token/0xb64ef51c888972c908cfacf59b47c1afbc0ab8ac/0x29b532092fd5031b9ee1e5fe07d627abedd5eda8)\n- [Only Token Balance for Augur](https://api.tokenbalance.com/balance/0x48c80F1f4D53D5951e5D5438B54Cba84f29F32a5/0x90fbfc09db2f4b6e8b65b7a237e15bba9dc5db0c)\n- [Only Token Balance for Golem](https://api.tokenbalance.com/balance/0xa74476443119A942dE498590Fe1f2454d7D4aC0d/0xe42b94dc4b02edef833556ede32757cf2b6cc455)\n\n# Run with Docker\nYou can easily start [Token Balance with Docker](https://hub.docker.com/r/hunterlong/tokenbalance/builds/). Register for a free [Infura.io API Key](https://infura.io/signup) to use Token Balance without downloading the ethereum blockchain.\n```\ndocker run -p 8080:8080 -e GETH_SERVER=https://mainnet.infura.io/APIKEY -d hunterlong/tokenbalance\n```\n\n# Use as Golang Package\nYou can use Token Balance as a typical Go Language package if you you like to implement ERC20 functionality into your own application.\n\n```bash\ngo get github.com/hunterlong/tokenbalance\n```\n\n###### First you'll want to connect to your Geth server or IPC\n```go\nimport (\n    \"github.com/hunterlong/tokenbalance\"\n)\n\nfunc main() {\n\t// connect to your Geth Server\n    configs = \u0026tokenbalance.Config{\n         GethLocation: \"https://eth.coinapp.io\",\n         Logs:         true,\n    }\n    configs.Connect()\n\n    // insert a Token Contract address and Wallet address\n    contract := \"0x86fa049857e0209aa7d9e616f7eb3b3b78ecfdb0\"\n    wallet := \"0xbfaa1a1ea534d35199e84859975648b59880f639\"\n\n    // query the blockchain and wallet details\n    token, err := tokenbalance.New(contract, wallet)\n\n    // Token Balance will respond back useful things\n    token.BalanceString()  // \"600000.0\"\n    token.ETHString()      // \"1.020095885777777767\"\n    token.Name             // \"OmiseGO\"\n    token.Symbol           // \"OMG\"\n    token.Decimals         // 18\n    token.Balance          // big.Int() (token balance)\n    token.ETH              // big.Int() (ether balance)\n}\n```\n\n# Implement in Google Sheets\nIf 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.\n```\n=ImportData(\"https://api.tokenbalance.com/balance/0xd26114cd6EE289AccF82350c8d8487fedB8A0C07/0xf9578adc61d07671f536d50afc5800232fc9fd86\")\n```\nSimple 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!\n\n# Implement in your App\nFeel 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.\n\n# Run Your Own Server\nTokenBalance isn't just an API, it's an opensource HTTP server that you can run on your own computer or server.\n\n\u003cp align=\"center\"\u003e\u003cimg width=\"85%\" src=\"https://img.cjx.io/tokenbalanceunix.gif\"\u003e\n\u003cimg width=\"85%\" src=\"https://img.cjx.io/tokenbalancewindows.gif\"\u003e\n\u003c/p\u003e\n\n## Installation\n##### Ubuntu 16.04\n```bash\ngit clone https://github.com/hunterlong/tokenbalance\ncd tokenbalance\ngo get \u0026\u0026 go build ./cmd\n```\n\n## Start TokenBalance Server\n```bash\ntokenbalance start --geth=\"/ethereum/geth.ipc\"\n```\nThis will create a light weight HTTP server will respond balance information about a ethereum contract token.\n\n## Optional Config\n```bash\ntokenbalance start --geth=\"/ethereum/geth.ipc\" --port 8080 --ip 127.0.0.1\n```\n\n#### CURL Request\n```bash\nCONTRACT=0xa74476443119A942dE498590Fe1f2454d7D4aC0d\nETH_ADDRESS=0xda0aed568d9a2dbdcbafc1576fedc633d28eee9a\n\ncurl https://api.tokenbalance.com/token/$CONTRACT/$ETH_ADDRESS\n```\n\n#### Response\n```bash\n{\n    \"name\": \"Kin\",\n    \"wallet\": \"0x393c82c7Ae55B48775f4eCcd2523450d291f2418\",\n    \"symbol\": \"KIN\",\n    \"decimals\": 18,\n    \"balance\": \"15788648\",\n    \"eth_balance\": \"0.217960852347180212\",\n    \"block\": 4274167\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhunterlong%2Ftokenbalance","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhunterlong%2Ftokenbalance","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhunterlong%2Ftokenbalance/lists"}