Swap Guide

PREFER A UI? USE ALLWAYS ACCESS

You don't need the CLI to swap. Allways Access is the hosted exchange app run by the Ventura Labs validator — sign in with Google, GitHub or an anonymous access key, fund credits, and swap in the browser without running any software. The rest of this guide is the CLI path.

Prerequisites

• Run alw --help to verify your install — see Getting Started for setup.
• A funded Solana keypair — every reservation settles on Solana and pays a 0.02 SOL fee (admin-tunable; check the live value with alw view config), even when neither leg is SOL.
• Funds on your source chain.

Every pair is hub↔spoke with SOL or TAO as the hub, so every swap moves a hub asset on one leg. See the full pair list.

Who broadcasts the source funds

alw swap now reserves a miner and prints where to send. By default it then sends for you on an interactive terminal (--send) and only prints the instructions in a script (--no-send). Sending it yourself always works: a plain transfer from the exact address you named, never an exchange withdrawal, then relay the tx hash with alw swap post-tx <hash>. For a SOL source, the reservation pins your CLI Solana keypair as the sender — send from that exact key.

YOUR WALLET MUST SURFACE THE TXID

The txid is the only thing validators can verify your send by — if you can't paste it into alw swap post-tx <hash>, the reservation expires. Confirm your wallet shows txids before you reserve. Avoid custodial senders: validators also require the sender address to match the one your reservation pinned.

Every quote declares its backing

A miner backs each quote with either SOL collateral (held on Solana) or a TAO bond (held in an immutable vault on Bittensor). There is one market per pair — quotes of both backings mix in the same list, ranked by rate — and you pick by rate, as ever. What the backing changes is the failure guarantee the quote carries:

• SOL-backed quote — if the miner fails to deliver, you get an instant SOL refund from the miner's on-chain collateral.
• TAO-backed quote — you are reimbursed in TAO from the miner's bond, shortly after the timeout — validators carry the timeout verdict to the vault and reach quorum there before it pays.

The difference is timing only: either way you are made whole from the bond that backed the quote. (Testnet start: TAO-backed swaps run 0.1–1 τ per swap.)

Previewing rates

Compare miners without committing:

alw swap quote --from btc --to sol --amount 0.001

This shows every miner quoting that direction, their rate, and what you'd receive after the 1% fee. Rows whose collateral can't cover your amount, or that fall outside the backing's min_swap / max_swap bounds, are flagged — those wouldn't be accepted on-chain.

To swap with a specific miner from that list, pass its pubkey to alw swap now --miner <pubkey> — or bare --miner to choose from a numbered list of viable miners.

Running a swap

alw swap now prompts for anything you omit on an interactive terminal. In a script, name the direction, amount, and addresses up front:

alw swap now \
  --from btc --to sol \
  --amount 0.001 \
  --from-address tb1qYourBtcAddr \
  --receive-address YourSolanaPubkey \
  --yes

What it does:

1. Picks the best miner quoting your direction that can cover your amount (or the one you pinned with --miner), and shows the estimated receive after the 1% fee.
2. If the miner's pool is already open and contested, it tells you before you pay: how many entries, when the window closes, and your odds (or that a validator is in the pool, which an unrouted user essentially can't beat).
3. Enters the miner's pool (pays the reservation fee), cranks and waits out the draw, and — if you won the seat — finalizes your reservation with your amounts at the pinned rate.
4. Prints the miner's deposit address and the exact amount to send, then sends it for you (--send) or leaves it to you. Either way the hash is relayed immediately with alw swap post-tx <hash> — validators verify and initiate.

Re-running alw swap now is safe: if you already hold a drawn seat or a live reservation on that miner, it resumes it instead of paying for a second entry.

One limit to know for back-to-back swaps: the contract enforces one live reservation per (miner, source chain, source address). A second swap through the same miner, funded from the same source address, is rejected until the previous reservation's window — including any extension validators granted while confirmations accrued — has run out, even if that swap already completed. Rapid sequential swaps: use a different source address, pick another miner, or wait out the window.

Track it through completion:

alw view swap <swap_key> --watch

sol→btc swaps wait on Bitcoin confirmations (~20 min for the destination leg); btc→sol waits on the BTC source confirmations. ETH legs wait 32 Ethereum confirmations (~6–7 min). SOL/TAO legs settle in seconds — a sol↔tao swap completes in ~2–3 minutes end to end.

Flag	What it sets
--from	Source asset, by wire id — the pair list has every one
--to	Destination asset — what you receive; one leg must be a hub
--amount	Amount to send, in source-chain units
--from-address	Your source-chain address — the one you will send from (required for a non-SOL source); validators reject a deposit from any other sender
--receive-address	Your destination-chain address — where the miner sends your funds
--from-tx-hash	Source tx hash, if you've already broadcast the send
--miner	Pin a miner instead of auto-selecting; bare --miner opens a picker
--send / --no-send	Broadcast the source funds for you, then relay and watch (default: on for a terminal, off for a script)
--yes	Skip the confirmation prompt

Every pair must include a hub leg, SOL or TAO — the CLI rejects a direction without one.

What the reservation step does

Between picking a miner and sending funds, the CLI runs the reservation lottery:

