Python SDK

The official Python client for SpaceRouter Proxy. Sync, async, and on-chain payment in one package.

Install

pip install spacerouter

Requires Python 3.10 or later.

Synchronous client

from spacerouter import SpaceRouter
from spacerouter.payment import SpaceRouterSPACE

consumer = SpaceRouterSPACE(
    gateway_url="https://gateway.spacerouter.org",
    proxy_url="http://gateway.spacerouter.org:8080",
    private_key="0xYOUR_PRIVATE_KEY",
)

with SpaceRouter(
    consumer.address.lower(),                  # wallet address as first positional arg
    gateway_url="http://gateway.spacerouter.org:8080",
    payment=consumer,
    auto_settle=True,
    region="KR",
    ip_type="residential",
) as router:
    response = router.get("https://httpbin.org/ip")
    print(response.json())

Constructor

SpaceRouter(
    payer_address: str,                       # consumer wallet (lowercase 0x-hex)
    *,
    gateway_url: str = "https://gateway.spacerouter.org",
    payment: SpaceRouterSPACE,                # required — signs per-request challenges
    auto_settle: bool = False,                # sync receipts after each request
    protocol: Literal["http"] = "http",       # "http" only — socks5 not supported in v1.5+
    region: str | None = None,
    ip_type: str | None = None,
    timeout: float = 30.0,
)

HTTP methods

Each method takes a URL and forwards keyword arguments to httpx:

router.get(url, **kwargs)
router.post(url, json=..., **kwargs)
router.put(url, **kwargs)
router.patch(url, **kwargs)
router.delete(url, **kwargs)
router.head(url, **kwargs)
router.request(method, url, **kwargs)

Per-request routing override

kr_router = router.with_routing(region="KR", ip_type="residential")
us_router = router.with_routing(region="US")

kr_router.get("https://httpbin.org/ip")

Async client

import asyncio
from spacerouter import AsyncSpaceRouter
from spacerouter.payment import SpaceRouterSPACE

async def main():
    consumer = SpaceRouterSPACE(
        gateway_url="https://gateway.spacerouter.org",
        proxy_url="http://gateway.spacerouter.org:8080",
        private_key="0xYOUR_PRIVATE_KEY",
    )
    async with AsyncSpaceRouter(
        consumer.address.lower(),
        gateway_url="http://gateway.spacerouter.org:8080",
        payment=consumer,
        auto_settle=True,
    ) as router:
        response = await router.get("https://httpbin.org/ip")
        print(await response.json())

asyncio.run(main())

Manual signing (advanced)

If you can't use the bundled SpaceRouter / AsyncSpaceRouter clients, you can build the four X-SpaceRouter-* headers yourself and stamp them on the proxy CONNECT.

from spacerouter.payment import SpaceRouterSPACE

consumer = SpaceRouterSPACE(
    gateway_url="https://gateway.spacerouter.org",
    proxy_url="http://gateway.spacerouter.org:8080",
    private_key="0xYOUR_PRIVATE_KEY",
)

challenge = await consumer.request_challenge()
headers = consumer.build_auth_headers(challenge)
# … attach `headers` to the proxy CONNECT request

# Sync any pending Leg-1 receipts on chain
result = await consumer.sync_receipts()
print(result["accepted"], result["pending_count"])

See the full walk-through in Pay with SPACE.

Errors

Every SpaceRouter error subclasses SpaceRouterError:

Class	HTTP	Raised when
AuthenticationError	407	Payment headers missing or challenge signature rejected.
QuotaExceededError	402	Escrow balance below the request's price, or legacy Proxy-Authorization: Basic detected (api_key_auth_deprecated).
RateLimitError	429	Too many requests. Has retry_after.
NoNodesAvailableError	503	No Provider matches your region/type filter.
UpstreamError	502	Provider couldn't reach the target site.

from spacerouter import SpaceRouter, NoNodesAvailableError

try:
    router.get("https://httpbin.org/ip")
except NoNodesAvailableError:
    print("No matching nodes — try a different region")

Configuration via environment

The CLI and SDK both read these:

Variable	Purpose
SR_GATEWAY_URL	Override the gateway hostname (mostly for testing).
SR_GATEWAY_MANAGEMENT_URL	Management API endpoint (/auth/challenge, /leg1/*).
SR_ESCROW_PRIVATE_KEY	Wallet key for deposit/withdraw and per-request signing.
SR_ESCROW_CONTRACT_ADDRESS	TokenPaymentEscrow contract address.
SR_ESCROW_CHAIN_RPC	Creditcoin RPC for on-chain calls.