# claim-root (/docs/tx/claim-root)

Root dividends accrue as shares of each validator's basket — an
escrowed index fund of subnet alpha the chain builds from the validator's
root dividends per its root weights (see `set_root_weights`). This call
redeems the signing coldkey's owed shares on every validator it
root-stakes to. The `subnets` argument is retained for call-data
compatibility with pre-basket clients and is ignored — baskets have no
per-subnet claim selection.

Prefer :class:`ClaimRootWithHotkey` to claim a single validator.

`plan` (and `btcli root claim --dry-run`) estimates the reserved
inclusion fee versus the fee that will actually settle, compares that
spent fee to accrued yield, warns when the claim loses money, and
refuses when free TAO cannot cover the reserve.

| Signer    | Origin                                 | Pallet          | Wraps                                                                                        |
| --------- | -------------------------------------- | --------------- | -------------------------------------------------------------------------------------------- |
| `coldkey` | signed account (pallet role may apply) | SubtensorModule | [`SubtensorModule.claim_root`](/code/pallets/subtensor/src/macros/dispatches.rs#L1965-L1990) |

## Parameters [#parameters]

| Parameter | Type             | Required | Description                                                                                                      |
| --------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `subnets` | array of integer | no       | Ignored (kept for old-client call-data compatibility). Pass any non-empty netuid list; baskets claim fund-level. |

Address parameters (`--hotkey`, `--coldkey`, `--dest`, ...) accept a raw ss58
address, an address-book or proxy-book name, or a local wallet/hotkey name.

## CLI [#cli]

Preview with `--dry-run` (shows fee, effects, and policy result without
submitting), then submit:

```bash
btcli tx claim-root --dry-run
btcli tx claim-root -w my_coldkey
```

## Python [#python]

```python
import bittensor as bt
from bittensor.wallet import Wallet

wallet = Wallet(name="my_coldkey", hotkey="my_hotkey")
intent = bt.ClaimRoot()

sub = bt.Subtensor()
plan = sub.plan(intent, wallet)   # fee, effects, policy — no submission
result = sub.execute(intent, wallet)
if not result.success:
    print(result.error.code, result.error.remediation)
```

(`bt.Subtensor` is also the async client — `async with bt.Subtensor() as client:`
— see [The client](/docs/concepts/client).) Or build the intent by op name, as
an agent would:

```python
result = sub.execute_tool("claim_root", {...}, wallet)
```

## On-chain implementation [#on-chain-implementation]

`SubtensorModule.claim_root` — [`pallets/subtensor/src/macros/dispatches.rs#L1972`](/code/pallets/subtensor/src/macros/dispatches.rs#L1965-L1990):

```rust
#[pallet::call_index(121)]
// Signer is not in the call data, so admission uses the conservative
// MAX_ROOT_CLAIM_WORK envelope. Execution refuses a fat coldkey that
// would exceed it — use claim_root_with_hotkey per validator.
#[pallet::weight(
    <T as crate::pallet::Config>::WeightInfo::claim_root(Pallet::<T>::root_claim_declared_work())
)]
pub fn claim_root(
    origin: OriginFor<T>,
    subnets: BTreeSet<NetUid>,
) -> DispatchResultWithPostInfo {
    let coldkey: T::AccountId = ensure_signed(origin)?;
    let _ = subnets; // ignored: basket claims are fund-level, not per-subnet

    let hotkeys = StakingHotkeys::<T>::get(&coldkey);
    ensure!(
        Self::root_claim_fits_declared_budget(&hotkeys),
        Error::<T>::RootClaimTooHeavy
    );
    let hotkey_count = hotkeys.len() as u32;
    let outcome = Self::do_root_claim(coldkey.clone(), hotkeys)?;
    Self::maybe_add_coldkey_index(&coldkey);

    let weight = Self::root_claim_actual_weight(hotkey_count, &outcome);
    Ok((Some(weight), Pays::Yes).into())
}
```

Delegates to [`root_claim_fits_declared_budget`](/code/pallets/subtensor/src/staking/claim_root.rs#L769), [`do_root_claim`](/code/pallets/subtensor/src/staking/claim_root.rs#L806), [`maybe_add_coldkey_index`](/code/pallets/subtensor/src/staking/claim_root.rs#L835).

Every file is browsable under [/code](/code) exactly as built into the runtime, or as plain text under `/code/raw/<path>` (index: [`/code/index.json`](/code/index.json)).