{"id":13651654,"url":"https://github.com/cc32d9/eosio_light_api","last_synced_at":"2025-04-22T22:31:42.893Z","repository":{"id":33452210,"uuid":"151824543","full_name":"cc32d9/eosio_light_api","owner":"cc32d9","description":"Light API for EOSIO networks","archived":false,"fork":false,"pushed_at":"2023-12-01T13:06:59.000Z","size":226,"stargazers_count":51,"open_issues_count":9,"forks_count":22,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-01-24T04:13:42.381Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cc32d9.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-10-06T09:25:33.000Z","updated_at":"2023-11-02T14:49:30.000Z","dependencies_parsed_at":"2024-01-03T05:13:43.393Z","dependency_job_id":"a1c43230-3bb9-41cc-9715-6c6aec613ffe","html_url":"https://github.com/cc32d9/eosio_light_api","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cc32d9%2Feosio_light_api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cc32d9%2Feosio_light_api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cc32d9%2Feosio_light_api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cc32d9%2Feosio_light_api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cc32d9","download_url":"https://codeload.github.com/cc32d9/eosio_light_api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250333985,"owners_count":21413487,"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":[],"created_at":"2024-08-02T02:00:51.269Z","updated_at":"2025-04-22T22:31:42.879Z","avatar_url":"https://github.com/cc32d9.png","language":"Perl","funding_links":[],"categories":["Developers"],"sub_categories":["Libraries and Frameworks"],"readme":"# EOSIO Light API\n\nThe API is providing information about EOSIO blockchain accounts and\ntoken balances. It is deployed for several blockchains, such as EOS,\nTelos, BOS, WAX, and Europechain. Also an endpoints for a number of\ntestnets are available.\n\n## HTTP API\n\nIn below examples, \"CHAIN\" stands for the name of the network where API is\ntaking the data (such as `eos`, `telos`, `wax` etc.).\n\n* `http://apihost.domain/api/networks` lists all known networks and\n  their information.\n\n* Retrieve all token balances, resources and authorization information\n for an account: `http://apihost.domain/api/account/CHAIN/ACCOUNT`\n\n* Retrieve only token balances for an account:\n  `http://apihost.domain/api/balances/CHAIN/ACCOUNT`\n\n* Retrieve all account information except token balances:\n  `http://apihost.domain/api/accinfo/CHAIN/ACCOUNT`\n\n* Retrieve REX balances (fund, maturing, matured) for an account:\n  `http://apihost.domain/api/rexbalance/CHAIN/ACCOUNT`\n\n* Retrieve raw REX information for an account (to perform calculations\n  on the client side):\n  `http://apihost.domain/api/rexraw/CHAIN/ACCOUNT`\n\n* Retrieve all accounts in all known EOSIO networks dependent on a\n public key (only up to 100 accounts are returned), including accounts\n with recursive permissions: `http://apihost.domain/api/key/KEY`\n\n* `http://apihost.domain/api/tokenbalance/CHAIN/ACCOUNT/CONTRACT/TOKEN`\n  returns a plain text with numeric output indicating the token\n  balance. Zero is returned if the token is not present or does not\n  exist.\n\n* `http://apihost.domain/api/topholders/CHAIN/CONTRACT/TOKEN/NUM` returns\n  top NUM holders of a specified token in a JSON array containing arrays\n  of (account, amount) pairs. NUM must not be less than 10 or more than\n  1000.\n\n* `http://apihost.domain/api/holdercount/CHAIN/CONTRACT/TOKEN` returns the\n  total count of token holders as plain text. The result is \"0\" if the\n  token does not exist.\n\n* `http://apihost.domain/api/usercount/CHAIN`\n  returns a plain text with total number of accounts in the network.\n\n* `http://apihost.domain/api/topram/CHAIN/NUM` returns top NUM RAM buyers\n  in a JSON array containing arrays of (account, bytes) pairs. NUM must\n  not be less than 10 or more than 1000.\n\n* `http://apihost.domain/api/topstake/CHAIN/NUM` returns top NUM stake\n  holders by sum of CPU and Net stakes, in a JSON array containing\n  arrays of (account, cpu_weight, net_weight) tuples. NUM must not be\n  less than 10 or more than 1000.\n\n* `http://apihost.domain/api/codehash/SHA256` retrieves all accounts in\n  all known networks by contract hash.\n\n* `http://apihost.domain/api/sync/CHAIN` returns a plain text with delay\n  in seconds that this server's blockchain database is behind the real\n  time, and a status: OK if the delay is within 180 seconds, or\n  'OUT_OF_SYNC' otherwise.\n\n* `http://apihost.domain/api/status` returns a plain text with either\n  'OK' or 'OUT_OF_SYNC' indicating the overall health of the API\n  host. If any of networks experience delay higher than 3 minutes, the\n  returned status is 'OUT_OF_SYNC', and HTTP status code is 503.\n\n\nIn addition, adding `?pretty=1` to the URL, you get the resulting JSON\nsorted and formatted for human viewing.\n\n## Websocket API\n\nWebsocket API is complimentary to HTTP API and is designed for bulk\nrequests. All communication is compliant with [JSON-RPC version\n2.0](https://www.jsonrpc.org/specification).\n\nThe client is expected to close the websoclet connection after it\nfinishes using it. The server sends periodic websocket ping requests\nand terminates the connection if the client fails to respond.\n\nBulk methods `get_accounts_from_keys` and `get_balances` require a\nparameter `reqid`. The requests return immediately, and the API starts\nsending RPC notifications. Each notification has the following fields:\n\n* `method`: the original RPC method that caused the notification;\n\n* `reqid`: the same value as was passed in `reqid` when calling the\n  request;\n\n* `data`: row of data according to request. It is omitted when `end`\n  is `true`;\n\n* `end`: if present and is `true`, this is the last notification for\n  this `reqid`. Additional fields `status` and `error` are delivered\n  to indicate the success of operation.\n\n* `status`: only present in the end notification. Value 200 indicates\n  success, and 500 indicates an error.\n\n* `error`: only present in the end notification. In case of success,\n  this field is set to `null`, and contains an error message\n  otherwise.\n\nNotifications are sent asynchronously, and if multiple requests are\nbeing served, the order of interleaving is random. But within each\n`reqid` the order of messages is guaranteed to have `end` message as\nthe last one.\n\nMethods that return token balances deliver the amounts as strings with\nexact number of decimals as specified in the token contract.\n\n\nRPC methods:\n\n* `get_networks` does not require any parameters, and returns a map of\n  network name as key and a map of `network, chainid, description,\n  systoken, decimals, production` as value.\n\n* `get_accounts_from_keys` requires the following parameters: `reqid`,\n  `network`, `keys` (array of public keys to search for, up to 100\n  keys). The method generates notifications with `account_name, perm,\n  weight, pubkey` in data field. Both legacy and new format of keys\n  are supported.\n\n* `get_balances` requires the following parameters: `reqid`,\n  `network`, `accounts` (array of account names, up to 100\n  accounts). The method generates notifications with `account,\n  balances` in the data field, where balances are in an array of maps\n  with `contract, currency, amount` keys.\n\n* `get_token_holders` requires the following parameters: `reqid`,\n  `network`, `contract` and `currency`. The method generates\n  notifications with `account, amount` in the data field, returning\n  all token holders and their balances.\n\n\n## User support\n\nUser discussion and support in Telegram: https://t.me/lightapi\n\n\n## Public endpoints\n\nThis GitHub repository is the main location for two JSON files:\n\n* [networks.json](networks.json) lists the canonical chain names and\n  their attributes.\n\n* [endpoints.json](endpoints.json) lists some known public endpoins.\n\nAdditional endpoints could be discovered from block producers' bp.json\nif they utilize the [\"light-api\"\nfeature](https://github.com/eosrio/bp-info-standard?tab=readme-ov-file#api-features).\n\n\n## Project sponsors\n\n* [GetScatter](https://get-scatter.com/): engineering, hosting and\n  maintenance.\n\n* [EOS Cafe Block](https://www.eoscafeblock.com/): new features.\n\n* [Telos community](https://telosfoundation.io/): development of\n  additional features in Chronicle.\n\n* [EOS Amsterdam](https://eosamsterdam.net/) and\n  [Newdex](https://newdex.io/): development of Version 2\n\n* [EOS Amsterdam](https://eosamsterdam.net/): hosting for most public\n  blockchains.\n  \n* [SOV](https://www.soveos.one/): new features.\n\n\n\n## Installation\n\nThe database writer process (`lightapi_dbwrite.pl`) is a consumer for\n[Chronicle](https://github.com/EOSChronicleProject) data feed, and it\nwrites the blockchain information in real time into the local MariaDB\ndatabase.\n\n```\napt-get install git make cpanminus gcc g++ mariadb-server \\\nlibmysqlclient-dev libdbi-perl libjson-xs-perl libjson-perl libdatetime-format-iso8601-perl\n\ncpanm --notest DBD::MariaDB\ncpanm --notest Starman\ncpanm --notest Net::WebSocket::Server\ncpanm --notest Crypt::Digest::RIPEMD160;\n\n\ngit clone https://github.com/cc32d9/eosio_light_api.git /opt/eosio_light_api\n\ncd /opt/eosio_light_api/sql\nmysql \u003clightapi_dbcreate.sql\nsh create_tables.sh eos\nsh /opt/eosio_light_api/setup/add_eos_mainnet.sh\n\ncurl -sL https://deb.nodesource.com/setup_20.x | bash -\napt install -y nodejs\ncd /opt/eosio_light_api/wsapi\nnpm install\n\nvi /etc/default/lightapi_eos\n# add the Chronicle consumer socket details:\n# DBWRITE_OPTS=--port=8100\n\n# Optionally, edit /etc/default/lightapi_api and adjust variables\n# that are predefined in systemd/lightapi_api.service\n\ncd /opt/eosio_light_api/systemd\nsh install_systemd_dbwrite.sh eos\nsh install_systemd_api.sh\nsh install_systemd_wsapi.sh 5101 5102 5103 5104 5105\n\n# Now Starman is serving HTTP requests and you can build your HTTP service\n# with nginx or exposing Starman directly\n\n\n# Cron job for token holder counts\ncat \u003e/etc/cron.d/lightapi \u003c\u003c'EOT'\n*/5 * * * * root perl /opt/eosio_light_api/scripts/lightapi_holdercounts.pl\nEOT\n\n## set up chronicle\n\ncd /var/local\nwget https://github.com/EOSChronicleProject/eos-chronicle/releases/download/v3.3/antelope-chronicle-3.3-Clang-11.0.1-ubuntu22.04-x86_64.deb\napt install ./antelope-chronicle-3.3-Clang-11.0.1-ubuntu22.04-x86_64.deb\ncp /usr/local/share/chronicle_receiver\\@.service /etc/systemd/system/\nsystemctl daemon-reload\n\n\n# Chronicle configuration:\n# \"host\" and \"port\" point to the EOSIO/Leap state history source.\n# \"exp-ws-host\" and \"exp-ws-port\" point to the lightapi_dbwrite.pl process.\n# \"blacklist-tables-contract\" reduces the amount of processing on bulky contracts.\n\nmkdir -p /srv/eos/chronicle-config\ncat \u003e/srv/eos/chronicle-config/config.ini \u003c\u003c'EOT'\nhost = 10.0.3.1\nport = 9090\nmode = scan\nplugin = exp_ws_plugin\nexp-ws-host = 127.0.0.1\nexp-ws-port = 8100\nexp-ws-bin-header = true\nskip-block-events = true\nskip-traces = true\nblacklist-tables-contract = atomicassets\nblacklist-tables-contract = atomicmarket\nblacklist-tables-contract = utxomng.xsat\nblacklist-tables-contract = playuplandme\nblacklist-tables-contract = eosio.evm\nEOT\n\n# You need to initialize the Chronicle database from the first block\n# in the state history archive. See the Chronicle Tutorial for more\n# details. You may point it to a temporarfy state history source\n# during the initialization and later switch to the production state\n# history. Big networks like WAX or EOS require a lot of RAM for\n# Chronicle to process the startup data. You may need a temporary\n# server with 256GB of RAM, or a lot of swap space.\n\n/usr/local/sbin/chronicle-receiver --config-dir=/srv/eos/chronicle-config \\\n --data-dir=/srv/eos/chronicle-data \\\n --host=my.ship.host.domain.com --port=8080 \\\n --start-block=186332760 \n\n# Once it displays the progress of acknowledged blocks, stop it and start as a service\nsystemctl enable chronicle_receiver@eos\nsystemctl start chronicle_receiver@eos\n\n\n```\n\n\n## Public database access\n\nA replica of LightAPI databases is provided by EOS Amsterdam for\npublic access. The goal is to allow queries which are not implemented\nby the API. There is no SLA, and the service is offered at best\neffort. You can query the SYNC table to see if the data is up to date.\n\nAccess to the database is throttled on the network level for the sake\nof fair use.\n\nThe database schema is available in\n[sql/lightapi_dbcreate.sql](sql/lightapi_dbcreate.sql).\n\n```\nmysql --host=pubdb.eu.eosamsterdam.net --port=3301 --user=lightapiro \\\n  --password=lightapiro --database=lightapi\n```\n\nQuery examples:\n\n```\nselect * from wax_CURRENCY_BAL where account_name = 'cc32dninexxx';\n\nselect * from wax_CURRENCY_BAL where contract='eosio.token' and currency='WAX' and amount \u003e 500000;\n\nselect count(*) from wax_USERRES where account_name like '%.wam';\n```\n\n\n## Copyright and License\n\nCopyright 2018-2024 cc32d9@gmail.com\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcc32d9%2Feosio_light_api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcc32d9%2Feosio_light_api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcc32d9%2Feosio_light_api/lists"}