Skip to main content

​
Objective

Run a local instance of the Validator Rewards API, expose it on an HTTP port, and verify the main service endpoints.

​
Prerequisites

  • A local checkout of the ton-validators-rewards-api source code.
  • Go 1.25.0 or later.
  • Optional: Docker Engine.
Audience: Intermediate. Assumes familiarity with Go builds, environment variables, and HTTP requests.

​
Build and start the binary

Run the following commands from the project root: 
go build -o ton-validators-rewards-api .
./ton-validators-rewards-api
The service listens on port 8080 by default. When -config is not set, startup downloads https://ton.org/global-config.json and uses the liteservers from that file.

​
Configure the process

The process loads environment variables from a .env file in the working directory, when present. Supported environment variables:
VariableDescription
PORTHTTP port. Default: 8080.
UPTRACE_DSNUptrace DSN for tracing. If unset, telemetry stays disabled.
Use a different port: 
PORT=3000 ./ton-validators-rewards-api
Define placeholders: <CONFIG_PATH>: path to a TON global config JSON file. Use a custom TON global config file: 
./ton-validators-rewards-api -config <CONFIG_PATH>

​
Run with Docker

Build and start the container image: 
docker build -t ton-validators-rewards-api .
docker run -p 8080:8080 ton-validators-rewards-api
Use a custom config file in Docker: 
docker run -p 8080:8080 \
  -v $(pwd)/config.json:/config.json:ro \
  ton-validators-rewards-api -config /config.json

​
Verify

Check the health endpoint: 
curl http://localhost:8080/health
Expected output: 
{"status":"ok"}
Open the Swagger UI: 
http://localhost:8080/swagger
Fetch the current validator snapshot: 
curl http://localhost:8080/api/validators
The response is JSON and includes block, election_id, total_stake, and validators.

​
Troubleshoot

  • If startup fails while downloading the default config, start the service with -config <CONFIG_PATH> and use a local TON global config file.
  • If port 8080 is already in use, set PORT to a different value.
  • If GET /api/round-rewards returns an error that the round is not finished, query an older finished round by election_id or by a block inside that round.