CLI

A command-line tool for sending requests, managing your escrow balance, and inspecting on-chain state.

Install

pip install spacerouter

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

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

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

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

Example output for balance:

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

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

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.

receipts — inspect on-chain receipt state

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

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