Cloud World Model Wallet Auth API
The Wallet Auth API from Cloud World Model — 4 operation(s) for wallet auth.
The Wallet Auth API from Cloud World Model — 4 operation(s) for wallet auth.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/cloudworldmodel-ai:cloudworldmodel-ai-wallet-auth-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Cloudworldmodel Ai Wallet Auth API
version: 1.0.0
contact:
name: Cloud World Model API Support
url: https://www.cloudworldmodel.ai
email: api@cloudworldmodel.ai
license:
name: MIT
url: https://opensource.org/licenses/MIT
description: 'Operations tagged Wallet Auth across 3 of this provider''s published API definitions: cloudworldmodel-ai-openapi.json, cloudworldmodel-ai-agent-x402-openapi.yml, cloudworldmodel-ai-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://www.cloudworldmodel.ai/api
description: Production
- url: http://localhost:5000/api
description: Local development
tags:
- name: Wallet Auth
paths:
/wallet-auth/challenge:
x-stability: stable
post:
tags:
- Wallet Auth
summary: Generate an EIP-191 sign-in challenge
description: 'Issues a one-time nonce for the given EVM wallet address. The caller must
sign the returned `message` string with `personal_sign` (EIP-191) and
submit the hex signature to `POST /wallet-auth/verify` within 5 minutes.
Rate-limited to 10 requests per IP per minute to prevent nonce-farming.
No authentication required.'
operationId: walletAuthChallenge
security: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- walletAddress
properties:
walletAddress:
type: string
pattern: ^0x[0-9a-fA-F]{40}$
description: The EVM wallet address requesting a sign-in challenge
example: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
responses:
'200':
description: Challenge nonce issued
content:
application/json:
schema:
type: object
required:
- nonce
- message
- expiresAt
properties:
nonce:
type: string
description: The random hex nonce (32 hex chars)
example: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
message:
type: string
description: The full message string to sign with personal_sign
example: 'Sign in to Cloud World Model
Nonce: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
Expires: 2026-01-01T00:05:00.000Z'
expiresAt:
type: string
format: date-time
description: ISO-8601 timestamp when the nonce expires (5 minutes)
'400':
$ref: '#/components/responses/BadRequest'
'429':
description: Rate limit exceeded — 10 challenges per IP per minute
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
$ref: '#/components/responses/InternalError'
servers:
- url: https://www.cloudworldmodel.ai/api
description: Production
- url: http://localhost:5000/api
description: Local development
/wallet-auth/verify:
x-stability: stable
post:
tags:
- Wallet Auth
summary: Generate a session token from an EIP-191 signature
description: 'Verifies the EIP-191 personal_sign signature for the challenge previously
issued by `POST /wallet-auth/challenge`. On success, returns a 24-hour
JWT session token.
Use the token as `Authorization: Bearer ` on `GET /simulations`
and `GET /simulations/{simulationId}` to list and retrieve simulations
claimed by this wallet address without a traditional API key.
The nonce is single-use and consumed on successful verification.
No authentication required.'
operationId: walletAuthVerify
security: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- walletAddress
- signature
properties:
walletAddress:
type: string
pattern: ^0x[0-9a-fA-F]{40}$
description: The EVM wallet address that signed the challenge
example: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
signature:
type: string
description: Hex-encoded EIP-191 signature from personal_sign (0x-prefixed, 65 bytes)
example: 0x1234...ef01b
responses:
'200':
description: Signature verified — session token issued
content:
application/json:
schema:
type: object
required:
- token
- walletAddress
- expiresIn
properties:
token:
type: string
description: JWT session token (HS256, 24-hour TTL)
walletAddress:
type: string
description: The lowercase verified wallet address
example: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'
expiresIn:
type: integer
description: Token lifetime in seconds (86400 = 24 hours)
example: 86400
'400':
$ref: '#/components/responses/BadRequest'
'401':
description: Invalid or expired signature
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
$ref: '#/components/responses/InternalError'
servers:
- url: https://www.cloudworldmodel.ai/api
description: Production
- url: http://localhost:5000/api
description: Local development
/wallet-auth/revoke:
x-stability: stable
post:
tags:
- Wallet Auth
summary: Revoke a wallet session JWT
description: 'Immediately revokes a wallet session JWT by recording its `jti` claim in
the server-side revocation set. Any subsequent request that presents the
same token will be rejected with `401 Invalid or expired wallet session
token`, even though the token has not yet reached its natural 24-hour
expiry.
**Use cases:** explicit sign-out, leaked-token containment, key rotation.
The token must be cryptographically valid (correct signature, not yet
expired) and must carry a `jti` claim (all tokens issued by this server
do). Tokens that are already expired or tampered are silently treated as
invalid.
**Revocation persistence:** the revocation set is in-memory. It survives
for the lifetime of the server process but is cleared on restart/redeploy.
Because tokens are 24-hour-lived, the maximum exposure window after a
server restart is bounded by the remaining natural TTL of any in-flight
tokens.
No authentication header is required — the token to revoke is read from
the request body.'
operationId: walletAuthRevoke
security: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- token
properties:
token:
type: string
description: The wallet session JWT to revoke
responses:
'200':
description: Token successfully revoked
content:
application/json:
schema:
type: object
required:
- revoked
- jti
properties:
revoked:
type: boolean
example: true
jti:
type: string
description: The JWT ID that was added to the revocation set
example: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
'400':
$ref: '#/components/responses/BadRequest'
'401':
description: Token is invalid, already expired, or missing a jti claim
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
$ref: '#/components/responses/InternalError'
servers:
- url: https://www.cloudworldmodel.ai/api
description: Production
- url: http://localhost:5000/api
description: Local development
/wallet-auth/x402-session:
x-stability: stable
post:
tags:
- Wallet Auth
summary: Generate a wallet session JWT via x402 micro-payment
description: '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).'
operationId: walletAuthX402Session
x-x402-call-type: wallet_session
x-x402-price-usdc: $0.0030
security:
- x402: []
- x402Solana: []
requestBody:
required: false
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
responses:
'200':
description: Session JWT issued alongside x402 settlement
content:
application/json:
schema:
type: object
properties:
settlement:
type: object
description: x402 on-chain settlement details
properties:
status:
type: string
example: confirmed
transactionHash:
type: string
example: 0xabc123...
walletSession:
type: object
description: '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.
'
properties:
token:
type: string
description: JWT session token (HS256, 24-hour TTL, reusable until expiry)
expiresAt:
type: string
format: date-time
description: ISO-8601 expiry timestamp
'400':
$ref: '#/components/responses/BadRequest'
'402':
$ref: '#/components/responses/X402PaymentRequired'
'500':
$ref: '#/components/responses/InternalError'
servers:
- url: https://www.cloudworldmodel.ai/api
description: Production
- url: http://localhost:5000/api
description: Local development
components:
schemas:
FieldError:
type: object
description: A single structured field-level error returned on HTTP 400 responses
required:
- code
- pointer
- message
properties:
code:
$ref: '#/components/schemas/ValidationErrorCode'
pointer:
type: string
description: JSON Pointer (RFC 6901) to the field that caused the error, or an empty string for request-level errors
example: /resources/0/provider
message:
type: string
description: Human-readable description of the error
example: Unknown provider 'gce'; valid values are aws, gcp, azure, oci, digitalocean
suggestion:
type: string
description: Optional actionable hint for self-correction
example: 'Use one of: aws, gcp, azure, oci, digitalocean'
suggestions:
type: array
description: For UNKNOWN_REGION errors, the 3-5 closest matching regions ranked by similarity to the invalid input
items:
type: object
required:
- regionKey
- regionLabel
properties:
regionKey:
type: string
description: Canonical shortcode for the region
example: use2
regionLabel:
type: string
description: Standard provider label for the region
example: us-east-2
ValidationErrorCode:
type: string
description: Machine-readable error code indicating the category of validation failure
enum:
- INVALID_FIELD
- MISSING_REQUIRED
- UNKNOWN_PROVIDER
- UNKNOWN_SIZE
- UNKNOWN_REGION
- INVALID_REQUEST
ValidationErrorResponse:
type: object
description: Response body for HTTP 400 errors — either a single error or an array of field errors
oneOf:
- type: object
required:
- error
properties:
error:
$ref: '#/components/schemas/FieldError'
- type: object
required:
- errors
properties:
errors:
type: array
items:
$ref: '#/components/schemas/FieldError'
minItems: 1
Error:
type: object
required:
- error
properties:
error:
type: string
description: Error message
example: Simulation not found
details:
type: array
description: Detailed validation errors (for 400 responses)
items:
type: object
responses:
InternalError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
X402PaymentRequired:
description: '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.
'
content:
application/json:
schema:
type: object
required:
- x402Version
- error
- resource
- accepts
properties:
x402Version:
type: integer
example: 2
error:
type: string
example: Payment required. Send an X-PAYMENT header containing a signed USDC payment on Base (x402 protocol).
resource:
type: object
required:
- url
- description
- mimeType
properties:
url:
type: string
description: Full URL of the endpoint being paid for.
description:
type: string
description: Human-readable description of the metered call.
mimeType:
type: string
example: application/json
accepts:
type: array
items:
type: object
required:
- scheme
- network
- amount
- payTo
- maxTimeoutSeconds
- asset
properties:
scheme:
type: string
example: exact
network:
type: string
description: CAIP-2 network identifier.
example: eip155:8453
amount:
type: string
description: Payment amount in USDC atomic units (6-decimal integer string).
example: '5000'
payTo:
type: string
description: Recipient wallet address on the selected network.
maxTimeoutSeconds:
type: integer
example: 300
asset:
type: string
description: USDC contract or mint address on the selected network.
example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
extra:
type: object
description: 'Network-specific x402 details. Solana options include
`feePayer`, the PayAI wallet that sponsors the transaction fee.
'
extensions:
type: object
description: Optional protocol extensions (empty object in standard use).
BadRequest:
description: Invalid request data — structured field-level error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API Key or Wallet Session JWT
description: 'API key or wallet-session JWT authentication using Bearer tokens in the Authorization header.
**How to authenticate:**
1. Create an API key using POST /api/keys
2. Include the key in the Authorization header: `Bearer cwm_live_<your_key>`
3. All RL environment endpoints require authentication
**Rate Limits:**
- Default: 1000 requests/hour per key
- Configurable per key
- Returns 429 when exceeded
'
UiSessionCookie:
type: apiKey
in: cookie
name: cwm_ui_session
description: 'HttpOnly browser-workspace session cookie issued by
`POST /api/ui/simulations`. It authorizes UI mutations for simulations
owned by that browser workspace.
'
x402:
type: apiKey
in: header
name: X-PAYMENT
description: "x402 v2 Base micropayment option. Select the Base entry from\n`GET /api/billing/x402/config` `paymentOptions`, then send its signed USDC\nmicro-payment in the `X-PAYMENT` header to get full access to the metered\nendpoint in a single round-trip — no account, no API key, no sign-up required.\n\n**402 → pay → retry loop:**\n1. Call the endpoint without an `X-PAYMENT` header.\n2. Receive a `402 Payment Required` response. The body is a\n standard JSON `PaymentRequired` object. The same payload is also\n echoed as a base64-encoded string in the `PAYMENT-REQUIRED`\n response header for clients that cannot access the body.\n3. Decode the `PaymentRequired` body (or the `PAYMENT-REQUIRED`\n header) to read the exact `payTo` wallet,\n USDC amount, network, and facilitator URL.\n4. Construct and sign the payment with your x402 client library.\n5. Retry the Base request with the `X-PAYMENT` header — the server\n verifies via `https://facilitator.payai.network` and responds `200`.\n\n**Optional Solana:** When `paymentOptions` advertises a Solana entry, callers\nmay instead select it and use `PAYMENT-SIGNATURE`. Solana is an additional\noption; use `X-PAYMENT` for the Base option shown by this security scheme.\n\n**Discovery:** `GET /api/billing/x402/config` returns the live `payTo`\naddress, canonical `paymentOptions`, per-call-type USDC amounts, facilitator\nURL, and the credits-per-USDC conversion rate. Always fetch this before\nhardcoding any amounts or a payment header.\n\n**Price range:** $0.0030 per 3-credit call — $0.0050 per 5-credit\ncall (see `x-x402-price-usdc` on each\noperation for the exact amount).\n\n**Facilitator:** `https://facilitator.payai.network` (PayAI-operated,\nverifies the advertised Base and optional Solana options).\n"
x402Solana:
type: apiKey
in: header
name: PAYMENT-SIGNATURE
description: 'Optional x402 v2 Solana payment alternative. Use this security option only
when `GET /api/billing/x402/config` `paymentOptions` advertises a Solana
network, then send its signed Solana USDC payment payload in the
`PAYMENT-SIGNATURE` header. Include the option''s `feePayer` detail when
constructing the transaction.
For the primary Base payment option, select the `x402` security option
instead and send its signed payment payload in the `X-PAYMENT` header.
'
x-refined-from:
- cloudworldmodel-ai-openapi.json
- cloudworldmodel-ai-agent-x402-openapi.yml
- cloudworldmodel-ai-openapi.yml