> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openagents.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Spark

> Spark wallet CLI commands verified in local testnet/regtest runs.

## Overview

This page lists only the Spark CLI commands that were **personally verified** to
work in local testing. Commands not listed here were **not verified** in this
pass and are intentionally omitted.

## Verification scope

* **Date:** January 28, 2026
* **Environment:** local dev build via `cargo run -p openagents-cli --bin oa -- ...`
* **Network:** `testnet` (Spark SDK maps testnet/signet to regtest)
* **Auth:** `SPARK_MNEMONIC` set to a BIP39 seed; no API key required for regtest

## CLI entrypoints

Both binaries behave the same:

* `openagents`
* `oa`

Examples below use `oa`.

## Verified commands

### Key management

```bash theme={null}
oa spark new --words 12 --no-private --json
```

```bash theme={null}
oa spark derive --mnemonic "word1 ... word12" --json
```

```bash theme={null}
oa spark derive --mnemonic "word1 ... word12" --no-private --json
```

```bash theme={null}
oa spark seed --mnemonic "word1 ... word12" --json
```

```bash theme={null}
oa spark pubkey --private-hex <32-byte-hex> --json
```

### Wallet basics

```bash theme={null}
oa spark wallet info --ensure-synced --json
```

```bash theme={null}
oa spark wallet balance --json
```

```bash theme={null}
oa spark wallet network --timeout-secs 5 --json
```

```bash theme={null}
oa spark wallet disconnect --json
```

### Receive

```bash theme={null}
oa spark receive --method spark-address --json
```

```bash theme={null}
oa spark receive --method spark-invoice --amount 1000 --description "test" --json
```

```bash theme={null}
oa spark receive --method spark-invoice --amount 1 --token-identifier <token_id> --json
```

```bash theme={null}
oa spark receive --method bolt11 --amount 1000 --description "bolt" --expiry-secs 3600 --json
```

```bash theme={null}
oa spark receive --method bitcoin --json
```

### Send

Send a Spark invoice:

```bash theme={null}
oa spark send <spark_invoice> --json
```

Send a Lightning (BOLT-11) invoice:

```bash theme={null}
oa spark send <bolt11_invoice> --json
```

Send a Spark HTLC transfer:

```bash theme={null}
oa spark send <spark_address> --amount 100 --htlc-payment-hash <sha256> --htlc-expiry-secs 600 --json
```

### Payments

```bash theme={null}
oa spark payments list --limit 5 --json
```

```bash theme={null}
oa spark payments list --limit 1 --asset-filter bitcoin --json
```

```bash theme={null}
oa spark payments get <payment_id> --json
```

### Parse inputs

```bash theme={null}
oa spark parse <bolt11_invoice> --json
```

### Deposits

```bash theme={null}
oa spark deposits list --json
```

### Fiat helpers

```bash theme={null}
oa spark fiat currencies --json
```

```bash theme={null}
oa spark fiat rates --json
```

### Tokens (metadata only)

```bash theme={null}
oa spark tokens metadata <token_id> --json
```

### Message signing

```bash theme={null}
oa spark message sign "hello" --json
```

```bash theme={null}
oa spark message check "hello" <pubkey_hex> <signature_hex> --json
```

### Optimization

```bash theme={null}
oa spark optimize status --json
```

```bash theme={null}
oa spark optimize start --json
```

```bash theme={null}
oa spark optimize cancel --json
```

### Settings

```bash theme={null}
oa spark settings get --json
```

```bash theme={null}
oa spark settings set --spark-private-mode-enabled false --json
```

```bash theme={null}
oa spark settings set --spark-private-mode-enabled true --json
```

## Notes

* Mainnet requires an API key; regtest/testnet does not.
* For wallet commands, you can pass the mnemonic via `--mnemonic`, `--mnemonic-file`, `--stdin`,
  or set `SPARK_MNEMONIC`.
* Commands not listed here were not verified in this pass (e.g., LNURL, lightning address,
  faucet, issuer operations, on-chain claim/refund flows).

## Known issues / unverified commands

* `oa spark wallet sync`: returned `{}` then the process logged a background `h2` panic
  (`state=Closed(ScheduledLibraryReset(CANCEL))`). The command itself returned successfully,
  but this needs investigation in the SDK/runtime.
* `oa spark lightning-address check|get|register|delete`: not verified; CLI failed with
  “LNURL server is not configured”.
* `oa spark lnurl prepare|pay|withdraw`: not verified (no LNURL endpoint available in test env).
* `oa spark faucet`: not verified (faucet auth required).
* `oa spark tokens issuer ...`: not verified; balance returned “No issuer token found”.
* `oa spark deposits claim|refund`: not verified (no unclaimed deposits available).
* `oa spark send --token-identifier ...`: not verified; token send failed with
  “No payment created from token invoice”.