diff --git a/.gitignore b/.gitignore
index aad06735e..ee77c0df1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,4 +22,4 @@ node_modules/
__pycache__
# Generated folders
-/stats/
+/stats/
\ No newline at end of file
diff --git a/docs.json b/docs.json
index ea7350a15..9923694bd 100644
--- a/docs.json
+++ b/docs.json
@@ -119,6 +119,14 @@
}
]
},
+ {
+ "group": "Validator rewards API",
+ "pages": [
+ "ecosystem/api/validator-rewards/overview",
+ "ecosystem/api/validator-rewards/run-locally",
+ "ecosystem/api/validator-rewards/api-reference"
+ ]
+ },
"ecosystem/api/price"
]
},
diff --git a/ecosystem/api/validator-rewards/api-reference.mdx b/ecosystem/api/validator-rewards/api-reference.mdx
new file mode 100644
index 000000000..bd4ec4c4c
--- /dev/null
+++ b/ecosystem/api/validator-rewards/api-reference.mdx
@@ -0,0 +1,195 @@
+---
+title: "Validator rewards API reference"
+sidebarTitle: "API reference"
+mode: "wide"
+---
+
+import { Aside } from "/snippets/aside.jsx";
+
+Self-hosted HTTP endpoints for validator stake, validation round metadata, and
+finished round reward distribution.
+
+
+
+## Formats and conventions
+
+- All balance, stake, and reward fields are decimal strings in nanoTON.
+ `1 TON = 1,000,000,000 nanoTON`.
+- `seqno` and `block` values are masterchain block sequence numbers.
+- `election_id` is the validation round `electAt` timestamp.
+- `election_id` and `block` are mutually exclusive on endpoints that accept
+ both parameters.
+- Error responses use HTTP `400` for invalid query parameters and HTTP `500`
+ for service-side failures.
+
+Define placeholders:
+
+- ``: base URL of the running service.
+- ``: masterchain block sequence number.
+- ``: masterchain block sequence number inside the target round.
+- ``: election ID of the target round.
+
+## Service routes
+
+| Endpoint | Response | Description |
+| ----------------------- | -------- | ----------------------------------------- |
+| `GET /health` | JSON | Return `{"status":"ok"}`. |
+| `GET /swagger` | HTML | Return the local Swagger UI. |
+| `GET /api/openapi.yaml` | YAML | Return the embedded OpenAPI 3.0 document. |
+
+## Common objects
+
+### Validator entry
+
+`validators` in `GET /api/validators` and `GET /api/round-rewards` use the same
+object shape.
+
+| Field | Description |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `rank` | Position in the validator list, sorted by `effective_stake` in descending order. |
+| `pubkey` | Validator public key encoded as lowercase hex. |
+| `effective_stake` | Effective stake locked in the elector contract. |
+| `weight` | Share of total effective stake in the selected response, from `0` to `1`. |
+| `reward` | Reward amount. In `GET /api/validators`, this is the per-block estimate for the target block. In `GET /api/round-rewards`, this is the total reward for the selected finished round. |
+| `pool` | Pool smart contract address in bounceable base64url form, when available. |
+| `pool_type` | Detected pool type: `nominator-pool-v1.0`, `single-nominator-pool-v1.0`, `single-nominator-pool-v1.1`, or `other`. |
+| `validator_address` | Validator wallet or control address, when available. |
+| `owner_address` | Owner address for a single nominator pool, when available. |
+| `validator_stake` | Validator's own deposited funds. Present for `nominator-pool-v1.0`. |
+| `nominators_stake` | Sum of nominator deposits. Present for `nominator-pool-v1.0`. |
+| `total_stake` | Total pool funds computed as `effective_stake + credit`, where `credit` is the returned stake still held in the elector contract. |
+| `validator_reward_share` | Fraction of rewards kept by the validator, for example `0.3` for `30%`. Present for `nominator-pool-v1.0`. |
+| `nominators_count` | Number of nominators. Present for `nominator-pool-v1.0`. |
+| `nominators` | Array of nominator entries. Present for `nominator-pool-v1.0`. |
+
+### Nominator entry
+
+| Field | Description |
+| ----------------- | --------------------------------------------------------------- |
+| `address` | Nominator wallet address in bounceable base64url form. |
+| `weight` | Share of total nominator deposits in the pool, from `0` to `1`. |
+| `reward` | Reward amount assigned to the nominator. |
+| `effective_stake` | Nominator share of the validator's effective stake. |
+| `stake` | Raw nominator deposit in the pool contract. |
+
+## `GET /api/validators`
+
+Return the active validator set for a target masterchain block. If `seqno` is
+not provided, the service uses the latest masterchain block.
+
+```bash
+curl "/api/validators?seqno="
+```
+
+Query parameters:
+
+| Parameter | Type | Description |
+| --------- | -------- | --------------------------------------------------- |
+| `seqno` | `uint32` | Target masterchain block sequence number. Optional. |
+
+Response fields:
+
+| Field | Description |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `response_time_ms` | Server-side response time in milliseconds. |
+| `block.seqno` | Resolved masterchain block sequence number. |
+| `block.time` | Target block time in UTC, RFC 3339 format. |
+| `validation_round.start` | Validation round start time for the target block. |
+| `validation_round.end` | Validation round end time for the target block. |
+| `validation_round.start_block` | First masterchain block of the round, when resolved. |
+| `validation_round.end_block` | Last masterchain block of the round, when the round has already finished. |
+| `election_id` | Election ID of the round active at the target block. |
+| `prev_election_id` | Election ID of the previous round, when resolved. |
+| `next_election_id` | Election ID of the next round, when the selected round has already finished. |
+| `elector_balance` | Elector contract balance at the target block. |
+| `total_stake` | Sum of effective stakes across the active validator set. |
+| `reward_per_block` | Estimated total reward for the target block, computed as the change in the elector `bonuses` value between the target block and the previous block. |
+| `validators` | Array of validator entries. |
+
+## `GET /api/validation-rounds`
+
+Return metadata for the round selected by `election_id`, `block`, or the latest
+masterchain block.
+
+```bash
+curl "/api/validation-rounds?block="
+```
+
+
+
+Query parameters:
+
+| Parameter | Type | Description |
+| ------------- | -------- | ------------------------------------------------------------------------------------------------------- |
+| `election_id` | `int64` | Return the round that matches this election ID. Optional. Mutually exclusive with `block`. |
+| `block` | `uint32` | Return the round that contains this masterchain block. Optional. Mutually exclusive with `election_id`. |
+
+Response fields:
+
+| Field | Description |
+| ------------------ | ----------------------------------------------------------------- |
+| `response_time_ms` | Server-side response time in milliseconds. |
+| `rounds` | Array of validation round entries. |
+| `error` | Optional top-level error string when round traversal stops early. |
+
+Validation round entry fields:
+
+| Field | Description |
+| ------------------ | -------------------------------------------------------------------- |
+| `election_id` | Election ID of the selected round. |
+| `start` | Validation round start time in UTC, RFC 3339 format. |
+| `end` | Validation round end time in UTC, RFC 3339 format. |
+| `start_block` | First masterchain block of the round. |
+| `end_block` | Last masterchain block of the round, when the round has finished. |
+| `finished` | `true` when the round has finished. |
+| `prev_election_id` | Election ID of the previous round, when resolved. |
+| `next_election_id` | Election ID of the next round, when the selected round has finished. |
+| `error` | Optional per-round error string. |
+
+## `GET /api/round-rewards`
+
+Return per-validator and per-nominator reward distribution for a finished
+validation round.
+
+```bash
+curl "/api/round-rewards?election_id="
+```
+
+Exactly one of `election_id` or `block` is required.
+
+Query parameters:
+
+| Parameter | Type | Description |
+| ------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
+| `election_id` | `int64` | Election ID of a finished round. Optional. Mutually exclusive with `block`. |
+| `block` | `uint32` | Masterchain block sequence number inside a finished round. Optional. Mutually exclusive with `election_id`. |
+
+Response fields:
+
+| Field | Description |
+| ------------------ | ------------------------------------------------------- |
+| `response_time_ms` | Server-side response time in milliseconds. |
+| `election_id` | Election ID of the selected finished round. |
+| `prev_election_id` | Election ID of the previous round, when resolved. |
+| `next_election_id` | Election ID of the next round. |
+| `round_start` | Validation round start time in UTC, RFC 3339 format. |
+| `round_end` | Validation round end time in UTC, RFC 3339 format. |
+| `start_block` | First masterchain block of the round. |
+| `end_block` | Last masterchain block of the round. |
+| `total_bonuses` | Total bonuses paid by the elector for the round. |
+| `total_stake` | Total stake recorded for the round in `past_elections`. |
+| `validators` | Array of validator entries. |
+
+If the selected round has not finished yet, the service returns HTTP `500` with
+an error message in the response body.
+
+## See also
+
+- [Nominator pool contracts](/ecosystem/staking/nominator-pools)
+- [Single nominator pool contracts](/ecosystem/staking/single-nominator)
diff --git a/ecosystem/api/validator-rewards/overview.mdx b/ecosystem/api/validator-rewards/overview.mdx
new file mode 100644
index 000000000..9e0815920
--- /dev/null
+++ b/ecosystem/api/validator-rewards/overview.mdx
@@ -0,0 +1,69 @@
+---
+title: "Validator rewards API overview"
+sidebarTitle: "Overview"
+---
+
+import { Aside } from "/snippets/aside.jsx";
+
+Validator rewards API is a self-hosted HTTP API that reads validator
+reward and staking data directly from TON liteservers through the
+[tongo library](https://github.com/tonkeeper/tongo).
+
+
+
+## What the API returns
+
+- Current validator data for a target masterchain block, including effective
+ stake, per-block reward estimates, pool addresses, and optional nominator
+ breakdowns.
+- Validation round metadata for the round selected by `election_id`, `block`,
+ or the latest masterchain block.
+- Reward distribution for a finished validation round.
+- Local service routes for Swagger UI and the embedded OpenAPI document.
+
+## How the service resolves data
+
+- It reads the active validator set from config param `34`.
+- It reads the elector contract to resolve `past_elections`, total stake,
+ bonuses, and returned stake.
+- It inspects pool contract code hashes to classify pools as
+ `nominator-pool-v1.0`, `single-nominator-pool-v1.0`,
+ `single-nominator-pool-v1.1`, or `other`.
+- It creates one lite client connection per available liteserver and
+ distributes requests across those connections in round-robin order.
+- When no custom config is provided, it downloads
+ the [TON Mainnet global config](https://ton.org/global-config.json), caches
+ it in memory for seven days, and refreshes the lite client after the cache
+ time to live (TTL) expires.
+
+## When to use it
+
+- Build validator dashboards that need current effective stake and pool
+ composition.
+- Compute reward splits for a finished validation round.
+- Inspect nominator pool balances and validator reward shares.
+- Compare the elector's locked stake with pool balances and returned stake.
+
+## Endpoints
+
+| Endpoint | Purpose |
+| ---------------------------- | ----------------------------------------------------------- |
+| `GET /health` | Return service status. |
+| `GET /api/validators` | Return current validators for a target masterchain block. |
+| `GET /api/validation-rounds` | Return metadata for the selected validation round. |
+| `GET /api/round-rewards` | Return reward distribution for a finished validation round. |
+| `GET /api/openapi.yaml` | Return the embedded OpenAPI document. |
+| `GET /swagger` | Open the local Swagger UI. |
+
+## Next steps
+
+- [How to run the validator rewards API locally](/ecosystem/api/validator-rewards/run-locally)
+- [Validator rewards API reference](/ecosystem/api/validator-rewards/api-reference)
+
+## See also
+
+- [Nominator pool contracts](/ecosystem/staking/nominator-pools)
+- [Single nominator pool contracts](/ecosystem/staking/single-nominator)
diff --git a/ecosystem/api/validator-rewards/run-locally.mdx b/ecosystem/api/validator-rewards/run-locally.mdx
new file mode 100644
index 000000000..4f5e14617
--- /dev/null
+++ b/ecosystem/api/validator-rewards/run-locally.mdx
@@ -0,0 +1,122 @@
+---
+title: "How to run the validator rewards API locally"
+sidebarTitle: "Run locally"
+---
+
+import { Aside } from "/snippets/aside.jsx";
+
+## 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](https://github.com/the-ton-tech/ton-validators-rewards-api).
+- [Go](https://go.dev/dl/) 1.25.0 or later.
+- Optional: [Docker Engine](https://docs.docker.com/engine/install/).
+
+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:
+
+```bash
+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:
+
+| Variable | Description |
+| ------------- | ------------------------------------------------------------ |
+| `PORT` | HTTP port. Default: `8080`. |
+| `UPTRACE_DSN` | Uptrace DSN for tracing. If unset, telemetry stays disabled. |
+
+Use a different port:
+
+```bash
+PORT=3000 ./ton-validators-rewards-api
+```
+
+Define placeholders:
+``: path to a TON global config JSON file.
+
+Use a custom TON global config file:
+
+```bash
+./ton-validators-rewards-api -config
+```
+
+
+
+## Run with Docker
+
+Build and start the container image:
+
+```bash
+docker build -t ton-validators-rewards-api .
+docker run -p 8080:8080 ton-validators-rewards-api
+```
+
+Use a custom config file in Docker:
+
+```bash
+docker run -p 8080:8080 \
+ -v $(pwd)/config.json:/config.json:ro \
+ ton-validators-rewards-api -config /config.json
+```
+
+## Verify
+
+Check the health endpoint:
+
+```bash
+curl http://localhost:8080/health
+```
+
+Expected output:
+
+```json
+{"status":"ok"}
+```
+
+Open the Swagger UI:
+
+```text
+http://localhost:8080/swagger
+```
+
+Fetch the current validator snapshot:
+
+```bash
+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 ` and use a local copy of the [TON Mainnet global
+ config](https://ton-blockchain.github.io/global.config.json).
+- 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.
diff --git a/resources/dictionaries/custom.txt b/resources/dictionaries/custom.txt
index b314f0a4b..fbae2dca3 100644
--- a/resources/dictionaries/custom.txt
+++ b/resources/dictionaries/custom.txt
@@ -236,6 +236,7 @@ DEXes
DEXs
DHT
DHTs
+DSN
DNAT
Diffie
dockerize
@@ -736,10 +737,12 @@ TON
TON.cx
TONCO
Toncoin
+Tongo
toncoin.org
Tonkeeper
tonlib
Tonscan
+tongo
tonscan.com
tonscan.org
Tonstakers
@@ -790,6 +793,7 @@ untyped
unvoted
updatable
Upgradability
+Uptrace
uptimes
URIs
USDe