Validator selection

Decide whether a staking yield needs a validator, fetch candidates, and pass the right argument name into enter.

Before you call POST /v1/actions/enter on a staking yield, work out whether it needs a validator at all, and if it does, which argument name carries it. This guide covers the decision, the validators endpoint, and how Preferred validators, Bring your own node, and Whitelabel nodes differ.

Prerequisites

• A yield.xyz API key, sent as x-api-key on every request.
• A staking yield’s full metadata from GET /v1/yields/{yieldId}. See Stake a token for the full discover, inspect, enter loop this guide plugs into.

Decide whether a validator applies

Read two fields from the yield object, in order:

1. Check mechanics.requiresValidatorSelection

   true means the yield delegates to validators you choose; false means it doesn’t, either because the provider assigns one internally or because selection doesn’t apply (a liquid-staking token, a pooled product with no per-validator choice).

2. Read mechanics.arguments.{enter,exit}.fields for the exact argument

   requiresValidatorSelection only tells you whether selection happens somewhere in the flow, not on which action or under what name. The argument schema is authoritative: look for a field named validatorAddress or validatorAddresses in mechanics.arguments.enter.fields, .exit.fields, or a mechanics.arguments.manage entry, and check its own required flag.

Three outcomes follow:

Outcome	What you see in the schema	Example
Validator required, you choose it	validatorAddress or validatorAddresses marked required: true on enter (often on exit too)	Solana native multi-validator staking, Cosmos SDK chains, Tron, Polkadot and Kusama validator staking
Provider assigns the validator	No validator field on enter; validatorAddress required: true on exit only	Ethereum native staking via Figment, P2P, Luganodes, Validation Cloud
Not applicable	No validator field on either action	Liquid staking (Lido stETH), most pooled products

A field named validatorAddress takes one address; validatorAddresses takes an array. Send exactly the field name the schema gives you, nothing more generic: passing validatorAddress where the schema names validatorAddresses (or the reverse) fails the request.

Some yields route a pool’s own address through the singular field. Polkadot and Kusama pool staking, and TON’s nomination-pool staking, both require validatorAddress, but the value you pass is the pool’s address, not an individual validator’s. Cardano requires validatorAddress on enter only; its exit schema takes no validator field. Confirm this per yield instead of assuming a pattern.

Verified examples

Solana native staking: validatorAddress, required on enter and exit

solana-sol-native-multivalidator-staking requires validatorAddress (singular) on both enter and exit. Delegating to several validators means one enter call per validator, each producing its own stake account.

Tron native staking: validatorAddresses, enter only

tron-trx-native-staking requires validatorAddresses (array) plus tronResource on enter; exit takes only amount, no validator field.

Polkadot and Kusama validator staking: validatorAddresses on both actions

The substrate validator-staking module requires validatorAddresses (array) on both enter and exit. The separate pool-staking module (polkadot-dot-pool-staking, kusama-ksm-pool-staking) instead requires the singular validatorAddress, carrying the pool’s address, on both actions.

Cardano: validatorAddress on enter only

cardano-ada-native-staking requires validatorAddress on enter; its exit schema has no validator field at all.

Ethereum dedicated-validator staking: no field on enter, validatorAddress on exit

Figment, P2P, Luganodes, and Validation Cloud native ETH staking take no validator field on enter; the provider assigns the validator. exit requires validatorAddress (Figment and Validation Cloud also require signatureVerification) to identify which validator to exit from.

Fetch and choose a validator

When the schema requires a validator, call GET /v1/yields/{yieldId}/validators before building the enter request:

cURL

curl --request GET \
  --url 'https://api.yield.xyz/v1/yields/solana-sol-native-multivalidator-staking/validators?preferred=true&status=active' \
  --header "x-api-key: $YIELD_API_KEY"

Response (excerpt)

{
  "items": [
    {
      "address": "7XG...vote",
      "name": "Example Validator",
      "commission": 0.05,
      "status": "active",
      "preferred": true,
      "votingPower": 0.013
    }
  ]
}

The endpoint accepts name, address, provider, status, and preferred as filters, plus offset and limit for pagination. Filtering status=active (or checking the field client-side) excludes validators the API reports as jailed, deactivating, inactive, full, or not_found, so you don’t offer a delegation target that will fail on-chain. preferred=true narrows the list to yield.xyz’s Preferred validators. address is the value you pass back as validatorAddress or one entry of validatorAddresses; use commission and, where present, rewardRate to help the user compare candidates. See the validators endpoint reference for the full ValidatorDto shape.

Changing validators later

Most yields have no in-place validator change: exit the position from the current validator, then enter again with a different validatorAddress (or validatorAddresses), following the same schema-driven flow as the initial enter.

Cosmos SDK native staking is the exception. An active balance there can carry a RESTAKE pending action that redelegates it to another validator without unbonding first. Run it through POST /v1/actions/manage with action: "RESTAKE", the balance’s passthrough unchanged, and the destination validator as validatorAddress in arguments. Look for RESTAKE in the balance’s pendingActions (not RESTAKE_REWARDS, which restakes rewards) before falling back to exit and re-enter. See Tracking balances for running pending actions.

Preferred validators vs bring your own node vs whitelabel nodes

These are three ways to route delegations, not variations on the same flow. Preferred validators are yield.xyz’s curated, pre-vetted set: filter to preferred=true and pass one straight into validatorAddress, no setup required. Bring your own node routes delegations to validator addresses you already operate; you still discover and pass the address the same way, but it resolves to your own infrastructure. Whitelabel nodes go further: yield.xyz deploys and operates a dedicated validator under your brand, arranged directly with yield.xyz rather than through the API. Use Preferred validators by default, Bring your own node when you already run infrastructure, and Whitelabel nodes when you want branded infrastructure without operating it yourself.

Next steps

Stake a token

Plug validator selection into the full enter, sign, submit, and track flow.

Preferred validators

The full ValidatorDto shape and how PVN validators are curated.

Bring your own node

Route delegations to validators you operate.

Actions

The full action and argument-schema model.