# 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

```bash
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

```bash
# 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)

```bash
# 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)

```bash
# 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).