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

# Request authentication nonce

> Generate a random nonce for SIWS (Sign In With Solana) authentication.
The nonce is valid for 5 minutes. Maximum 3 active nonces per wallet.
Use this nonce to construct a canonical SIWS message for wallet signing:

```
Sign in to Joyride

Wallet: {wallet}
Nonce: {nonce}
```

**Rate limit:** 10 requests/minute per IP.




## OpenAPI

````yaml /_generated/openapi.yaml post /v1/auth/nonce
openapi: 3.1.0
info:
  title: Joyride Exchange REST API
  version: 1.0.0
  description: >
    REST API for the Joyride 0DTE Options Exchange.


    ## Authentication


    **Public endpoints** (`/health`, `/v1/market/*`, `/v1/spot/*`,
    `/v1/oracle/*`) require no authentication.


    **Competition prize claims** (`/v1/competition/claim`) are
    self-authenticated

    by a Solana ed25519 signature over the wallet, Discord handle, and payout

    destination in the request body. No JWT is required for that endpoint.


    **Account endpoints** (`/v1/account/*`, `/v1/orders/*`,
    `/v1/social/profile`, `/v1/social/avatar`) require JWT authentication via
    one of:

    1. `Authorization: Bearer <jwt>` header (primary — native clients)

    2. `Cookie: joyride_session=<jwt>` (web clients, set automatically by
    `/v1/auth/verify`)


    **Withdrawal endpoints** (`/withdrawals`, `/v1/withdrawals`) require the

    `Authorization: Bearer <jwt>` header. A session cookie alone is not
    accepted.


    Obtain a JWT by completing the SIWS (Sign In With Solana) flow:

    1. `POST /v1/auth/nonce` with your wallet address to get a nonce

    2. Sign the canonical SIWS message with your wallet

    3. `POST /v1/auth/verify` with wallet, signature, and message to receive a
    JWT


    **Mutating admin endpoints** require a bearer token:

    ```

    Authorization: Bearer <ADMIN_TOKEN>

    ```


    ## Data Conventions


    - **Prices**: Integer values in USDC micros (1 USDC = 1,000,000 micros).
      Example: `1500000` = $1.50
    - **Sizes**: Integer values in millicontracts (1 contract = 1000
    millicontracts).
      Example: `1000` = 1 contract
    - **Balances**: USDC micros. Example: `10_000_000_000` = $10,000

    - **Timestamps**: Unix microseconds (µs since epoch)

    - **Instrument IDs**: Format `{ASSET}_USDC-{DMMMYY}-{STRIKE}-{C|P}`.
      Example: `SOL_USDC-28FEB26-150-C`

    ## Trading


    **Trading is WebSocket-only.** The HTTP API has no order placement
    endpoints.

    See the AsyncAPI spec for WebSocket trading methods.
  contact:
    name: Joyride Engineering
    email: engineering@joyride.exchange
  license:
    name: Proprietary
servers:
  - url: https://joyride.exchange/api
    description: Production
security: []
tags:
  - name: Authentication
    description: |
      SIWS (Sign In With Solana) authentication flow. Obtain a JWT for use
      with all authenticated endpoints. No prior authentication required.
  - name: Health
    description: Service health check.
  - name: Market Data
    description: Publicly accessible market data. No authentication required.
  - name: Account
    description: User-specific account data. Requires user identification.
  - name: Orders
    description: User order history. Requires user identification.
  - name: Withdrawals
    description: Request signed withdrawal authorizations and list withdrawal history.
  - name: Social
    description: Social features — profiles, leaderboard, and activity.
  - name: Referrals
    description: Referral-code validation and attribution surfaces.
  - name: Competition
    description: Competition-specific collection flows.
  - name: Spot
    description: Spot prices and volatility data.
  - name: Oracle
    description: Oracle data — prices, TWAP previews, and settlement timing.
  - name: AI Chat
    description: >
      AI-powered trading assistant. Uses SIWS (Sign In With Solana)
      authentication

      and JWT sessions. Returns responses as Server-Sent Events (SSE).
  - name: Admin
    description: Administrative operations. Requires admin bearer token.
paths:
  /v1/auth/nonce:
    post:
      tags:
        - Authentication
      summary: Request authentication nonce
      description: |
        Generate a random nonce for SIWS (Sign In With Solana) authentication.
        The nonce is valid for 5 minutes. Maximum 3 active nonces per wallet.
        Use this nonce to construct a canonical SIWS message for wallet signing:

        ```
        Sign in to Joyride

        Wallet: {wallet}
        Nonce: {nonce}
        ```

        **Rate limit:** 10 requests/minute per IP.
      operationId: requestAuthNonce
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NonceRequest'
      responses:
        '200':
          description: Nonce generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NonceResponse'
        '400':
          description: Invalid wallet address (must be valid base58, 32 bytes)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited (10 requests/minute per IP)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security: []
components:
  schemas:
    NonceRequest:
      type: object
      properties:
        wallet:
          type: string
          description: Solana wallet address (base58-encoded, 32 bytes)
          example: GmQozSzrtMjXt5F1Bed8Vrt55zCbiga8vDZr47RX9wC8
      required:
        - wallet
    NonceResponse:
      type: object
      properties:
        nonce:
          type: string
          description: Random 32-character hex nonce (valid for 5 minutes)
          example: a1b2c3d4e5f67890a1b2c3d4e5f67890
      required:
        - nonce
    Error:
      type: object
      properties:
        error:
          type: string
          description: >-
            Human-readable error message (auth failures may include an `auth_*`
            code prefix)
          example: Instrument not found
      required:
        - error

````