openapi: 3.0.0
info:
  title: Monero Blaster API
  description: |
    Multi-tenant Monero payment orchestration API.
    Send XMR to 1–16 recipients in a single on-chain transaction,
    with automatic worker rotation and master-wallet refill.

    **Base URL (tenant endpoints):**
    `https://blaster.libremonero.com/tenants/{tenant_id}/api/orchestrator/`

    **Authentication (POST endpoints only):**
    Include `X-Blaster-Key: <your_api_key>` header.
    GET endpoints (health, version, balance) are public.

    **Amounts:** Always XMR as a float (e.g. `0.001` = 1 mXMR). Never atomic units.
  version: "0.9.1"
  contact:
    url: https://blaster.libremonero.com/docs

servers:
  - url: https://blaster.libremonero.com
    description: Production

components:
  securitySchemes:
    BlasterKey:
      type: apiKey
      in: header
      name: X-Blaster-Key
      description: API key obtained from your tenant Admin panel → Settings → API Key

  schemas:
    ServiceStatus:
      type: object
      properties:
        state:
          type: string
          enum: [ready, no_funds, paused]
        available:
          type: boolean
        total_workers:
          type: integer
        available_workers:
          type: integer
        max_amount_per_tx:
          type: number
          format: float
        message:
          type: string
        retry_in_seconds:
          type: integer
          nullable: true
        retry_in_minutes:
          type: number
          nullable: true

    TenantVersion:
      type: object
      properties:
        blaster_version_created:
          type: string
          example: "0.9.0"
        blaster_version_upgraded:
          type: string
          nullable: true
          example: "0.9.1"
        tenant_created_at:
          type: string
          format: date
          example: "2026-04-24"

    Worker:
      type: object
      properties:
        id:
          type: integer
        address:
          type: string
        available:
          type: boolean
        balance:
          type: number
          format: float
          description: Unlocked balance in XMR
        locked_balance:
          type: number
          format: float
        total_balance:
          type: number
          format: float
        rpc_online:
          type: boolean
        daemon_connected:
          type: boolean
        daemon_synced:
          type: boolean
        status:
          type: string
          enum: [ready, critical, locked]
        blocks_to_unlock:
          type: integer
        seconds_to_unlock:
          type: integer

    Destination:
      type: object
      required: [address, amount_xmr]
      properties:
        address:
          type: string
          description: Monero destination address (starts with 4 or 8, 95–106 chars)
          example: "49ggnf2K23Di5MxrVg3Edw..."
        amount_xmr:
          type: number
          format: float
          description: Amount in XMR (float, NOT atomic units)
          example: 0.001
        label:
          type: string
          description: Optional human-readable label (logged, not on-chain)
          example: "Seller payment"
        merchant_id:
          type: string
          description: Optional party identifier
          example: "merchant_001"

    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
        error_code:
          type: string
        message:
          type: string
        retry_in_seconds:
          type: integer
          nullable: true

