# lock-stake (/docs/tx/lock-stake)

Commits part of the signing coldkey's alpha on the subnet as locked
stake: the locked amount builds conviction the longer it stays locked.
The lock acts as a subnet-wide floor on unstaking, not a hold on a
specific position — the coldkey can freely unstake anything above the
locked mass, and the locked amount itself keeps earning normally. The
coldkey's total alpha on the subnet, summed across all hotkeys, must
cover the locked amount; conviction can be pointed at one hotkey while
the stake sits on another. If a lock already exists on the subnet, the
hotkey must match the existing lock's hotkey or the call fails with
`LockHotkeyMismatch` — repeat calls only top up the lock; use
`move_lock` to change hotkeys. Whether the lock decays over time or
persists is controlled per coldkey per subnet with
`set_perpetual_lock`.

| Signer    | Pallet          | Wraps                        |
| --------- | --------------- | ---------------------------- |
| `coldkey` | SubtensorModule | `SubtensorModule.lock_stake` |

## Parameters [#parameters]

| Parameter      | Type              | Required | Description                                                                 |
| -------------- | ----------------- | -------- | --------------------------------------------------------------------------- |
| `netuid`       | integer           | yes      | Subnet the locked stake lives on.                                           |
| `amount_alpha` | number \| `"all"` | yes      | How much of the existing stake to lock.                                     |
| `hotkey_ss58`  | string            | no       | Hotkey the lock's conviction is credited to. Defaults to the wallet hotkey. |

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 lock-stake \
  --netuid <int> \
  --amount-alpha <amount|all> --dry-run
btcli tx lock-stake \
  --netuid <int> \
  --amount-alpha <amount|all> -w my_coldkey
```

## Python [#python]

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

wallet = Wallet(name="my_coldkey", hotkey="my_hotkey")
intent = sub.LockStake(netuid=1, amount_alpha=1.0)

async with sub.Client("finney") as client:
    plan = await client.plan(intent, wallet)   # fee, effects, policy — no submission
    result = await client.execute(intent, wallet)
    if not result.success:
        print(result.error.code, result.error.remediation)
```

Or build it by op name, as an agent would:

```python
await client.execute_tool("lock_stake", {...}, wallet)
```