Auth and wallet APIs

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.

Create a funding link

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

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

Start here

Use an agent

Publish an agent

Add payments

API reference

Quality and help

Pair a CLI session

Read wallet balance

Create a funding link

Check funding status

Failure

Next

​Pair a CLI session

​Read wallet balance

​Create a funding link

​Check funding status

​Failure

​Next

Pair a CLI session

Read wallet balance

Create a funding link

Check funding status

Failure

Next