AgentPMT Credits API

openapi: 3.2.0
info:
  title: Fast Credits API
  version: 0.1.0
tags:
- name: Credits
paths:
  /credits/balance:
    get:
      summary: Get My Credit Balance
      description: Check credit balance.
      operationId: get_my_credit_balance_credits_balance_get
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
          title: Authorization
      responses:
        '200':
          description: Current available credit balance and next expiration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerCreditBalanceResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Credits
  /credits/history:
    get:
      summary: Get My Credit History
      description: View credit transaction history.
      operationId: get_my_credit_history_credits_history_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          default: 50
          title: Limit
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
          title: Authorization
      responses:
        '200':
          description: Credit grants and transaction audit trail for the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerCreditHistoryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Credits
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    CustomerCreditTransaction:
      properties:
        _id:
          type: string
          title: Id
          description: Transaction document ID (serialized as `_id` in the response).
        user_id:
          type: string
          title: User Id
          description: Owning user ID.
        transaction_type:
          type: string
          title: Transaction Type
          description: One of `grant`, `expiration`, `revocation`, or `purchase` (tool deduction).
        amount_credits:
          type: integer
          title: Amount Credits
          description: Credits applied by this transaction. Negative for debits (expiration/revocation/purchase), positive for grants.
        amount_usd:
          type: number
          title: Amount Usd
          description: USD equivalent of the transaction.
        balance_after_credits:
          type: integer
          title: Balance After Credits
          description: Balance in credits after applying the transaction.
        balance_after_usd:
          type: number
          title: Balance After Usd
          description: Balance in USD after applying the transaction.
        date_created:
          type: string
          title: Date Created
          description: ISO-8601 timestamp of the transaction.
      additionalProperties: true
      type: object
      required:
      - _id
      - user_id
      - transaction_type
      - amount_credits
      - amount_usd
      - balance_after_credits
      - balance_after_usd
      - date_created
      title: CustomerCreditTransaction
    CustomerCreditHistoryData:
      properties:
        grants:
          items:
            $ref: '#/components/schemas/CustomerCreditGrant'
          type: array
          title: Grants
          description: Credit grants owned by the caller, newest first.
        transactions:
          items:
            $ref: '#/components/schemas/CustomerCreditTransaction'
          type: array
          title: Transactions
          description: Transaction audit trail, newest first.
      type: object
      required:
      - grants
      - transactions
      title: CustomerCreditHistoryData
    CustomerCreditGrant:
      properties:
        _id:
          type: string
          title: Id
          description: Grant document ID (serialized as `_id` in the response).
        user_id:
          type: string
          title: User Id
          description: Owning user ID.
        amount_credits:
          type: integer
          title: Amount Credits
          description: Credits originally granted (positive integer).
        amount_usd:
          type: number
          title: Amount Usd
          description: USD equivalent of the grant at issuance.
        remaining_credits:
          type: integer
          title: Remaining Credits
          description: Credits still available from this grant.
        credit_type:
          type: string
          title: Credit Type
          description: Grant source classification (for example `admin_grant`, `referral_signup`, `x402_purchase`).
        source_metadata:
          additionalProperties: true
          type: object
          title: Source Metadata
          description: Free-form metadata supplied when the grant was created.
        date_created:
          type: string
          title: Date Created
          description: ISO-8601 timestamp the grant was issued.
        pooled_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Pooled At
          description: ISO-8601 timestamp the grant was added to the pool.
        expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Expires At
          description: ISO-8601 timestamp the grant expires.
      additionalProperties: true
      type: object
      required:
      - _id
      - user_id
      - amount_credits
      - amount_usd
      - remaining_credits
      - credit_type
      - date_created
      title: CustomerCreditGrant
    CustomerCreditHistoryResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: '`true` when the history lookup succeeded.'
          default: true
        message:
          type: string
          title: Message
          description: Human-readable status message.
          default: Credit history retrieved successfully
        data:
          $ref: '#/components/schemas/CustomerCreditHistoryData'
      type: object
      required:
      - data
      title: CustomerCreditHistoryResponse
    CustomerCreditBalanceData:
      properties:
        balance:
          type: integer
          title: Balance
          description: Current available credit balance, in whole credits (100 credits = $1).
          examples:
          - 1250
        expiration:
          anyOf:
          - type: string
          - type: 'null'
          title: Expiration
          description: ISO-8601 timestamp of the next credit expiration, or null when the balance is zero.
          examples:
          - '2026-05-01T00:00:00+00:00'
        expires_in_days:
          anyOf:
          - type: integer
          - type: 'null'
          title: Expires In Days
          description: Whole days until the next expiration, or null when the balance is zero.
          examples:
          - 14
      type: object
      required:
      - balance
      title: CustomerCreditBalanceData
    CustomerCreditBalanceResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: '`true` when the balance lookup succeeded.'
          default: true
        message:
          type: string
          title: Message
          description: Human-readable status message.
          default: Credit balance retrieved successfully
        data:
          $ref: '#/components/schemas/CustomerCreditBalanceData'
      type: object
      required:
      - data
      title: CustomerCreditBalanceResponse
  securitySchemes:
    HTTPBasic:
      type: http
      scheme: basic