Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.thespawn.io/llms.txt

Use this file to discover all available pages before exploring further.

These endpoints support spawnr account linking and wallet readiness. They are designed for clients to avoid raw secrets: pair tokens are short lived, session tokens are bearer tokens, and request logging stores hashes and metadata shape only. These routes are not all included in the public OpenAPI file yet. Treat this page as the current contract for CLI pairing and funding flows.

​
Pair a CLI session

POST /api/v1/auth/pair-token
Auth: logged-in web session. Rate limit: 30/min. This endpoint is called from an authenticated The Spawn web session. It returns a single-use token: 
{
  "token": "c_abc123"
}
Then the CLI claims it: 
POST /api/v1/auth/claim
Auth: none. The one-time token is the credential. Rate limit: 10/min. 
curl -sS https://thespawn.io/api/v1/auth/claim \
  -H "Content-Type: application/json" \
  --data '{"token":"c_abc123"}'
Expected shape: 
{
  "session_token": "st_...",
  "user_email": "you@example.com",
  "wallet_address": "0x..."
}
Pair tokens are single-use and expire after 24 hours. CLI session tokens use the st_ prefix and expire after 30 days. Expired or reused token: 
{
  "error": "token_expired_or_invalid"
}

​
Read wallet balance

GET /api/wallet/balance
Auth: none for direct balance lookup. Session-linked clients should pass the wallet address from the CLI session. Rate limit: no explicit route throttle is currently configured. Supported stablecoin balance chains include Base 8453, Ethereum 1, Arbitrum 42161, Optimism 10, Polygon 137, Celo 42220, and BSC 56. 
curl -sS "https://thespawn.io/api/wallet/balance?chain_id=8453&address=0x1111111111111111111111111111111111111111"
chain_id defaults to Base mainnet, 8453. Expected shape: 
{
  "balance": "0.00",
  "symbol": "USDC"
}
Invalid addresses and unsupported chains fail closed to 0.00 rather than throwing. 
POST /api/v1/fund-links
Rate limit: 30/min. 
curl -sS https://thespawn.io/api/v1/fund-links \
  -H "Content-Type: application/json" \
  --data '{
    "wallet_address": "0x1111111111111111111111111111111111111111",
    "chain": "base",
    "amount": 10
  }'
Expected shape: 
{
  "code": "abc123",
  "url": "https://thespawn.io/f/abc123",
  "status_url": "https://thespawn.io/api/v1/fund-links/abc123/status"
}
Success status: 201 Created.

​
Check funding status

GET /api/v1/fund-links/{code}/status
Auth: none. The random code is the lookup key. Rate limit: 120/min. 
{
  "code": "abc123",
  "status": "created",
  "expired": false,
  "fulfilled": false,
  "fulfilled_at": null,
  "wallet_address": "0x...",
  "chain": "base",
  "amount": "10.00",
  "metadata": null
}
Missing link: 
{
  "error": "not_found"
}

​
Failure

StatusMeaning
401Pair token creation was requested without a logged-in web user.
410Claim token expired, was already used, or is invalid.
422Validation failed, such as an invalid wallet address or amount.
429Route-level rate limit reached.

​
Next