> ## Documentation Index
> Fetch the complete documentation index at: https://yieldxyz.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/guides/earn/staking/stake) 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:

<Steps>
  <Step title="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).
  </Step>

  <Step title="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.
  </Step>
</Steps>

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.

<Note>
  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.
</Note>

### Verified examples

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Tron native staking: validatorAddresses, enter only">
    `tron-trx-native-staking` requires `validatorAddresses` (array) plus `tronResource` on `enter`; `exit` takes only `amount`, no validator field.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Cardano: validatorAddress on enter only">
    `cardano-ada-native-staking` requires `validatorAddress` on `enter`; its exit schema has no validator field at all.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Fetch and choose a validator

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

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```typescript TypeScript theme={null}
  const params = new URLSearchParams({ preferred: 'true', status: 'active' });
  const res = await fetch(
    `https://api.yield.xyz/v1/yields/solana-sol-native-multivalidator-staking/validators?${params}`,
    { headers: { 'x-api-key': process.env.YIELD_API_KEY! } },
  );
  const { items } = await res.json();
  ```
</CodeGroup>

```json Response (excerpt) theme={null}
{
  "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](/documentation/earn/staking/validators/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](/api-reference/YieldsController_getYieldValidators) 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](/guides/earn/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](/documentation/earn/staking/validators/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](/documentation/earn/staking/validators/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](/documentation/advanced-setup/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

<Columns cols={2}>
  <Card title="Stake a token" icon="coins" href="/guides/earn/staking/stake">
    Plug validator selection into the full enter, sign, submit, and track flow.
  </Card>

  <Card title="Preferred validators" icon="star" href="/documentation/earn/staking/validators/preferred-validators">
    The full ValidatorDto shape and how PVN validators are curated.
  </Card>

  <Card title="Bring your own node" icon="server" href="/documentation/earn/staking/validators/bring-your-own-node">
    Route delegations to validators you operate.
  </Card>

  <Card title="Actions" icon="bolt" href="/documentation/earn/core-concepts/actions">
    The full action and argument-schema model.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.