An API for integrating validators and pools with the Nimiq Wallet and other apps, helping stakers choose where to stake.

Dashboards

Mainnet      Testnet

Validators and Staking Pools: A validator can operate as a staking pool, allowing multiple users to stake. Pools must provide detailed information such as fees, payout schedules, and contact details to ensure trust and transparency.

Stakers can evaluate a validator’s reliability using the Validator Trust Score (VTS) and review staking pool details like payout schedules to select the best option.

Add your Validator Information

If you operate a staking pool and want to be displayed in the Nimiq Wallet, follow these steps:

1. Fork this repository.
2. Add your Validator File:
   • Create a new JSON file in the public/validators/main-albatross directory.
   • Use the provided example template in the directory to structure your data.
3. Review the Description Guidelines.
4. Learn about the JSON Schema.
5. Submit a PR to this repository. A Nimiq team member will review your submission within 3 days.
6. Once the PR is submitted, check that the API endpoint returns your information. This process may take a few minutes.

Warning

Nimiq reserves the right to make minor adjustments to the content submitted by validator owners if necessary.

Recommendations for your Validator Description

Description

This information will be displayed in the wallet to help stakers decide which pool they want to stake in. Providing clear and concise information helps stakers make informed decisions. For complete guidelines and suggestions, check our Staking Pools Handbook.

• Length: Aim for 1-2 sentences (20-40 words).
• Clarity: Highlight unique aspects of your pool, such as reliability, transparency or low fees.
• Strengths: Mention features like high uptime, low fees, strong community support or eco-friendly practices.
• Tone: Keep a friendly and professional tone.

Good Example: "Our pool offers 99.9% uptime, low fees, and strong security, ensuring a seamless staking experience. Join us for a reliable, transparent, and staker-focused service." Bad Example: "Stake with us for unmatched rewards and the highest profits! Don’t miss your chance to earn big — this is the ultimate opportunity for stakers!"

Validator JSON schema

Use the following schema to create your validator information file. You can start by copying this example JSON template. When you add your validator information, you'll need to include specific keys in your JSON file. Below is an explanation of each key and its possible values.

Required Keys:

• name: The name of your validator. If you don’t provide a name, your validator address will be used by default.
• description: A short description of your validator. Use this to highlight what makes your validator unique or appealing to stakers.
• address: The address of the validator in this format NQXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX.
• fee: Use either static or dynamic fees:
  • For static fees, use fee with a percentage between 0 and 1 (0.05 represents a 5% fee).
  • For dynamic fees, use the following 3 values:
    • feeLowest: The minimum possible fee.
    • feeHighest: The maximum possible fee.
    • feeDescription: Outline the conditions for various fees.
• payoutType: The method used to payout the rewards. Possible values are:
  • restake: Rewards are automatically restaked.
  • direct: Rewards are paid directly into the staker's wallet and are not automatically restaked. Requires:
    • payoutAddress: Provide address you will payout from.
    • payoutSchedule: Specify the frequency of payouts using the cron job format. Example: 0 */6 * * * for payouts every 6 hours.
  • none: No rewards will be paid out.
  • custom: Custom payout scheme. Requires:
    • payoutScheme: A description of the custom payout method (e.g., "Pays 50% of rewards every 1st of the month").
• website: The URL of your validator's website or any similar source of information (Telegram pinned message, Discord...)
• logo: A logo in SVG or PNG format (min size: 224x224px) with a transparent background, encoded in Base64 to represent your validator. Background colors should be avoided unless they ensure clear contrast.
• contact: At least one contact allowing validators to share contact details so users can easily get in touch.
  • email
  • telegram (optional). e.g. @nimiq
  • twitter (optional). e.g. @nimiq
  • discordInvitationUrl (optional). A URL to your Discord invitation.
  • bluesky (optional). e.g. @nimiq
  • github (optional). e.g. nimiq
  • linkedin (optional). e.g. nimiq
  • facebook (optional). e.g. nimiq
  • instagram (optional). e.g. @nimiq
  • youtube (optional). e.g. nimiq

Validator Trustscore

