Add README with command reference and Dune CLI credit

README.md

@@ -0,0 +1,80 @@
+# Sparkscan CLI
+
+A command-line interface for interacting with the [Sparkscan](https://sparkscan.io/) API.
+
+Inspired by the [Dune CLI](https://github.com/duneanalytics/cli/tree/main).
+
+## Installation
+
+```bash
+curl -sSfL https://raw.githubusercontent.com/refrakts/sparkscan-cli/main/install.sh | bash
+```
+
+Or install with Go:
+
+```bash
+go install github.com/refrakts/sparkscan-cli/cmd@latest
+```
+
+## Authentication
+
+```bash
+# Set via environment variable
+export SPARKSCAN_API_KEY=<key>
+```
+
+The `--api-key` flag is available on all commands to override the environment variable.
+
+## Commands
+
+### `sparkscan address`
+
+Query Spark addresses.
+
+| Command | Description |
+|---------|-------------|
+| `address get <address>` | Get address summary including balances and transaction count |
+| `address tokens <address>` | Get tokens held by an address |
+| `address transactions <address> [--limit] [--offset]` | Get transactions for an address |
+| `address history net-worth <address> [--limit] [--from] [--to] [--cursor]` | Get historical net worth snapshots |
+| `address history sats <address> [--limit] [--from] [--to] [--cursor]` | Get historical sats balance |
+| `address history token <address> <token-identifier> [--limit] [--from] [--to] [--cursor]` | Get historical token balance |
+
+### `sparkscan token`
+
+Query tokens on the Spark network.
+
+| Command | Description |
+|---------|-------------|
+| `token get <identifier>` | Get token details by identifier or search by name |
+| `token holders <identifier> [--limit] [--offset]` | Get top holders of a token |
+| `token transactions <identifier> [--limit] [--offset]` | Get transactions for a token |
+| `token list [--limit] [--cursor] [--sort] [--sort-direction] [--has-icon] [--holder] [--min-holders]` | List tokens with filtering and sorting |
+| `token issuer-lookup [--pubkeys] [--tokens]` | Look up token issuer information |
+| `token metadata --tokens <addresses>` | Fetch metadata for multiple tokens |
+
+### `sparkscan tx`
+
+Query transactions.
+
+| Command | Description |
+|---------|-------------|
+| `tx get <txid>` | Get a transaction by ID |
+| `tx latest [--limit]` | Get the latest network transactions |
+
+### `sparkscan version`
+
+Print the CLI version.
+
+## Global Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--api-key` | Sparkscan API key (overrides `SPARKSCAN_API_KEY`) | |
+| `--base-url` | API base URL | `https://api.sparkscan.io` |
+| `--network` | Network: `MAINNET` or `REGTEST` | `MAINNET` |
+| `-o, --output` | Output format: `text` or `json` | `text` |
+
+## License
+
+[MIT](LICENSE)