🔄Swaps

🔄 Swaps

Swap any asset across any supported chain — Bitcoin ↔ Starknet, Bitcoin ↔ Spark, Starknet ↔ Starknet, Runes ↔ BTC, and more. The CLI routes through integrated DEXes including AVNU (Starknet), Flashnet (Spark), Dotswap, and Sats Terminal (Runes).

Token format

Tokens are specified as protocol:ticker or protocol:contract.name:

Token	Example
Bitcoin BTC	bitcoin:BTC
Spark BTC	spark:BTC
Rune (by ID)	runes:840000:3
Starknet WBTC	starknet:WBTC
Starknet STRK	starknet:STRK
Starknet USDC	starknet:USDC
Stacks STX	stacks:STX
Stacks sBTC	stacks:SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token

Get a quote

xverse-wallet swap quote --from bitcoin:BTC --to starknet:WBTC --amount 0.01 --json

Returns quotes from all available providers with rates, fees, and estimated output.

Options

Option	Description
--from <token>	Source token (required)
--to <token>	Destination token (required)
--amount <value>	Amount of the source token
--provider <code>	Filter by specific provider

Execute a swap

# Preview
xverse-wallet swap execute --from bitcoin:BTC --to starknet:WBTC --amount 0.01 --json

# Execute (auto-selects best quote)
xverse-wallet swap execute --from bitcoin:BTC --to starknet:WBTC --amount 0.01 --yes --json

Options

Option	Description
--from <token>	Source token (required)
--to <token>	Destination token (required)
--amount <value>	Amount of the source token
--provider <code>	Use a specific provider
--slippage <pct>	Slippage tolerance (percentage)
--fee-rate <rate>	Fee rate for Bitcoin L1 transactions
--yes	Execute (omit for dry run)

Common swap routes

Same-chain (instant, seconds)

# Starknet ↔ Starknet
swap quote --from starknet:STRK --to starknet:WBTC --amount 100 --json
swap quote --from starknet:USDC --to starknet:WBTC --amount 100 --json

# Spark ↔ Spark
swap quote --from spark:BTC --to spark:USDB --amount 0.001 --json

Cross-chain (minutes — involves BTC L1 confirmations)

# Bitcoin ↔ Starknet
swap quote --from bitcoin:BTC --to starknet:WBTC --amount 0.005 --json
swap quote --from starknet:WBTC --to bitcoin:BTC --amount 0.005 --json

# Bitcoin ↔ Stacks
swap quote --from bitcoin:BTC --to stacks:STX --amount 0.01 --json

# Bitcoin ↔ Spark
swap quote --from bitcoin:BTC --to spark:BTC --amount 0.001 --json

# Runes ↔ BTC
swap quote --from runes:840000:3 --to bitcoin:BTC --amount 1000 --json

Tip: Prefer same-chain swaps when possible — they settle in seconds. Cross-chain routes involving Bitcoin L1 require block confirmations (~10-30 minutes).