api-1.yaml

openapi: 3.0.0
paths:
  /auth/signing-message:
    get:
      description: Returns a signing message with a randomly generated nonce for
        authentication purposes.
      operationId: AuthController_getSigningMessage
      parameters: []
      responses:
        "200":
          description: A signing message containing a nonce has been successfully generated
          content:
            application/json:
              schema:
                type: string
                example: >-
                  Welcome to Limitless.exchange! Please sign this message to
                  verify your identity.


                  Nonce: 0xa1b2c3d4e5f67890...
      summary: Get signing message
      tags:
        - Authentication
  /auth/verify-auth:
    get:
      description: Verifies if the user is authenticated by checking the session cookie
      operationId: AuthController_verifyAuth
      parameters: []
      responses:
        "200":
          description: User is authenticated
          content:
            application/json:
              schema:
                type: string
                description: Ethereum address of the authenticated user
                example: "0x1234567890123456789012345678901234567890"
        "401":
          description: User is not authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The token cookie is required
      security:
        - limitless_session: []
      summary: Verify authentication
      tags:
        - Authentication
  /auth/login:
    post:
      description: Authenticates a user with a signed message and creates a session
      operationId: AuthController_login
      parameters:
        - name: x-account
          in: header
          description: The Ethereum address of the user
          required: true
          schema:
            type: string
        - name: x-signing-message
          in: header
          description: The signing message generated by the server
          required: true
          schema:
            type: string
        - name: x-signature
          in: header
          description: The signature generated by signing the message with the user's wallet
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserDto"
      responses:
        "200":
          description: User has been successfully logged in and a session cookie has been
            set
          content:
            application/json:
              schema:
                type: object
                properties:
                  account:
                    type: string
                    example: "0x1234567890123456789012345678901234567890"
                  displayName:
                    type: string
                    example: 0x1234...7890
                  smartWallet:
                    type: string
                    nullable: true
                    example: "0x0987654321098765432109876543210987654321"
                  client:
                    type: string
                    example: eoa
        "400":
          description: Bad request (missing or invalid parameters)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Smart wallet is required
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Error creating JWT token
      summary: User login
      tags:
        - Authentication
  /auth/logout:
    post:
      description: Logs out the user by clearing the session cookie
      operationId: AuthController_logout
      parameters: []
      responses:
        "200":
          description: User has been successfully logged out
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Logged out successfully
      security:
        - limitless_session: []
      summary: User logout
      tags:
        - Authentication
  /markets/active/{categoryId}:
    get:
      description: Retrieves markets and groups that are active and not yet resolved,
        with optional category filtering
      operationId: MarketController_getActiveMarkets[0]
      parameters:
        - name: page
          required: false
          in: query
          description: Page number for pagination
          schema:
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of items per page
          schema:
            example: 10
            type: number
        - name: sortBy
          required: false
          in: query
          description: Sort by query parameter
          schema:
            example: newest
            type: string
        - name: tradeType
          required: false
          in: query
          description: Filter by trade type (amm, clob, or group)
          schema:
            enum:
              - amm
              - clob
              - group
            type: string
        - name: automationType
          required: false
          in: query
          description: Filter by automation type (manual, lumy, or sports)
          schema:
            enum:
              - manual
              - lumy
              - sports
            type: string
        - name: categoryId
          required: false
          in: path
          description: Filter markets by category ID
          schema:
            type: number
      responses:
        "200":
          description: Active markets and groups with volume and liquidity data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BrowseActiveMarketsResponseDto"
        "500":
          description: Server error when retrieving markets data
      summary: Browse Active Markets
      tags:
        - Markets
  /markets/active:
    get:
      description: Retrieves markets and groups that are active and not yet resolved,
        with optional category filtering
      operationId: MarketController_getActiveMarkets[1]
      parameters:
        - name: page
          required: false
          in: query
          description: Page number for pagination
          schema:
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of items per page
          schema:
            example: 10
            type: number
        - name: sortBy
          required: false
          in: query
          description: Sort by query parameter
          schema:
            example: newest
            type: string
        - name: tradeType
          required: false
          in: query
          description: Filter by trade type (amm, clob, or group)
          schema:
            enum:
              - amm
              - clob
              - group
            type: string
        - name: automationType
          required: false
          in: query
          description: Filter by automation type (manual, lumy, or sports)
          schema:
            enum:
              - manual
              - lumy
              - sports
            type: string
        - name: categoryId
          required: false
          in: path
          description: Filter markets by category ID
          schema:
            type: number
      responses:
        "200":
          description: Active markets and groups with volume and liquidity data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BrowseActiveMarketsResponseDto"
        "500":
          description: Server error when retrieving markets data
      summary: Browse Active Markets
      tags:
        - Markets
  /markets/categories/count:
    get:
      description: Returns the number of active markets for each category and the
        total market count
      operationId: MarketController_getActiveMarketCountPerCategory
      parameters: []
      responses:
        "200":
          description: Object containing category counts and total count
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CategoryCountResponseDto"
        "500":
          description: Server error when retrieving category count data
      summary: Get active market count per category
      tags:
        - Markets
  /markets/active/slugs:
    get:
      description: Retrieves slugs, strike prices, tickers, and deadlines for all
        active markets and groups. Group markets are nested under their parent
        group.
      operationId: MarketController_getActiveSlugs
      parameters: []
      responses:
        "200":
          description: List of active market and group slugs with metadata
          content:
            application/json:
              schema:
                type: array
                items:
                  oneOf:
                    - type: object
                      properties:
                        slug:
                          type: string
                          description: Market slug identifier
                          example: btc-price-prediction-2024
                        strikePrice:
                          type: string
                          nullable: true
                          description: Strike price extracted from market title
                          example: "50000"
                        ticker:
                          type: string
                          nullable: true
                          description: Asset ticker symbol
                          example: BTC
                        deadline:
                          type: string
                          nullable: true
                          format: date-time
                          description: Market expiration deadline
                          example: 2024-12-31T23:59:59Z
                      required:
                        - slug
                      description: Individual market entry
                    - type: object
                      properties:
                        slug:
                          type: string
                          description: Group slug identifier
                          example: crypto-predictions-2024
                        strikePrice:
                          type: "null"
                          description: Groups do not have strike prices
                        ticker:
                          type: string
                          description: Group asset ticker symbol
                          example: USDC
                        deadline:
                          type: string
                          nullable: true
                          format: date-time
                          description: Group expiration deadline
                          example: 2024-12-31T23:59:59Z
                        markets:
                          type: array
                          items:
                            type: object
                            properties:
                              slug:
                                type: string
                                description: Market slug within the group
                                example: btc-50k-prediction
                            required:
                              - slug
                          description: Array of markets within this group
                      required:
                        - slug
                        - deadline
                        - markets
                      description: Group entry with nested markets
        "500":
          description: Server error when retrieving market slugs
      summary: Get active market slugs with metadata
      tags:
        - Markets
  /markets/{addressOrSlug}:
    get:
      description: Retrieves market or group data using either an Ethereum address or
        a slug identifier
      operationId: MarketController_find
      parameters:
        - name: addressOrSlug
          required: true
          in: path
          description: Market/group address (0x...) or slug identifier (my-market-name)
          schema:
            example: crypto-predictions-2025
      responses:
        "200":
          description: Market or group details with pricing and volume data
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ClobMarketResponseDto"
                    description: CLOB market with position IDs and trading data
                  - $ref: "#/components/schemas/NegRiskGroupResponseDto"
                    description: NegRisk group with nested markets array
                  - $ref: "#/components/schemas/AmmMarketResponseDto"
                    description: AMM market with liquidity and volume data
        "404":
          description: Market or group not found
        "500":
          description: Server error when retrieving market/group data
      summary: Get Market Details
      tags:
        - Markets
  /markets/{slug}/get-feed-events:
    get:
      description: Retrieves the latest feed events related to a specific market with
        pagination support
      operationId: MarketController_getFeedEvent
      parameters:
        - name: page
          required: false
          in: query
          description: Page number for pagination
          schema:
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of events per page
          schema:
            example: 10
            type: number
        - name: slug
          required: false
          in: path
          description: Slug of the market
          schema:
            example: my-market-slug-123
      responses:
        "200":
          description: List of feed events for the market
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeedEventsResponseDto"
        "500":
          description: Server error when retrieving feed events
      security:
        - bearer: []
      summary: Get feed events for a market
      tags:
        - Markets
  /markets/{slug}/historical-price:
    get:
      description: Retrieve historical price data for a specific market with
        configurable time intervals
      operationId: MarketOrderbookController_getHistoricalPrice
      parameters:
        - name: to
          required: false
          in: query
          description: End date for historical data
          schema:
            example: 2024-01-31T23:59:59Z
        - name: from
          required: false
          in: query
          description: Start date for historical data
          schema:
            example: 2024-01-01T00:00:00Z
        - name: interval
          required: false
          in: query
          description: Time interval for data points
          schema:
            enum:
              - 1h
              - 6h
              - 1d
              - 1w
              - 1m
              - all
            type: string
        - name: slug
          required: true
          in: path
          description: Market slug identifier
          schema:
            example: presidential-election-2024
      responses:
        "200":
          description: Historical price data
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    title:
                      type: string
                      example: YES Token
                    prices:
                      type: array
                      items:
                        type: object
                        properties:
                          price:
                            type: number
                            example: 0.75
                          timestamp:
                            type: string
                            example: 2024-01-15T10:30:00Z
      summary: Get Historical Prices
      tags:
        - Trading
  /markets/{slug}/orderbook:
    get:
      description: Retrieve the current orderbook for a market showing all open buy
        and sell orders
      operationId: MarketOrderbookController_getOrderbook
      parameters:
        - name: slug
          required: true
          in: path
          description: Market slug identifier
          schema:
            example: presidential-election-2024
      responses:
        "200":
          description: Current orderbook with bids and asks
          content:
            application/json:
              schema:
                type: object
                properties:
                  adjustedMidpoint:
                    type: number
                    example: 0.75
                  asks:
                    type: array
                    items:
                      type: object
                      properties:
                        price:
                          type: number
                          example: 0.76
                        size:
                          type: number
                          example: 100
                  bids:
                    type: array
                    items:
                      type: object
                      properties:
                        price:
                          type: number
                          example: 0.74
                        size:
                          type: number
                          example: 150
                  lastTradePrice:
                    type: number
                    example: 0.75
                  maxSpread:
                    type: number
                    example: 0.05
                  minSize:
                    type: number
                    example: 1
                  tokenId:
                    type: string
                    example: "196332044857908579498285167379934237586289302353716299439995448593246\
                      45414627"
        "400":
          description: Market does not support orderbook (AMM market)
        "404":
          description: Market not found
      summary: Get Orderbook
      tags:
        - Trading
  /markets/{slug}/locked-balance:
    get:
      description: Get the amount of funds locked in open orders for the authenticated user
      operationId: MarketOrderbookController_getLockedBalance
      parameters:
        - name: slug
          required: true
          in: path
          description: Market slug identifier
          schema:
            example: presidential-election-2024
      responses:
        "200":
          description: User's locked balance details
          content:
            application/json:
              schema:
                type: object
                properties:
                  lockedBalance:
                    type: string
                    example: "250.50"
                  lockedBalanceFormatted:
                    type: string
                    example: 250.50 USDC
                  currency:
                    type: string
                    example: USDC
                  orderCount:
                    type: number
                    example: 3
      security:
        - limitless_session: []
      summary: Get Locked Balance
      tags:
        - Trading
  /markets/{slug}/user-orders:
    get:
      description: Get all orders placed by the authenticated user for a specific market
      operationId: MarketOrderbookController_getUserOrders
      parameters:
        - name: statuses
          required: false
          in: query
          description: Order status(es) to filter by. Defaults to [LIVE] if not provided
          schema:
            type: array
            items:
              type: string
              enum:
                - LIVE
                - MATCHED
        - name: limit
          required: false
          in: query
          description: Maximum number of orders to return
          schema:
            minimum: 1
            example: 100
            type: number
        - name: slug
          required: true
          in: path
          description: Market slug identifier
          schema:
            example: presidential-election-2024
      responses:
        "200":
          description: List of user orders for the market
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: "12345"
                        side:
                          type: string
                          example: BUY
                        price:
                          type: string
                          example: "0.75"
                        quantity:
                          type: string
                          example: "100"
                        status:
                          type: string
                          example: LIVE
      security:
        - limitless_session: []
      summary: User Orders
      tags:
        - Trading
  /markets/{slug}/events:
    get:
      description: Get recent events for a specific market including trades, orders,
        and liquidity changes
      operationId: MarketOrderbookController_getMarketEvents
      parameters:
        - name: page
          required: false
          in: query
          description: Page number for pagination
          schema:
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of events per page
          schema:
            example: 20
            type: number
        - name: slug
          required: true
          in: path
          description: Market slug identifier
          schema:
            example: presidential-election-2024
      responses:
        "200":
          description: List of market events
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: event-123
                        type:
                          type: string
                          example: ORDER_PLACED
                        timestamp:
                          type: string
                          example: 2024-01-15T10:30:00Z
                        data:
                          type: object
                          additionalProperties: true
      summary: Market Events
      tags:
        - Trading
  /markets/search:
    get:
      operationId: MarketSearchController_search
      parameters:
        - name: query
          required: true
          in: query
          description: Search query text
          schema:
            example: Sports betting markets with high odds
            type: string
        - name: limit
          required: false
          in: query
          description: Maximum number of results to return
          schema:
            default: 10
            example: 10
            type: number
        - name: page
          required: false
          in: query
          description: Number of page
          schema:
            default: 1
            example: 0
            type: number
        - name: similarityThreshold
          required: false
          in: query
          description: Minimum similarity score (0-1)
          schema:
            default: 0.5
            example: 0.5
            type: number
      responses:
        "200":
          description: Returns markets matching the search query
        "400":
          description: Invalid request parameters
        "500":
          description: Internal server error
      summary: Search for markets based on semantic similarity
      tags:
        - Markets
  /portfolio/trades:
    get:
      description: Retrieve all trades executed by the authenticated user
      operationId: PortfolioController_getTrades
      parameters: []
      responses:
        "200":
          description: List of user trades with details
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        "401":
          description: Unauthorized
      security:
        - bearer: []
        - limitless_session: []
      summary: Get Trades
      tags:
        - Portfolio
  /portfolio/positions:
    get:
      description: Retrieve all active positions with P&L calculations and market values
      operationId: PortfolioController_getPositions
      parameters: []
      responses:
        "200":
          description: Complete portfolio positions with summary
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PortfolioPositionsDto"
        "401":
          description: Unauthorized
      security:
        - bearer: []
        - limitless_session: []
      summary: Get Positions
      tags:
        - Portfolio
  /portfolio/pnl-chart:
    get:
      description: "Hybrid PnL: realised series + current total snapshot"
      operationId: PortfolioController_getPnlChart
      parameters:
        - name: timeframe
          required: false
          in: query
          description: Timeframe window for percent change and chart series
          schema:
            example: 7d
            type: string
      responses:
        "200":
          description: PnL chart data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PortfolioPnlChartDto"
        "401":
          description: Unauthorized
      security:
        - bearer: []
        - limitless_session: []
      summary: Get portfolio PnL chart
      tags:
        - Portfolio
  /portfolio/history:
    get:
      description: Paginated history including AMM, CLOB trades, splits/merges,
        NegRisk conversions
      operationId: PortfolioController_getHistory
      parameters:
        - name: page
          required: true
          in: query
          description: Page number
          schema:
            example: 1
            type: number
        - name: limit
          required: true
          in: query
          description: Number of items per page
          schema:
            example: 10
            type: number
        - name: from
          required: false
          in: query
          description: Start date for filtering (ISO 8601 format)
          schema:
            format: date-time
            example: 2024-01-01T00:00:00.000Z
            type: string
        - name: to
          required: false
          in: query
          description: End date for filtering (ISO 8601 format)
          schema:
            format: date-time
            example: 2024-12-31T23:59:59.999Z
            type: string
      responses:
        "200":
          description: Paginated history of all user actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HistoryResponseDto"
        "400":
          description: Invalid pagination parameters
        "401":
          description: Unauthorized
      security:
        - bearer: []
        - limitless_session: []
      summary: Get History
      tags:
        - Portfolio
  /portfolio/points:
    get:
      operationId: PortfolioController_getPointsBreakdown
      parameters: []
      responses:
        "200":
          description: Points breakdown
        "401":
          description: Unauthorized
      security:
        - bearer: []
        - limitless_session: []
      summary: Get points breakdown
      tags:
        - Portfolio
  /portfolio/{account}/traded-volume:
    get:
      description: Get total traded volume and statistics for a specific user
      operationId: PublicPortfolioController_tradedVolume
      parameters:
        - name: account
          required: true
          in: path
          description: User Ethereum address
          schema:
            example: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
            type: string
      responses:
        "200":
          description: User trading volume statistics
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
      summary: User Total Volume
      tags:
        - Public Portfolio
  /portfolio/{account}/positions:
    get:
      description: Retrieve all positions for a specific user address
      operationId: PublicPortfolioController_getPositions
      parameters:
        - name: account
          required: true
          in: path
          description: User Ethereum address
          schema:
            example: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
            type: string
      responses:
        "200":
          description: Complete list of user positions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PortfolioPositionsDto"
      summary: Get All User Positions
      tags:
        - Public Portfolio
  /portfolio/{account}/pnl-chart:
    get:
      description: "Hybrid PnL: realised series + current total snapshot"
      operationId: PublicPortfolioController_getPnlChart
      parameters:
        - name: account
          required: true
          in: path
          description: User Ethereum address
          schema:
            example: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
            type: string
        - name: timeframe
          required: false
          in: query
          description: Timeframe window for percent change and chart series
          schema:
            example: 7d
            type: string
      responses:
        "200":
          description: PnL chart data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PortfolioPnlChartDto"
      summary: Get portfolio PnL chart (public)
      tags:
        - Public Portfolio
  /portfolio/trading/allowance:
    get:
      description: Check USDC allowance for CLOB or NegRisk trading contracts
      operationId: TradingPortfolioController_getAllowance
      parameters:
        - name: type
          required: true
          in: query
          description: "Trading type: CLOB or NegRisk"
          schema:
            enum:
              - clob
              - negrisk
            type: string
        - name: spender
          required: false
          in: query
          description: Optional spender address override (e.g., venue exchange address)
          schema:
            type: string
      responses:
        "200":
          description: User allowance information
          content:
            application/json:
              schema:
                type: object
                properties:
                  allowance:
                    type: string
                    example: "1000000000000"
                  hasMinimumAllowance:
                    type: boolean
                    example: true
                  type:
                    type: string
                    enum:
                      - clob
                      - negrisk
                    example: clob
                  spender:
                    type: string
                    example: 0x...
                  checkedAddress:
                    type: string
                    example: 0x...
        "400":
          description: Invalid type parameter
        "401":
          description: Unauthorized
        "404":
          description: Profile not found
      security:
        - bearer: []
        - limitless_session: []
      summary: Get User Trading Allowance
      tags:
        - Portfolio
  /orders:
    post:
      description: Creates a buy/sell order for prediction market positions. Requires
        signed order data.
      operationId: OrderController_createOrder
      parameters: []
      requestBody:
        required: true
        description: Order creation data including signature and order parameters
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateOrderDto"
      responses:
        "201":
          description: Order successfully created and matched
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrderResponseDto"
        "400":
          description: Invalid order data, insufficient balance/allowance, or market
            deadline passed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponseDto"
        "401":
          description: User not authenticated
        "500":
          description: Server error during order creation
      security:
        - limitless_session: []
      summary: Create Order
      tags:
        - Trading
  /orders/{orderId}:
    delete:
      description: Cancel an open order and return locked funds
      operationId: OrderController_cancelOrder
      parameters:
        - name: orderId
          required: true
          in: path
          description: Unique identifier of the order to be cancelled
          schema:
            example: 6f52b6d2-6c9e-4a5c-8a4f-28ab4b7ff203
            type: string
      responses:
        "200":
          description: Order successfully cancelled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CancelOrderResponseDto"
        "400":
          description: Order cannot be cancelled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponseDto"
        "401":
          description: User not authenticated or not the order owner
        "500":
          description: Server error during cancellation
      security:
        - bearer: []
      summary: Cancel Order
      tags:
        - Trading
  /orders/cancel-batch:
    post:
      operationId: OrderController_cancelOrderBatch
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeleteOrderBatchDto"
      responses:
        "200":
          description: All orders successfully cancelled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CancelOrderBatchResponseDto"
        "207":
          description: Partial success - some orders cancelled, some failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CancelOrderBatchResponseDto"
        "400":
          description: Orders from different markets, invalid order data, or no orders
            could be cancelled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponseDto"
        "401":
          description: User not authenticated or not the owner of all orders
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponseDto"
        "500":
          description: Server error during batch cancellation
      security:
        - bearer: []
      summary: Cancel multiple orders in batch
      tags:
        - Trading
  /orders/all/{slug}:
    delete:
      operationId: OrderController_cancelAllOrders
      parameters: []
      responses:
        "200":
          description: All orders successfully cancelled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CancelAllOrdersResponseDto"
        "207":
          description: Partial success - some orders cancelled, some failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CancelAllOrdersResponseDto"
        "400":
          description: Invalid market slug or no orders could be cancelled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponseDto"
        "401":
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponseDto"
        "500":
          description: Server error during cancellation
      security:
        - bearer: []
      summary: Cancel all of a user's orders in a specific market
      tags:
        - Trading