1. Enter the pool — open_or_request enters you into the miner's pool and pays the non-refundable reservation fee (base 0.02 SOL; a routed entry pays less — the router's stake weight discounts it, up to 95% off). The first entry pins the miner's rate for the pool window.
2. Draw — after the window closes, a stake-weighted lottery picks the winner. The CLI cranks it for you and polls for the result.
3. Finalize — if you won the seat, the CLI names your amounts on-chain, making the reservation live. Only then does it tell you to send funds.

Once live, the reservation holds the miner exclusively — no one else can reserve them, and they can't withdraw or deactivate — until the swap completes or the reservation TTL (8 min on mainnet, 10 on testnet) expires. Inspect it any time:

alw view reservation

SEND THE EXACT AMOUNT, WHILE THE RESERVATION IS LIVE

There is no escrow on the source leg — your deposit goes straight to the miner, and only the reservation ties it to a swap. Send the exact pinned amount, from the pinned sender address, while the reservation is live: a deposit that lands after expiry matches nothing and isn't refundable on-chain. The CLI refuses to instruct a send when too little TTL remains — but once you broadcast, landing in time is on your transaction. For BTC, use a sane fee rate and RBF upward if your tx is stuck as expiry approaches.

SELF-REPRESENTED vs ROUTED

With a router configured (alw config set env testnet sets the Ventura Labs validator; alw config set env mainnet clears the key, so mainnet self-represents until you set one; alw config set router <hotkey> picks your own), alw swap now is validator-routed: the validator enters the pool with its stake weight, pays the entry fee, and finalizes the won seat with you pinned — you just wait for the reservation to go live. --no-router (or an empty router) self-represents: you are your own router — no validator involved, but zero draw weight, so a validator in the same pool wins. Self-representing stays fine for developers, agents, and low-contention miners.

Self-representing skips the router, not the rules: the contract enforces the same reservation invariants directly — your destination address can't be the miner's own delivery address, and the one-reservation-per-source-address limit above applies — and validators re-check the address rules before attesting, so a reservation that dodges them on a technicality (an address-casing variant, say) simply never initiates.

Do NOT send funds while a routed swap is still waiting — only send once the CLI shows your live reservation. Early deposits fail the validators' freshness checks and are not recoverable.

Worked example: BTC → SOL

Step 1 — reserve. The CLI enters the pool, wins the draw, finalizes, then displays the miner's BTC address and the exact amount:

alw swap now --from btc --to sol --amount 0.001 \
  --from-address tb1q... --receive-address <your-sol-pubkey>

Step 2 — send the exact amount from your wallet (the one at --from-address), then relay the hash immediately — do not wait for confirmations:

alw swap post-tx <your_btc_txid>

Deferred confirmation means validators accept the seen-but-unconfirmed deposit and wait out the ~2 BTC confirmations server-side, extending your reservation while they accrue. Sleeping before post-tx is how you lose the reservation.

Resuming a swap

If the flow was interrupted after the reservation:

alw view reservation          # 1. still live?
alw swap now --from ... --to ...   # 2. if live, re-run with the same direction — it resumes your seat instead of paying again
# already sent the funds? just submit the hash:
alw swap post-tx <hash>
# 3. if expired, start a new swap — nothing is lost but the reservation fee

Tracking your swap

Command	Description
alw view swap <key> --watch	Live tracking until completion
alw view swap <key>	One-time view with timeline + tx hashes
alw status	Quick dashboard — balances, active swaps, reservations
alw view active-swaps	All swaps on the contract

Status progression:

Status	Meaning
PendingAttestation	Deposit relayed, validators verifying + about to initiate
Active	Swap initiated, waiting for the miner to deliver
Fulfilled	Miner delivered, validators verifying both legs
Completed	Both legs verified — funds are on the destination chain
TimedOut	Miner failed to deliver — you're reimbursed from the backing the quote declared
Cancelled	Your destination could not receive — no slash and no refund (see below)

On the dashboard

Everything above is also on the Allways dashboard (testnet: test.all-ways.io). The CLI and dashboard read the same on-chain events, so they always agree.

If something goes wrong

Miner doesn't deliver: the swap times out after the fulfillment deadline and you're reimbursed from the backing the quote declared. A SOL-backed quote pays you 1.1× the swap's SOL value from the miner's collateral — instantly, automatically, at your reservation's pinned Solana identity. A TAO-backed quote reimburses you in TAO from the miner's bond shortly after the timeout, once validators carry the verdict to the vault and reach quorum there. (If a payout looks missing, check alw view swap <swap_key>.)

Swap Cancelled: validators proved your destination cannot receive — a blacklisted or paused token, a contract that reverts a correctly-gassed transfer, a reserved Solana account. The miner is not at fault, so nothing is slashed and nothing is refunded: your source funds stay with them. Check the receive address is a plain, unfrozen account before you send.

Lost the draw: someone else won the seat — the CLI names the winner. Self-represented, your 0.02 SOL reservation fee is spent (it's non-refundable, win or lose); routed, the router paid the entry fee, so nothing left your wallet. No other funds moved either way. Re-run to enter the next round, or pick a less contested miner.

Reservation expired: the miner auto-unlocks. Start a new swap — you only forfeit the 0.02 SOL reservation fee.

INFO

Your funds are protected by the backing the quote declared. Every quote is answered by a specific bond — SOL collateral on Solana or a TAO bond on Bittensor — posted before the miner can be reserved; if they fail to deliver, you're made whole from it.

For full command details, see the CLI Reference.