openapi: 3.0.0
info:
  title: Blast API
  description: Create and manage Solana SOL and SPL token airdrops.
  version: 1.0.3
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    def-0:
      type: object
      required:
        - error
        - message
        - statusCode
      properties:
        error:
          type: string
        message:
          type: string
        statusCode:
          type: number
      title: errorResponse
paths:
  /auth/challenge:
    get:
      operationId: getAuthChallenge
      summary: Get a wallet signing challenge
      tags:
        - Auth
      parameters:
        - schema:
            type: string
          in: query
          name: address
          required: true
      responses:
        "200":
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
        "400":
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: number
  /auth/verify:
    post:
      operationId: verifyAuthChallenge
      summary: Verify a signed challenge and issue tokens
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - address
                - signature
              properties:
                address:
                  type: string
                signature:
                  type: string
      responses:
        "200":
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                  - token
                  - expiresAt
                  - refreshToken
                properties:
                  token:
                    type: string
                  expiresAt:
                    type: number
                  refreshToken:
                    type: string
        "400":
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                  - message
                  - statusCode
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: number
        "401":
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                  - message
                  - statusCode
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: number
  /auth/refresh:
    post:
      operationId: refreshAuthToken
      summary: Refresh authentication tokens
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - address
                - refreshToken
              properties:
                address:
                  type: string
                refreshToken:
                  type: string
      responses:
        "200":
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                  - token
                  - expiresAt
                  - refreshToken
                properties:
                  token:
                    type: string
                  expiresAt:
                    type: number
                  refreshToken:
                    type: string
        "400":
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                  - message
                  - statusCode
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: number
        "401":
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                  - message
                  - statusCode
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: number
  /airdrops:
    post:
      operationId: createAirdrop
      summary: Create a SOL airdrop
      tags:
        - Airdrops
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - batches
              properties:
                batches:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: array
                    minItems: 1
                    maxItems: 20
                    items:
                      type: object
                      required:
                        - address
                        - atomicAmount
                      properties:
                        address:
                          type: string
                        atomicAmount:
                          type: integer
                          minimum: 1
      security:
        - bearerAuth: []
      responses:
        "201":
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                    enum:
                      - created
        "400":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
        "401":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
        "500":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
    get:
      operationId: listAirdrops
      summary: List your airdrops
      tags:
        - Airdrops
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Default Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                    - id
                    - totalAmount
                    - recipientCount
                    - status
                    - label
                    - createdAt
                    - updatedAt
                    - recipients
                    - mintAddress
                    - decimals
                  properties:
                    id:
                      type: string
                    totalAmount:
                      type: number
                    recipientCount:
                      type: number
                    status:
                      type: string
                      enum:
                        - created
                        - processing
                        - completed
                        - failed
                    label:
                      type: string
                    createdAt:
                      type: number
                    updatedAt:
                      type: number
                    mintAddress:
                      type: string
                    decimals:
                      type: integer
                    recipients:
                      type: array
                      items:
                        type: object
                        required:
                          - address
                          - atomicAmount
                        properties:
                          address:
                            type: string
                          atomicAmount:
                            type: number
        "401":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
  /airdrops/token:
    post:
      operationId: createTokenAirdrop
      summary: Create an SPL token airdrop
      tags:
        - Airdrops
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - mintAddress
                - decimals
                - batches
              properties:
                mintAddress:
                  type: string
                decimals:
                  type: integer
                  minimum: 0
                  maximum: 9
                batches:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: array
                    minItems: 1
                    maxItems: 4
                    items:
                      type: object
                      required:
                        - address
                        - atomicAmount
                      properties:
                        address:
                          type: string
                        atomicAmount:
                          type: integer
                          minimum: 1
      security:
        - bearerAuth: []
      responses:
        "201":
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                    enum:
                      - created
        "400":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
        "401":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
        "500":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
  /airdrops/{id}:
    delete:
      operationId: deleteAirdrop
      summary: Delete an unstarted airdrop
      tags:
        - Airdrops
      parameters:
        - schema:
            type: string
          in: path
          name: id
          required: true
      security:
        - bearerAuth: []
      responses:
        "204":
          description: Default Response
          content:
            application/json:
              schema: {}
        "400":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
        "401":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
        "404":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
    get:
      operationId: getAirdrop
      summary: Get airdrop details
      tags:
        - Airdrops
      parameters:
        - schema:
            type: string
          in: path
          name: id
          required: true
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                  - status
                  - recipientCount
                  - totalAmount
                  - label
                  - transactions
                  - createdAt
                  - updatedAt
                  - mintAddress
                  - decimals
                properties:
                  id:
                    type: string
                  status:
                    type: string
                    enum:
                      - created
                      - processing
                      - completed
                      - failed
                  recipientCount:
                    type: integer
                  totalAmount:
                    type: integer
                  label:
                    type: string
                  createdAt:
                    type: integer
                  updatedAt:
                    type: integer
                  mintAddress:
                    type: string
                  decimals:
                    type: integer
                  transactions:
                    type: array
                    items:
                      type: object
                      required:
                        - id
                        - status
                        - recipients
                        - createdAt
                        - updatedAt
                        - signature
                        - bullJobId
                        - retryCount
                        - errorMessage
                      properties:
                        id:
                          type: number
                        status:
                          type: string
                          enum:
                            - pending
                            - confirming
                            - confirmed
                            - failed
                            - expired
                        createdAt:
                          type: integer
                        updatedAt:
                          type: integer
                        retryCount:
                          type: number
                        signature:
                          type: string
                          nullable: true
                        bullJobId:
                          type: string
                          nullable: true
                        errorMessage:
                          type: string
                          nullable: true
                        recipients:
                          type: array
                          items:
                            type: object
                            required:
                              - address
                              - atomicAmount
                            properties:
                              address:
                                type: string
                              atomicAmount:
                                type: number
        "401":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
        "404":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
  /airdrops/{id}/start:
    post:
      operationId: startAirdrop
      summary: Submit signed transactions for an airdrop
      tags:
        - Airdrops
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              items:
                type: object
                required:
                  - batchId
                  - blockhash
                  - lastValidBlockHeight
                  - minContextSlot
                  - txBase64
                properties:
                  batchId:
                    type: number
                  blockhash:
                    type: string
                  lastValidBlockHeight:
                    type: integer
                    minimum: 1
                  minContextSlot:
                    type: integer
                    minimum: 1
                  txBase64:
                    type: string
      parameters:
        - schema:
            type: string
          in: path
          name: id
          required: true
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                    enum:
                      - processing
                  message:
                    type: string
                  jobs:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                        jobId:
                          type: string
        "400":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
        "401":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
        "404":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
        "500":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
  /airdrops/{airdropId}/retry-batch/{batchId}:
    post:
      operationId: retryAirdropTransaction
      summary: Retry an expired airdrop transaction
      tags:
        - Airdrops
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - blockhash
                - lastValidBlockHeight
                - minContextSlot
                - txBase64
              properties:
                blockhash:
                  type: string
                lastValidBlockHeight:
                  type: integer
                  minimum: 0
                minContextSlot:
                  type: integer
                  minimum: 0
                txBase64:
                  type: string
      parameters:
        - schema:
            type: string
          in: path
          name: airdropId
          required: true
        - schema:
            type: string
          in: path
          name: batchId
          required: true
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                properties:
                  success:
                    type: boolean
        "400":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
        "401":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
        "404":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
  /airdrops/{airdropId}/set-label:
    post:
      operationId: setAirdropLabel
      summary: Set an airdrop label
      tags:
        - Airdrops
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - label
              properties:
                label:
                  type: string
                  maxLength: 30
      parameters:
        - schema:
            type: string
          in: path
          name: airdropId
          required: true
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                properties:
                  success:
                    type: boolean
        "400":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
        "401":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
        "404":
          description: Default Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/def-0"
  /health:
    get:
      operationId: getHealth
      summary: Check service health
      tags:
        - Health
      responses:
        "200":
          description: Default Response
          content:
            application/json:
              schema:
                enum:
                  - ok
servers:
  - url: http://localhost:3000
    description: Development server
  - url: https://blastsolace.prasko.io
    description: Production server
tags:
  - name: Auth
    description: Wallet authentication and token refresh.
  - name: Airdrops
    description: Create, manage, and process airdrops.
  - name: Health
    description: Service health.