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

# Get Alerts

> Search, filter, and paginate through the full historical archive of insider alerts.

Want to backtest a strategy? Need to find every whale buy on Crypto markets from last week? This is your endpoint. You can filter the entire Polychads database using the parameters below.

<ParamField query="page" type="integer" default="1">
  The page number to fetch.
</ParamField>

<ParamField query="page_size" type="integer" default="20">
  How many results to pack into one page.
  *Limits: Free: 20, Pro: 50, Enterprise: 100.*
</ParamField>

<ParamField query="category" type="string">
  Isolate a specific market sector: `crypto`, `politics`, `world`, `tech`, `finance`, `pop_culture`, `other`.
</ParamField>

<ParamField query="side" type="string">
  Filter by action: `BUY` or `SELL`.
</ParamField>

<ParamField query="min_usdc" type="float">
  Only show trades larger than this USDC amount. Great for filtering out noise.
</ParamField>

<ParamField query="min_signal" type="integer">
  Only show alerts with a Signal Score equal to or higher than this (0-100).
</ParamField>

<ParamField query="q" type="string">
  Power search. Matches against the market question, market slug, or exact wallet address.
</ParamField>

### Try it out

<RequestExample>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_KEY_HERE" \
    "https://polychadsbot.xyz/api/v1/alerts?category=crypto&min_signal=80&min_usdc=5000&page=1"
  ```

  ```python Python theme={null}
  import requests

  r = requests.get(
      "https://polychadsbot.xyz/api/v1/alerts",
      headers={"Authorization": "Bearer YOUR_KEY_HERE"},
      params={"category": "crypto", "min_signal": 80, "min_usdc": 5000}
  )
  data = r.json()
  print(f"Found {data['total']} alerts matching your criteria.")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "alerts": [
      {
        "id": 2218,
        "alert_type": "fresh",
        "wallet_address": "0xcd5D...30D9",
        "market_id": "0x4441...890a",
        "event_title": "Opinion FDV above $500M?",
        "side": "BUY",
        "outcome": "Yes",
        "entry_price": 0.49,
        "usdc_value": 8500.0,
        "signal_score": 85,
        "category": "crypto",
        "created_at": "2026-02-27 11:10:12"
      }
    ],
    "total": 142,
    "page": 1,
    "page_size": 20,
    "has_more": true
  }
  ```
</ResponseExample>


## OpenAPI

````yaml GET /alerts
openapi: 3.0.3
info:
  title: Polychads Alerts API
  version: '1.0'
  description: Real-time Polymarket insider trading alerts
servers:
  - url: https://polychadsbot.xyz/api/v1
security:
  - bearerAuth: []
paths:
  /alerts:
    get:
      summary: Get Alerts
      description: Paginated alert history with filtering.
      operationId: getAlerts
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          description: Page number
        - name: page_size
          in: query
          schema:
            type: integer
            default: 20
          description: Results per page
        - name: category
          in: query
          schema:
            type: string
            enum:
              - crypto
              - politics
              - world
              - tech
              - finance
              - pop_culture
              - other
          description: Filter by category
        - name: side
          in: query
          schema:
            type: string
            enum:
              - BUY
              - SELL
          description: Filter by trade direction
        - name: min_usdc
          in: query
          schema:
            type: number
          description: Minimum trade size in USDC
        - name: min_signal
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 100
          description: Minimum signal score
        - name: q
          in: query
          schema:
            type: string
          description: Text search — matches market title, slug, or wallet address
      responses:
        '200':
          description: Paginated alerts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedAlerts'
components:
  schemas:
    PaginatedAlerts:
      type: object
      properties:
        alerts:
          type: array
          items:
            $ref: '#/components/schemas/Alert'
        total:
          type: integer
        page:
          type: integer
        page_size:
          type: integer
        has_more:
          type: boolean
    Alert:
      type: object
      properties:
        id:
          type: integer
        alert_type:
          type: string
          enum:
            - fresh
            - fresh_accumulator
            - cluster
        wallet_address:
          type: string
        event_title:
          type: string
        event_slug:
          type: string
        market_id:
          type: string
        side:
          type: string
          enum:
            - BUY
            - SELL
        outcome:
          type: string
        entry_price:
          type: number
        usdc_value:
          type: number
        signal_score:
          type: integer
        trade_count:
          type: integer
        category:
          type: string
        created_at:
          type: string
        resolved:
          type: boolean
        won:
          type: boolean
          nullable: true
        profit_usdc:
          type: number
          nullable: true
        details:
          type: object
          nullable: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your API key — get one from @chadsapibot on Telegram

````