info:
  title: Limitless Exchange API
  description: >
    
    # Limitless Exchange Trading API


    *Production-ready API for prediction market trading, portfolio management,
    and market data*


    > 🎯 **Quick Navigation**: [Authentication](#tag/authentication) |
    [Markets](#tag/markets) | [Trading](#tag/trading) |
    [Portfolio](#tag/portfolio)


    ---
      


    ## 🚀 Quick Start


    Choose your preferred programming language for complete end-to-end
    implementation:


    ### Overview


    The Limitless Exchange API offers both REST and WebSocket integration:


    **REST API (Trading)**:

    1. **🔐 Authentication**: Use API key for all programmatic access

    2. **📊 Fetch Market Data**: Get market info including venue contract
    addresses (once per market)

    3. **📋 Order Creation**: Build and sign orders using EIP-712 structured
    data

    4. **🚀 Order Submission**: Submit signed orders and receive confirmations


    **WebSocket API (Real-Time Data)**:

    1. **🔌 Connection**: Connect to `/markets` namespace for real-time updates

    2. **📊 Subscriptions**: Subscribe to market prices and position changes

    3. **📡 Events**: Handle live market data and transaction updates


    ### 🔐 Authentication for API Users


    > **⚠️ DEPRECATION NOTICE**: Cookie-based session authentication is
    deprecated and will be removed within weeks. Please migrate to API keys
    immediately.


    | Method | Header | Status |

    |--------|--------|--------|

    | **API Key** | `X-API-Key: lmts_...` | ✅ Required for programmatic access |

    | Cookie Session | `Cookie: limitless_session=...` | ⚠️ Deprecated (removal
    imminent) |


    **Getting an API Key**


    API keys can only be created via the Limitless Exchange UI:

    1. Log in to [limitless.exchange](https://limitless.exchange) using your
    wallet

    2. Click your profile menu (top right)

    3. Select "Api keys"

    4. Generate a new key


    **Using Your API Key**


    Include in all requests via the `X-API-Key` header:


    ```bash

    # REST API

    curl -H "X-API-Key: lmts_your_key_here"
    https://api.limitless.exchange/markets


    # WebSocket - pass X-API-Key header during connection handshake

    ```


    ### Migration from Cookie to API Key


    If you're currently using cookie-based authentication, migrate by:


    1. **Generate an API key** via the UI (profile menu → Api keys)

    2. **Replace cookie header** with API key header:


    ```diff

    # Before (deprecated)

    - Cookie: limitless_session=your_session_token


    # After

    + X-API-Key: lmts_your_key_here

    ```


    3. **Remove session management code** - no more login flow or cookie
    handling needed


    ### Important: Venue System for CLOB Markets


    CLOB markets use a **venue system** where each market is associated with
    specific contract addresses. Before placing orders:


    1. **Fetch market data once**: `GET /markets/:slug` returns venue
    information

    2. **Use venue.exchange**: This is the `verifyingContract` for EIP-712 order
    signing

    3. **Cache the venue**: Venue data is static per market - fetch once and
    reuse


    **Sample venue response:**

    ```json

    {
      "venue": {
        "exchange": "0xA1b2C3...",
        "adapter": "0xD4e5F6..."
      }
    }

    ```


    ### Required Approvals


    Before trading, set up token approvals based on order type:


    | Order Type | Market Type | Approve To |

    |------------|-------------|------------|

    | BUY | All CLOB | USDC → `venue.exchange` |

    | SELL | Simple CLOB | CT → `venue.exchange` |

    | SELL | NegRisk/Grouped | CT → `venue.exchange` AND `venue.adapter` |


    ### Checksummed Addresses


    All addresses must use **checksummed format** (EIP-55 mixed-case):

    - Authentication: `x-account` header

    - Orders: `maker` and `signer` fields

    - Example: `0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed`


    ### Implementation Guides


    **[🐍 Python Quick Start](#description/-python-quick-start)**

    - REST API: eth-account, requests, and web3.py libraries

    - WebSocket: python-socketio, asyncio integration


    **[☕ Java Quick Start](#description/-java-quick-start)**  

    - REST API: Web3j, OkHttp3, and Jackson libraries


    **[📦 Node.js/TypeScript Quick
    Start](#description/-nodejs-typescript-quick-start)**

    - REST API: viem, ethers, and cross-fetch libraries

    - WebSocket: socket.io-client for real-time trading

    - Full TypeScript support with end-to-end examples


    **[🔌 WebSocket Integration](#description/-websocket-integration)**

    - Real-time market data and position updates

    - Production-ready Python client with authentication


    ---
      


    ## 🐍 Python Quick Start


    Complete end-to-end Python implementation for Limitless Exchange API
    integration.
      

    #### Python E2E Order Creation Guide


    ⚠️ **IMPORTANT DISCLAIMER** ✨ ⚠️


    ```

    This is an example script for educational purposes only.

    Limitless Labs is not responsible for any losses or mistakes.

    This script should be adjusted to your personal needs and risk tolerance.

    Always test with small amounts first and understand the code before using
    it.

    USE AT YOUR OWN RISK.

    ```


    This guide provides a complete walkthrough of creating orders on Limitless
    Exchange using Python, from authentication to order signing and submission.


    #### Overview


    The order creation process involves:


    1. **Authentication** ✨: Use API key for all programmatic access

    2. **Fetch Market Data** ✨: Get venue information from `GET /markets/:slug`
    (cache per market)

    3. **Order Construction** ✨: Build the order payload with proper parameters

    4. **EIP-712 Signing** ✨: Sign the order using venue's exchange address as
    `verifyingContract`

    5. **Order Submission** ✨: Submit the signed order to the API


    #### 🔐 Authentication for API Users


    > **⚠️ DEPRECATION NOTICE** ✨: Cookie-based session authentication is
    deprecated and will be removed within weeks. Migrate to API keys
    immediately.


    **Authentication Methods:** ✨


    - **API Key** ✨ (header: `X-API-Key: lmts_...`) - Required for programmatic
    access

    - **Cookie Session** ✨ (header: `Cookie: limitless_session=...`) -
    Deprecated, removal imminent


    **Getting an API Key** ✨:

    API keys can only be created via the UI: Login → profile menu (top right) →
    Api keys


    **Using Your API Key** ✨:

    Include in all requests: `X-API-Key: lmts_your_key_here`


    **Note** ✨: Private key is still required for EIP-712 order signing, but API
    key handles request authentication.


    #### Migration from Cookie to API Key


    Replace cookie header with API key header:


    ```diff

    // 🎯 Copy and customize this example

    #### Before (deprecated)

    - headers["cookie"] = f"limitless_session={session_cookie}"


    #### After

    + headers["X-API-Key"] = api_key

    ```


    #### Important: Venue System


    CLOB markets use a **venue system** ✨ where each market has specific
    contract addresses. You must:


    - Fetch market data via `GET /markets/:slug` to get `venue.exchange` and
    `venue.adapter`

    - Use `venue.exchange` as the `verifyingContract` in EIP-712 domain

    - Cache venue data per market (it's static and doesn't change)


    #### Required Approvals


    Before trading, set up token approvals:


    - **BUY orders** ✨: Approve USDC to `venue.exchange`

    - **SELL orders (simple CLOB)** ✨: Approve conditional tokens to
    `venue.exchange`

    - **SELL orders (NegRisk/grouped)** ✨: Approve conditional tokens to
    **both** ✨ `venue.exchange` AND `venue.adapter`


    #### Prerequisites


    #### Required Python Packages


    ```bash

    # 💻 Run in your terminal

    // 🎯 Copy and customize this example

    pip install eth-account requests web3

    ```


    #### Complete Implementation


    ```python

    // 🎯 Copy and customize this example

    #!/usr/bin/env python3

    """

    Limitless Exchange Trading Script

    WARNING: This is a demo script. Use at your own risk.

    Limitless Labs is not responsible for any losses or mistakes.

    """


    import requests

    import json

    import time

    import os

    from eth_account import Account

    from eth_account.messages import encode_defunct



    def sign_message(self, message: str) -> str:
        """Sign a message using the private key."""
        if not self.account:
            raise Exception("Private key not provided. Cannot sign message.")

        print(f"🖊️  Signing message for account: {self.account.address}")

        message_hash = encode_defunct(text=message)
        signed_message = self.account.sign_message(message_hash)
        signature_hex = signed_message.signature.hex()

        print(
            f"   Generated signature: {signature_hex[:10]}... (length: {len(signature_hex)})"
        )

        return signature_hex


    ####
    ============================================================================

    #### DISCLAIMER AND WARNING

    ####
    ============================================================================

    print("⚠️  WARNING: This is an example trading script for educational
    purposes.")

    print("⚠️  Limitless Labs is not responsible for any losses or mistakes.")

    print("⚠️  Always test with small amounts first and understand the code.")

    print("⚠️  USE AT YOUR OWN RISK.\n")


    ####
    ============================================================================

    #### Import Compatibility Layer

    ####
    ============================================================================


    try:
        from eth_account.messages import encode_typed_data

        print("✅ Successfully imported encode_typed_data from eth_account.messages")
    except ImportError:
        try:
            from eth_account.messages import encode_structured_data as encode_typed_data

            print("✅ Using encode_structured_data (fallback)")
        except ImportError as e:
            print(f"❌ Import error: {e}")

    ####
    ============================================================================

    #### Configuration

    ####
    ============================================================================


    API_BASE_URL = os.getenv("API_URL", "https://api.limitless.exchange")


    #### Market cache - stores venue data per market slug (venue is static per
    market)

    MARKET_CACHE = {}


    #### EIP-712 Type Definitions

    ORDER_TYPES = {
        "Order": [
            {"name": "salt", "type": "uint256"},
            {"name": "maker", "type": "address"},
            {"name": "signer", "type": "address"},
            {"name": "taker", "type": "address"},
            {"name": "tokenId", "type": "uint256"},
            {"name": "makerAmount", "type": "uint256"},
            {"name": "takerAmount", "type": "uint256"},
            {"name": "expiration", "type": "uint256"},
            {"name": "nonce", "type": "uint256"},
            {"name": "feeRateBps", "type": "uint256"},
            {"name": "side", "type": "uint8"},
            {"name": "signatureType", "type": "uint8"},
        ]
    }


    ####
    ============================================================================

    #### Utility Functions

    ####
    ============================================================================



    def string_to_hex(text):
        """Convert string to hex representation with 0x prefix."""
        return "0x" + text.encode("utf-8").hex()


    ####
    ============================================================================

    #### Market Data Functions

    ####
    ============================================================================



    def get_market_data(slug):
        """
        Fetch market data including venue information.
        Uses cache to avoid repeated API calls (venue is static per market).

        Args:
            slug: The market slug

        Returns:
            dict: Market data including venue, tokens, etc.
        """
        if slug in MARKET_CACHE:
            print(f"📦 Using cached market data for: {slug}")
            return MARKET_CACHE[slug]

        print(f"📊 Fetching market data for: {slug}")
        response = requests.get(f"{API_BASE_URL}/markets/{slug}")
        if response.status_code == 200:
            market = response.json()
            MARKET_CACHE[slug] = market
            print(f"✅ Market data cached. Venue exchange: {market.get('venue', {}).get('exchange')}")
            return market
        else:
            raise Exception(f"Failed to get market data: {response.status_code} - {response.text}")


    def get_venue_exchange(slug):
        """
        Get the venue exchange address for a market (used as verifyingContract).

        Args:
            slug: The market slug

        Returns:
            str: The venue exchange address (checksummed)
        """
        market = get_market_data(slug)
        venue = market.get("venue")
        if not venue or not venue.get("exchange"):
            raise Exception(f"Market {slug} does not have venue data")
        return venue["exchange"]


    ####
    ============================================================================

    #### Authentication Functions

    ####
    ============================================================================



    def get_signing_message():
        """
        Fetch the signing message from the API.

        Returns:
            str: The signing message to be signed
        """
        response = requests.get(f"{API_BASE_URL}/auth/signing-message")
        if response.status_code == 200:
            return response.text
        else:
            raise Exception(f"Failed to get signing message: {response.status_code}")


    def authenticate(private_key, signing_message):
        """
        Authenticate with the Limitless Exchange API.

        Args:
            private_key: Your wallet's private key
            signing_message: The message to sign for authentication

        Returns:
            tuple: (session_cookie, user_data)

        Note:
            The address must be checksummed (EIP-55 format).
            eth_account.Account.from_key() returns checksummed addresses by default.

            TIP: Session cookie is valid for ~30 days. Consider saving to file and secure it! :
            # Save after authentication:
            # with open('.session_cookie.json', 'w') as f:
            #     json.dump({'cookie': session_cookie, 'user_data': user_data}, f)
            #
            # Load on subsequent runs:
            # with open('.session_cookie.json', 'r') as f:
            #     saved = json.load(f)
            #     session_cookie, user_data = saved['cookie'], saved['user_data']
        """
        hex_message = "0x" + signing_message.encode("utf-8").hex()

        # Get the Ethereum address from the private key
        if not private_key.startswith("0x"):
            private_key = "0x" + private_key
        account = Account.from_key(private_key)
        # account.address is already checksummed (EIP-55 format)
        ethereum_address = account.address

        print(f"Using address (checksummed): {ethereum_address}")
        print(f"Signing message: {repr(signing_message)}")

        # Sign the message
        message = encode_defunct(text=signing_message)
        signature = account.sign_message(message)
        sig_hex = signature.signature.hex()
        if not sig_hex.startswith("0x"):
            sig_hex = "0x" + sig_hex

        # x-account must be checksummed address
        headers = {
            "x-account": ethereum_address,
            "x-signing-message": hex_message,
            "x-signature": sig_hex,
            "Content-Type": "application/json",
        }

        response = requests.post(
            f"{API_BASE_URL}/auth/login", headers=headers, json={"client": "eoa"}
        )

        if response.status_code == 200:
            session_cookie = response.cookies.get("limitless_session")
            return session_cookie, response.json()
        else:
            raise Exception(
                f"Authentication failed: {response.status_code} - {response.text}"
            )


    ####
    ============================================================================

    #### Order Creation Functions

    ####
    ============================================================================



    def create_order_payload_without_signature(
        maker_address, token_id, maker_amount, taker_amount, fee_rate_bps
    ):
        """
        Create the base order payload without signature.

        Args:
            maker_address: The maker's wallet address
            token_id: The token ID to trade (YES or NO token)
            maker_amount: Amount the maker is offering (scaled)
            taker_amount: Amount the maker wants in return (scaled)
            fee_rate_bps: Fee rate in basis points

        Returns:
            dict: Order payload ready for signing
        """
        salt = int(time.time() * 1000) + (24 * 60 * 60 * 1000)  # Current time + 24h in ms

        return {
            "salt": salt,
            "maker": maker_address,
            "signer": maker_address,
            "taker": "0x0000000000000000000000000000000000000000",  # Open to any taker
            "tokenId": str(token_id),  # Keep as string for API
            "makerAmount": maker_amount,
            "takerAmount": taker_amount,
            "expiration": "0",  # No expiration
            "nonce": 0,
            "feeRateBps": fee_rate_bps,
            "side": 0,  # 0 = BUY
            "signatureType": 0,  # 0 = EOA signature
        }


    def get_eip712_domain(venue_exchange_address):
        """
        Get the EIP-712 domain for signing.

        Args:
            venue_exchange_address: The venue's exchange contract address from market data

        Returns:
            dict: EIP-712 domain object
        """
        return {
            "name": "Limitless CTF Exchange",
            "version": "1",
            "chainId": 8453,  # Base chain ID
            "verifyingContract": venue_exchange_address,
        }


    def create_signature_for_order_payload(venue_exchange_address,
    order_payload, private_key):
        """
        Sign an order payload using EIP-712.

        Args:
            venue_exchange_address: The venue's exchange address (verifyingContract)
            order_payload: The order data to sign
            private_key: Private key for signing

        Returns:
            str: Hex-encoded signature
        """
        # Remove '0x' prefix if present
        if private_key.startswith("0x"):
            private_key = private_key[2:]

        # Create account
        account = Account.from_key("0x" + private_key)

        # Get domain data using venue's exchange address
        domain_data = get_eip712_domain(venue_exchange_address)

        # Convert string fields to int for signing
        message_data = {
            "salt": order_payload["salt"],
            "maker": order_payload["maker"],
            "signer": order_payload["signer"],
            "taker": order_payload["taker"],
            "tokenId": int(order_payload["tokenId"]),
            "makerAmount": order_payload["makerAmount"],
            "takerAmount": order_payload["takerAmount"],
            "expiration": int(order_payload["expiration"])
            if order_payload["expiration"]
            else 0,
            "nonce": order_payload["nonce"],
            "feeRateBps": order_payload["feeRateBps"],
            "side": order_payload["side"],
            "signatureType": order_payload["signatureType"],
        }

        print(f"Domain: {json.dumps(domain_data, indent=2)}")
        print(f"Types: {json.dumps(ORDER_TYPES, indent=2)}")
        print(f"Message: {json.dumps(message_data, indent=2)}")

        # Sign using eth_account's implementation of EIP-712
        encoded_message = encode_typed_data(domain_data, ORDER_TYPES, message_data)
        signed_message = account.sign_message(encoded_message)

        # Extract signature
        signature = signed_message.signature.hex()

        print(f"Successfully generated EIP-712 Signature: {signature}")
        return "0x" + signature


    def create_order_api(order_payload, api_key=None, session_cookie=None):
        """
        Submit an order to the API.

        Args:
            order_payload: Complete order payload with signature
            api_key: API key for authentication (recommended)
            session_cookie: Authentication session cookie (deprecated)

        Returns:
            dict: API response with order details
        """
        api_url = f"{API_BASE_URL}/orders"

        headers = {
            "Content-Type": "application/json",
            "Accept": "application/json",
        }

        # Prefer API key over session cookie
        if api_key:
            headers["X-API-Key"] = api_key
        elif session_cookie:
            print("⚠️  Using deprecated cookie auth. Please migrate to API keys.")
            headers["cookie"] = f"limitless_session={session_cookie}"
        else:
            raise Exception("Authentication required: provide api_key or session_cookie")

        print(f"Order payload: {json.dumps(order_payload, indent=2)}")

        try:
            response = requests.post(
                api_url, headers=headers, json=order_payload, timeout=35
            )

            if response.status_code != 201:
                print(f"Failed to create order. Status: {response.status_code}")
                print(f"Response: {response.text}")
                raise Exception(f"API Error {response.status_code}: {response.text}")

            result = response.json()
            print(f"Order created successfully: {json.dumps(result, indent=2)}")
            return result

        except Exception as error:
            print(f"Error creating order: {error}")
            raise error


    ####
    ============================================================================

    #### Main Trading Function

    ####
    ============================================================================



    def execute_trade(trading_params, market_slug, session_cookie, user_data,
    private_key):
        """
        Main function to execute a trade on Limitless Exchange.

        Args:
            trading_params: Dictionary containing:
                - sharePrice: price in cents (e.g., 65 for 65¢)
                - amount: amount in shares (e.g., 100)
                - firstType: "YES" or "NO"

            market_slug: The market slug (used to fetch market data including venue)

            session_cookie: Session cookie from authenticate() - REQUIRED
            user_data: User data from authenticate() - REQUIRED
            private_key: Your wallet's private key (for order signing only)

        Returns:
            dict: Order execution result

        Note:
            You MUST authenticate before calling this function:

            signing_message = get_signing_message()
            session_cookie, user_data = authenticate(private_key, signing_message)

            TIP: Session cookie is valid for ~30 days. Save to file and reuse:
            # Save after first auth:
            # with open('.session_cookie.json', 'w') as f:
            #     json.dump({'cookie': session_cookie, 'user_data': user_data}, f)
            #
            # Load on subsequent runs:
            # with open('.session_cookie.json', 'r') as f:
            #     saved = json.load(f)
            #     session_cookie, user_data = saved['cookie'], saved['user_data']
        """

        # Step 1: Fetch market data (cached per market)
        # This gets venue info needed for EIP-712 signing
        market_data = get_market_data(market_slug)
        venue_exchange = market_data["venue"]["exchange"]
        print(f"Using venue exchange: {venue_exchange}")

        # Step 2: Calculate amounts
        price_in_cents = trading_params["sharePrice"]
        amount = trading_params["amount"]
        trade_type = "GTC"  # Good Till Cancelled
        scaling_factor = 1000000  # 1e6 for USDC (6 decimals)

        # Get token IDs from market data
        # positionIds[0] = YES token, positionIds[1] = NO token
        position_ids = market_data.get("positionIds", [])
        if len(position_ids) < 2:
            raise Exception("Market does not have valid position IDs")

        first_user_token = (
            position_ids[0]
            if trading_params["firstType"] == "YES"
            else position_ids[1]
        )

        # Calculate amounts
        price_in_dollars = price_in_cents / 100  # Convert cents to dollars
        total_cost = price_in_dollars * amount  # Total cost in dollars
        maker_amount = round(total_cost * scaling_factor)
        taker_amount = round(amount * scaling_factor)

        print(
            f"Trading: {amount} shares at {price_in_cents} cents ({price_in_dollars} dollars) each"
        )
        print(f"Total cost: {total_cost} dollars")
        print(f"Maker amount: {maker_amount}")
        print(f"Taker amount: {taker_amount}")

        # Step 3: Create order payload without signature
        # user_data["account"] is already checksummed
        order_payload_without_signature = create_order_payload_without_signature(
            user_data["account"],
            first_user_token,
            maker_amount,
            taker_amount,
            user_data.get("rank", {}).get("feeRateBps", 0),
        )

        # Step 4: Sign the order using venue's exchange address
        signature = create_signature_for_order_payload(
            venue_exchange, order_payload_without_signature, private_key
        )

        # Step 5: Create final order payload
        final_order_payload = {
            "order": {
                **order_payload_without_signature,
                "price": price_in_dollars,  # Send as decimal
                "signature": signature,
            },
            "ownerId": user_data["id"],
            "orderType": trade_type,
            "marketSlug": market_slug,
        }

        print(
            f"Order placed for ${price_in_cents} cents, amount: {amount}, share type: {trading_params['firstType']}"
        )

        # Step 6: Submit to API
        result = create_order_api(final_order_payload, session_cookie)
        return result


    ####
    ============================================================================

    #### Example Usage

    ####
    ============================================================================


    if __name__ == "__main__":
        print("=" * 80)
        print("LIMITLESS EXCHANGE TRADING SCRIPT - DEMO")
        print("=" * 80)
        print("\n⚠️  This is a demonstration script. Please modify for your needs.")
        print("⚠️  Never share your private key with anyone.")
        print("⚠️  Always test with small amounts first.\n")
        print("=" * 80)

        # Example parameters - REPLACE THESE WITH YOUR ACTUAL VALUES
        trading_params = {
            "sharePrice": 50,  # Price in cents (50¢)
            "amount": 2,  # Number of shares
            "firstType": "YES",  # 'YES' or 'NO'
        }

        # Market slug - the script will fetch market data (including venue and tokens) automatically
        market_slug = "example-market-slug"  # Replace with actual market slug

        # SECURITY WARNING: Never hardcode your private key!
        # Use environment variables or secure key management
        private_key = os.getenv("PRIVATE_KEY", "<FALLBACK_VALUE_FOR_P_KEY>")

        if private_key == "<FALLBACK_VALUE_FOR_P_KEY>":
            print(
                "❌ ERROR: Please set your private key in the environment variable PRIVATE_KEY"
            )
            print("Example: export PRIVATE_KEY='0x...'")
            exit(1)

        print("🚀 Starting trading script...")
        print(f"Trading parameters: {trading_params}")
        print(f"Market slug: {market_slug}")

        try:
            # Step 1: Authenticate (or load from saved file)
            # TIP: Read cookie from saved file as it lasts 30 days
            # import json
            # try:
            #     with open('.session_cookie.json', 'r') as f:
            #         saved = json.load(f)
            #         session_cookie = saved['cookie']
            #         user_data = saved['user_data']
            #         print("✅ Loaded session from file")
            # except FileNotFoundError:
            #     signing_message = get_signing_message()
            #     session_cookie, user_data = authenticate(private_key, signing_message)
            #     # Save for reuse:
            #     with open('.session_cookie.json', 'w') as f:
            #         json.dump({'cookie': session_cookie, 'user_data': user_data}, f)
            #     print("💾 Session saved to file")

            # For demo, authenticate each time (you should save/load from file):
            signing_message = get_signing_message()
            session_cookie, user_data = authenticate(private_key, signing_message)
            print(f"✅ Authenticated as: {user_data['account']}")

            # Step 2: Execute trade with authenticated session
            # Market data (including venue) is fetched and cached automatically
            result = execute_trade(
                trading_params,
                market_slug,
                session_cookie,
                user_data,
                private_key
            )
            print("\n✅ Trade executed successfully!")
            print(f"Result: {json.dumps(result, indent=2)}")

            # You can execute more trades with the same session:
            # result2 = execute_trade(other_params, market_slug, session_cookie, user_data, private_key)

        except Exception as e:
            print(f"\n❌ Error executing trade: {e}")
            import traceback

            traceback.print_exc()
    ```


    #### Important Notes


    #### ⚠️ Security Considerations


    - **NEVER** ✨ share your private key with anyone

    - **NEVER** ✨ commit your private key to version control

    - Use environment variables to store sensitive information

    - Always test with small amounts first

    - Understand the code before using it with real funds


    #### Authentication Flow


    **IMPORTANT** ✨: You must authenticate BEFORE calling `execute_trade()`. The
    function requires a valid session.


    ```python

    // 🎯 Copy and customize this example

    #### Step 1: Authenticate (do this once)

    signing_message = get_signing_message()

    session_cookie, user_data = authenticate(private_key, signing_message)


    #### Step 2: Execute trade(s) with the session

    result = execute_trade(trading_params, market_slug, session_cookie,
    user_data, private_key)


    #### You can execute multiple trades with the same session:

    result2 = execute_trade(other_params, market_slug, session_cookie,
    user_data, private_key)

    ```


    #### Session Reuse (Recommended)


    Session cookies are valid for ~30 days. To avoid repeated authentication,
    consider saving the session to a file after first authentication and loading
    it on subsequent runs.


    **Recommendations** ✨:


    - Use `json.dump()` to save `session_cookie` and `user_data` after
    authentication

    - Use `json.load()` to read the saved session on subsequent runs

    - Handle `FileNotFoundError` when session file doesn't exist

    - Add session file to `.gitignore` to prevent committing sensitive data

    - Set restrictive file permissions: `chmod 600 .session_cookie.json`


    #### Order Types


    - **GTC (Good Till Cancelled)** ✨: Order remains active until filled or
    cancelled

    - **FOK (Fill or Kill)** ✨: Fill completely or cancel


    #### Price Calculation


    - Prices are in cents (e.g., 65 = 65¢ = 0.65 USD)

    - YES price = probability of outcome occurring

    - NO price = 1 - YES price


    #### Amount Calculation


    - USDC has 6 decimals (1 USDC = 1,000,000 units)

    - Shares are scaled by 1e6 for precision

    - Always verify calculations before submitting orders


    #### Market Types


    - **single-clob** ✨: Standard central limit order book markets

    - **group-negrisk** ✨: Grouped markets with multiple related outcomes


    #### Error Handling


    Always implement proper error handling for:


    - Network failures

    - Authentication errors

    - Insufficient balance

    - Market closed/resolved

    - Invalid order parameters


    #### Environment Variables


    Set these environment variables for production use:


    ```bash

    # 💻 Run in your terminal

    // 🎯 Copy and customize this example

    #### Recommended: API key for request authentication

    export API_KEY="lmts_..."     # Your API key (generate via UI: profile menu
    → Api keys)


    #### Required: For EIP-712 order signing

    export PRIVATE_KEY="0x..."    # Your wallet private key


    #### Optional (defaults shown)

    export API_URL="https://api.limitless.exchange"

    ```


    **Note** ✨: Contract addresses (exchange, adapter) are now fetched
    dynamically from the market's venue data via `GET /markets/:slug`. You no
    longer need to configure them as environment variables.


    #### Troubleshooting


    #### Common Issues


    1. **ImportError for encode_typed_data** ✨
       - Solution: Upgrade eth-account: `pip install eth-account==0.10.0 `

    2. **Authentication Failed** ✨
       - Check that your private key is correct
       - Ensure you're using the correct format (with or without '0x' prefix)

    3. **Order Creation Failed** ✨
       - Verify market slug and token IDs are correct
       - Check that you have sufficient balance
       - Ensure the market is still open

    4. **Signature Verification Failed** ✨
       - Ensure you're using the venue's exchange address from market data
       - Verify the chain ID matches (8453 for Base)
       - Make sure addresses are checksummed (EIP-55 format)

    #### Disclaimer


    **This script is provided for educational purposes only. Limitless Labs is
    not responsible for any losses, mistakes, or unintended consequences from
    using this code. Trading involves risk, and you should never trade more than
    you can afford to lose. Always understand the code you're running and test
    with small amounts first.** ✨


    #### Support


    For API support and questions:


    - Documentation: https://limitlesslabs.notion.site/

    - Support: hey@limitless.network



    ---



    _Last updated: 2026-02-03_




    ## ☕ Java Quick Start


    Complete end-to-end Java implementation for Limitless Exchange API
    integration.
      

    #### Java E2E Order Creation Guide


    ⚠️ **IMPORTANT DISCLAIMER** ✨ ⚠️


    ```

    This is an example implementation for educational purposes only.

    Limitless Labs is not responsible for any losses or mistakes.

    This code should be adjusted to your personal needs and risk tolerance.

    Always test with small amounts first and understand the code before using
    it.

    USE AT YOUR OWN RISK.

    ```


    This guide provides a complete Java implementation for creating orders on
    Limitless Exchange, from authentication to order signing and submission.


    #### Overview


    The order creation process involves:


    1. **Authentication** ✨: Get a signing message and authenticate with your
    wallet (use checksummed addresses)

    2. **Fetch Market Data** ✨: Get venue information from `GET /markets/:slug`
    (cache per market)

    3. **Order Construction** ✨: Build the order payload with proper parameters

    4. **EIP-712 Signing** ✨: Sign the order using venue's exchange address as
    `verifyingContract`

    5. **Order Submission** ✨: Submit the signed order to the API


    #### Important: Venue System


    CLOB markets use a **venue system** ✨ where each market has specific
    contract addresses. You must:


    - Fetch market data via `GET /markets/:slug` to get `venue.exchange` and
    `venue.adapter`

    - Use `venue.exchange` as the `verifyingContract` in EIP-712 domain

    - Cache venue data per market (it's static and doesn't change)


    #### Required Approvals


    Before trading, set up token approvals:


    - **BUY orders** ✨: Approve USDC to `venue.exchange`

    - **SELL orders (simple CLOB)** ✨: Approve conditional tokens to
    `venue.exchange`

    - **SELL orders (NegRisk/grouped)** ✨: Approve conditional tokens to
    **both** ✨ `venue.exchange` AND `venue.adapter`


    #### Project Setup


    #### Project Structure


    Create the following directory structure:


    ```

    limitless-trading-example/

    ├── build.gradle

    ├── gradle/

    │   └── wrapper/

    │       ├── gradle-wrapper.jar

    │       └── gradle-wrapper.properties

    ├── gradlew

    ├── gradlew.bat

    └── src/
        └── main/
            └── java/
                └── com/
                    └── limitless/
                        └── example/
                            └── LimitlessTradingExample.java
    ```


    #### Initialize Gradle Project


    ```bash

    # 💻 Run in your terminal

    // 🎯 Copy and customize this example

    mkdir limitless-trading-example

    cd limitless-trading-example

    gradle init --type java-application

    ```


    #### Dependencies


    #### build.gradle


    ```gradle

    // 🎯 Copy and customize this example

    plugins {
        id 'java'
        id 'application'
    }


    group = 'com.limitless.example'

    version = '1.0.0'

    sourceCompatibility = '11'


    repositories {
        mavenCentral()
    }


    dependencies {
        // Web3j for Ethereum operations
        implementation 'org.web3j:core:4.9.8'
        implementation 'org.web3j:crypto:4.9.8'

        // OkHttp for HTTP operations
        implementation 'com.squareup.okhttp3:okhttp:4.11.0'
        implementation 'com.squareup.okhttp3:okhttp-urlconnection:4.11.0'

        // Jackson for JSON processing
        implementation 'com.fasterxml.jackson.core:jackson-databind:2.15.2'

        // Bouncy Castle for additional crypto support
        implementation 'org.bouncycastle:bcprov-jdk15on:1.70'

        // SLF4J for logging
        implementation 'org.slf4j:slf4j-api:2.0.7'
        implementation 'ch.qos.logback:logback-classic:1.4.8'

        // Testing
        testImplementation 'junit:junit:4.13.2'
    }


    application {
        mainClass = 'com.limitless.example.LimitlessTradingExample'
    }


    // Create a fat JAR with all dependencies

    task fatJar(type: Jar) {
        manifest {
            attributes 'Main-Class': 'com.limitless.example.LimitlessTradingExample'
        }
        archiveClassifier = 'all'
        from {
            configurations.runtimeClasspath.collect { it.isDirectory() ? it : zipTree(it) }
        }
        with jar
    }

    ```


    #### Complete Implementation


    #### LimitlessTradingExample.java


    ```java

    // 🎯 Copy and customize this example

    package com.limitless.example;


    import com.fasterxml.jackson.databind.JsonNode;

    import com.fasterxml.jackson.databind.ObjectMapper;

    import com.fasterxml.jackson.databind.node.ObjectNode;

    import com.fasterxml.jackson.databind.node.ArrayNode;


    import okhttp3.CookieJar;

    import okhttp3.JavaNetCookieJar;

    import okhttp3.MediaType;

    import okhttp3.OkHttpClient;

    import okhttp3.Request;

    import okhttp3.RequestBody;

    import okhttp3.Response;


    import org.web3j.crypto.Credentials;

    import org.web3j.crypto.Sign;

    import org.web3j.crypto.StructuredDataEncoder;

    import org.web3j.crypto.Keys;


    import org.slf4j.Logger;

    import org.slf4j.LoggerFactory;

    import org.web3j.utils.Numeric;


    import java.io.IOException;

    import java.math.BigInteger;

    import java.net.CookieManager;

    import java.net.HttpCookie;

    import java.nio.charset.StandardCharsets;

    import java.util.*;

    import java.util.concurrent.TimeUnit;


    /**
     * Limitless Exchange Trading Example
     *
     * WARNING: This is a demo implementation. Use at your own risk.
     * Limitless Labs is not responsible for any losses or mistakes.
     *
     * This example demonstrates how to:
     * - Authenticate with the Limitless Exchange API
     * - Create and sign orders using EIP-712
     * - Submit orders to the exchange
     */
    public class LimitlessTradingExample {

        private static final Logger logger = LoggerFactory.getLogger(LimitlessTradingExample.class);
        private static final ObjectMapper objectMapper = new ObjectMapper();

        // ============================================================================
        // Configuration
        // ============================================================================

        private static final String API_BASE_URL = System.getenv("API_URL") != null ?
            System.getenv("API_URL") : "https://api.limitless.exchange";

        private static final int CHAIN_ID = 8453; // Base chain ID

        // Market cache - stores market data per slug (venue is static per market)
        private static final Map<String, JsonNode> MARKET_CACHE = new HashMap<>();

        // HTTP client with cookie support
        private static final CookieManager cookieManager = new CookieManager();
        private static final OkHttpClient httpClient = new OkHttpClient.Builder()
            .cookieJar(new JavaNetCookieJar(cookieManager))
            .connectTimeout(30, TimeUnit.SECONDS)
            .readTimeout(30, TimeUnit.SECONDS)
            .build();

        // ============================================================================
        // Data Classes
        // ============================================================================

        public static class TradingParams {
            public final int firstPrice;  // Price in cents
            public final int amount;      // Number of shares
            public final String firstType; // "YES" or "NO"

            public TradingParams(int firstPrice, int amount, String firstType) {
                this.firstPrice = firstPrice;
                this.amount = amount;
                this.firstType = firstType;
            }
        }


        public static class AuthResult {
            public final String sessionCookie;
            public final JsonNode userData;

            public AuthResult(String sessionCookie, JsonNode userData) {
                this.sessionCookie = sessionCookie;
                this.userData = userData;
            }
        }

        // ============================================================================
        // Utility Functions
        // ============================================================================

        private static String stringToHex(String text) {
            return "0x" + Numeric.toHexStringNoPrefix(text.getBytes(StandardCharsets.UTF_8));
        }

        // ============================================================================
        // Market Data Functions
        // ============================================================================

        /**
         * Fetch market data including venue information.
         * Uses cache to avoid repeated API calls (venue is static per market).
         */
        private static JsonNode getMarketData(String slug) throws IOException {
            if (MARKET_CACHE.containsKey(slug)) {
                logger.info("Using cached market data for: {}", slug);
                return MARKET_CACHE.get(slug);
            }

            logger.info("Fetching market data for: {}", slug);

            Request request = new Request.Builder()
                .url(API_BASE_URL + "/markets/" + slug)
                .get()
                .build();

            try (Response response = httpClient.newCall(request).execute()) {
                if (!response.isSuccessful()) {
                    throw new IOException("Failed to get market data: " + response.code() + " - " + response.body().string());
                }

                JsonNode market = objectMapper.readTree(response.body().string());
                MARKET_CACHE.put(slug, market);

                String venueExchange = market.path("venue").path("exchange").asText(null);
                logger.info("Market data cached. Venue exchange: {}", venueExchange);

                return market;
            }
        }

        /**
         * Get the venue exchange address for a market (used as verifyingContract).
         */
        private static String getVenueExchange(String slug) throws IOException {
            JsonNode market = getMarketData(slug);
            JsonNode venue = market.get("venue");
            if (venue == null || venue.get("exchange") == null) {
                throw new IOException("Market " + slug + " does not have venue data");
            }
            return venue.get("exchange").asText();
        }

        // ============================================================================
        // Authentication
        // ============================================================================

        private static String getSigningMessage() throws IOException {
            logger.info("Fetching signing message from API...");

            Request request = new Request.Builder()
                .url(API_BASE_URL + "/auth/signing-message")
                .get()
                .build();

            try (Response response = httpClient.newCall(request).execute()) {
                if (!response.isSuccessful()) {
                    throw new IOException("Failed to get signing message: " + response.code());
                }

                String signingMessage = response.body().string();
                logger.info("Signing message received: {}", signingMessage);
                return signingMessage;
            }
        }

        private static AuthResult authenticate(String privateKey, String signingMessage) throws Exception {
            logger.info("Authenticating with private key...");

            // Create credentials from private key
            Credentials credentials = Credentials.create(privateKey);
            String address = credentials.getAddress();
            logger.info("Using address: {}", address);

            // Sign the message
            byte[] messageBytes = signingMessage.getBytes(StandardCharsets.UTF_8);
            Sign.SignatureData signature = Sign.signPrefixedMessage(messageBytes, credentials.getEcKeyPair());

            // Convert signature to hex
            String signatureHex = Numeric.toHexString(signature.getR()) +
                                  Numeric.toHexStringNoPrefix(signature.getS()) +
                                  Numeric.toHexStringNoPrefix(signature.getV());

            // Prepare request
            String hexMessage = stringToHex(signingMessage);

            ObjectNode requestBody = objectMapper.createObjectNode();
            requestBody.put("client", "eoa");

            RequestBody body = RequestBody.create(
                objectMapper.writeValueAsString(requestBody),
                MediaType.parse("application/json")
            );

            String checksumAddress = Keys.toChecksumAddress(credentials.getAddress());

            Request request = new Request.Builder()
                .url(API_BASE_URL + "/auth/login")
                .addHeader("x-account", checksumAddress)
                .addHeader("x-signing-message", hexMessage)
                .addHeader("x-signature", signatureHex)
                .addHeader("Content-Type", "application/json")
                .addHeader("Accept", "application/json")
                .post(body)
                .build();

            try (Response response = httpClient.newCall(request).execute()) {
                if (!response.isSuccessful()) {
                    throw new Exception("Authentication failed: " + response.code() + " - " + response.body().string());
                }

                // Extract session cookie
                String sessionCookie = null;
                for (HttpCookie cookie : cookieManager.getCookieStore().getCookies()) {
                    if ("limitless_session".equals(cookie.getName())) {
                        sessionCookie = cookie.getValue();
                        break;
                    }
                }

                if (sessionCookie == null) {
                    throw new Exception("Session cookie not found in response");
                }

                JsonNode userData = objectMapper.readTree(response.body().string());
                logger.info("Authenticated as: {}", userData.get("account").asText());

                return new AuthResult(sessionCookie, userData);
            }
        }

        // ============================================================================
        // Order Creation
        // ============================================================================

        private static Map<String, Object> createOrderPayloadWithoutSignature(
                String makerAddress,
                String tokenId,
                long makerAmount,
                long takerAmount,
                int feeRateBps) {

            long salt = System.currentTimeMillis() + (24L * 60 * 60 * 1000); // Current time + 24h

            Map<String, Object> payload = new LinkedHashMap<>();
            payload.put("salt", salt);
            payload.put("maker", Keys.toChecksumAddress(makerAddress));
            payload.put("signer", Keys.toChecksumAddress(makerAddress));
            payload.put("taker", "0x0000000000000000000000000000000000000000");
            payload.put("tokenId", tokenId); // Keep as string for API
            payload.put("makerAmount", makerAmount);
            payload.put("takerAmount", takerAmount);
            payload.put("expiration", "0");
            payload.put("nonce", 0);
            payload.put("feeRateBps", feeRateBps);
            payload.put("side", 0); // 0 = BUY
            payload.put("signatureType", 0);

            return payload;
        }

        // ============================================================================
        // EIP-712 Signing
        // ============================================================================

        /**
         * Get the EIP-712 domain for signing.
         * @param venueExchangeAddress The venue's exchange contract address from market data
         */
        private static Map<String, Object> getEip712Domain(String venueExchangeAddress) {
            Map<String, Object> domain = new LinkedHashMap<>();
            domain.put("name", "Limitless CTF Exchange");
            domain.put("version", "1");
            domain.put("chainId", CHAIN_ID);
            domain.put("verifyingContract", venueExchangeAddress);

            return domain;
        }

        /**
         * Sign an order payload using EIP-712.
         * @param venueExchangeAddress The venue's exchange address (verifyingContract)
         * @param orderPayload The order data to sign
         * @param privateKey Private key for signing
         */
        private static String createSignatureForOrderPayload(
                String venueExchangeAddress,
                Map<String, Object> orderPayload,
                String privateKey) throws Exception {

            logger.info("Creating EIP-712 signature...");

            Credentials credentials = Credentials.create(privateKey);
            Map<String, Object> domain = getEip712Domain(venueExchangeAddress);

            // Convert for signing (tokenId and expiration to BigInteger)
            Map<String, Object> signingPayload = new LinkedHashMap<>(orderPayload);
            signingPayload.put("tokenId", new BigInteger(orderPayload.get("tokenId").toString()));
            signingPayload.put("expiration", new BigInteger(orderPayload.get("expiration").toString()));

            // Create EIP-712 typed data structure
            ObjectNode typedData = objectMapper.createObjectNode();

            // Add domain
            ObjectNode domainNode = objectMapper.createObjectNode();
            domainNode.put("name", domain.get("name").toString());
            domainNode.put("version", domain.get("version").toString());
            domainNode.put("chainId", (Integer) domain.get("chainId"));
            domainNode.put("verifyingContract", domain.get("verifyingContract").toString());
            typedData.set("domain", domainNode);

            // Add types
            ObjectNode types = objectMapper.createObjectNode();

            // EIP712Domain
            ArrayNode domainTypeArray = objectMapper.createArrayNode();
            domainTypeArray.add(objectMapper.createObjectNode().put("name", "name").put("type", "string"));
            domainTypeArray.add(objectMapper.createObjectNode().put("name", "version").put("type", "string"));
            domainTypeArray.add(objectMapper.createObjectNode().put("name", "chainId").put("type", "uint256"));
            domainTypeArray.add(objectMapper.createObjectNode().put("name", "verifyingContract").put("type", "address"));
            types.set("EIP712Domain", domainTypeArray);

            // Order
            ArrayNode orderTypeArray = objectMapper.createArrayNode();
            orderTypeArray.add(objectMapper.createObjectNode().put("name", "salt").put("type", "uint256"));
            orderTypeArray.add(objectMapper.createObjectNode().put("name", "maker").put("type", "address"));
            orderTypeArray.add(objectMapper.createObjectNode().put("name", "signer").put("type", "address"));
            orderTypeArray.add(objectMapper.createObjectNode().put("name", "taker").put("type", "address"));
            orderTypeArray.add(objectMapper.createObjectNode().put("name", "tokenId").put("type", "uint256"));
            orderTypeArray.add(objectMapper.createObjectNode().put("name", "makerAmount").put("type", "uint256"));
            orderTypeArray.add(objectMapper.createObjectNode().put("name", "takerAmount").put("type", "uint256"));
            orderTypeArray.add(objectMapper.createObjectNode().put("name", "expiration").put("type", "uint256"));
            orderTypeArray.add(objectMapper.createObjectNode().put("name", "nonce").put("type", "uint256"));
            orderTypeArray.add(objectMapper.createObjectNode().put("name", "feeRateBps").put("type", "uint256"));
            orderTypeArray.add(objectMapper.createObjectNode().put("name", "side").put("type", "uint8"));
            orderTypeArray.add(objectMapper.createObjectNode().put("name", "signatureType").put("type", "uint8"));
            types.set("Order", orderTypeArray);

            typedData.set("types", types);
            typedData.put("primaryType", "Order");

            // Add message
            ObjectNode message = objectMapper.valueToTree(signingPayload);
            typedData.set("message", message);
            typedData.put("primaryType", "Order");

            // Sign using Web3j's structured data signing
            StructuredDataEncoder encoder = new StructuredDataEncoder(typedData.toString());
            byte[] structuredData = encoder.getStructuredData();

            Sign.SignatureData signature = Sign.signMessage(structuredData, credentials.getEcKeyPair());

            String signatureHex = Numeric.toHexString(signature.getR()) +
                                 Numeric.toHexStringNoPrefix(signature.getS()) +
                                 Numeric.toHexStringNoPrefix(signature.getV());

            logger.info("Successfully generated EIP-712 signature: {}", signatureHex);
            return signatureHex;
        }

        // ============================================================================
        // Order Submission
        // ============================================================================

        private static JsonNode createOrderApi(Map<String, Object> orderPayload, String sessionCookie) throws Exception {
            logger.info("Submitting order to API...");

            String jsonPayload = objectMapper.writeValueAsString(orderPayload);
            logger.debug("Order payload: {}", jsonPayload);

            RequestBody body = RequestBody.create(
                jsonPayload,
                MediaType.parse("application/json")
            );

            Request request = new Request.Builder()
                .url(API_BASE_URL + "/orders")
                .addHeader("Cookie", "limitless_session=" + sessionCookie)
                .addHeader("Content-Type", "application/json")
                .addHeader("Accept", "application/json")
                .post(body)
                .build();

            try (Response response = httpClient.newCall(request).execute()) {
                String responseBody = response.body().string();

                if (response.code() != 201) {
                    logger.error("Failed to create order. Status: {}", response.code());
                    logger.error("Response: {}", responseBody);
                    throw new Exception("API Error " + response.code() + ": " + responseBody);
                }

                JsonNode result = objectMapper.readTree(responseBody);
                logger.info("Order created successfully: {}", result);
                return result;
            }
        }

        // ============================================================================
        // Main Trading Function
        // ============================================================================

        /**
         * Main function to execute a trade on Limitless Exchange.
         * @param tradingParams Trading parameters (price, amount, type)
         * @param marketSlug The market slug (used to fetch market data including venue)
         * @param privateKey Your wallet's private key
         */
        public static JsonNode executeTrade(TradingParams tradingParams, String marketSlug, String privateKey)
                throws Exception {

            logger.info("=" + "=".repeat(79));
            logger.info("Starting trade execution...");
            logger.info("=" + "=".repeat(79));

            // Step 1: Authenticate
            String signingMessage = getSigningMessage();
            AuthResult authResult = authenticate(privateKey, signingMessage);

            // Step 2: Fetch market data (cached per market)
            // This gets venue info needed for EIP-712 signing
            JsonNode marketData = getMarketData(marketSlug);
            String venueExchange = marketData.path("venue").path("exchange").asText();
            logger.info("Using venue exchange: {}", venueExchange);

            // Step 3: Calculate amounts
            int priceInCents = tradingParams.firstPrice;
            int amount = tradingParams.amount;
            String tradeType = "GTC"; // Good Till Cancelled
            long scalingFactor = 1000000L; // 1e6 for USDC (6 decimals)

            // Get token IDs from market data
            // positionIds[0] = YES token, positionIds[1] = NO token
            JsonNode positionIds = marketData.get("positionIds");
            if (positionIds == null || positionIds.size() < 2) {
                throw new Exception("Market does not have valid position IDs");
            }

            String selectedToken = "YES".equals(tradingParams.firstType) ?
                positionIds.get(0).asText() : positionIds.get(1).asText();

            // Calculate amounts
            double priceInDollars = priceInCents / 100.0;
            double totalCost = priceInDollars * amount;
            long makerAmount = Math.round(totalCost * scalingFactor);
            long takerAmount = Math.round(amount * scalingFactor);

            logger.info("Trading: {} shares at {} cents ({} dollars) each",
                amount, priceInCents, priceInDollars);
            logger.info("Total cost: {} dollars", totalCost);
            logger.info("Maker amount: {}", makerAmount);
            logger.info("Taker amount: {}", takerAmount);

            // Step 4: Create order payload without signature
            // authResult.userData.get("account") is already checksummed
            String makerAddress = authResult.userData.get("account").asText();
            int feeRateBps = authResult.userData.path("rank").path("feeRateBps").asInt(0);

            Map<String, Object> orderPayload = createOrderPayloadWithoutSignature(
                makerAddress,
                selectedToken,
                makerAmount,
                takerAmount,
                feeRateBps
            );

            // Step 5: Sign the order using venue's exchange address
            String signature = createSignatureForOrderPayload(venueExchange, orderPayload, privateKey);

            // Step 6: Create final order payload
            Map<String, Object> finalOrderPayload = new LinkedHashMap<>();
            Map<String, Object> orderWithSignature = new LinkedHashMap<>(orderPayload);
            orderWithSignature.put("price", priceInDollars);
            orderWithSignature.put("signature", signature);

            finalOrderPayload.put("order", orderWithSignature);
            finalOrderPayload.put("ownerId", authResult.userData.get("id").asInt());
            finalOrderPayload.put("orderType", tradeType);
            finalOrderPayload.put("marketSlug", marketSlug);

            logger.info("Order placed for {} cents, amount: {}, share type: {}",
                priceInCents, amount, tradingParams.firstType);

            // Step 7: Submit to API
            return createOrderApi(finalOrderPayload, authResult.sessionCookie);
        }

        // ============================================================================
        // Main Method - Example Usage
        // ============================================================================

        public static void main(String[] args) {
            System.out.println("=" + "=".repeat(79));
            System.out.println("LIMITLESS EXCHANGE TRADING EXAMPLE - JAVA");
            System.out.println("=" + "=".repeat(79));
            System.out.println("\n⚠️  WARNING: This is an example trading application for educational purposes.");
            System.out.println("⚠️  Limitless Labs is not responsible for any losses or mistakes.");
            System.out.println("⚠️  Always test with small amounts first and understand the code.");
            System.out.println("⚠️  USE AT YOUR OWN RISK.\n");
            System.out.println("=" + "=".repeat(79));

            try {
                // Example parameters - REPLACE THESE WITH YOUR ACTUAL VALUES
                TradingParams tradingParams = new TradingParams(
                    50,    // Price in cents (50¢)
                    2,     // Number of shares
                    "YES"  // "YES" or "NO"
                );

                // Market slug - the script will fetch market data (including venue and tokens) automatically
                String marketSlug = "example-market-slug";  // Replace with actual market slug

                // SECURITY WARNING: Never hardcode your private key!
                // Use environment variables or secure key management
                String privateKey = System.getenv("PRIVATE_KEY");

                if (privateKey == null || privateKey.isEmpty()) {
                    System.err.println("❌ ERROR: Please set your private key in the PRIVATE_KEY environment variable");
                    System.err.println("Example: export PRIVATE_KEY='0x...'");
                    System.exit(1);
                }

                System.out.println("🚀 Starting trading example...");
                System.out.println("Trading parameters: " +
                    tradingParams.amount + " shares at " +
                    tradingParams.firstPrice + " cents for " +
                    tradingParams.firstType);
                System.out.println("Market slug: " + marketSlug);

                // Execute the trade
                // Market data (including venue) is fetched and cached automatically
                JsonNode result = executeTrade(tradingParams, marketSlug, privateKey);

                System.out.println("\n✅ Trade executed successfully!");
                System.out.println("Result: " + objectMapper.writerWithDefaultPrettyPrinter()
                    .writeValueAsString(result));

            } catch (Exception e) {
                System.err.println("\n❌ Error executing trade: " + e.getMessage());
                e.printStackTrace();
            }
        }
    }

    ```


    #### Important Notes


    #### ⚠️ Security Considerations


    - **NEVER** ✨ share your private key with anyone

    - **NEVER** ✨ commit your private key to version control

    - Use environment variables to store sensitive information

    - Always test with small amounts first

    - Understand the code before using it with real funds


    #### Order Types


    - **GTC (Good Till Cancelled)** ✨: Order remains active until filled or
    cancelled

    - **FOK (Fill or Kill)** ✨: Fill completely or cancel


    #### Price Calculation


    - Prices are in cents (e.g., 65 = 65¢ = 0.65 USD)

    - YES price = probability of outcome occurring

    - NO price = 1 - YES price


    #### Amount Calculation


    - USDC has 6 decimals (1 USDC = 1,000,000 units)

    - Shares are scaled by 1e6 for precision

    - Always verify calculations before submitting orders


    #### Market Types


    - **single-clob** ✨: Standard central limit order book markets

    - **group-negrisk** ✨: Grouped markets with multiple related outcomes


    #### Build and Run


    #### Install Dependencies


    ```bash

    # 💻 Run in your terminal

    // 🎯 Copy and customize this example

    ./gradlew build

    ```


    #### Run the Application


    ```bash

    # 💻 Run in your terminal

    // 🎯 Copy and customize this example

    #### With environment variable

    export PRIVATE_KEY="0x..."

    ./gradlew run


    #### Or with system property

    ./gradlew run -DPRIVATE_KEY="0x..."

    ```


    #### Create Executable JAR


    ```bash

    # 💻 Run in your terminal

    // 🎯 Copy and customize this example

    ./gradlew fatJar

    java -jar build/libs/limitless-trading-example-1.0.0-all.jar

    ```


    #### Environment Variables


    Set these environment variables for production use:


    ```bash

    # 💻 Run in your terminal

    // 🎯 Copy and customize this example

    #### Required

    export PRIVATE_KEY="0x..."  # Your wallet private key


    #### Optional (defaults shown)

    export API_URL="https://api.limitless.exchange"

    ```


    **Note** ✨: Contract addresses (exchange, adapter) are now fetched
    dynamically from the market's venue data via `GET /markets/:slug`. You no
    longer need to configure them as environment variables.


    #### Troubleshooting


    #### Common Issues


    1. **Build Failures** ✨
       - Ensure Java 11+ is installed
       - Check internet connection for dependency downloads
       - Clear Gradle cache: `./gradlew clean`

    2. **Authentication Failed** ✨
       - Verify private key format (with or without '0x' prefix)
       - Check API endpoint accessibility
       - Ensure signing message is current

    3. **Order Creation Failed** ✨
       - Verify market slug and token IDs
       - Check account balance
       - Ensure market is still open

    4. **Signature Verification Failed** ✨
       - Ensure you're using the venue's exchange address from market data
       - Check chain ID (8453 for Base)
       - Make sure addresses are checksummed (use `Keys.toChecksumAddress()`)
       - Ensure Web3j version compatibility

    #### Key Features


    ✅ **Authentication** ✨: Message signing with Ethereum private key  

    ✅ **EIP-712 Signing** ✨: Complete EIP-712 typed data signing for orders  

    ✅ **Order Creation** ✨: Same payload structure as Python/TypeScript  

    ✅ **API Integration** ✨: HTTP requests with proper headers and cookies  

    ✅ **Error Handling** ✨: Comprehensive exception handling  

    ✅ **Logging** ✨: SLF4J with Logback for proper logging


    #### Disclaimer


    **This code is provided for educational purposes only. Limitless Labs is not
    responsible for any losses, mistakes, or unintended consequences from using
    this code. Trading involves risk, and you should never trade more than you
    can afford to lose. Always understand the code you're running and test with
    small amounts first.** ✨


    #### Support


    For API support and questions:


    - Documentation: https://limitlesslabs.notion.site/

    - Support: hey@limitless.network



    ---



    _Last updated: 2025-12-16_




    ## 📦 Node.js/TypeScript Quick Start


    Complete end-to-end Node.js/TypeScript implementation for trading and
    WebSocket subscriptions.
      

    #### Node.js (TypeScript) – Place Order + Subscribe to Updates


    ```

    This is an example for educational purposes only.

    Limitless Labs is not responsible for any losses or mistakes.

    Use at your own risk.

    ```


    #### Overview


    - Place an order via REST (EIP-712 signing required)

    - Subscribe via WebSocket to:
      - AMM price updates for specific market addresses
      - CLOB orderbook updates for specific market slugs

    Important: subscriptions replace previous ones. If you want AMM prices and
    CLOB orderbook at the same time, send both `marketAddresses` and
    `marketSlugs` together in a single `subscribe_market_prices` call.


    Production WS URL: `wss://ws.limitless.exchange` namespace `/markets`

    Production API URL: `https://api.limitless.exchange`


    #### Important: Venue System for CLOB Markets


    CLOB markets use a **venue system** ✨ where each market has specific
    contract addresses. Before placing orders:


    1. **Fetch market data once** ✨: `GET /markets/:slug` returns venue
    information

    2. **Use venue.exchange** ✨: This is the `verifyingContract` for EIP-712
    order signing

    3. **Cache the venue** ✨: Venue data is static per market - fetch once and
    reuse


    **Required Approvals:** ✨


    - **BUY orders** ✨: Approve USDC to `venue.exchange`

    - **SELL orders (simple CLOB)** ✨: Approve conditional tokens to
    `venue.exchange`

    - **SELL orders (NegRisk/grouped)** ✨: Approve conditional tokens to
    **both** ✨ `venue.exchange` AND `venue.adapter`


    **Checksummed Addresses:** ✨

    All addresses must use checksummed format (EIP-55). Use `getAddress()` from
    viem to ensure proper formatting.


    #### Prerequisites


    - Node 18+ (or any V8/Node LTS)

    - Packages:


    ```bash

    # 💻 Run in your terminal

    // 🎯 Copy and customize this example

    pnpm add socket.io-client cross-fetch ethers viem

    ```


    - Env variables (example):


    ```bash

    # 💻 Run in your terminal

    // 🎯 Copy and customize this example

    export API_KEY="lmts_..."      # Your API key (recommended)

    export PRIVATE_KEY="0x..."     # Your wallet private key (for order signing)

    export API_URL="https://api.limitless.exchange"

    ```


    #### 🔐 Authentication for API Users


    > **⚠️ DEPRECATION NOTICE** ✨: Cookie-based session authentication is
    deprecated and will be removed within weeks. Migrate to API keys
    immediately.


    **Getting an API Key** ✨:

    API keys can only be created via the UI: Login → profile menu (top right) →
    Api keys


    **Using Your API Key** ✨:


    - REST: Include `X-API-Key` header in all requests

    - WebSocket: Pass `X-API-Key` header during connection handshake


    #### Migration from Cookie to API Key


    Replace cookie with API key header:


    ```diff

    // 🎯 Copy and customize this example

    #### REST API

    - Cookie: limitless_session=your_session

    + X-API-Key: lmts_your_key_here


    #### WebSocket (extraHeaders)

    - { Cookie: `limitless_session=${session}` }

    + { 'X-API-Key': apiKey }

    ```


    **⚠️ Security Warning:** ✨  

    Store API keys and private keys securely. Never commit them to version
    control. For production, use proper secret management services.



    ---



    #### TypeScript Helpers (minimal)


    ```ts

    // 🎯 Copy and customize this example

    // market.ts - Market data fetching with caching

    import fetch from 'cross-fetch';


    type MarketVenue = {
      exchange: `0x${string}`;
      adapter?: `0x${string}`;
    };


    type MarketData = {
      id: number;
      slug: string;
      positionIds: string[];
      venue: MarketVenue;
    };


    // Cache market data per slug (venue is static per market)

    const marketCache = new Map<string, MarketData>();


    export async function getMarketData(apiBase: string, slug: string):
    Promise<MarketData> {
      const cached = marketCache.get(slug);
      if (cached) {
        console.log(`Using cached market data for: ${slug}`);
        return cached;
      }

      console.log(`Fetching market data for: ${slug}`);
      const res = await fetch(`${apiBase}/markets/${slug}`);
      if (!res.ok) throw new Error(`Failed to get market: ${res.status} ${await res.text()}`);

      const market = (await res.json()) as MarketData;
      marketCache.set(slug, market);
      console.log(`Market data cached. Venue exchange: ${market.venue?.exchange}`);

      return market;
    }


    export function getVenueExchange(market: MarketData): `0x${string}` {
      if (!market.venue?.exchange) {
        throw new Error(`Market ${market.slug} does not have venue data`);
      }
      return market.venue.exchange;
    }

    ```


    ```ts

    // 🎯 Copy and customize this example

    // auth.ts

    import fetch from 'cross-fetch';


    // API Key authentication

    export function getApiKeyHeaders(apiKey: string) {
      return {
        'X-API-Key': apiKey,
        'content-type': 'application/json',
        accept: 'application/json',
      } as const;
    }


    // Fetch user profile using API key

    export async function getUserWithApiKey(apiBase: string, apiKey: string) {
      const res = await fetch(`${apiBase}/profile`, {
        headers: getApiKeyHeaders(apiKey),
      });
      if (!res.ok) throw new Error(`Failed to get profile: ${res.status} ${await res.text()}`);
      return res.json();
    }

    ```


    ```ts

    // 🎯 Copy and customize this example

    // orders.ts (viem-based FOK market order example)

    import fetch from 'cross-fetch';

    import { parseUnits, type WalletClient, type Account, type Transport, type
    Chain } from 'viem';


    type OrderMessage = {
      salt: string;
      maker: `0x${string}`;
      signer: `0x${string}`;
      taker: `0x${string}`;
      tokenId: string;
      makerAmount: string;
      takerAmount: string;
      expiration: string;
      nonce: string;
      feeRateBps: string;
      side: number; // 0 buy, 1 sell
      signatureType: number; // 0 EOA
    };


    const EIP712_DOMAIN = [
      { name: 'name', type: 'string' },
      { name: 'version', type: 'string' },
      { name: 'chainId', type: 'uint256' },
      { name: 'verifyingContract', type: 'address' },
    ] as const;


    const ORDER_STRUCTURE = [
      { name: 'salt', type: 'uint256' },
      { name: 'maker', type: 'address' },
      { name: 'signer', type: 'address' },
      { name: 'taker', type: 'address' },
      { name: 'tokenId', type: 'uint256' },
      { name: 'makerAmount', type: 'uint256' },
      { name: 'takerAmount', type: 'uint256' },
      { name: 'expiration', type: 'uint256' },
      { name: 'nonce', type: 'uint256' },
      { name: 'feeRateBps', type: 'uint256' },
      { name: 'side', type: 'uint8' },
      { name: 'signatureType', type: 'uint8' },
    ] as const;


    /**
     * Create a signed order for CLOB trading.
     * @param client - viem WalletClient with account
     * @param options.verifyingContract - The venue's exchange address from market data (GET /markets/:slug)
     */
    export async function createSignedOrder(
      client: WalletClient<Transport, Chain, Account>,
      options: {
        amount: string; // USD amount in decimal, e.g., '1.5'
        side: 0 | 1; // 0 buy, 1 sell
        tokenId: string;
        decimals?: number; // default 6
        chainId: number; // e.g., 8453
        verifyingContract: `0x${string}`; // venue.exchange from market data
      },
    ) {
      const maker = client.account!.address as `0x${string}`;
      const salt = String(Math.round(Math.random() * Date.now()));
      const makerAmount = parseUnits(options.amount, options.decimals ?? 6).toString();

      const order: OrderMessage = {
        salt,
        maker,
        signer: maker,
        taker: '0x0000000000000000000000000000000000000000',
        tokenId: options.tokenId,
        makerAmount,
        takerAmount: '1', // FOK market order semantics
        expiration: '0',
        nonce: '0',
        feeRateBps: '300',
        side: options.side,
        signatureType: 0,
      };

      const typedData = {
        primaryType: 'Order',
        types: { EIP712Domain: EIP712_DOMAIN, Order: ORDER_STRUCTURE },
        domain: {
          name: 'Limitless CTF Exchange',
          version: '1',
          chainId: options.chainId,
          verifyingContract: options.verifyingContract,
        },
        message: order,
      } as const;

      const signature = await client.signTypedData(typedData);
      return { order, signature } as const;
    }


    export async function submitOrder(
      apiBase: string,
      payload: {
        order: OrderMessage & { price?: number; signature: string };
        ownerId: number;
        orderType: 'FOK' | 'GTC';
        marketSlug: string;
      },
      extraHeaders?: Record<string, string>,
    ) {
      const res = await fetch(`${apiBase}/orders`, {
        method: 'POST',
        headers: {
          accept: 'application/json',
          'content-type': 'application/json',
          ...(extraHeaders || {}),
        },
        body: JSON.stringify(payload),
      });
      if (!res.ok) throw new Error(`Order failed: ${res.status} ${await res.text()}`);
      return res.json();
    }

    ```


    ```ts

    // 🎯 Copy and customize this example

    // ws.ts

    import { io, Socket } from 'socket.io-client';


    // Note: Cookie-based auth was previously supported but is now deprecated.

    // Use API key authentication for all programmatic access.


    export function connectMarkets(apiKey?: string) {
      const url = 'wss://ws.limitless.exchange/markets';
      const transports = ['websocket'];

      const opts: Parameters<typeof io>[1] = { transports };

      if (apiKey) {
        opts.extraHeaders = { 'X-API-Key': apiKey };
      }

      const socket: Socket = io(url, opts);
      return socket;
    }


    // If need to only subscribe to AMM prices, use this function

    export function subscribeAmmPrices(socket: Socket, marketAddresses:
    string[]) {
      socket.emit('subscribe_market_prices', { marketAddresses });

      // Server emits 'newPriceData' to the same room
      socket.on('newPriceData', (data: unknown) => {
        // Shape may include: { marketAddress?, updatedPrices, blockNumber, timestamp }
        console.log('AMM price update:', data);
      });
    }


    // If need to only subscribe to CLOB orderbook, use this function

    export function subscribeClobOrderbook(socket: Socket, marketSlugs:
    string[]) {
      socket.emit('subscribe_market_prices', { marketSlugs });

      // Server emits 'orderbookUpdate' per slug room
      socket.on('orderbookUpdate', (data: unknown) => {
        // Shape: { marketSlug, orderbook, timestamp }
        console.log('Orderbook update:', data);
      });
    }

    ```


    ```ts

    // 🎯 Copy and customize this example

    // wallet.ts

    import { createWalletClient, http } from 'viem';

    import { privateKeyToAccount } from 'viem/accounts';

    import { base } from 'viem/chains';


    export function createWalletFromPrivateKey(privateKey: `0x${string}`) {
      const account = privateKeyToAccount(privateKey);

      const client = createWalletClient({
        account,
        chain: base, // Base mainnet (chain ID 8453)
        transport: http(),
      });

      return client;
    }

    ```



    ---



    #### End-to-end example


    ```ts

    // 🎯 Copy and customize this example

    // main.ts

    import { getApiKeyHeaders, getUserWithApiKey } from './auth';

    import { getMarketData, getVenueExchange } from './market';

    import { createSignedOrder, submitOrder } from './orders';

    import { connectMarkets } from './ws';

    import { createWalletFromPrivateKey } from './wallet';


    async function main() {
      const API_URL = process.env.API_URL || 'https://api.limitless.exchange';
      const API_KEY = process.env.API_KEY || ''; // Your API key (recommended)
      const PRIVATE_KEY = process.env.PRIVATE_KEY || ''; // For order signing only

      if (!API_KEY) {
        throw new Error('API_KEY environment variable is required. Generate one via UI: profile menu → Api keys');
      }

      // Market slug for CLOB trading
      const marketSlug = 'example-market-slug'; // Replace with actual market slug

      // 1) Get user profile using API key (no session management needed!)
      const user = await getUserWithApiKey(API_URL, API_KEY);
      console.log('Authenticated as', user.account);

      // 2) Fetch market data (cached per market) to get venue and token info
      const market = await getMarketData(API_URL, marketSlug);
      const verifyingContract = getVenueExchange(market);
      console.log('Using venue exchange:', verifyingContract);

      // Get token IDs from market data
      // positionIds[0] = YES token, positionIds[1] = NO token
      const tokenId = market.positionIds[0]; // YES token for this example

      // 3) Connect WS with API key
      const socket = connectMarkets(API_KEY);

      // Combined subscription (send both arrays together to avoid replacing previous subscriptions)
      const marketAddresses = ['0xE082AF5a25f5D3904fae514CD03dC99F9Ff39fBc']; // AMM markets array
      const marketSlugs = [marketSlug]; // CLOB markets array
      socket.emit('subscribe_market_prices', { marketAddresses, marketSlugs });

      // Handlers
      socket.on('newPriceData', (data: unknown) => console.log('AMM price update:', data)); // AMM markets only
      socket.on('orderbookUpdate', (data: unknown) => console.log('Orderbook update:', data)); // CLOB markets only

      // 4) Create wallet client from private key (still needed for EIP-712 order signing)
      const client = createWalletFromPrivateKey(PRIVATE_KEY as `0x${string}`);

      // 5) Prepare and place CLOB order using venue's exchange address
      const { order, signature } = await createSignedOrder(client, {
        amount: '1.5',
        side: 0, // 0 = BUY
        tokenId,
        decimals: 6,
        chainId: 8453,
        verifyingContract, // From venue data
      });

      const orderPayload = {
        order: { ...order, signature },
        ownerId: user.id,
        orderType: 'FOK' as const,
        marketSlug,
      };

      // 6) Submit order with API key
      const result = await submitOrder(API_URL, orderPayload, {
        'X-API-Key': API_KEY,
      });
      console.log('Order created:', result);
    }


    main().catch((e) => {
      console.error(e);
      process.exit(1);
    });

    ```



    ---



    #### Event reference (server-side)


    - Namespace: `/markets`

    - Subscribe:
      - `subscribe_market_prices` with `{ marketAddresses?: string[]; marketSlugs?: string[] }`
    - Emits:
      - `newPriceData` for AMM prices
      - `orderbookUpdate` for CLOB orderbook

    Payload shapes are minimal and may evolve; rely on keys shown in console in
    the snippets.



    ---



    #### Notes


    - **API keys are required** ✨ for all programmatic access. Use the
    `X-API-Key` header.

    - **Cookie-based auth is deprecated** ✨ and will be removed in a future
    release. Migrate to API keys.

    - For public AMM prices or orderbook, authentication is not required.

    - Scale USDC to 6 decimals when computing amounts.

    - **Venue data is static** ✨: Fetch market data once per market and cache
    it. Do not fetch before every trade.

    - **Checksummed addresses** ✨: All addresses must be in EIP-55 checksummed
    format. viem's `getAddress()` and `privateKeyToAccount()` return checksummed
    addresses by default.

    - Contract addresses (exchange, adapter) are fetched dynamically from the
    market's venue data via `GET /markets/:slug`.

    - **Private key is still needed** ✨ for EIP-712 order signing, but API key
    handles authentication.


    _Last updated: 2026-01-22_




    ## 🔌 WebSocket Integration


    Real-time market data and position updates using WebSocket connections.
      

    ##### Python WebSocket Real-Time Data Guide


    ⚠️ **IMPORTANT DISCLAIMER** ⚠️


    ```

    This is an example script for educational purposes only.

    Limitless Labs is not responsible for any losses or mistakes.

    This script should be adjusted to your personal needs and risk tolerance.

    Always test with small amounts first and understand the code before using
    it.

    USE AT YOUR OWN RISK.

    ```


    This guide provides a complete walkthrough of connecting to Limitless
    Exchange WebSocket for real-time market data and position updates using
    Python.


    #### Overview


    The Socket.io integration process involves:


    1. **Authentication**: Use API key for all programmatic access

    2. **WebSocket Connection**: Connect to the `markets` namespace

    3. **Event Subscription**: Subscribe to market prices and position updates

    4. **Real-Time Events**: Handle incoming market data and position changes


    #### Prerequisites


    ##### Required Python Packages


    ```bash

    # Connection Commands

    pip install python-socketio[asyncio] eth-account==0.10.0 requests asyncio

    ```


    **Important**: Make sure you have compatible versions of these packages. The
    script has been tested with the specified dependencies.


    ##### 🔐 Authentication for API Users


    > **⚠️ DEPRECATION NOTICE**: Cookie-based session authentication is
    deprecated and will be removed within weeks. Migrate to API keys
    immediately.


    **Getting an API Key**:

    API keys can only be created via the UI: Login → profile menu (top right) →
    Api keys


    **Using Your API Key**:

    Pass `X-API-Key` header during WebSocket connection handshake.


    ##### Migration from Cookie to API Key


    Replace cookie with API key header:


    ```diff

    ##### WebSocket connection headers

    - headers = {'Cookie': f'limitless_session={session_cookie}'}

    + headers = {'X-API-Key': api_key}

    ```


    ##### Environment Variables


    ```bash

    # Connection Commands

    ##### Recommended: API key for programmatic access

    export API_KEY="lmts_..."     # Your API key


    ##### Only needed for order signing (not for WebSocket auth)

    export PRIVATE_KEY="0x..."    # Your wallet private key


    ##### Optional: Enable debug logging

    export DEBUG=1

    ```


    Note: in real case you'd want to avoid storing private key and api key in
    plaintext in environment variables. Use proper secret management services.


    #### Complete Implementation


    ##### 1. Common Utilities (`common_utils.py`)


    ```python

    # WebSocket Client Implementation

    #!/usr/bin/env python3

    """

    Common Utilities for Limitless Exchange

    Shared authentication and utility functions

    """


    import requests

    from eth_account import Account

    from eth_account.messages import encode_defunct


    ##### Import encode_structured_data with version compatibility


    try:
        from eth_account.messages import encode_typed_data
        print("✅ Successfully imported encode_typed_data from eth_account.messages")
    except ImportError:

    try:
        from eth_account.messages import encode_structured_data as encode_typed_data
        print("✅ Using encode_structured_data (fallback)")
    except ImportError as e:
        print(f"❌ Import error: {e}")
        print("Please install the correct version:")
        print("pip install eth-account=0.10.0")
    raise ImportError("encode_typed_data not available. Please upgrade
    eth-account: pip install eth-account==0.10.0")


    def string_to_hex(text):

    """Convert string to hex representation with 0x prefix."""

    return '0x' + text.encode('utf-8').hex()


    def authenticate(private_key, signing_message):

    """

    Authenticate with Limitless Exchange API using private key

        Args:
            private_key: Private key for signing
            signing_message: Message to sign from get_signing_message()

        Returns:
            tuple: (session_cookie, user_data)
        """
        account = Account.from_key(private_key)
        address = account.address
        print(f"Using address: {address}")

        print(f"Signing message: {repr(signing_message)}")
        message = encode_defunct(text=signing_message)
        signature = account.sign_message(message)

        hex_message = string_to_hex(signing_message)
        sig_hex = signature.signature.hex()
        if not sig_hex.startswith('0x'):
            sig_hex = '0x' + sig_hex

        headers = {
            'x-account': address,
            'x-signing-message': hex_message,
            'x-signature': sig_hex,
            'Content-Type': 'application/json',
            'Accept': 'application/json'
        }

        response = requests.post(
            'https://api.limitless.exchange/auth/login',
            headers=headers,
            json={'client': 'eoa'}
        )

        if response.status_code == 200:
            session_cookie = response.cookies.get('limitless_session')
            return session_cookie, response.json()
        else:
            raise Exception(f"Authentication failed: {response.status_code} - {response.text}")

    def get_signing_message():

    """

    Get signing message from Limitless Exchange API

        Returns:
            str: Signing message to be used for authentication
        """
        response = requests.get('https://api.limitless.exchange/auth/signing-message')
        if response.status_code == 200:
            return response.text
        else:
            raise Exception(f"Failed to get signing message: {response.status_code}")

    ##### Re-export encode_typed_data for backward compatibility


    __all__ = ['authenticate', 'get_signing_message', 'string_to_hex',
    'encode_typed_data']

    ```


    ##### 2. WebSocket Client (`socket-subs.py`)


    ```

    In below script you need to pass MARKET_ADDRESSES, please read code.

    ```


    ```python

    # WebSocket Client Implementation

    #!/usr/bin/env python3

    """

    Limitless Exchange WebSocket Client - Streamlined Example

    Perfect for quick setup and real-time data handling

    Connect to real-time market data and position updates

    """


    import asyncio

    import json

    import logging

    import os

    from typing import Optional, List


    import socketio

    from common_utils import authenticate, get_signing_message


    logging.basicConfig(level=logging.WARNING, format='%(message)s')

    logger = logging.getLogger(__name__)


    ##### Global configuration


    MARKET_ADDRESSES = ["<MARKET_ADDRESS>"] # Hourly market address fetched from
    Active markets


    class LimitlessWebSocket:

    """

    Streamlined WebSocket client for Limitless Exchange

    Essential functionality: authentication, connection, subscription, events


    Note: Cookie-based auth was previously supported but is now deprecated.

    Use API key authentication for all programmatic access.

    """

        def __init__(
            self,
            websocket_url: str = "wss://ws.limitless.exchange",
            api_key: Optional[str] = None,
        ):
            self.websocket_url = websocket_url
            self.api_key = api_key
            self.connected = False
            self.subscribed_markets: List[str] = []

            # Socket.IO client with minimal logging
            self.sio = socketio.AsyncClient(logger=False, engineio_logger=False)
            self._setup_handlers()

        def _setup_handlers(self):
            """Setup essential event handlers"""

            @self.sio.event(namespace='/markets')
            async def connect():
                self.connected = True
                print("✅ Connected to /markets")

                # Re-subscribe to markets after reconnection
                if self.subscribed_markets:
                    await asyncio.sleep(1)
                    await self._resubscribe()

            @self.sio.event(namespace='/markets')
            async def disconnect():
                self.connected = False
                print("❌ Disconnected from /markets")

            @self.sio.event(namespace='/markets')
            async def authenticated(data):
                print(f"Received packet MESSAGE data 2/markets, [\"authenticated\", {json.dumps(data)}]")

            @self.sio.event(namespace='/markets')
            async def newPriceData(data):
                """Print raw newPriceData packet"""
                print(f"Received packet MESSAGE data 2/markets, [\"newPriceData\", {json.dumps(data)}]")

            @self.sio.event(namespace='/markets')
            async def positions(data):
                """Print raw positions packet"""
                print(f"Received packet MESSAGE data 2/markets, [\"positions\", {json.dumps(data)}]")

            @self.sio.event(namespace='/markets')
            async def system(data):
                print(f"Received packet MESSAGE data 2/markets, [\"system\", {json.dumps(data)}]")

            @self.sio.event(namespace='/markets')
            async def exception(data):
                """Print raw exception packet"""
                print(f"Received packet MESSAGE data 2/markets, [\"exception\", {json.dumps(data)}]")

        async def connect(self):
            """Connect to WebSocket"""
            try:
                print(f"🔌 Connecting to {self.websocket_url}...")

                # Prepare connection options with authentication headers
                connect_options = {'transports': ['websocket']}

                if self.api_key:
                    connect_options['headers'] = {'X-API-Key': self.api_key}
                    print("🔑 Using API key authentication")
                else:
                    print("📊 Connecting in public mode (no authentication)")

                await self.sio.connect(
                    self.websocket_url,
                    namespaces=['/markets'],
                    **connect_options
                )

                # Wait for connection to establish
                max_retries = 10
                for _ in range(max_retries):
                    if self.connected:
                        break
                    await asyncio.sleep(0.2)

                if self.connected:
                    print("✅ Successfully connected")
                else:
                    print("❌ Connection failed")

            except Exception as e:
                print(f"❌ Connection error: {e}")
                raise

        async def subscribe_markets(self, market_addresses: List[str]):
            """Subscribe to market price updates"""
            if not self.connected:
                print("❌ Not connected - call connect() first")
                return

            print(f"📊 Subscribing to {len(market_addresses)} markets")
            payload = {'marketAddresses': market_addresses}

            # Subscribe to price updates
            await self.sio.emit('subscribe_market_prices', payload, namespace='/markets')
            print("✅ Subscribed to market prices")

            # Subscribe to positions if authenticated with API key
            if self.api_key:
                await self.sio.emit('subscribe_positions', payload, namespace='/markets')
                print("✅ Subscribed to positions")

            # Track subscribed markets for reconnection
            self.subscribed_markets.extend(
                addr for addr in market_addresses if addr not in self.subscribed_markets
            )

        async def _resubscribe(self):
            """Re-subscribe to markets after reconnection"""
            if self.subscribed_markets:
                await self.subscribe_markets(self.subscribed_markets)

        async def disconnect(self):
            """Disconnect from WebSocket"""
            if self.connected:
                await self.sio.disconnect()
                print("👋 Disconnected")

        async def wait(self):
            """Keep connection alive and listen for events"""
            await self.sio.wait()

    def get_default_markets():

    """Helper function to access global market addresses"""

    return MARKET_ADDRESSES



    async def main():

    """Main execution function"""

    global MARKET_ADDRESSES

        # Note: Cookie-based auth was previously supported but is now deprecated.
        # Use API key authentication for all programmatic access.
        api_key = os.getenv('API_KEY')

        print("=" * 50)
        print("Limitless Exchange WebSocket Client")
        print("=" * 50)

        if api_key:
            print("🔑 API key detected - authenticated mode")
        else:
            print("📊 Public mode - price data only")

        # Create and run client
        client = LimitlessWebSocket(api_key=api_key)

        try:
            # Connect to WebSocket
            await client.connect()

            # Subscribe to markets
            if MARKET_ADDRESSES:
                await client.subscribe_markets(MARKET_ADDRESSES)
            else:
                print("⚠️ No market addresses configured")
                return

            print("📡 Listening for events... Press Ctrl+C to stop")

            # Keep connection alive
            await client.wait()

        except KeyboardInterrupt:
            print("\n🛑 Shutting down...")
        except Exception as e:
            print(f"Error: {e}")
        finally:
            await client.disconnect()


    async def simple_usage_example():

    """Simple example for API docs""" # Basic usage

    client = LimitlessWebSocket(private_key=os.getenv('PRIVATE_KEY'))

    await client.connect()

    await client.subscribe_markets(MARKET_ADDRESSES)

    await client.wait()


    if __name__ == "__main__": # Set debug logging if needed

    if os.getenv('DEBUG'):

    logging.getLogger().setLevel(logging.DEBUG)

        asyncio.run(main())
    ```


    #### Key Features


    ##### 🔐 Authentication Modes


    The WebSocket client supports two modes:


    - **Public Mode**: Access to market prices without authentication

    - **Authenticated Mode**: Full access including position updates and
    transactions


    ##### 📡 Event Types



    - **`newPriceData`**: Real-time price updates for markets - Public

    - **`positions`**: User position changes - Required

    - **`system`**: Connection status and notifications - Public

    - **`authenticated`**: Authentication confirmation - Required

    - **`exception`**: Error messages and exceptions - Public




    ##### 🎯 Market Subscription


    ```python

    # WebSocket Client Implementation

    ##### Subscribe to specific markets

    await client.subscribe_markets([
        "0x1234...",  # Market address 1
        "0x5678..."   # Market address 2
    ])

    ```


    #### Usage Examples


    ##### Basic Connection (Public Data)


    ```python

    # WebSocket Client Implementation

    import asyncio

    from socket_subs import LimitlessWebSocket


    async def public_data_example():
        client = LimitlessWebSocket()
        await client.connect()
        await client.subscribe_markets(["0x1234..."])
        await client.wait()

    asyncio.run(public_data_example())

    ```


    ##### Authenticated Connection with API Key


    ```python

    # WebSocket Client Implementation

    import os

    import asyncio

    from socket_subs import LimitlessWebSocket


    async def authenticated_example():
        api_key = os.getenv('API_KEY')  # export API_KEY='lmts_...'
        client = LimitlessWebSocket(api_key=api_key)

        await client.connect()
        await client.subscribe_markets(["0x1234..."])
        await client.wait()

    asyncio.run(authenticated_example())

    ```


    > **Note**: Cookie-based authentication was previously supported but is now
    deprecated. Use API keys for all programmatic access.


    ##### Custom Event Handling


    ```python

    # WebSocket Client Implementation

    class CustomWebSocket(LimitlessWebSocket):
        def _setup_handlers(self):
            super()._setup_handlers()

            @self.sio.event(namespace='/markets')
            async def newPriceData(data):
                """Custom price data handler"""
                market_address = data.get('marketAddress')
                prices = data.get('updatedPrices', {})
                print(f"Market {market_address}: YES={prices.get('yes')}, NO={prices.get('no')}")

            @self.sio.event(namespace='/markets')
            async def positions(data):
                """Custom position handler"""
                account = data.get('account')
                positions = data.get('positions', [])
                print(f"User {account} has {len(positions)} positions")
    ```


    #### Important Notes


    ##### ⚠️ Security Considerations


    - **NEVER** share your API key or private key with anyone

    - **NEVER** commit credentials to version control

    - Use environment variables to store sensitive information

    - Test with small amounts first

    - Understand the code before using it with real funds


    ##### WebSocket Configuration


    - **URL**: `wss://ws.limitless.exchange` (production)

    - **Namespace**: `/markets` for trading data

    - **Transport**: WebSocket only (no polling fallback)

    - **Authentication**: API key via `X-API-Key` header


    ##### Connection Management


    - **Auto-reconnection**: Built-in reconnection logic

    - **Market re-subscription**: Automatic re-subscription after reconnection

    - **Error handling**: Comprehensive error logging and recovery


    ##### Market Address Format


    Market addresses are contract addresses in hexadecimal format, example:


    ```

    0x1234567890123456789012345678901234567890

    ```


    Get active market addresses from:


    - API endpoint: `/markets`

    - WebSocket events

    - Market browser


    #### Event Data Schemas


    ##### Price Update Event


    ```json

    {
      "marketAddress": "0x1234...",
      "updatedPrices": {
        "yes": "0.65",
        "no": "0.35"
      },
      "blockNumber": 12345678,
      "timestamp": "2024-01-01T00:00:00.000Z"
    }

    ```


    ##### Position Update Event


    ```json

    {
      "account": "0xabcd...",
      "marketAddress": "0x1234...",
      "positions": [
        {
          "tokenId": "123456",
          "balance": "1000000",
          "outcomeIndex": 0
        }
      ],
      "type": "AMM"
    }

    ```


    ##### System Message Event


    ```json

    {
      "message": "Successfully subscribed to market price updates",
      "markets": ["0x1234...", "0x5678..."]
    }

    ```


    #### Troubleshooting


    ##### Common Issues


    1. **Import Error for socketio**
       - Solution: Install with async support: `pip install python-socketio[asyncio]`

    2. **Connection Failed**
       - Check WebSocket URL is correct
       - Verify network connectivity
       - Check if market addresses are valid

    3. **Authentication Failed**
       - Verify private key format (with or without '0x' prefix)
       - Check that signing message request succeeds
       - Ensure wallet has sufficient permissions

    4. **No Data Received**
       - Verify market addresses are active
       - Check subscription was successful
       - Enable debug logging to see raw events

    ##### Debug Mode


    Enable detailed logging:


    ```bash

    # Connection Commands

    export DEBUG=1

    python socket-subs.py

    ```


    #### Environment Variables


    Set these environment variables for production use:


    ```bash

    # Connection Commands

    ##### Recommended: API key for authenticated features

    export API_KEY="lmts_..."     # Your API key (generate via UI: profile menu
    → Api keys)


    ##### Only needed for order signing (not WebSocket auth)

    export PRIVATE_KEY="0x..."    # Your wallet private key


    ##### Optional debugging

    export DEBUG=1  # Enable debug logging

    ```


    #### WebSocket Events Reference



    - **`connect`**: Server → Client - None - Connection established

    - **`disconnect`**: Server → Client - None - Connection lost

    - **`subscribe_market_prices`**: Client → Server - None - Subscribe to price
    updates

    - **`subscribe_positions`**: Client → Server - Required - Subscribe to
    position updates

    - **`newPriceData`**: Server → Client - None - Market price update

    - **`positions`**: Server → Client - Required - Position balance update

    - **`system`**: Server → Client - None - System notifications

    - **`authenticated`**: Server → Client - Required - Authentication
    confirmation

    - **`exception`**: Server → Client - None - Error notifications




    #### Performance Considerations


    - **Connection pooling**: Reuse connections when possible

    - **Event batching**: Handle multiple events efficiently

    - **Memory usage**: Monitor memory consumption for long-running processes

    - **Reconnection limits**: Implement exponential backoff for failed
    connections


    #### Disclaimer


    **This script is provided for educational purposes only. Limitless Labs is
    not responsible for any losses, mistakes, or unintended consequences from
    using this code. Trading involves risk, and you should never trade more than
    you can afford to lose. Always understand the code you're running and test
    with small amounts first.**


    #### Support


    For API support and questions:


    - Documentation: https://limitlesslabs.notion.site/

    - Support: hey@limitless.network



    ---



    _Last updated: 2026-02-03_
  version: "1.0"
  contact:
    name: API Support
    url: https://limitless.exchange
    email: hey@limitless.network
tags:
  - name: Authentication
    description: User authentication and session management
  - name: Markets
    description: Browse, search, and analyze prediction markets
  - name: Trading
    description: Create, manage, and cancel orders
  - name: Portfolio
    description: Position tracking, trade history, and performance
servers:
  - url: https://api.limitless.exchange
    description: Production API
components:
  securitySchemes:
    cookie:
      type: apiKey
      in: cookie
      name: limitless_session
      description: Session authentication cookie obtained from /auth/login
    bearer:
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for API access (alternative to cookie auth)
      name: Authorization
      type: http
      in: Header
  schemas:
    CreateUserDto:
      type: object
      properties:
        client:
          type: string
          description: Client type for authentication
          enum:
            - eoa
            - etherspot
            - base
          example: eoa
        smartWallet:
          type: string
          description: Smart wallet address (required for Smart Wallet client)
          example: "0x1234567890123456789012345678901234567890"
        r:
          type: string
          description: Referral code associated with the user who referred (invited) this
            user
      required:
        - client
    BrowseActiveMarketsResponseDto:
      type: object
      properties:
        data:
          type: array
          description: Array of active markets with complete trading data including
            volume, liquidity, and recent feed events
          example:
            - id: 7495
              address: "0x76d3e2098Be66Aa7E15138F467390f0Eb7349B9b"
              conditionId: "0x812f578437dc536def1412e4e593ef310884262c22868b30c1e58582e5f3e9b\
                f"
              title: $DOGE above $0.21652 on Sep 1, 12:00 UTC?
              description: This market will resolve to "YES" if the price of $DOGE is above
                $0.21652...
              collateralToken:
                address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
                decimals: 6
                symbol: USDC
              creator:
                name: Limitless
                imageURI: https://limitless.exchange/assets/images/logo.svg
                link: https://x.com/trylimitless
              prices:
                - 42.8
                - 57.2
              categories:
                - Hourly
              tags:
                - Lumy
                - Recurring
                - Hourly
                - Simple Mode
              status: FUNDED
              expired: false
              expirationDate: Sep 1, 2025
              expirationTimestamp: 1756728000000
              volume: "164109293"
              volumeFormatted: "164.109293"
              openInterest: "48310707"
              openInterestFormatted: "48.310707"
              liquidity: "50000000"
              liquidityFormatted: "50.000000"
              tradeType: amm
              marketType: single
              slug: dollardoge-above-dollar021652-on-sep-1-1200-utc-1756724413009
              feedEvents:
                - eventType: NEW_TRADE
                  timestamp: 2025-09-01T11:30:31.000Z
                  user:
                    id: 7080
                    account: "0xea27f6788F083e6070961d3E52A2e596367E04CC"
                    name: GG
                    rankName: Bronze
                    points: "0.00000000"
                  data:
                    title: $DOGE above $0.21652 on Sep 1, 12:00 UTC?
                    address: "0x76d3e2098Be66Aa7E15138F467390f0Eb7349B9b"
                    strategy: Buy
                    outcome: NO
                    contracts: "9.071313"
                    tradeAmount: "5"
                    tradeAmountUSD: "4.999525"
                    marketId: 7495
          items:
            type: object
            description: Market object with complete trading data (FEMarket type)
            additionalProperties: true
        totalMarketsCount:
          type: number
          description: Total number of active markets available for pagination
          example: 150
      required:
        - data
        - totalMarketsCount
    CategoryCountResponseDto:
      type: object
      properties:
        category:
          type: object
          description: Number of active markets per category
          example:
            "1": 10
            "2": 5
            "3": 8
          additionalProperties:
            type: number
        totalCount:
          type: number
          description: Total number of active markets
          example: 23
      required:
        - category
        - totalCount
    FeedEventsResponseDto:
      type: object
      properties:
        data:
          type: object
          description: Array of feed events with pagination (FEFeedEvents type)
          example:
            data:
              - eventType: NEW_TRADE
                timestamp: 2025-09-01T11:30:31.000Z
                user:
                  name: GG
                  rankName: Bronze
                data:
                  title: Market Title
                  strategy: Buy
                  outcome: YES
            totalPages: 5
          additionalProperties: true
      required:
        - data
    PortfolioRewardsChartEntryDto:
      type: object
      properties:
        timestamp:
          type: number
          description: Timestamp of the rewards entry
          example: 1672531200000
        userRewards:
          type: string
          description: User rewards for this timestamp in token decimals
          example: "25000000"
        totalRewards:
          type: string
          description: Total rewards for this timestamp in token decimals
          example: "60000000"
      required:
        - timestamp
        - userRewards
        - totalRewards
    EpochRewardDataDto:
      type: object
      properties:
        epochId:
          type: number
          description: Unique identifier of the epoch
          example: 1
        timestamp:
          format: date-time
          type: string
          description: Timestamp when the epoch occurred
          example: 2024-01-01T00:00:00.000Z
        totalRewards:
          type: string
          description: Total rewards distributed in this epoch in token decimals
          example: "1500000"
        userRewards:
          type: string
          description: User rewards earned in this epoch in token decimals
          example: "150000"
        earnedPercent:
          type: number
          description: Part of total rewards earned by the user - [0; 1]
          example: 0.1
      required:
        - epochId
        - timestamp
        - totalRewards
        - userRewards
        - earnedPercent
    PortfolioRewardsDto:
      type: object
      properties:
        todaysRewards:
          type: string
          description: Rewards earned today in token decimals
          example: "50250000"
        totalUnpaidRewards:
          type: string
          description: Total unpaid rewards in token decimals
          example: "200750000"
        totalUserRewardsLastEpoch:
          type: string
          description: Total user rewards from the last epoch in token decimals
          example: "150500000"
        rewardsChartData:
          description: Chart data showing rewards over time
          type: array
          items:
            $ref: "#/components/schemas/PortfolioRewardsChartEntryDto"
        rewardsByEpoch:
          description: Rewards data by epoch
          type: array
          items:
            $ref: "#/components/schemas/EpochRewardDataDto"
      required:
        - todaysRewards
        - totalUnpaidRewards
        - totalUserRewardsLastEpoch
        - rewardsByEpoch
    AmmPositionDto:
      type: object
      properties:
        collateralAmount:
          type: string
          description: Amount of collateral invested in token decimals
          example: "100500000"
        latestTrade:
          type: object
          description: Latest trade associated with this position
        market:
          type: object
          description: Market information for this position
        outcomeIndex:
          type: number
          description: Index of the outcome token
          example: 0
        outcomeTokenAmount:
          type: string
          description: Amount of outcome tokens held in token decimals
          example: "50250000"
        account:
          type: string
          description: Wallet address that was used to create this position
          example: "0x1234567890123456789012345678901234567890"
      required:
        - market
        - outcomeIndex
    Market:
      type: object
      properties:
        address:
          type: string
          description: The address of the FixedProductMarketMaker contract.
          minLength: 42
          maxLength: 42
          nullable: true
          uniqueItems: true
        title:
          type: string
          description: Represents the question of the market, the title metadata of the
            market.
          maxLength: 70
          nullable: false
          uniqueItems: true
        proxyTitle:
          type: string
          maxLength: 70
          default: null
          nullable: true
          uniqueItems: true
        description:
          type: string
          description: The description of the market.
          uniqueItems: false
          nullable: false
        question_id:
          type: object
          description: The bytes32 parsed title of the market.
          minLength: 66
          maxLength: 66
          uniqueItems: true
          nullable: true
        condition_id:
          type: object
          description: The bytes32 conditionId of the market, representing the conditions
            defined on condition preparation.
          minLength: 66
          maxLength: 66
          nullable: true
          uniqueItems: true
        position_ids:
          description: Array of position IDs (max 2 elements)
          maxItems: 2
          nullable: true
          items:
            type: array
          type: array
        outcome_slot_count:
          type: number
          description: The number of outcomes in the market.
          minimum: 2
          maximum: 2
          nullable: false
          default: 2
        winning_index:
          type: number
          description: The outcome index that was reported by the oracle.
          minimum: 0
          maximum: 1
          nullable: true
        payout_numerators:
          description: The oracle payout numerators that the oracle reported.
          nullable: true
          type: array
          items:
            type: string
        status:
          type: string
          description: Indicates the status of the market.
          nullable: false
        og_url:
          type: string
          description: The URL of the market OG image for SEO.
          nullable: true
        image_url:
          type: string
          description: The URL of the market logo image for SEO.
          nullable: true
        deadline:
          type: string
          description: The deadline of the market.
          nullable: false
        hidden:
          type: boolean
          default: false
        txHash:
          type: string
          default: null
        resolutionTxHash:
          type: string
          default: null
        priority_index:
          type: number
          default: null
      required:
        - address
        - title
        - proxyTitle
        - description
        - question_id
        - condition_id
        - position_ids
        - outcome_slot_count
        - winning_index
        - payout_numerators
        - status
        - og_url
        - image_url
        - deadline
        - hidden
        - txHash
        - resolutionTxHash
        - priority_index
    PositionDataDto:
      type: object
      properties:
        cost:
          type: string
          description: Cost basis of the position in token decimals (e.g. 1 USDC = 1000000)
          example: "75000000"
        fillPrice:
          type: string
          description: Average fill price of the position (price per share in token
            decimals)
          example: "750000"
        realisedPnl:
          type: string
          description: Realized profit/loss from closed positions in token decimals
          example: "0"
        unrealizedPnl:
          type: string
          description: Unrealized profit/loss based on current market price in token
            decimals
          example: "25000000"
        marketValue:
          type: string
          description: Current market value of the position in token decimals
          example: "100000000"
      required:
        - cost
        - fillPrice
        - realisedPnl
        - unrealizedPnl
        - marketValue
    MarketPositionDataDto:
      type: object
      properties:
        yes:
          description: Position data for YES outcome
          example:
            cost: "75000000"
            fillPrice: "750000"
            realisedPnl: "0"
            unrealizedPnl: "25000000"
            marketValue: "100000000"
          allOf:
            - $ref: "#/components/schemas/PositionDataDto"
        no:
          description: Position data for NO outcome
          example:
            cost: "25000000"
            fillPrice: "250000"
            realisedPnl: "0"
            unrealizedPnl: "-5000000"
            marketValue: "20000000"
          allOf:
            - $ref: "#/components/schemas/PositionDataDto"
      required:
        - yes
        - no
    ClobPositionDto:
      type: object
      properties:
        market:
          description: Market information
          allOf:
            - $ref: "#/components/schemas/Market"
        positions:
          description: Position data for the market
          allOf:
            - $ref: "#/components/schemas/MarketPositionDataDto"
        latestTrade:
          type: object
          description: Latest trade prices
        tokensBalance:
          type: object
          description: Token balances in token decimals
        orders:
          type: object
          description: Order information
        rewards:
          type: object
          description: Rewards information for this position
      required:
        - market
        - positions
        - tokensBalance
        - orders
    PortfolioPositionsDto:
      type: object
      properties:
        rewards:
          description: Rewards information for the portfolio
          allOf:
            - $ref: "#/components/schemas/PortfolioRewardsDto"
        points:
          type: number
          description: User points
          example: 123
        accumulativePoints:
          type: number
          description: User accumulative points
          example: 456
        amm:
          description: List of AMM positions
          type: array
          items:
            $ref: "#/components/schemas/AmmPositionDto"
        clob:
          description: List of CLOB positions
          type: array
          items:
            $ref: "#/components/schemas/ClobPositionDto"
        group:
          description: Grouped CLOB positions (if enabled)
          type: array
          items:
            type: object
      required:
        - rewards
        - points
        - accumulativePoints
        - amm
        - clob
    PortfolioPnlChartPointDto:
      type: object
      properties:
        timestamp:
          type: number
          description: Point timestamp (ms)
          example: 1700000000000
        value:
          type: number
          description: Series value in USD (realised PnL)
          example: 123.45
      required:
        - timestamp
        - value
    PortfolioPnlChartDto:
      type: object
      properties:
        timeframe:
          type: string
          description: Timeframe window used for previous/current comparison
          example: 7d
        data:
          description: Realised PnL series (USD) for the selected timeframe
          type: array
          items:
            $ref: "#/components/schemas/PortfolioPnlChartPointDto"
        currentValue:
          type: number
          description: Current realised PnL (USD)
          example: -7.04
        previousValue:
          type: number
          description: Previous realised PnL (USD) at timeframe start
          example: -6.5
        percentChange:
          type: number
          description: Percent change between previousValue and currentValue (realised PnL)
          example: 8.24
        current:
          type: object
          description: "Current PnL snapshot (hybrid: realised + unrealized + total)"
          nullable: true
      required:
        - timeframe
        - data
        - currentValue
        - previousValue
        - percentChange
    HistoryMarketGroupDto:
      type: object
      properties:
        id:
          type: number
          description: Unique identifier of the group
          example: 10000037
        slug:
          type: string
          description: Slug identifier of the group
          example: positionconverted-test-1744046422596
        title:
          type: string
          description: Title of the group
          example: PositionConverted test
        status:
          type: string
          description: Status of the group
          example: FUNDED
        deadline:
          type: string
          description: Deadline for the group
          example: 2025-04-11T22:34:56.000Z
        hidden:
          type: boolean
          description: Whether the group is hidden
          example: false
        txHash:
          type: string
          description: Transaction hash for the group
          example: null
        resolutionTxHash:
          type: string
          description: Resolution transaction hash
          example: null
        priorityIndex:
          type: number
          description: Priority index of the group
          example: 0
        metadata:
          type: object
          description: Group metadata
          example:
            isBannered: false
        negRiskMarketId:
          type: string
          description: Onchain NegRisk market ID as identified by the NegriskAdapter
            smart-contract
          example: "0xe103633b40e9b664f8acc89e8cf7b7916475961ae1708a249fa5d6c933168c00"
        createdAt:
          type: string
          description: Creation timestamp
          example: 2025-04-07T17:20:22.135Z
        updatedAt:
          type: string
          description: Last update timestamp
          example: 2025-04-07T17:22:08.464Z
      required:
        - id
        - slug
        - title
        - status
        - deadline
        - hidden
        - priorityIndex
        - metadata
        - negRiskMarketId
        - createdAt
        - updatedAt
    HistoryMarketDto:
      type: object
      properties:
        closed:
          type: boolean
          description: Whether the market is closed
          example: false
        collateral:
          type: object
          description: Collateral token information
          example:
            symbol: USDC
            id: 7
            decimals: 6
        group:
          description: Market group information
          allOf:
            - $ref: "#/components/schemas/HistoryMarketGroupDto"
        condition_id:
          type: string
          description: Condition ID of the market
          example: "0x08518bc4bb8a3dbb89aac4425ace0876b94a5dfa77dee47a20737a19cf67e325"
        funding:
          type: number
          description: Market funding amount
          example: 0
        id:
          type: number
          description: Market ID
          example: 980
        slug:
          type: string
          description: Market slug
          example: market-1-1744046422691
        title:
          type: string
          description: Market title
          example: Market 1
        deadline:
          type: string
          description: Market deadline
          example: 2025-04-11T22:34:56.000Z
      required:
        - closed
        - collateral
        - group
        - condition_id
        - funding
        - id
        - slug
        - title
        - deadline
    HistoryEntryDto:
      type: object
      properties:
        blockTimestamp:
          type: number
          description: Block timestamp of the operation
          example: 1744115608
        collateralAmount:
          type: string
          description: Collateral amount involved in the operation
          example: "0"
        market:
          description: Market information
          allOf:
            - $ref: "#/components/schemas/HistoryMarketDto"
        outcomeTokenAmount:
          type: string
          description: Amount of outcome tokens involved
          example: "100"
        outcomeTokenAmounts:
          description: Amounts of outcome tokens for each outcome
          example:
            - "100"
            - "0"
          type: array
          items:
            type: string
        outcomeIndex:
          type: number
          description: Index of the outcome
          example: 0
        outcomeTokenPrice:
          type: number
          description: Price of the outcome token
          example: 0.5
        strategy:
          type: string
          description: Type of operation
          example: Convert
          enum:
            - Buy
            - Sell
            - Limit Buy
            - Limit Sell
            - Market Buy
            - Market Sell
            - Split
            - Merge
            - Convert
        transactionHash:
          type: string
          description: Transaction hash of the operation
          example: "0x992f36465f938b21a6a5fe3c417c98c3268a616a05479d2dc53870c6cd1a0761"
      required:
        - blockTimestamp
        - collateralAmount
        - market
        - outcomeTokenAmount
        - outcomeTokenAmounts
        - outcomeIndex
        - outcomeTokenPrice
        - strategy
    HistoryResponseDto:
      type: object
      properties:
        data:
          description: List of history entries
          type: array
          items:
            $ref: "#/components/schemas/HistoryEntryDto"
        totalCount:
          type: number
          description: Total count of entries
          example: 8
      required:
        - data
        - totalCount
    Order:
      type: object
      properties:
        salt:
          type: number
          description: Unique random value for signature uniqueness (prevents replay
            attacks)
          example: 1234567890
        maker:
          type: string
          description: Ethereum address of the maker (order creator)
          example: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
          pattern: ^0x[a-fA-F0-9]{40}$
        signer:
          type: string
          description: Address that signed the order
          example: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
        taker:
          type: string
          description: Specific taker address (optional for open orders)
          example: "0x0000000000000000000000000000000000000000"
        tokenId:
          type: string
          description: Token ID being traded (YES or NO position ID from conditional token)
          example: "196332044857908579498285167379934237586289302353716299439995448593246\
            45414627"
        makerAmount:
          type: number
          description: Amount the maker is offering (in wei, 18 decimals)
          example: 1000000000000000000
          minimum: 0
        takerAmount:
          type: number
          description: Amount the maker wants in return (in wei, 18 decimals)
          example: 750000000000000000
          minimum: 0
        expiration:
          type: string
          description: Order expiration timestamp
          example: 2025-04-30T23:59:59Z
        nonce:
          type: number
          description: Order nonce for cancellation tracking
          example: 42
        price:
          type: number
          description: Order price as decimal (0.01-0.99, required for GTC orders)
          example: 0.75
          minimum: 0.01
          maximum: 0.99
        feeRateBps:
          type: number
          description: Fee rate in basis points (1% = 100)
          example: 0
        side:
          type: number
          description: "Order side: 0 = BUY, 1 = SELL"
          enum:
            - 0
            - 1
          example: 0
        signature:
          type: string
          description: EIP-712 signature of order details
          example: 0x123abc456def789ghi0123abc456def789ghi0123abc456def789ghi0123456789012345678901
        signatureType:
          type: number
          description: Signature type (0-3)
          enum:
            - 0
            - 1
            - 2
            - 3
          example: 2
      required:
        - salt
        - maker
        - signer
        - tokenId
        - makerAmount
        - takerAmount
        - feeRateBps
        - side
        - signature
        - signatureType
    CreateOrderDto:
      type: object
      properties:
        order:
          description: Order details including signature and amounts
          allOf:
            - $ref: "#/components/schemas/Order"
        ownerId:
          type: number
          description: Profile ID of the order owner
          example: 12345
        orderType:
          type: string
          description: Order type (GTC=Good Till Cancelled, FOK=Fill Or Kill)
          enum:
            - FOK
            - GTC
          example: GTC
        marketSlug:
          type: string
          description: Market identifier slug
          example: biden-vs-trump-2024
      required:
        - order
        - ownerId
        - orderType
        - marketSlug
    MakerMatch:
      type: object
      properties: {}
    OrderResponseDto:
      type: object
      properties:
        order:
          description: Order details
          allOf:
            - $ref: "#/components/schemas/Order"
        makerMatches:
          description: Maker matches if order was matched immediately
          type: array
          items:
            $ref: "#/components/schemas/MakerMatch"
      required:
        - order
    ErrorResponseDto:
      type: object
      properties:
        message:
          type: string
          description: Error message
          example: Invalid order data
      required:
        - message
    CancelOrderResponseDto:
      type: object
      properties:
        message:
          type: string
          description: Confirmation message for the cancelled order
          example: Order canceled successfully
      required:
        - message
    DeleteOrderBatchDto:
      type: object
      properties:
        orderIds:
          description: Array of order IDs to be cancelled in a single batch operation
          example:
            - 6f52b6d2-6c9e-4a5c-8a4f-28ab4b7ff203
            - 9e31c452-8a2b-42d1-b327-65f18d07dc96
          items:
            type: array
          type: array
      required:
        - orderIds
    CancelOrderFailure:
      type: object
      properties:
        orderId:
          type: string
          description: Order ID that failed to cancel
          example: b53f0e4b-1529-45cc-ad39-e27f4c6eab5a
        reason:
          type: string
          description: Error code indicating the reason for failure
          example: ORDER_NOT_FOUND
          enum:
            - ORDER_NOT_FOUND
            - UNKNOWN_ERROR
        message:
          type: string
          description: User-friendly error message
          example: Order not found or already canceled
      required:
        - orderId
        - reason
        - message
    CancelOrderBatchResponseDto:
      type: object
      properties:
        message:
          type: string
          description: Confirmation message for the cancelled orders
          example: Orders canceled successfully
        canceled:
          description: Array of successfully cancelled order IDs
          example:
            - 611badac-8dfc-48a0-b09e-59654adea1c5
          type: array
          items:
            type: string
        failed:
          description: Array of orders that failed to cancel with reasons
          type: array
          items:
            $ref: "#/components/schemas/CancelOrderFailure"
      required:
        - message
    CancelAllOrdersResponseDto:
      type: object
      properties:
        message:
          type: string
          description: Confirmation message for cancelling all orders
          example: Orders canceled successfully
        canceled:
          description: Array of successfully cancelled order IDs
          example:
            - 611badac-8dfc-48a0-b09e-59654adea1c5
          type: array
          items:
            type: string
        failed:
          description: Array of orders that failed to cancel with reasons
          type: array
          items:
            $ref: "#/components/schemas/CancelOrderFailure"
      required:
        - message