Bitculator Alarms API

openapi: 3.2.0
info:
  title: Bitculator Data Alarms API
  description: 'Programmatic access to Bitculator market data: coins, prices, history, exchanges, trust scores, tickers, pairs, wallets, sentiment, technical indicators, liquidations, editorial content, and calculators.'
  version: 1.0.0
servers:
- url: https://bitculator.com
security:
- default: []
tags:
- name: Alarms
  description: 'Price-alarm CRUD — the same alarms the web app manages. Alarms consume the key

    owner''s alarm inventory balance, are TARGET-type on coins only, and an above/below

    vs current-value guard blocks alarms that would self-trigger instantly. Key-scoped

    (the API key sets the owner) and never response-cached.'
paths:
  /api/v1/alarms:
    get:
      summary: List alarms
      operationId: listAlarms
      description: 'The key owner''s alarms, newest first, paginated. Filter by `status`, `direction`

        or `notification` channel.'
      parameters:
      - in: query
        name: page
        description: Page number (1-based).
        example: 1
        required: false
        schema:
          type:
          - integer
          - 'null'
          description: Page number (1-based).
          example: 1
      - in: query
        name: per_page
        description: Rows per page (1–100, default 25).
        example: 25
        required: false
        schema:
          type:
          - integer
          - 'null'
          description: Rows per page (1–100, default 25).
          example: 25
      - in: query
        name: status
        description: 'Filter by state: `active` or `triggered`.'
        example: active
        required: false
        schema:
          type:
          - string
          - 'null'
          description: 'Filter by state: `active` or `triggered`.'
          example: active
      - in: query
        name: direction
        description: 'Filter by trigger direction: `above` or `below`.'
        example: above
        required: false
        schema:
          type:
          - string
          - 'null'
          description: 'Filter by trigger direction: `above` or `below`.'
          example: above
      - in: query
        name: notification
        description: 'Filter by delivery channel: `email`, `push` or `webhook`.'
        example: email
        required: false
        schema:
          type:
          - string
          - 'null'
          description: 'Filter by delivery channel: `email`, `push` or `webhook`.'
          example: email
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                  - id: 42
                    name: BTC six figures
                    coin:
                      slug: bitcoin
                      symbol: BTC
                      name: Bitcoin
                    metric: rate
                    direction: above
                    target: '100000'
                    notification: email
                    status: active
                    created_at: '2026-06-21T09:15:00+00:00'
                  meta:
                    current_page: 1
                    per_page: 25
                    total: 3
                    last_page: 1
                properties:
                  data:
                    type: array
                    example:
                    - id: 42
                      name: BTC six figures
                      coin:
                        slug: bitcoin
                        symbol: BTC
                        name: Bitcoin
                      metric: rate
                      direction: above
                      target: '100000'
                      notification: email
                      status: active
                      created_at: '2026-06-21T09:15:00+00:00'
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 42
                        name:
                          type: string
                          example: BTC six figures
                        coin:
                          type: object
                          properties:
                            slug:
                              type: string
                              example: bitcoin
                            symbol:
                              type: string
                              example: BTC
                            name:
                              type: string
                              example: Bitcoin
                        metric:
                          type: string
                          example: rate
                        direction:
                          type: string
                          example: above
                        target:
                          type: string
                          example: '100000'
                        notification:
                          type: string
                          example: email
                        status:
                          type: string
                          example: active
                        created_at:
                          type: string
                          example: '2026-06-21T09:15:00+00:00'
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 25
                      total:
                        type: integer
                        example: 3
                      last_page:
                        type: integer
                        example: 1
      tags:
      - Alarms
    post:
      summary: Create an alarm
      operationId: createAnAlarm
      description: 'Creates a TARGET alarm on a coin and spends one alarm slot from the key owner''s

        balance. The target is checked against the coin''s current value so the alarm

        cannot self-trigger instantly: an `above` alarm must target more than the current

        value, a `below` alarm less.'
      parameters: []
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 43
                    name: BTC six figures
                    coin:
                      slug: bitcoin
                      symbol: BTC
                      name: Bitcoin
                    metric: rate
                    direction: above
                    target: '100000'
                    notification: email
                    status: active
                    created_at: '2026-07-03T08:00:00+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 43
                      name:
                        type: string
                        example: BTC six figures
                      coin:
                        type: object
                        properties:
                          slug:
                            type: string
                            example: bitcoin
                          symbol:
                            type: string
                            example: BTC
                          name:
                            type: string
                            example: Bitcoin
                      metric:
                        type: string
                        example: rate
                      direction:
                        type: string
                        example: above
                      target:
                        type: string
                        example: '100000'
                      notification:
                        type: string
                        example: email
                      status:
                        type: string
                        example: active
                      created_at:
                        type: string
                        example: '2026-07-03T08:00:00+00:00'
      tags:
      - Alarms
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: A label for the alarm (max 255 characters).
                  example: BTC six figures
                coin:
                  type: string
                  description: The coin's slug identifier.
                  example: bitcoin
                metric:
                  type: string
                  description: 'The watched metric: `rate`, `volume` or `marketcap`.'
                  example: rate
                direction:
                  type: string
                  description: 'Trigger direction: `above` or `below`.'
                  example: above
                target:
                  type: number
                  description: The threshold value (must sit on the `direction` side of the coin's current value).
                  example: 100000
                notification:
                  type: string
                  description: 'Delivery channel: `email`, `push` or `webhook`.'
                  example: email
              required:
              - name
              - coin
              - metric
              - direction
              - target
              - notification
  /api/v1/alarms/{id}:
    parameters:
    - in: path
      name: id
      description: The alarm id.
      example: 42
      required: true
      schema:
        type: integer
    delete:
      summary: Delete an alarm
      operationId: deleteAnAlarm
      description: Deletes one of the key owner's alarms and refunds the alarm slot it consumed.
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    deleted: true
                properties:
                  data:
                    type: object
                    properties:
                      deleted:
                        type: boolean
                        example: true
      tags:
      - Alarms
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: Create a Data API key in your <a href="/user/developer/api">developer console</a> — keys are Bearer-only and carry the <code>data-api</code> ability. Keep them server-side; they are never meant for client-side embedding.