> For the complete documentation index, see [llms.txt](https://docs.spacecoin.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.spacecoin.org/spacerouter-proxy/service-user-guide/cli.md).

# CLI

### Install

```bash
pip install spacerouter
```

The Python package ships with the `spacerouter` command. Verify it's on your `PATH`:

```bash
spacerouter --version
```

### Environment

Most commands read defaults from these environment variables:

| Variable                     | Used by                                  |
| ---------------------------- | ---------------------------------------- |
| `SR_GATEWAY_URL`             | `request` commands                       |
| `SR_GATEWAY_MANAGEMENT_URL`  | `request` commands (challenge endpoint)  |
| `SR_ESCROW_CHAIN_RPC`        | `escrow`, `receipts`                     |
| `SR_ESCROW_CONTRACT_ADDRESS` | `escrow`, `receipts`                     |
| `SR_ESCROW_PRIVATE_KEY`      | `escrow` write commands, `request --pay` |

### `request` — send proxy requests

```bash
spacerouter request get https://httpbin.org/ip --pay --region US --ip-type residential

spacerouter request post https://api.example.com/v1/items --pay \
    -H "Content-Type: application/json" \
    --data '{"name":"widget"}'
```

Sub-commands: `get`, `post`, `put`, `patch`, `delete`, `head`.

#### Common flags

| Flag                 | Purpose                                                                    |
| -------------------- | -------------------------------------------------------------------------- |
| `--pay`              | Sign the request with the SPACE-payment flow (required for paid requests). |
| `--auto-settle`      | After `--pay`, sign and submit the parked Leg 1 receipt in the same step.  |
| `--gateway-url URL`  | Gateway endpoint (overrides `SR_GATEWAY_URL`).                             |
| `--region XX`        | 2-letter ISO country code.                                                 |
| `--ip-type TYPE`     | `residential`, `mobile`, `business`, `hosting`.                            |
| `-H, --header`       | Add a request header (repeat for multiple).                                |
| `-d, --data`         | Request body (string, file, or `@filename`).                               |
| `--timeout SEC`      | Request timeout in seconds.                                                |
| `--output FORMAT`    | `json` (default) or `raw`.                                                 |
| `--follow-redirects` | Follow HTTP redirects.                                                     |

### `escrow` — manage your on-chain balance

#### Read commands

```bash
spacerouter escrow balance <address>
spacerouter escrow token-balance <address>
spacerouter escrow withdrawal-request <address>
spacerouter escrow withdrawal-delay
```

Example output for `balance`:

```json
{
  "address": "0xAbc…",
  "escrow_balance_wei": 50000000000000000000,
  "escrow_balance_space": "50.0"
}
```

#### Write commands (need `--private-key` or `SR_ESCROW_PRIVATE_KEY`)

```bash
spacerouter escrow approve <amount_wei>            # one-shot ERC-20 allowance
spacerouter escrow deposit <amount_wei>
spacerouter escrow initiate-withdrawal <amount_wei>
spacerouter escrow execute-withdrawal
spacerouter escrow cancel-withdrawal
```

All amounts are in wei. 1 SPACE = 10¹⁸ wei. The 5-day withdrawal delay is enforced by the contract — see [Pay with SPACE](/spacerouter-proxy/service-user-guide/pay-with-space-v1.5.md).

### `receipts` — inspect on-chain receipt state

```bash
spacerouter receipts pending     # list unsigned receipts the gateway has for you
spacerouter receipts sync        # fetch, sign, and submit all pending receipts
spacerouter receipts is-settled <client_address> <request_uuid>
spacerouter receipts show <client_address> <request_uuid>
```

Use `sync` after a session to make sure the gateway can claim its bandwidth fees on-chain. `is-settled` lets you double-check that a specific request was claimed.

### Examples

#### Top up and use SPACE for a session

```bash
export SR_ESCROW_PRIVATE_KEY=0x...

spacerouter escrow deposit 50000000000000000000   # 50 SPACE

# … run your scripts …
spacerouter request get https://httpbin.org/ip --pay --region KR

spacerouter receipts sync
spacerouter escrow balance 0xYourAddress
```