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

# Search

> Search events, markets, and traders

<Note>**3** credits per request</Note><hr />

<AccordionGroup>
  <Accordion title="You will get">
    * Full-text search across events, markets, and traders matching the query string `q`.
    * Optionally restrict to one `type` (`events`, `markets`, or `traders`).
    * The unified search-box backend for prediction markets.
  </Accordion>
</AccordionGroup>


## OpenAPI

````yaml /api-reference/openapi.json get /v1/prediction/search
openapi: 3.0.0
info:
  title: CoinStats Public API
  description: >-
    CoinStats Public API — programmatic access to market data, news, NFTs,
    wallets, exchange connections, and user portfolios. Authenticate every
    request with the `X-API-KEY` header (or an OAuth Bearer token in the
    `Authorization` header). Generate keys at https://openapi.coinstats.app.
  version: '1.0'
  contact: {}
servers:
  - url: https://api.coinstats.app
security: []
tags:
  - name: CoinStats
    description: ''
  - name: Market Data
    description: >-
      The Market Data section of the API provides endpoints to access a wide
      range of market-related information, including cryptocurrency coins,
      ticker data, and fiat currency rates. This category offers comprehensive
      data to help users monitor and analyze the cryptocurrency market, track
      prices, and gain insights into market trends
  - name: News
    description: >-
      The News section of the API allows you to access news articles and updates
      related to cryptocurrencies and the blockchain industry. It provides
      valuable information from various sources to keep you informed about the
      latest developments
  - name: NFTs
    description: >-
      The NFT section of the API provides endpoints to interact with
      Non-Fungible Tokens (NFTs), which are unique digital assets stored on a
      blockchain. These endpoints allow you to retrieve information about NFTs,
      including collections, assets, trending NFTs, and specific assets
      associated with wallet addresses.
  - name: Wallet Data
    description: >-
      The Wallet section of the API provides a comprehensive set of endpoints to
      manage and interact with wallets. It enables users to retrieve wallet
      balances, monitor syncing status, fetch transaction data, and synchronize
      wallet information with the blockchain. By integrating these endpoints
      into your application, you can offer robust wallet functionality to your
      users.
  - name: Exchange Connection
    description: >-
      The Exchange Connection section of the API provides a comprehensive set of
      endpoints to manage and interact with exchanges. It enables users to
      retrieve exchange balances, monitor syncing status, fetch transaction
      data. By integrating these endpoints into your application, you can offer
      robust exchange portfolio tracking functionality to your users.
  - name: User Portfolio
    description: >-
      The Portfolio section of the API provides a comprehensive set of endpoints
      to manage and interact with Share Portfolios. It enables users to retrieve
      current Portfolio Coins and Transactions.
  - name: Usage
    description: The Usage section provides account-level API usage data.
  - name: Status
    description: The Status section provides API availability checks.
  - name: Prediction · Markets
    description: >-
      Polymarket markets: list/trend/detail, live CLOB prices and order book,
      OHLC candles, and price history. Prices are probabilities in 0..1, money
      is USD, dates are ISO 8601.
  - name: Prediction · Events
    description: >-
      Polymarket events — groups of related markets (e.g. one market per
      candidate). List, trend, and fetch an event with its child markets.
  - name: Prediction · Traders
    description: >-
      Trader leaderboard plus deep per-trader analytics: profile, open
      positions, trade history, daily PnL, category stats, aggregate trade
      stats, and composite score.
  - name: Prediction · Analytics
    description: >-
      Platform-wide analytics: overview stats, smart-money and whale traders,
      trending-by-smart-money markets, and composite market signals.
  - name: Prediction · Search
    description: Full-text search across Polymarket events, markets, and traders.
