repository·master·Indexed 19 days ago
https://github.com/tonkeeper/opentonapiAn open-source blockchain indexer and API compatible with TonAPI. It provides high-level abstractions for TON entities such as Jettons and NFTs, as well as access to accounts, transactions, and traces, simplifying the development of TON-based applications.
The project is organized into several key directories that define its functionality. If you are looking to integrate with or extend specific features, use the following mapping:
api/: Contains OpenAPI configuration files used by ogen to generate API interfaces.cmd/api/main.go: The main entry point for executing the application.internal/: Contains private utility functions and helpers.pkg/: The location of all core, functional packages.ogen.yaml: The OpenAPI configuration for code generation.Core functionality is located in the pkg/ directory. Key packages include:
addressbook: Manages known addresses, jettons, NFT collections, and manual configurations.api: Implements the business logic for API endpoints (e.g., querying addresses, transactions).blockchain: Handles transaction payloads to lite servers and real-time block indexing.config: Manages application configuration via environment variables.gasless: Manages gasless transaction operations.spam: Filters spam/scam actions for TON, Jetton, and NFT transfers.rates: Fetches and converts market prices for TON tokens.The project uses OpenAPI Generator (ogen) to generate Go code from OpenAPI v3 specifications.
ogen.yaml.api/ directory.gen.go file is used to trigger the code generation based on the OGEN specification.The LITE_SERVERS environment variable accepts a comma-separated list of servers in the format ip:port:public-key.
Important Note on Historical Data:
If you do not explicitly set LITE_SERVERS, the application defaults to using a random public Lite Server. By default, these are often Full nodes, which do not provide access to historical data. To access historical data, you must explicitly configure Archive nodes. You can find public Archive nodes in the official global-config.json.
To begin using the project, follow the setup and running instructions in the documentation to get the application running in your local environment. For a high-level overview of the project structure and its modular packages, refer to the structure guide.
1. Follow [02_SETUP_AND_RUN.md](./02_SETUP_AND_RUN.md) to set up and run the source code locally.
2. Refer to [03_STRUCTURE.md](./03_STRUCTURE.md) to understand the project structure and packages.To run OpenTonAPI directly from the source code, you must have Go installed and provide the libemulator.so shared library from the TON blockchain release repository.
Steps:
go version).libemulator.so and place it in a directory (e.g., /app/lib).LD_LIBRARY_PATH environment variable to point to that directory.go run cmd/api/main.go.The application defaults to port 8081 unless the PORT environment variable is set.
# 1. Setup libemulator
mkdir -p /app/lib
wget -O /app/lib/libemulator.so https://github.com/ton-blockchain/ton/releases/download/v2024.08/libemulator-linux-x86_64.so
# 2. Configure library path
export LD_LIBRARY_PATH=/app/lib/
# 3. Run the application
go run cmd/api/main.go
# Or run with custom configuration
PORT=8080 LOG_LEVEL=DEBUG go run cmd/api/main.goTo run OpenTonAPI using Docker, clone the repository, build the image, and run the container. By default, the API is exposed on port 8081. You can verify the application is running by accessing the /v2/status endpoint.
Steps:
git clone https://github.com/tonkeeper/opentonapi.gitcd opentonapidocker build -t myopentonapi .docker run -d -p 8081:8081 myopentonapiYou can also pass environment variables (like LOG_LEVEL) using the -e flag.
# Build the image
docker build -t myopentonapi .
# Run the container in the background on port 8081
docker run -d -p 8081:8081 myopentonapi
# Run with a specific log level
docker run -d -p 8081:8081 -e LOG_LEVEL=DEBUG myopentonapiYou can run Opentonapi as a containerized service using Docker. By default, it maps port 8081.
docker run -d -p8081:8081 tonkeeper/opentonapiTo use advanced features such as traces, NFTs, and Jettons, you must configure the service to watch specific accounts. You can do this by passing a comma-separated list of raw account addresses to the ACCOUNTS environment variable when running the application.
ACCOUNTS="comma-separated-list-of-raw-account-addresses" make runThe Go SDK for TonAPI has been moved to a dedicated repository. To use the SDK in your Go projects, visit the new repository instead of this one:
Opentonapi can be configured using the following environment variables:
| Env variable | Default value | Description |
|---|---|---|
PORT | 8081 | Port used to accept incoming HTTP connections |
LOG_LEVEL | INFO | Logging verbosity level |
LITE_SERVERS | - | A comma-separated list of TON lite servers in the format ip:port:public-key (e.g., 127.0.0.1:14395:6PGkPQSbyFp12esf1NqmDOaLoFA8i9+Mp5+cAx5wtTU=) |
METRICS_PORT | 9010 | Port used to expose the /metrics endpoint for Prometheus |
ACCOUNTS | - | A comma-separated list of raw account addresses to watch |
Note: To enable advanced features like traces, NFTs, and Jettons, you must provide a list of accounts to watch using the ACCOUNTS variable.
The sentry package automatically initializes itself using the SENTRY_DSN environment variable.
SENTRY_DSN is empty, the package remains uninitialized and Send calls will do nothing.TracesSampleRate of 1.0.Flush with a 2-second timeout.