The VTS is a metric designed to help stakers evaluate the performance and reliability of validators. The VTS provides a transparent way to assess validator behavior, empowering stakers to make informed decisions when choosing where to stake their funds.

The VTS is displayed in the Nimiq Wallet, allowing stakers to compare validators and select the one that best meets their needs.

• Read the docs
• Checkout the pnpm package

Validators API

The Validators API provides endpoints to retrieve validator information for integration with tools, dashboards, and other applications.

Endpoint	Description
/api/v1/validators	Retrieves the validator list. See query params
/api/v1/validators/:validator_address	Retrieves the validator information
/api/v1/supply	Retrieves supply status

Validators Dashboard

The Validators Dashboard is a simple Nuxt application that displays all validators along with their scores. You can access the dashboard here: https://validators-api-mainnet.pages.dev/

Tip

Check also the deployment section to learn how to access to the testnet and preview environments.

How the API works

The API has different endpoints to retrieve information about validators and staking metrics. In the following sections we will focus on how the validators scores are calculated and how the data is stored.

Range

We fetch the data from the last ~9 months to calculate the score. In order to do this, we have a function to calculate the window of epochs to fetch.

• fromXXX: The information for the first block/epoch we consider (~9 months). We have: fromEpoch, fromBlockNumber, fromTimestamp
• toXXX: The information for the last block/epoch we consider. We have: toEpoch, toBlockNumber, toTimestamp
• snapshotXXX: The information for current epoch. (It is not called currentEpoch as this could be missleading when talking about a range that is in the past). We have: snapshotEpoch, snapshotBlockNumber, snapshotTimestamp. If you have a better name, please suggest it.

We also do have an UI component to visualize the range, check the status, and debug.

Fetcher

The fetcher is a process that retrieves data from the Nimiq network and stores it in a D1 database. The fetcher runs every hour and collects data about the validators in two different ways:

Ended epochs

It fetches the data from epochs already ended and stores it in the database the following variables:

• epoch: The epoch number.
• validatorAddress: The address of the validator.
• missed: The number of batches where at least a slot was missed.
• rewarded: The number of batches rewarded.
• likelihood: The probability of being selected to produce a block, calculated by numSlots / SLOTS.
• dominanceViaSlots: Same as likelihood
• dominanceViaBalance: The dominance ratio of the validator, calculated by validatorBalance / totalBalance. Might be -1 if the balance was not fetched when the epoch was active.

Current epoch

It fetches the data from the current active epoch and stores it in the database the following variables:

• epoch: The epoch number.
• validatorAddress: The address of the validator.
• balance: The balance of the validator.
• stakers: The amount of stakers in the validator.

It will also set empty values for missed, rewarded, likelihood, and dominanceViaBalance for the current epoch. This is because the epoch is still active and the data is not available yet. Those fields will be updated once the epoch ends and only if the validator was selected to produce a block, otherwise they will remain untouched.

Types of validators

Type	Elected	Tracked
ElectedTrackedValidator	✅	✅
ElectedUntrackedValidator	✅	❌
UnelectedTrackedValidator	❌	✅
UnelectedUntrackedValidator	❌	❌

Note

Having a UnelectedUntrackedValidator should only happen when the validator has been selected for the first time in history.

Development

Once it is cloned and installed the dependencies, you must run:

pnpm db:generate
pnpm dev # or pnpm dev:local to use the local database

Deployment

The deployment is handled by the NuxtHub Action.

There are 4 different environments:

Nuxt Hub Env	GitHub Env	Dashboard URL	Trigger
production	production-mainnet	Validators API Mainnet	Push to main branch
production	production-testnet	Validators API Testnet	Push to main branch
preview	preview-mainnet	Validators API Mainnet Preview	Push any commit to any branch
preview	preview-testnet	Validators API Testnet Preview	Push any commit to any branch

Each Nuxt Hub environment has its own database, so effectively we have 4 different databases and there are 4 tasks in the sync.yml workflow that are responsible for syncing the data from the Nimiq network to the database.

Write operations to main are restricted, only via PR.