swap_stake_limit

Call v233 → v277, v290 → v292, v297 → v298, v301 → v385, v391 → current #90

Swaps stake between subnets with price limit protection.

View calls on chain

Click items to navigate. Pan and zoom to explore.

Used by: stakersvalidatorsanalyticswallets

The Big Picture

Swapping between subnets exchanges Alpha tokens at market rates. For large swaps, this conversion can move against you. swap_stake_limit adds price protection - your swap only executes if you get an acceptable exchange rate. Essential for large stakeholders who can't afford to swap at bad rates during volatile periods.

Why This Matters

A 10,000 TAO swap between subnets with 2% slippage costs 200 TAO. The limit protects you - if the Alpha exchange rate moves too far, your transaction fails. You keep your position and can retry when conditions improve.

Example Scenario

You have 1000 Alpha on subnet 1 and want to move to subnet 3. Current rate is 1.0. You'll accept 0.98 (2% slippage) but not worse. Call swap_stake_limit(origin_netuid=1, dest_netuid=3, amount=1000, limit_price=0.98, allow_partial=false). If rate is 0.99, you get 990 Alpha on subnet 3. If rate is 0.95, transaction fails - your subnet 1 Alpha stays put.

Common Questions

How do I determine the right limit price?
Check current Alpha prices for both subnets. The effective rate is origin/destination. Add a buffer for acceptable slippage (1-3% typical). Set limit at your floor.
When should I use allow_partial?
If you need to move some stake even at worse rates, use allow_partial=true. For all-or-nothing moves (better for large rebalances), use false.
Is this more expensive than regular swap_stake?
Slightly higher gas for the limit check logic, but negligible. The protection is worth far more than the extra fee.

Use Cases

  • Rebalance between subnets with slippage protection
  • Large subnet position moves without excessive price impact
  • Algorithmic rebalancing with guaranteed price floors
  • Protect against unfavorable Alpha exchange rates during subnet swaps

From Chain Metadata

Swaps a specified amount of stake from one subnet to another, while keeping the same coldkey and hotkey.

Input Parameters

#NameTypeDescription
0
hotkey
AccountId hotkey: Account address (32 bytes, SS58-encoded) (hex -> SS58)
1
origin_netuid
u16 NetUidorigin_netuid: Subnet ID (u16, 0-65535)
2
destination_netuid
u16 NetUiddestination_netuid: Subnet ID (u16, 0-65535)
3
alpha_amount
u64 AlphaBalancealpha_amount: Alpha amount in alpha-RAO (÷10⁹ for alpha) (RAO -> TAO (/ 10^9))
4
limit_price
u64 TaoBalancelimit_price: TAO amount in RAO (÷10⁹ for TAO) (RAO -> TAO (/ 10^9))
5
allow_partial
bool allow_partial (bool)

Permissions

Origin
Signed
Required Role
Any

Permission data inferred from metadata. May be incomplete.

Requirements

  • Has stake on origin subnet
  • Price meets limit requirement
  • Destination subnet exists and hotkey is registered

Effects

Events Emitted

StakeSwapped

Postconditions

  • Stake swapped at acceptable price
  • Alpha exchanged between subnet pools

Side Effects

  • Partial fill possible if allow_partial is true
  • Fill-or-kill if allow_partial is false

Possible Errors

NotEnoughStaketoWithdrawNotEnoughStakeNotEnoughStakeToWithdrawNotEnoughStakeToSetWeightsStakeToWithdrawIsZeroNotEnoughStakeToSetChildkeysNotEnoughBalanceToStakeStakeAlreadyAddedStakeRateLimitExceededUnstakeRateLimitExceededStakeTooLowForRootBelowStakeThresholdNomStakeBelowMinimumThresholdCannotUnstakeLockStakeUnavailableZeroMaxStakeAmountSameAutoStakeHotkeyAlreadySetAddStakeBurnRateLimitExceededInsufficientStakeForLock

Code Examples

import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443

const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);

// Build swap_stake_limit call (typed, named args)
const hotkey = "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY";
const origin_netuid = 1;
const destination_netuid = 1;
const alpha_amount = 1_000_000_000n;
const limit_price = 0n;
const allow_partial = true;

const tx = api.tx.SubtensorModule.swap_stake_limit({
  hotkey,
  origin_netuid,
  destination_netuid,
  alpha_amount,
  limit_price,
  allow_partial,
});

On-Chain Activity

Usage Frequency
●●●○○○ Moderate 10K–100K extrinsics

Occasional use

#39 most used call

Success Rate Reliable

80–95% of submissions succeed

As of block 7,429,232

Version History

v233 block 4,920,350 6 args
v290 block 5,947,548 6 args
v297 block 6,067,943 6 args
v301 block 6,205,194 6 args
v391 block 7,782,857 6 args Current

Runtime Info

View Source
Pallet Index
7
Call Index
90
First Version
v233
Current Version
v411
Back to SubtensorModule Calls