openapi: 3.0.0
info:
  title: lit-api-server Account Management Billing API
  description: Lit Express Node API Server
  version: 0.1.0
servers:
- url: /core/v1/
  description: Lit Protocol Express API (Core v1)
tags:
- name: Billing
paths:
  /billing/stripe_config:
    get:
      tags:
      - Billing
      description: GET /billing/stripe_config — returns the Stripe publishable key. No auth required; the publishable key is safe to expose.
      operationId: billing_stripe_config
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/StripeConfigResponse'
                - $ref: '#/components/schemas/ErrMessage'
  /billing/balance:
    get:
      tags:
      - Billing
      description: GET /billing/balance — returns the current credit balance for the authenticated user.
      operationId: billing_balance
      parameters:
      - name: X-Api-Key
        in: header
        description: 'API-mode auth: account or usage API key (alternatively `Authorization: Bearer <key>`). OR — for ChainSecured callers — omit X-Api-Key entirely and send `X-Wallet-Auth: <base64(JSON{typed_data, signature})>` where `typed_data` is EIP-712 with `primaryType: "BillingAuth"`. The signature proves wallet possession; the typed data must include the connected wallet address and an issuedAt timestamp within ±5 minutes.'
        schema:
          type: string
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/BillingBalanceResponse'
                - $ref: '#/components/schemas/ErrMessage'
  /billing/create_payment_intent:
    post:
      tags:
      - Billing
      description: POST /billing/create_payment_intent — creates a Stripe PaymentIntent and returns the client_secret for use with Stripe.js `confirmCardPayment`.
      operationId: billing_create_payment_intent
      parameters:
      - name: X-Api-Key
        in: header
        description: 'API-mode auth: account or usage API key (alternatively `Authorization: Bearer <key>`). OR — for ChainSecured callers — omit X-Api-Key entirely and send `X-Wallet-Auth: <base64(JSON{typed_data, signature})>` where `typed_data` is EIP-712 with `primaryType: "BillingAuth"`. The signature proves wallet possession; the typed data must include the connected wallet address and an issuedAt timestamp within ±5 minutes.'
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentIntentRequest'
        required: true
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/CreatePaymentIntentResponse'
                - $ref: '#/components/schemas/ErrMessage'
  /billing/confirm_payment:
    post:
      tags:
      - Billing
      description: POST /billing/confirm_payment — verifies a succeeded PaymentIntent and credits the account.
      operationId: billing_confirm_payment
      parameters:
      - name: X-Api-Key
        in: header
        description: 'API-mode auth: account or usage API key (alternatively `Authorization: Bearer <key>`). OR — for ChainSecured callers — omit X-Api-Key entirely and send `X-Wallet-Auth: <base64(JSON{typed_data, signature})>` where `typed_data` is EIP-712 with `primaryType: "BillingAuth"`. The signature proves wallet possession; the typed data must include the connected wallet address and an issuedAt timestamp within ±5 minutes.'
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmPaymentRequest'
        required: true
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/AccountOpResponse'
                - $ref: '#/components/schemas/ErrMessage'
components:
  schemas:
    AccountOpResponse:
      description: Response for account config operations (add_pkp_to_group, remove_pkp_from_group, add_usage_api_key, remove_usage_api_key).
      type: object
      required:
      - success
      properties:
        success:
          type: boolean
    ErrMessage:
      type: string
    CreatePaymentIntentResponse:
      description: POST /billing/create_payment_intent — client secret for Stripe.js confirmCardPayment.
      type: object
      required:
      - client_secret
      - payment_intent_id
      properties:
        client_secret:
          type: string
        payment_intent_id:
          type: string
    StripeConfigResponse:
      description: GET /billing/stripe_config — returns the Stripe publishable key for Stripe.js.
      type: object
      required:
      - publishable_key
      properties:
        publishable_key:
          type: string
    BillingBalanceResponse:
      description: GET /billing/balance — current credit balance for the authenticated API key.
      type: object
      required:
      - balance_cents
      - balance_display
      properties:
        balance_cents:
          description: Balance in cents.  Negative means credits are available; zero means exhausted.
          type: integer
          format: int64
        balance_display:
          description: Human-readable, e.g. "$5.00 credit".
          type: string
    ConfirmPaymentRequest:
      description: POST /billing/confirm_payment
      type: object
      required:
      - payment_intent_id
      properties:
        payment_intent_id:
          type: string
    CreatePaymentIntentRequest:
      description: POST /billing/create_payment_intent
      type: object
      required:
      - amount_cents
      properties:
        amount_cents:
          description: Amount to charge in US cents (minimum 500 = $5.00).
          type: integer
          format: int64