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

# Subscribe one or many tokens

> Subscribe a token (or up to 5000 in one call) to push/webhook updates. Idempotent: only genuinely-new tokens are charged (2 credits each). A bulk cost that would cross your cap is denied 402/429 (`action: raise_cap`) before anything is subscribed.



## OpenAPI

````yaml /api-reference/openapi.json post /subscriptions
openapi: 3.1.0
info:
  title: Serialized Audit API
  version: 1.0.0
  description: Submit a contract address and chain, receive an instant risk verdict.
servers:
  - url: https://www.serializedaudit.io/api
security:
  - apiKey: []
paths:
  /subscriptions:
    post:
      summary: Subscribe one or many tokens
      description: >-
        Subscribe a token (or up to 5000 in one call) to push/webhook updates.
        Idempotent: only genuinely-new tokens are charged (2 credits each). A
        bulk cost that would cross your cap is denied 402/429 (`action:
        raise_cap`) before anything is subscribed.
      operationId: createSubscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/TokenRef'
                - type: object
                  required:
                    - tokens
                  properties:
                    tokens:
                      type: array
                      minItems: 1
                      maxItems: 5000
                      items:
                        $ref: '#/components/schemas/TokenRef'
      responses:
        '200':
          description: Subscribed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscribeResult'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Billing wall.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentError'
        '429':
          description: >-
            Bulk subscribe would cross the cap (`action: raise_cap`, with
            required_credits / remaining_credits); nothing is subscribed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentError'
components:
  schemas:
    TokenRef:
      type: object
      required:
        - chain
        - address
      properties:
        chain:
          type: string
          description: Chain symbol (case-insensitive).
        address:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
    SubscribeResult:
      type: object
      properties:
        ok:
          type: boolean
        subscribed:
          type: integer
          description: Total tokens subscribed by this call (including already-subscribed).
        charged:
          type: integer
          description: Genuinely-new subscriptions billed (2 credits each).
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message.
    PaymentError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        action:
          type: string
          description: Suggested next step.
          enum:
            - wait
            - subscribe
            - add_payment
            - resubscribe
            - verify_payment
            - payment_processing
            - raise_cap
            - upgrade
      description: >-
        Billing denial. Bodies may carry additional context fields depending on
        the wall (resets_at, daily_limit, grace_usd, current_period_end,
        subscription_status).
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Auth-Key
      description: Your secret API key. Create one from your dashboard.

````