> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shodai.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Create wallet verification challenge

> Creates an account-bound EIP-4361 nonce for a wallet address. OAuth bearer tokens require agreements.write; API keys require the equivalent account entitlement. The challenge expires after five minutes, and requesting another nonce invalidates the prior nonce for the same authenticated account and address.

For the complete documentation index, see [llms.txt](https://docs.shodai.network/llms.txt).

Use an OAuth bearer access token with the `agreements.write` scope, or provide `X-API-Key` as the alternative credential. See [Authentication](/authentication) for delegated OAuth access and [Link a wallet and access agreements](/workflow/link-a-wallet-and-access-agreements) for the creator and participant access model.


## OpenAPI

````yaml /openapi.json post /v0/siwe/nonce
openapi: 3.1.0
info:
  title: Agreements API
  version: v0
  description: Author, deploy, read, and advance agreements through the Agreements API.
servers:
  - url: https://test-api.shodai.network
    description: Public base URL for the Agreements API testnet environment.
  - url: https://api.shodai.network
    description: Public base URL for the Agreements API production environment.
security: []
tags:
  - name: Agreement Records
    description: List and read agreement records.
  - name: Agreement Documents
    description: Resolve hosted agreement prose documents.
  - name: Authoring
    description: Check authored agreement JSON before deployment.
  - name: Deployment
    description: Preflight and deploy agreements.
  - name: Using Agreements
    description: Read state, inspect input history, and submit signed inputs.
  - name: Webhooks
    description: Register signed push callbacks for agreement events.
  - name: Wallet Access
    description: Prove control of a wallet and link it to the authenticated Shodai account.
  - name: System
    description: Health and OpenAPI discovery endpoints.
paths:
  /v0/siwe/nonce:
    post:
      tags:
        - Wallet Access
      summary: Create wallet verification challenge
      description: >-
        Creates an account-bound EIP-4361 nonce for a wallet address. OAuth
        bearer tokens require agreements.write; API keys require the equivalent
        account entitlement. The challenge expires after five minutes, and
        requesting another nonce invalidates the prior nonce for the same
        authenticated account and address.
      operationId: createSiweNonce
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SiweNonceRequest'
            examples:
              wallet:
                summary: Wallet to verify
                value:
                  address: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266'
      responses:
        '201':
          description: Created wallet verification challenge.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/SiweNonceResponse'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              examples:
                challenge:
                  summary: Five-minute wallet challenge
                  value:
                    data:
                      address: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266'
                      nonce: 0123456789abcdef0123456789abcdef
                      issuedAt: '2026-08-07T20:00:00.000Z'
                    meta:
                      apiVersion: v0
                      requestId: req_123
        '400':
          description: Invalid wallet address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: >-
            The authenticated Shodai account has paid_required entitlement mode
            for the requested scope. Per-call x402 settlement is not
            implemented. Treat this as an entitlement/operator issue.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            The credential lacks the required OAuth scope, the account lacks
            entitlement, or the account cannot access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - OAuthBearerAuth: []
components:
  schemas:
    SiweNonceRequest:
      type: object
      required:
        - address
      properties:
        address:
          type: string
          pattern: ^0x[0-9a-fA-F]{40}$
          description: EVM wallet address to verify.
      example:
        address: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266'
    SiweNonceResponse:
      type: object
      required:
        - address
        - nonce
        - issuedAt
      properties:
        address:
          type: string
          pattern: ^0x[0-9a-f]{40}$
          description: Normalized lowercase wallet address.
        nonce:
          type: string
          pattern: ^[0-9a-f]{32}$
          description: Single-use 32-character hexadecimal challenge nonce.
        issuedAt:
          type: string
          format: date-time
          description: Challenge issue time. The challenge expires five minutes later.
      example:
        address: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266'
        nonce: 0123456789abcdef0123456789abcdef
        issuedAt: '2026-08-07T20:00:00.000Z'
    ResponseMeta:
      type: object
      required:
        - apiVersion
        - requestId
      properties:
        apiVersion:
          type: string
          example: v0
        requestId:
          type: string
          description: Correlation ID for support and debugging.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - requestId
          properties:
            code:
              type: string
              example: unauthorized
              description: Stable machine-readable error code.
            message:
              type: string
              example: Missing API credential
              description: Safe human-readable error summary.
            details:
              description: Optional field errors or upstream-safe context.
            requestId:
              type: string
              description: Correlation ID for support and debugging.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Canonical API-key credential. Send X-API-Key: cns_pk_..., or
        Authorization: Bearer cns_pk_... only as an API-key compatibility alias.
      x-default: YOUR_API_KEY
    OAuthBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth access token issued by Shodai.
      x-default: Bearer YOUR_OAUTH_ACCESS_TOKEN

````