Getting Started

Prerequisites

• Python 3.10–3.14 — check with python3 --version.
• A Bittensor wallet and a Solana keypair — created in Set up your wallets after install.
• A self-custody Bitcoin wallet (only for BTC pairs) — Sparrow or Electrum both work and support testnet. Custodial services won't work: you must sign from your source address to prove ownership.

Install

Always install into a virtual environment — pip install -e . against system Python is brittle and blocked on many setups.

git clone https://github.com/entrius/allways.git
cd allways
python3 -m venv venv
source venv/bin/activate
pip install -e .

TIP

The venv only stays active in the shell where you activated it. Re-run source venv/bin/activate (from inside allways/) in every new terminal where you want alw.

Verify the install and skim the command overview — the note at the foot of the help output covers the usage terms:

alw --help

Set up your wallets

Bittensor wallet

Registers you on the subnet (miners/validators) and sends/receives the TAO leg of swaps. btcli is installed with the CLI above:

btcli wallet new-coldkey --wallet.name <your_bittensor_coldkey>
btcli wallet new-hotkey --wallet.name <your_bittensor_coldkey> --wallet.hotkey <your_bittensor_hotkey>

Save both mnemonics. Keys live in ~/.bittensor/wallets/ — see Bittensor wallets for more.

Solana keypair

Every on-chain action (reservations, collateral, quotes, votes) is signed by a Solana keypair — separate from your Bittensor wallet. The CLI reads ~/.solana/id.json by default (override with SOLANA_KEYPAIR_PATH or alw config set solana-keypair <path>).

Install the Solana CLI (provides solana-keygen and solana), then create the key:

sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"
export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"   # or open a new shell

solana-keygen new -o ~/.solana/id.json     # SAVE the seed phrase it prints
solana-keygen pubkey ~/.solana/id.json     # the address to fund

Fund it before use — every action pays a Solana fee, each reservation pays the reservation fee (base 0.02 SOL, stake-discounted when routed), and miners post SOL collateral (even a miner backing its quotes with a TAO bond posts a small one-time SOL identity deposit to bind — see the Miner Guide).

FUND IT FIRST — AND POINT AT THE RIGHT KEY

If no keypair exists, the CLI auto-generates an empty one at ~/.solana/id.json on first use — an unfunded key fails with Attempt to debit an account but found no record of a prior credit. Confirm solana-keygen pubkey matches the address you funded.

One-off signing with a different key: SOLANA_KEYPAIR_PATH=~/.config/solana/mykey.json alw miner activate. Back up every id.json — it holds your collateral and is your on-chain identity. Use a dedicated key per role, never one holding personal funds.

TESTNET FAUCETS

Asset	Faucet
SOL (devnet)	solana airdrop 2 <pubkey> --url https://api.devnet.solana.com · faucet.solana.com
TAO (test)	taoswap.org/testnet-faucet
BTC (testnet4)	mempool.space/testnet4/faucet · faucet.testnet4.dev — testnet3 faucets won't fund testnet4
every other spoke	its own network's faucet (Sepolia, Fuji, Amoy, …)

Configure

Mainnet (Finney) — the live network

alw config set env mainnet   # bittensor finney + every chain's mainnet + netuid 7 (self-represented)
alw config set wallet <your_bittensor_coldkey>
alw config set hotkey <your_bittensor_hotkey>

Testnet

alw config set env testnet   # bittensor test + every chain's testnet + netuid 19 + router (Ventura Labs)
alw config set wallet <your_bittensor_coldkey>
alw config set hotkey <your_bittensor_hotkey>

Wallet/hotkey are the local names from Set up your wallets, not addresses — btcli w list shows them.

INFO

The Solana program id is the same on mainnet and testnet — only the network differs. First swap? Dry-run on testnet before moving real funds.

Networks resolve from names — no RPC URLs to copy. env sets every chain at once; override one with alw config set <chain>-network <name> (alw config set --help lists them). Recommended: a keyed Solana RPC (alw config set solana-rpc <url> or SOLANA_RPC_URL) — unkeyed public endpoints rate-limit.

Check your configuration:

alw config

Verify

alw status

Shows your network connection, balances, active swaps, and miner status.

Next Steps

• Swap Guide — perform your first swap
• How It Works — the system design
• Incentive — how miners earn: the crown, strikes, capacity, pools
• Miner Guide — run a miner and earn from the rate spread
• Validator Guide — secure the network as a validator
• CLI Reference — complete command reference