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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.xverse.app/xverse-agentic-wallet/capabilities/spark-and-lightning.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.