Stripe Balance API — Balance Transactions

naftiko: 1.0.0-alpha2
info:
  label: Stripe Balance API — Balance Transactions
  description: 'Stripe Balance API — Balance Transactions. 2 operations. Lead operation: Balance Transactions. Self-contained
    Naftiko capability covering one Stripe business surface.'
  tags:
  - Stripe
  - Balance Transactions
  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-transactions
    baseUri: https://api.stripe.com
    description: Stripe Balance API — Balance Transactions business capability. Self-contained, no shared references.
    resources:
    - name: v1-balance_transactions
      path: /v1/balance_transactions
      operations:
      - name: getbalancetransactions
        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_transactions-id
      path: /v1/balance_transactions/{id}
      operations:
      - name: getbalancetransactionsid
        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-transactions-rest
    port: 8080
    description: REST adapter for Stripe Balance API — Balance Transactions. One Spectral-compliant resource per consumed
      operation, prefixed with /v1.
    resources:
    - path: /v1/v1/balance-transactions
      name: v1-balance-transactions
      description: REST surface for v1-balance_transactions.
      operations:
      - method: GET
        name: getbalancetransactions
        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-transactions.getbalancetransactions
        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-transactions/{id}
      name: v1-balance-transactions-id
      description: REST surface for v1-balance_transactions-id.
      operations:
      - method: GET
        name: getbalancetransactionsid
        description: <p>Retrieves the balance transaction with the given ID.</p>
        call: balance-balance-transactions.getbalancetransactionsid
        with:
          expand: rest.expand
          id: rest.id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: balance-balance-transactions-mcp
    port: 9090
    transport: http
    description: MCP adapter for Stripe Balance API — Balance Transactions. One tool per consumed operation, routed inline
      through this capability's consumes block.
    tools:
    - 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-transactions.getbalancetransactions
      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-transactions.getbalancetransactionsid
      with:
        expand: tools.expand
        id: tools.id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.