paths:
  # ── Public platform endpoints (no auth) ──────────────────────────────
  /health:
    get:
      tags: [Platform]
      summary: Platform health (public)
      description: |
        Global health check for the Blaster platform. No auth required.
        Useful for uptime monitors and status pages.
      responses:
        "200":
          description: Platform is up
          content:
            application/json:
              example:
                status: ok
                service: monero-blaster
                version: "0.9.1"
                build_date: "2026-04-29"

  /version:
    get:
      tags: [Platform]
      summary: Platform version (public)
      description: Returns the running Blaster version. No auth required.
      responses:
        "200":
          description: Version info
          content:
            application/json:
              example:
                service: monero-blaster
                version: "0.9.1"
                build_date: "2026-04-29"

  # ── Tenant orchestrator endpoints ─────────────────────────────────────
  /tenants/{tenant_id}/api/orchestrator/health:
    get:
      tags: [Tenant — System]
      summary: Tenant service health
      description: |
        Returns tenant service availability, Blaster version, and tenant creation
        version metadata. No authentication required.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema: {type: string}
          example: MY_TENANT
      responses:
        "200":
          description: Health status
          content:
            application/json:
              example:
                status: ok
                version: "0.9.1"
                build_date: "2026-04-29"
                tenant_id: MY_TENANT
                tenant_version:
                  blaster_version_created: "0.9.0"
                  tenant_created_at: "2026-04-24"
                service:
                  state: ready
                  available: true
                  total_workers: 2
                  available_workers: 2
                  max_amount_per_tx: 0.05
                  message: Ready
                  retry_in_seconds: null

  /tenants/{tenant_id}/api/orchestrator/version:
    get:
      tags: [Tenant — System]
      summary: Tenant orchestrator version
      description: Returns the Blaster version running for this tenant's orchestrator.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema: {type: string}
      responses:
        "200":
          description: Version info
          content:
            application/json:
              example:
                version: "0.9.1"
                build_date: "2026-04-29"
                component: orchestrator
                tenant_id: MY_TENANT

  /tenants/{tenant_id}/api/orchestrator/workers/status:
    get:
      tags: [Tenant — System]
      summary: Workers status & balances
      description: |
        Returns detailed status and balance for each worker wallet.
        No authentication required.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema: {type: string}
      responses:
        "200":
          description: Workers info
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: {type: boolean}
                  wallet_type: {type: string}
                  service:
                    $ref: '#/components/schemas/ServiceStatus'
                  workers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Worker'

  /tenants/{tenant_id}/api/orchestrator/master/balance:
    get:
      tags: [Tenant — Wallet]
      summary: Master wallet address & balance
      description: |
        Returns the master wallet XMR address and current balances.
        **Fund this address to load your tenant.**
        No authentication required.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema: {type: string}
      responses:
        "200":
          description: Master wallet info
          content:
            application/json:
              example:
                success: true
                address: "47CtgrDGM2tKmDZH..."
                balance: 0.0
                unlocked_balance: 0.0

  /tenants/{tenant_id}/api/orchestrator/transfer:
    post:
      tags: [Tenant — Transactions]
      summary: Send XMR to one recipient
      description: |
        Sends XMR from an available worker wallet to a single Monero address.
        The orchestrator automatically selects the best available worker (round-robin).

        **Authentication required:** `X-Blaster-Key` header.
      security:
        - BlasterKey: []
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema: {type: string}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [address, amount]
              properties:
                address:
                  type: string
                  description: Monero destination address
                  example: "49ggnf2K23Di5MxrVg3Edw..."
                amount:
                  type: number
                  format: float
                  description: Amount in XMR (float, NOT atomic units)
                  example: 0.001
            example:
              address: "49ggnf2K23Di5MxrVg3Edw..."
              amount: 0.001
      responses:
        "200":
          description: Transaction submitted successfully
          content:
            application/json:
              example:
                success: true
                tx_hash: "3577159b8d51e28a..."
                fee: 0.000030720
                amount: 0.001
                worker_id: 1
        "401":
          description: Missing or invalid API key
          content:
            application/json:
              example:
                success: false
                error: Unauthorized
        "503":
          description: No worker available (funds locked or insufficient balance)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                error_code: NO_WORKER_AVAILABLE
                retry_in_seconds: 708

  /tenants/{tenant_id}/api/orchestrator/send_split:
    post:
      tags: [Tenant — Transactions]
      summary: Split payment (1–16 recipients)
      description: |
        Sends XMR from one wallet to **multiple addresses in a single on-chain transaction**.
        Ideal for marketplaces (seller + platform fee), escrow, affiliate commissions.

        - Up to **16 destinations** per call
        - Automatically uses best available worker; falls back to master
        - All amounts in XMR float — never atomic units

        **Authentication required:** `X-Blaster-Key` header.
      security:
        - BlasterKey: []
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema: {type: string}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [destinations]
              properties:
                destinations:
                  type: array
                  minItems: 1
                  maxItems: 16
                  items:
                    $ref: '#/components/schemas/Destination'
                priority:
                  type: integer
                  description: "Fee priority: 1=default, 2=elevated, 3=priority, 4=custom"
                  default: 1
                  minimum: 1
                  maximum: 4
            example:
              destinations:
                - address: "49ggnf2K23Di5MxrVg3E..."
                  amount_xmr: 0.001
                  label: Seller payment
                  merchant_id: seller_001
                - address: "44iWqQXTVYndytaJewAk..."
                  amount_xmr: 0.0002
                  label: Platform fee
                  merchant_id: platform
              priority: 1
      responses:
        "200":
          description: Split transaction submitted
          content:
            application/json:
              example:
                success: true
                tx_hash: "6a77c3e8969bef29..."
                fee: 0.0000307
                worker_id: 1
                destinations_count: 2
        "401":
          description: Missing or invalid API key
        "503":
          description: Insufficient funds across all wallets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
