# add-collateral (/docs/tx/add-collateral)

Tops up the hotkey's registration collateral on the subnet — for example
to meet a validator-published per-machine requirement on resource
subnets. Prefers free alpha already staked on that hotkey and only buys
the shortfall with TAO from the coldkey. The signing coldkey must own
the hotkey. The locked alpha is real stake (it appreciates with the
subnet pool) but is not withdrawable: it is released back to free stake
through earned emission at the drain ratio snapshot the hotkey already
carries, survives deregistration, and is credited against the collateral
requirement on re-registration. There is no direct withdrawal path —
see `set_min_collateral` for maintaining a level without re-locking
drained funds.

Any TAO→alpha buy is fill-or-kill against `rate_tolerance` above spot
and must be submitted MEV-shielded — collateral purchases are not allowed
to clear unshielded at an unbounded AMM price.

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

## Parameters [#parameters]

| Parameter        | Type              | Required | Description                                                                                                                                            |
| ---------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `netuid`         | integer           | yes      | Subnet to lock collateral on.                                                                                                                          |
| `amount_alpha`   | number \| `"all"` | yes      | Alpha of collateral to add. Uses free stake on the hotkey first; only the shortfall is bought with TAO (that remainder must meet the staking minimum). |
| `hotkey_ss58`    | string            | no       | Miner hotkey the collateral attaches to. Defaults to the wallet hotkey.                                                                                |
| `rate_tolerance` | number            | no       | Maximum price move slippage protection accepts, as a fraction (0.05 = 5%). Ignored when slippage protection is disabled.                               |

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 add-collateral \
  --netuid <int> \
  --amount-alpha <amount|all> --dry-run
btcli tx add-collateral \
  --netuid <int> \
  --amount-alpha <amount|all> -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.AddCollateral(netuid=1, amount_alpha=1.0)

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("add_collateral", {...}, wallet)
```

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

`SubtensorModule.add_collateral` — [`pallets/subtensor/src/macros/dispatches.rs#L2443`](/code/pallets/subtensor/src/macros/dispatches.rs#L2441-L2451):

```rust
#[pallet::call_index(144)]
#[pallet::weight(<T as crate::pallet::Config>::WeightInfo::add_collateral())]
pub fn add_collateral(
    origin: OriginFor<T>,
    netuid: NetUid,
    hotkey: T::AccountId,
    alpha: AlphaBalance,
    limit_price: TaoBalance,
) -> DispatchResult {
    Self::do_add_collateral(origin, netuid, hotkey, alpha, limit_price)
}
```

Delegates to [`do_add_collateral`](/code/pallets/subtensor/src/subnets/collateral.rs#L545).

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)).