Generate a wallet session JWT via x402 micro-payment
Issues a 24-hour wallet session JWT in exchange for a small USDC micro-payment on Base (x402 protocol). Designed for managed/MPC wallets that cannot sign EIP-191 challenges directly.
Flow:
- Call this endpoint with no X-PAYMENT header — the server returns 402 Payment Required with the USDC amount and payment details.
- Submit the x402 payment and resend the request with the X-PAYMENT header populated.
- On success the response body includes both a settlement block (confirmed transaction hash) and a walletSession block containing the JWT token and its expiry.
The issuance is idempotent per transaction hash — replaying the same transaction hash returns the same session: the returned token carries the same jti (session nonce) as the original issuance. No new session record is created. The token's iat/exp timestamps differ between calls (each JWT is freshly signed), but the session identity bound by jti is stable across all replays of the same hash.
Token lifetime and persistence: Tokens are valid for 24 hours and reusable across requests until they expire. Token validity survives server restarts only when the WALLET_AUTH_JWT_SECRET environment variable is set to a stable, persistent value. Without it, an ephemeral per-process secret is used and all sessions are invalidated on every redeploy. The server logs a startup warning when this variable is absent.
Authentication: x402 micro-payment only (no API key required).
Request
- Base URL: https://www.cloudworldmodel.ai/api
- URL: https://www.cloudworldmodel.ai/api/wallet-auth/x402-session
- Auth: one of:
- API key in header X-PAYMENT
- API key in header PAYMENT-SIGNATURE
Request body
Response
Session JWT issued alongside x402 settlement
Example response
{
"settlement": {
"status": "confirmed",
"transactionHash": "0xabc123..."
}
}Changes
No recorded changes to this operation across all 1 revision of this API.