# Spark and Lightning

Spark is a Bitcoin L2 that enables instant, low-cost BTC transfers and Lightning Network payments. It's the payment backbone of the Xverse Agentic Wallet — your agent's primary rail for programmatic commerce.

### Why Spark matters for agents

Lightning via Spark is the fastest and cheapest way for an agent to send and receive BTC. Sub-cent fees, sub-second settlement, and native support for creating and paying invoices — making it ideal for machine-to-machine payments, micropayments, and paid API access.

### Check balance

```bash
xverse-wallet spark balance --json
```

> **Note:** `spark balance` automatically claims any pending incoming Spark transfers. Always run it before operations that need Spark BTC.

To check across multiple accounts:

```bash
xverse-wallet spark balance --accounts 0-4 --json
```

### Receive on Spark

```bash
xverse-wallet spark receive --json
```

Returns your Spark address for receiving BTC transfers on the Spark network.

### Send on Spark

Send BTC or tokens instantly on Spark:

```bash
# Preview
xverse-wallet spark send --token BTC --to <spark-address> --amount 0.001 --json

# Execute
xverse-wallet spark send --token BTC --to <spark-address> --amount 0.001 --yes --json
```

#### Options

| Option             | Description                        |
| ------------------ | ---------------------------------- |
| `--token <name>`   | Token to send (e.g. `BTC`, `USDB`) |
| `--to <address>`   | Destination Spark address          |
| `--amount <value>` | Amount to send                     |
| `--yes`            | Execute (omit for dry run)         |

### Deposit BTC from L1 to Spark

Move BTC from Bitcoin L1 into Spark. Requires 3 block confirmations (\~30 minutes).

```bash
# Deposit
xverse-wallet spark deposit --amount 0.001 --yes --json

# Check deposit status (without --amount shows pending deposits)
xverse-wallet spark deposit --json

# Claim after 3+ confirmations
xverse-wallet spark claim --json
```

### Withdraw BTC from Spark to L1

```bash
xverse-wallet spark withdraw --amount 0.001 --speed fast --yes --json
```

| Option           | Description                                      |
| ---------------- | ------------------------------------------------ |
| `--amount <btc>` | Amount to withdraw                               |
| `--to <address>` | L1 destination (defaults to your native address) |
| `--speed`        | `slow`, `medium`, or `fast`                      |
| `--yes`          | Execute                                          |

### Transaction history

```bash
xverse-wallet spark history --token BTC --json
xverse-wallet spark history --token BTC --offset 10 --limit 5 --json
```

***

### ⚡ Lightning Network

Lightning payments are powered by Spark. You need BTC on Spark to pay or create Lightning invoices.

#### Create a Lightning invoice (receive payments)

```bash
xverse-wallet spark lightning invoice --amount 50000 --memo "Order #1234" --json
```

Returns an encoded BOLT11 invoice string. Give this to the payer.

| Option            | Description                           |
| ----------------- | ------------------------------------- |
| `--amount <sats>` | Invoice amount in satoshis (required) |
| `--memo`          | Optional memo/description             |

#### Estimate a Lightning payment fee

```bash
xverse-wallet spark lightning estimate --invoice <bolt11> --json
```

For zero-amount invoices, specify the amount:

```bash
xverse-wallet spark lightning estimate --invoice <bolt11> --amount 1000 --json
```

#### Pay a Lightning invoice

```bash
# Preview
xverse-wallet spark lightning pay --invoice <bolt11> --json

# Execute
xverse-wallet spark lightning pay --invoice <bolt11> --yes --json
```

| Option               | Description                              |
| -------------------- | ---------------------------------------- |
| `--invoice <bolt11>` | BOLT11 invoice to pay (required)         |
| `--max-fee <sats>`   | Maximum routing fee in sats (default: 5) |
| `--amount <sats>`    | Amount for zero-amount invoices          |
| `--yes`              | Execute payment                          |

#### Lightning funding tips

* You need enough Spark BTC for the **payment amount + routing fee**. A 1-sat payment with `--max-fee 10` needs at least 11 sats on Spark.
* `spark balance` auto-claims incoming transfers — always run it before paying.
* Check all accounts for Spark BTC: `xverse-wallet portfolio --accounts 0-4 --json`
* If needed, consolidate from another account: `xverse-wallet -a 2 spark send --token BTC --to <account-0-spark-addr> --amount 0.0001 --yes --json`