Cloud World Model Wallet Auth API

The Wallet Auth API from Cloud World Model — 4 operation(s) for wallet auth.

GitHub OpenAPI

Operations 4

POST /wallet-auth/challenge Generate an EIP-191 sign-in challenge #
POST /wallet-auth/verify Generate a session token from an EIP-191 signature #
POST /wallet-auth/revoke Revoke a wallet session JWT #
POST /wallet-auth/x402-session Generate a wallet session JWT via x402 micro-payment #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/cloudworldmodel-ai:cloudworldmodel-ai-wallet-auth-api"
All apis
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.

Get an API 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 Specification

cloudworldmodel-ai-wallet-auth-api-openapi.yml Raw ↑
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