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

# Create a Hyperliquid liquidation alert

> POST /v1/alerts posts matching Hyperliquid liquidations to your webhook, Discord channel, Slack channel or Telegram chat within seconds, filtered by market, side, size and wallet.

See the [liquidation alerts guide](https://docs.ironflow.sh/guides/liquidation-alerts.md) for the message formats and how to verify a webhook signature.


## OpenAPI

````yaml POST /v1/alerts
openapi: 3.1.0
info:
  title: Ironflow API
  version: 1.0.0
  description: >
    Hyperliquid market data from Ironflow's own nodes: tick-level fills and

    trades, candles, funding rates, liquidations, mark prices, open interest,

    markets and wallet analytics over REST. One schema across native HL perps,

    HIP-3 builder markets, HIP-4 outcome contracts and HL spot.


    **Base URL:** `https://api.ironflow.sh`


    **Authentication:** Read endpoints work without a key (keyless access) or

    with a Bearer token in the `Authorization` header. Writes always need a key.

    ```

    Authorization: Bearer if_your_api_key

    ```

    Get a free key at https://ironflow.sh/key.


    **Access levels:**


    | Access | Requests per minute | History | Max range per request |

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

    | No key | 10 per IP | 24 hours | 1 hour |

    | Free key | 60 | 30 days | 6 hours |

    | Explorer | 100 | 90 days | 24 hours |

    | Builder | 1,000 | 1 year | 7 days |

    | Enterprise | 10,000 | full | unlimited |


    Without a market filter, high-volume endpoints allow at most 4 hours per
    request.

    `/v1/trades` filtered to one perp or spot market allows 24 hours per request

    without a key and on a free key.

    A header that is present but malformed returns 401; keyless access applies
    only

    when no `Authorization` header is sent.


    **Data availability:** fills and trades cover a rolling 12 months; other

    datasets start later (funding 2025-09-27, open interest and mark prices

    2026-04-29).


    **Timestamps:** All timestamps are Unix milliseconds (int64).


    **Pagination:** Paginated endpoints return a `cursor` in
    `pagination.next_cursor`.

    Pass it as the `cursor` query parameter to fetch the next page.

    When `pagination.has_more` is `false`, you have reached the last page.
  contact:
    name: Ironflow Support
    url: https://ironflow.sh
servers:
  - url: https://api.ironflow.sh
    description: Production
security:
  - bearerAuth: []
  - {}
tags:
  - name: Market Data
    description: Historical tick-level market data stored in ClickHouse.
  - name: Analytics
    description: >-
      Aggregated analytics. Net flows and funding stats work without a key; the
      others need a key (a free key works).
  - name: Cohorts
    description: Predefined and custom address groups for filtering market data.
  - name: Alerts
    description: >-
      Liquidation alerts that Ironflow posts to your webhook, Discord channel,
      Slack channel or Telegram chat.
  - name: Info Proxy
    description: >-
      Cached passthrough to the Hyperliquid Info API. No record caps, higher
      rate limits.
  - name: Export
    description: Bulk data export as CSV or Parquet (Builder tier and above).
  - name: Query
    description: >-
      Read-only ClickHouse SQL over curated Hyperliquid tables (hl.*), limited
      by tier.
  - name: System
    description: Health checks and metadata endpoints.
  - name: TradingApp
    description: >-
      Trading app Phase A — wallet auth (SIWE), agent-key provisioning, and
      kill-switch.
paths:
  /v1/alerts:
    post:
      tags:
        - Alerts
      summary: Create a liquidation alert
      description: |
        Ironflow posts each Hyperliquid liquidation that matches the filter to
        `url`, usually within a few seconds of the chain: an HTTPS webhook (a
        signed JSON body), a Discord channel webhook or a Slack incoming
        webhook (a chat message). For Telegram send `telegram_chat` instead
        of `url`, and add the bot named in the response's `setup` to that
        chat. One alert sends at most one message every 5
        seconds, listing what it matched since the last one, so a cascade
        arrives as a few messages rather than hundreds.

        Partial fills of one liquidated position in one transaction count as
        one liquidation, and `min_usd` applies to their total.

        **Tier limits:** free 1 alert, Explorer 5, Builder 20, Enterprise 100.
        Keyless requests cannot create alerts. On the free tier, Discord,
        Slack and Telegram messages end with a one-line Ironflow link.

        For a webhook the response carries `signing_secret` once: every
        delivery has an `X-Ironflow-Signature: t=<unix seconds>,v1=<hex>`
        header, the HMAC-SHA256 of `<t>.<raw body>` with that secret.
      operationId: createAlert
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                telegram_chat:
                  type: string
                  description: >-
                    A Telegram chat instead of `url`: a public @channel or group
                    name, or a numeric chat id (groups and channels start with
                    -100). The bot named in `setup` must be in the chat (in a
                    channel, as an admin that can post).
                  example: '@my_liquidations'
                url:
                  type: string
                  description: >-
                    Where to post: `https://discord.com/api/webhooks/...`,
                    `https://hooks.slack.com/services/...` or any public HTTPS
                    URL (port 443 or 8443). Required unless `telegram_chat` is
                    set.
                  example: https://discord.com/api/webhooks/123/abc
                name:
                  type: string
                  maxLength: 80
                  description: Shown in the message title.
                  example: BTC and ETH longs
                markets:
                  description: >-
                    Markets to watch: symbols or Hyperliquid coin names, as a
                    list or a comma-separated string (at most 50). Omit for
                    every market.
                  oneOf:
                    - type: array
                      items:
                        type: string
                    - type: string
                  example:
                    - BTC
                    - ETH-PERP
                    - xyz:NVDA
                side:
                  type: string
                  enum:
                    - any
                    - long
                    - short
                  default: any
                  description: 'The liquidated position: `long` means longs were liquidated.'
                min_usd:
                  type: number
                  minimum: 0
                  default: 0
                  description: Smallest liquidation to report, in USD.
                  example: 100000
                address:
                  type: string
                  description: Only this wallet's liquidations.
                  example: '0xabc0000000000000000000000000000000000001'
      responses:
        '201':
          description: >-
            Alert created. `signing_secret` appears only here, and only for
            webhooks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiquidationAlert'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    LiquidationAlert:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        type:
          type: string
          enum:
            - webhook
            - discord
            - slack
            - telegram
        destination:
          type: string
          description: Host of the URL, without its secret part, or the Telegram chat.
          example: discord.com/…
        markets:
          type: array
          items:
            type: string
          description: 'Empty: every market.'
          example:
            - BTC-PERP
            - ETH-PERP
        side:
          type: string
          enum:
            - any
            - long
            - short
        min_usd:
          type: number
          example: 100000
        address:
          type: string
        status:
          type: string
          enum:
            - active
            - disabled
          description: >-
            disabled after 20 failed deliveries in a row; a delivered test
            re-enables it.
        failures:
          type: integer
          description: Failed deliveries in a row.
        last_error:
          type: string
          example: 'destination answered HTTP 404: Unknown Webhook'
        last_sent_at:
          type: string
          format: date-time
          nullable: true
        sent_count:
          type: integer
          description: Liquidations delivered so far.
        created_at:
          type: string
          format: date-time
        signing_secret:
          type: string
          description: Webhooks only, in the create response only.
          example: whsec_3f9a...
        setup:
          type: string
          description: >-
            Create response only: what to do before the first message arrives
            (Telegram: which bot to add to the chat).
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable error code.
              example: RATE_LIMIT_EXCEEDED
            message:
              type: string
              description: Human-readable error description.
              example: Rate limit exceeded. Retry after 60 seconds.
  responses:
    BadRequest:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: BAD_REQUEST
              message: address is required
    Unauthorized:
      description: Missing or invalid API key.
      headers:
        WWW-Authenticate:
          schema:
            type: string
            example: Bearer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Invalid or missing API key
    Forbidden:
      description: Your tier does not include this feature.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: TIER_FORBIDDEN
              message: Export requires Builder tier or above
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Ironflow API key, format `if_xxxx`. Free keys at
        https://ironflow.sh/key. Optional on read endpoints.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.