Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pinax-network/antelope-token-api
Tokens information from the Antelope blockchains, powered by Substreams
https://github.com/pinax-network/antelope-token-api
api clickhouse substreams typescript web3
Last synced: about 2 months ago
JSON representation
Tokens information from the Antelope blockchains, powered by Substreams
- Host: GitHub
- URL: https://github.com/pinax-network/antelope-token-api
- Owner: pinax-network
- License: mit
- Created: 2023-10-30T11:29:27.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-08-28T16:15:39.000Z (4 months ago)
- Last Synced: 2024-08-29T17:47:24.630Z (4 months ago)
- Topics: api, clickhouse, substreams, typescript, web3
- Language: TypeScript
- Homepage:
- Size: 1.41 MB
- Stars: 2
- Watchers: 6
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Antelope Token API
[](https://github.com/pinax-network/antelope-token-api/actions/workflows/bun-test.yml)
> Tokens information from the Antelope blockchains, powered by [Substreams](https://substreams.streamingfast.io/)
## Swagger API
### Usage
| Method | Path | Query parameters
(* = **Required**) | Description |
| :---: | --- | --- | --- |
| GET
`text/html` | `/` | - | [Swagger](https://swagger.io/) API playground |
| GET
`application/json` | `/balance` | **`account*`**
`contract`
`symcode`
`limit`
`page` | Balances of an account |
| GET
`application/json` | `/balance/historical` | **`account*`**
`block_num`
`contract`
`symcode`
`limit`
`page` | Historical token balances |
| GET
`application/json` | `/head` | `limit`
`page` | Head block information |
| GET
`application/json` | `/holders` | **`contract*`**
**`symcode*`**
`limit`
`page` | List of holders of a token |
| GET
`application/json` | `/supply` | `block_num`
`issuer`
**`contract*`**
**`symcode*`**
`limit`
`page` | Total supply for a token |
| GET
`application/json` | `/tokens` | `limit`
`page` | List of available tokens |
| GET
`application/json` | `/transfers` | `block_range`
**`contract*`**
**`symcode*`**
`limit`
`page` | All transfers related to a token |
| GET
`application/json` | `/transfers/account` | **`account*`**
`block_range`
`from`
`to`
`contract`
`symcode`
`limit`
`page` | All transfers related to an account |
| GET
`application/json` | `/transfers/id` | **`trx_id*`**
`limit`
`page` | Specific transfer related to a token |
### Docs
| Method | Path | Description |
| :---: | --- | --- |
| GET
`application/json` | `/openapi` | [OpenAPI](https://www.openapis.org/) specification |
| GET
`application/json` | `/version` | API version and Git short commit hash |
### Monitoring
| Method | Path | Description |
| :---: | --- | --- |
| GET
`text/plain` | `/health` | Checks database connection |
| GET
`text/plain` | `/metrics` | [Prometheus](https://prometheus.io/) metrics |
### `X-Api-Key`
Use the `Variables` tab at the bottom to add your API key:
```json
{
"X-Api-Key": "changeme"
}
```
### Additional notes
- For the `block_range` parameter in `transfers`, you can pass a single integer value (low bound) or an array of two values (inclusive range).
- Use the `from` and `to` field for transfers of an account to further filter the results (i.e. incoming or outgoing transactions from/to another account).
- Don't forget to request the `meta` fields in the response to get access to pagination and statistics !
## Requirements
- [ClickHouse](clickhouse.com/), databases should follow a `{chain}_tokens_{version}` naming scheme. Database tables can be setup using the [`schema.sql`](./schema.sql) definitions created by the [`create_schema.sh`](./create_schema.sh) script.
- A [Substream sink](https://substreams.streamingfast.io/reference-and-specs/glossary#sink) for loading data into ClickHouse. We recommend [Substreams Sink ClickHouse](https://github.com/pinax-network/substreams-sink-clickhouse/) or [Substreams Sink SQL](https://github.com/pinax-network/substreams-sink-sql). This Token API makes use of the [`substreams-antelope-tokens`](https://github.com/pinax-network/substreams-antelope-tokens/) substream.
### API stack architecture
### Setting up the database backend (ClickHouse)
#### Without a cluster
Example on how to set up the ClickHouse backend for sinking [EOS](https://pinax.network/en/chain/eos) data.
1. Start the ClickHouse server
```console
clickhouse server
```
2. Create the token database
```console
echo "CREATE DATABASE eos_tokens_v1" | clickhouse client -h --port 9000 -d -u --password
```
3. Run the [`create_schema.sh`](./create_schema.sh) script
```console
./create_schema.sh -o /tmp/schema.sql
```
4. Execute the schema
```console
cat /tmp/schema.sql | clickhouse client -h --port 9000 -d -u --password
```
5. Run the [sink](https://github.com/pinax-network/substreams-sink-sql)
```console
substreams-sink-sql run clickhouse://:@:9000/eos_tokens_v1 \
https://github.com/pinax-network/substreams-antelope-tokens/releases/download/v0.4.0/antelope-tokens-v0.4.0.spkg `#Substreams package` \
-e eos.substreams.pinax.network:443 `#Substreams endpoint` \
1: `#Block range :` \
--final-blocks-only --undo-buffer-size 1 --on-module-hash-mistmatch=warn --batch-block-flush-interval 100 --development-mode `#Additional flags`
```
6. Start the API
```console
# Will be available on locahost:8080 by default
antelope-token-api --host --database eos_tokens_v1 --username --password --verbose
```
#### With a cluster
If you run ClickHouse in a [cluster](https://clickhouse.com/docs/en/architecture/cluster-deployment), change step 2 & 3:
2. Create the token database
```console
echo "CREATE DATABASE eos_tokens_v1 ON CLUSTER " | clickhouse client -h --port 9000 -d -u --password
```
3. Run the [`create_schema.sh`](./create_schema.sh) script
```console
./create_schema.sh -o /tmp/schema.sql -c
```
## [`Bun` Binary Releases](https://github.com/pinax-network/antelope-token-api/releases)
> [!WARNING]
> Linux x86 only
```console
$ wget https://github.com/pinax-network/antelope-token-api/releases/download/v4.0.0/antelope-token-api
$ chmod +x ./antelope-token-api
$ ./antelope-token-api --help
Usage: antelope-token-api [options]
Token balances, supply and transfers from the Antelope blockchains
Options:
-V, --version output the version number
-p, --port HTTP port on which to attach the API (default: "8080", env: PORT)
--hostname Server listen on HTTP hostname (default: "localhost", env: HOSTNAME)
--host Database HTTP hostname (default: "http://localhost:8123", env: HOST)
--database The database to use inside ClickHouse (default: "default", env: DATABASE)
--username Database user (default: "default", env: USERNAME)
--password Password associated with the specified username (default: "", env: PASSWORD)
--max-limit Maximum LIMIT queries (default: 10000, env: MAX_LIMIT)
-v, --verbose Enable verbose logging (choices: "true", "false", default: false, env: VERBOSE)
-h, --help display help for command
```
## `.env` Environment variables
```env
# API Server
PORT=8080
HOSTNAME=localhost
# Clickhouse Database
HOST=http://127.0.0.1:8123
DATABASE=default
USERNAME=default
PASSWORD=
MAX_LIMIT=500
# Logging
VERBOSE=true
```
## Docker environment
- Pull from GitHub Container registry
**For latest tagged release**
```bash
docker pull ghcr.io/pinax-network/antelope-token-api:latest
```
**For head of `main` branch**
```bash
docker pull ghcr.io/pinax-network/antelope-token-api:develop
```
- Build from source
```bash
docker build -t antelope-token-api .
```
- Run with `.env` file
```bash
docker run -it --rm --env-file .env ghcr.io/pinax-network/antelope-token-api
```
## Contributing
See [`CONTRIBUTING.md`](CONTRIBUTING.md).
### Quick start
Install [Bun](https://bun.sh/)
```console
bun install
bun dev
```
**Tests**
```console
bun lint
bun test
```