---
title: "Generate a wallet session JWT via x402 micro-payment"
method: POST
path: "/wallet-auth/x402-session"
tags: ["Wallet Auth"]
---

# Generate a wallet session JWT via x402 micro-payment

`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`

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).

## Request body

- object

## Response `200`

Session JWT issued alongside x402 settlement

- object
  - `settlement` object: x402 on-chain settlement details
    - `status` string
    - `transactionHash` string
  - `walletSession` object: Issued wallet session JWT (24-hour TTL). Tokens are reusable across requests until expiry. Token validity survives server restarts only when the `WALLET_AUTH_JWT_SECRET` environment variable is set to a stable, persistent value — without it sessions are invalidated on every redeploy.
    - `token` string: JWT session token (HS256, 24-hour TTL, reusable until expiry)
    - `expiresAt` string, date-time: ISO-8601 expiry timestamp

## Other responses

- `400`: Invalid request data — structured field-level error
- `402`: Payment required — the endpoint is metered and no API key was provided. The response body follows the [x402 v2 protocol](https://x402.org) and describes one or more USDC payment options that the caller can select before retrying the request. Base is always the first option and uses `X-PAYMENT`. When an `accepts` entry for Solana is present, it is an additional USDC-SPL option that uses `PAYMENT-SIGNATURE` and its `extra.feePayer` value. The server verifies either payment through the PayAI facilitator at `https://facilitator.payai.network`. The `PAYMENT-REQUIRED` response header carries this entire JSON body as a base64-encoded string for protocol-aware clients. Call `GET /api/billing/x402/config` to retrieve the current price table and wallet address and `paymentOptions` before constructing a payment.
- `500`: Internal server error

---

[API](https://skmtc.dev/cloudworldmodel/apis/cloud-world-model-agent-api.md) · [All operations](https://skmtc.dev/cloudworldmodel/apis/cloud-world-model-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cloudworldmodel/apis/cloud-world-model-agent-api/revisions/ecc3ad1ff07f?raw)