paths:
  /v1/prediction/search:
    get:
      tags:
        - Prediction · Search
      summary: Search events, markets, and traders
      operationId: search
      parameters:
        - name: q
          required: true
          in: query
          description: Search query (min 2 chars)
          schema:
            minLength: 2
            type: string
        - name: type
          required: false
          in: query
          description: Restrict result type
          schema:
            type: string
            enum:
              - events
              - markets
              - traders
        - name: limit
          required: false
          in: query
          schema:
            maximum: 50
            default: 20
            example: 20
            type: number
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponseDto'
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                statusCode: 400
                message: Bad Request
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                statusCode: 401
                message: Unauthorized
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '403':
          description: Forbidden
          content:
            application/json:
              example:
                statusCode: 403
                message: Forbidden
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '404':
          description: Not Found
          content:
            application/json:
              example:
                statusCode: 404
                message: Not Found
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '409':
          description: Conflict (for some endpoints)
          content:
            application/json:
              example:
                statusCode: 409
                message: Transactions not synced
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '429':
          description: Too Many Requests
          content:
            application/json:
              example:
                statusCode: 429
                message: Rate limit exceeded
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '503':
          description: Service Unavailable
          content:
            application/json:
              example:
                statusCode: 503
                message: Service Unavailable. Please Contact Support
      security:
        - X-API-KEY: []
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl --request GET \
              --url 'https://api.coinstats.app/v1/prediction/search?q=<q>' \
              --header 'X-API-KEY: <api-key>'
        - lang: python
          label: Python
          source: |-
            import requests

            url = "https://api.coinstats.app/v1/prediction/search?q=<q>"

            headers = {"X-API-KEY": "<api-key>"}

            response = requests.request("GET", url, headers=headers)

            print(response.json())
        - lang: javascript
          label: JavaScript
          source: >-
            const options = {method: 'GET', headers: {'X-API-KEY':
            '<api-key>'}};


            fetch('https://api.coinstats.app/v1/prediction/search?q=<q>',
            options)
              .then((response) => response.json())
              .then((response) => console.log(response))
              .catch((err) => console.error(err));
        - lang: php
          label: PHP
          source: |-
            <?php

            $curl = curl_init();

            curl_setopt_array($curl, [
              CURLOPT_URL => "https://api.coinstats.app/v1/prediction/search?q=<q>",
              CURLOPT_RETURNTRANSFER => true,
              CURLOPT_CUSTOMREQUEST => "GET",
              CURLOPT_HTTPHEADER => [
                "X-API-KEY: <api-key>"
              ],
            ]);

            $response = curl_exec($curl);
            $err = curl_error($curl);

            curl_close($curl);

            if ($err) {
              echo "cURL Error #:" . $err;
            } else {
              echo $response;
            }
        - lang: go
          label: Go
          source: "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n)\n\nfunc main() {\n\n\turl := \"https://api.coinstats.app/v1/prediction/search?q=<q>\"\n\n\treq, _ := http.NewRequest(\"GET\", url, nil)\n\n\treq.Header.Add(\"X-API-KEY\", \"<api-key>\")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := io.ReadAll(res.Body)\n\n\tfmt.Println(string(body))\n}"
        - lang: java
          label: Java
          source: >-
            HttpResponse<String> response =
            Unirest.get("https://api.coinstats.app/v1/prediction/search?q=<q>")
              .header("X-API-KEY", "<api-key>")
              .asString();
