Home

Awesome

EOSIO Light API

The API is providing information about EOSIO blockchain accounts and token balances. It is deployed for several blockchains, such as EOS, Telos, BOS, WAX, and Europechain. Also an endpoints for a number of testnets are available.

HTTP API

In below examples, "CHAIN" stands for the name of the network where API is taking the data (such as eos, telos, wax etc.).

In addition, adding ?pretty=1 to the URL, you get the resulting JSON sorted and formatted for human viewing.

Websocket API

Websocket API is complimentary to HTTP API and is designed for bulk requests. All communication is compliant with JSON-RPC version 2.0.

The client is expected to close the websoclet connection after it finishes using it. The server sends periodic websocket ping requests and terminates the connection if the client fails to respond.

Bulk methods get_accounts_from_keys and get_balances require a parameter reqid. The requests return immediately, and the API starts sending RPC notifications. Each notification has the following fields:

Notifications are sent asynchronously, and if multiple requests are being served, the order of interleaving is random. But within each reqid the order of messages is guaranteed to have end message as the last one.

Methods that return token balances deliver the amounts as strings with exact number of decimals as specified in the token contract.

RPC methods:

User support

User discussion and support in Telegram: https://t.me/lightapi

Public endpoints

This GitHub repository is the main location for two JSON files:

Additional endpoints could be discovered from block producers' bp.json if they utilize the "light-api" feature.

Project sponsors

Installation

The database writer process (lightapi_dbwrite.pl) is a consumer for Chronicle data feed, and it writes the blockchain information in real time into the local MariaDB database.

apt-get install git make cpanminus gcc g++ mariadb-server \
libmysqlclient-dev libdbi-perl libjson-xs-perl libjson-perl libdatetime-format-iso8601-perl

cpanm --notest DBD::MariaDB
cpanm --notest Starman
cpanm --notest Net::WebSocket::Server
cpanm --notest Crypt::Digest::RIPEMD160;


git clone https://github.com/cc32d9/eosio_light_api.git /opt/eosio_light_api

cd /opt/eosio_light_api/sql
mysql <lightapi_dbcreate.sql
sh create_tables.sh eos
sh /opt/eosio_light_api/setup/add_eos_mainnet.sh

curl -sL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs
cd /opt/eosio_light_api/wsapi
npm install

vi /etc/default/lightapi_eos
# add the Chronicle consumer socket details:
# DBWRITE_OPTS=--port=8100

# Optionally, edit /etc/default/lightapi_api and adjust variables
# that are predefined in systemd/lightapi_api.service

cd /opt/eosio_light_api/systemd
sh install_systemd_dbwrite.sh eos
sh install_systemd_api.sh
sh install_systemd_wsapi.sh 5101 5102 5103 5104 5105

# Now Starman is serving HTTP requests and you can build your HTTP service
# with nginx or exposing Starman directly


# Cron job for token holder counts
cat >/etc/cron.d/lightapi <<'EOT'
*/5 * * * * root perl /opt/eosio_light_api/scripts/lightapi_holdercounts.pl
EOT

## set up chronicle

cd /var/local
wget https://github.com/EOSChronicleProject/eos-chronicle/releases/download/v3.3/antelope-chronicle-3.3-Clang-11.0.1-ubuntu22.04-x86_64.deb
apt install ./antelope-chronicle-3.3-Clang-11.0.1-ubuntu22.04-x86_64.deb
cp /usr/local/share/chronicle_receiver\@.service /etc/systemd/system/
systemctl daemon-reload


# Chronicle configuration:
# "host" and "port" point to the EOSIO/Leap state history source.
# "exp-ws-host" and "exp-ws-port" point to the lightapi_dbwrite.pl process.
# "blacklist-tables-contract" reduces the amount of processing on bulky contracts.

mkdir -p /srv/eos/chronicle-config
cat >/srv/eos/chronicle-config/config.ini <<'EOT'
host = 10.0.3.1
port = 9090
mode = scan
plugin = exp_ws_plugin
exp-ws-host = 127.0.0.1
exp-ws-port = 8100
exp-ws-bin-header = true
skip-block-events = true
skip-traces = true
blacklist-tables-contract = atomicassets
blacklist-tables-contract = atomicmarket
blacklist-tables-contract = utxomng.xsat
blacklist-tables-contract = playuplandme
blacklist-tables-contract = eosio.evm
EOT

# You need to initialize the Chronicle database from the first block
# in the state history archive. See the Chronicle Tutorial for more
# details. You may point it to a temporarfy state history source
# during the initialization and later switch to the production state
# history. Big networks like WAX or EOS require a lot of RAM for
# Chronicle to process the startup data. You may need a temporary
# server with 256GB of RAM, or a lot of swap space.

/usr/local/sbin/chronicle-receiver --config-dir=/srv/eos/chronicle-config \
 --data-dir=/srv/eos/chronicle-data \
 --host=my.ship.host.domain.com --port=8080 \
 --start-block=186332760 

# Once it displays the progress of acknowledged blocks, stop it and start as a service
systemctl enable chronicle_receiver@eos
systemctl start chronicle_receiver@eos

Public database access

A replica of LightAPI databases is provided by EOS Amsterdam for public access. The goal is to allow queries which are not implemented by the API. There is no SLA, and the service is offered at best effort. You can query the SYNC table to see if the data is up to date.

Access to the database is throttled on the network level for the sake of fair use.

The database schema is available in sql/lightapi_dbcreate.sql.

mysql --host=pubdb.eu.eosamsterdam.net --port=3301 --user=lightapiro \
  --password=lightapiro --database=lightapi

Query examples:

select * from wax_CURRENCY_BAL where account_name = 'cc32dninexxx';

select * from wax_CURRENCY_BAL where contract='eosio.token' and currency='WAX' and amount > 500000;

select count(*) from wax_USERRES where account_name like '%.wam';

Copyright and License

Copyright 2018-2024 cc32d9@gmail.com

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.