Stripe Balance API — Balance

naftiko: 1.0.0-alpha2
info:
  label: Stripe Balance API — Balance
  description: 'Stripe Balance API — Balance. 3 operations. Lead operation: Balance. Self-contained Naftiko capability covering
    one Stripe business surface.'
  tags:
  - Stripe
  - Balance
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    STRIPE_API_KEY: STRIPE_API_KEY
capability:
  consumes:
  - type: http
    namespace: balance-balance
    baseUri: https://api.stripe.com
    description: Stripe Balance API — Balance business capability. Self-contained, no shared references.
    resources:
    - name: v1-balance
      path: /v1/balance
      operations:
      - name: getbalance
        method: GET
        description: <p>Retrieves the current account balance, based on the authentication that was used to make the request.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: expand
          in: query
          type: array
          description: Specifies which fields in the response should be expanded.
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-balance-history
      path: /v1/balance/history
      operations:
      - name: getbalancehistory
        method: GET
        description: <p>Returns a list of transactions that have contributed to the Stripe account balance (e.g., charges,
          transfers, and so forth). The transactions are returned in sorted order, with the most recent transactions appearing
          first.</p>
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: created
          in: query
          type: string
        - name: currency
          in: query
          type: string
          description: Only return transactions in a certain currency. Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html),
            in lowercase. Must be a [sup
        - name: ending_before
          in: query
          type: string
          description: A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list.
            For instance, if you make a list request and receive 100 ob
        - name: expand
          in: query
          type: array
          description: Specifies which fields in the response should be expanded.
        - name: limit
          in: query
          type: integer
          description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default
            is 10.
        - name: payout
          in: query
          type: string
          description: For automatic Stripe payouts only, only returns transactions that were paid out on the specified payout
            ID.
        - name: source
          in: query
          type: string
          description: Only returns the original transaction.
        - name: starting_after
          in: query
          type: string
          description: A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list.
            For instance, if you make a list request and receive 100 o
        - name: type
          in: query
          type: string
          description: 'Only returns transactions of the given type. One of: `adjustment`, `advance`, `advance_funding`, `anticipation_repayment`,
            `application_fee`, `application_fee_r'
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-balance-history-id
      path: /v1/balance/history/{id}
      operations:
      - name: getbalancehistoryid
        method: GET
        description: <p>Retrieves the balance transaction with the given ID.</p>
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: expand
          in: query
          type: array
          description: Specifies which fields in the response should be expanded.
        - name: id
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    authentication:
      type: bearer
      token: '{{env.STRIPE_API_KEY}}'
  exposes:
  - type: rest
    namespace: balance-balance-rest
    port: 8080
    description: REST adapter for Stripe Balance API — Balance. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/v1/balance
      name: v1-balance
      description: REST surface for v1-balance.
      operations:
      - method: GET
        name: getbalance
        description: <p>Retrieves the current account balance, based on the authentication that was used to make the request.
        call: balance-balance.getbalance
        with:
          expand: rest.expand
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/balance/history
      name: v1-balance-history
      description: REST surface for v1-balance-history.
      operations:
      - method: GET
        name: getbalancehistory
        description: <p>Returns a list of transactions that have contributed to the Stripe account balance (e.g., charges,
          transfers, and so forth). The transactions are returned in sorted order, with the most recent transactions appearing
          first.</p>
        call: balance-balance.getbalancehistory
        with:
          created: rest.created
          currency: rest.currency
          ending_before: rest.ending_before
          expand: rest.expand
          limit: rest.limit
          payout: rest.payout
          source: rest.source
          starting_after: rest.starting_after
          type: rest.type
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/balance/history/{id}
      name: v1-balance-history-id
      description: REST surface for v1-balance-history-id.
      operations:
      - method: GET
        name: getbalancehistoryid
        description: <p>Retrieves the balance transaction with the given ID.</p>
        call: balance-balance.getbalancehistoryid
        with:
          expand: rest.expand
          id: rest.id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: balance-balance-mcp
    port: 9090
    transport: http
    description: MCP adapter for Stripe Balance API — Balance. One tool per consumed operation, routed inline through this
      capability's consumes block.
    tools:
    - name: p-retrieves-current-account-balance-based
      description: <p>Retrieves the current account balance, based on the authentication that was used to make the request.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: balance-balance.getbalance
      with:
        expand: tools.expand
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: p-returns-list-transactions-that-have
      description: <p>Returns a list of transactions that have contributed to the Stripe account balance (e.g., charges, transfers,
        and so forth). The transactions are returned in sorted order, with the most recent transactions appearing first.</p>
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: balance-balance.getbalancehistory
      with:
        created: tools.created
        currency: tools.currency
        ending_before: tools.ending_before
        expand: tools.expand
        limit: tools.limit
        payout: tools.payout
        source: tools.source
        starting_after: tools.starting_after
        type: tools.type
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: p-retrieves-balance-transaction-given-id
      description: <p>Retrieves the balance transaction with the given ID.</p>
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: balance-balance.getbalancehistoryid
      with:
        expand: tools.expand
        id: tools.id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.