components:
  schemas:
    SearchResponseDto:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the request succeeded
          example: true
        timestamp:
          type: string
          description: ISO 8601 timestamp the response was generated
          example: '2025-06-19T12:00:00.000Z'
        query:
          type: string
        data:
          $ref: '#/components/schemas/SearchResultDataDto'
      required:
        - success
        - timestamp
        - data
    SearchResultDataDto:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventDto'
        markets:
          type: array
          items:
            $ref: '#/components/schemas/MarketDto'
        traders:
          type: array
          items:
            $ref: '#/components/schemas/TraderDto'
    EventDto:
      type: object
      properties:
        source:
          type: string
          example: polymarket
        sourceId:
          type: string
        eventId:
          type: number
        slug:
          type: string
          example: us-election-2024
        title:
          type: string
          example: 2024 US Presidential Election
        description:
          type: string
        image:
          type: string
        icon:
          type: string
        startDate:
          type: string
        endDate:
          type: string
        volume:
          type: number
        volume24hr:
          type: number
        liquidity:
          type: number
        competitive:
          type: number
        active:
          type: boolean
        closed:
          type: boolean
        archived:
          type: boolean
        restricted:
          type: boolean
        marketIds:
          type: array
          items:
            type: string
        tagIds:
          type: array
          items:
            type: string
        seriesId:
          type: string
    MarketDto:
      type: object
      properties:
        source:
          type: string
          example: polymarket
        sourceId:
          type: string
          example: '0x1234'
        conditionId:
          type: string
          example: 0xcondition...
        marketId:
          type: number
          example: 512345
        slug:
          type: string
          example: will-btc-hit-100k-2025
        question:
          type: string
          example: Will BTC hit $100k in 2025?
        description:
          type: string
        image:
          type: string
        icon:
          type: string
        outcomes:
          example:
            - 'Yes'
            - 'No'
          type: array
          items:
            type: string
        outcomePrices:
          example:
            - 0.62
            - 0.38
          type: array
          items:
            type: number
        clobTokenIds:
          type: array
          items:
            type: string
        volume:
          type: number
          example: 1500000
        volume24hr:
          type: number
          example: 45000
        liquidity:
          type: number
          example: 230000
        openInterest:
          type: number
        bestBid:
          type: number
        bestAsk:
          type: number
        spread:
          type: number
        midpoint:
          type: number
        startDate:
          type: string
        endDate:
          type: string
        active:
          type: boolean
        closed:
          type: boolean
        resolved:
          type: boolean
        acceptingOrders:
          type: boolean
        resolutionSource:
          type: string
        resolvedOutcome:
          type: string
        resolvedAt:
          type: string
        eventId:
          type: number
        eventSlug:
          type: string
        tagIds:
          type: array
          items:
            type: string
        priceChange24hr:
          type: number
        volumeChange24hr:
          type: number
    TraderDto:
      type: object
      properties:
        walletAddress:
          type: string
          example: 0xabc...
        username:
          type: string
        displayName:
          type: string
        profileImageUrl:
          type: string
        bio:
          type: string
        xUsername:
          type: string
        volume:
          type: number
        volume24hr:
          type: number
        volume7d:
          type: number
        volume30d:
          type: number
        pnl:
          type: number
        pnl24hr:
          type: number
        pnl7d:
          type: number
        pnl30d:
          type: number
        pnl1d:
          type: number
        pnl14d:
          type: number
        pnl90d:
          type: number
        unrealizedPnl:
          type: number
        winCount:
          type: number
        lossCount:
          type: number
        winAmount:
          type: number
        lossAmount:
          type: number
        totalPositions:
          type: number
        roi:
          type: number
        score:
          type: number
        tags:
          type: array
          items:
            type: string
        rank:
          type: number
        rankByVolume:
          type: number
        rankByPnl:
          type: number
        winRate:
          type: number
        totalTrades:
          type: number
        marketsTraded:
          type: number
        avgPositionSize:
          type: number
        tier:
          type: number
          enum:
            - 1
            - 2
            - 3
            - 4
          example: 1
        isHotTop:
          type: boolean
        isWhale:
          type: boolean
        isSmartMoney:
          type: boolean
        positions:
          type: array
          items:
            $ref: '#/components/schemas/PositionDto'
        positionsCount:
          type: number
        positionsValue:
          type: number
        dataTruncated:
          type: boolean
        cashBalance:
          type: number
          description: >-
            On-chain USDC balance (Polygon), refreshed in the background on
            profile view
        cashBalanceAt:
          type: string
          format: date-time
    PositionDto:
      type: object
      properties:
        conditionId:
          type: string
        clobTokenId:
          type: string
        marketSlug:
          type: string
        marketTitle:
          type: string
        outcome:
          type: string
        size:
          type: number
        avgPrice:
          type: number
        currentPrice:
          type: number
        initialValue:
          type: number
        currentValue:
          type: number
        cashPnl:
          type: number
        percentPnl:
          type: number
  securitySchemes:
    X-API-KEY:
      type: apiKey
      in: header
      name: X-API-KEY
      description: >-
        API key required to access the endpoints. Generate one from your
        dashboard at https://openapi.coinstats.app and pass it in the
        `X-API-KEY` request header. Never expose your key in client-side code.

````