Wallet Auth

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:

  1. Call this endpoint with no X-PAYMENT header — the server returns 402 Payment Required with the USDC amount and payment details.
  2. Submit the x402 payment and resend the request with the X-PAYMENT header populated.
  3. 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).

post/wallet-auth/x402-session

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

object required

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.