> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kirafin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List deposits (all virtual accounts)

> List inbound deposits across **all** of your virtual accounts (a client-level feed, no virtual-account id in the path), newest first. Supports pagination and filtering.

**Query parameters**

-   `page` — 1-indexed page number.
-   `limit` — page size (`1`–`100`).
-   `status` — filter by `PENDING`, `COMPLETED`, `FAILED`, `REFUNDED`, `KYT_PENDING`, or `KYT_REJECTED`.
-   `virtual_account_id` — restrict the feed to one virtual account.
-   `from_date` / `to_date` — inclusive bounds on the deposit's received timestamp. Accept an ISO 8601 date-time or a date-only `YYYY-MM-DD` string (a date-only `to_date` is treated as end-of-day).

The response is an object with a `deposits[]` array plus page-based pagination (`total`, `page`, `limit`, `total_pages`). Each deposit has the same shape as `GET /v1/virtual-accounts/{virtual_account_id}/deposits`. All money values are decimal strings.

**Example response (200):**

```json
{
  "deposits": [
    {
      "id": "7f1e9c2a-3b4d-4e5f-8a90-112233445566",
      "virtual_account_id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": "1000.00",
      "currency": "USD",
      "status": "COMPLETED",
      "sender": {
        "name": "Acme Corp",
        "account_number": "****6789",
        "address": "123 Market St, San Francisco, CA"
      },
      "recipient": {
        "name": "Jane Q Doe",
        "company_name": "Doe Holdings LLC",
        "country": "US"
      },
      "payment_rail": "WIRE",
      "settlement_tx_hash": null,
      "source": {
        "name": "Acme Corp",
        "account_number": "****6789",
        "address": "123 Market St, San Francisco, CA",
        "payment_rail": "WIRE",
        "reference_number": "REF-998877",
        "imad": "20260625MMQFMP0100001",
        "omad": null,
        "trace_number": null
      },
      "fees": {
        "base_fees": {
          "fixed_fee": "2.50",
          "percentage_fee": "0.00",
          "fx_markup": "0.00"
        },
        "client_markup": {
          "fixed_fee": "1.00",
          "percentage_fee": "0.00",
          "fx_markup": "0.00"
        },
        "total_fees": "3.50"
      },
      "net_amount": "996.50",
      "net_currency": "USD",
      "created_at": "2026-06-24T18:05:32.000Z",
      "updated_at": "2026-06-24T18:07:10.000Z",
      "metadata": {
        "invoice_id": "INV-2026-0042"
      }
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 10,
  "total_pages": 5
}
```

{/* version-stamp:start — generated by scripts/stamp-versions.ts, do not edit */}

<Info>Stable since **2025-01-01** — unchanged in **2026-06-01**.</Info>

{/* version-stamp:end */}


## OpenAPI

````yaml /openapi/kira-api.2026-06-01.json get /v1/virtual-accounts/deposits
openapi: 3.1.0
info:
  title: Kira API
  version: '2026-06-01'
  description: >-
    REST API for users, KYC/KYB verification, virtual accounts, payouts,
    recipients, and webhooks. Every request requires an `x-api-key` header and a
    bearer access token (see Authentication). Pin your account to version
    `2026-04-14` before integrating.
  contact:
    name: Kira API Support
    email: support@kirafin.ai
servers:
  - url: https://api.balampay.com
    description: Production
  - url: https://api.balampay.com/sandbox
    description: Sandbox
security:
  - bearerAuth: []
    apiKeyAuth: []
tags:
  - name: Authentication
  - name: Versioning
  - name: Users
  - name: Virtual Accounts
  - name: Quotations
  - name: Payouts
  - name: Recipients
  - name: Reference
  - name: RFIs
paths:
  /v1/virtual-accounts/deposits:
    get:
      tags:
        - Virtual Accounts
      summary: List deposits (all virtual accounts)
      description: >-
        List inbound deposits across **all** of your virtual accounts (a
        client-level feed, no virtual-account id in the path), newest first.
        Supports pagination and filtering.


        **Query parameters**


        -   `page` — 1-indexed page number.

        -   `limit` — page size (`1`–`100`).

        -   `status` — filter by `PENDING`, `COMPLETED`, `FAILED`, `REFUNDED`,
        `KYT_PENDING`, or `KYT_REJECTED`.

        -   `virtual_account_id` — restrict the feed to one virtual account.

        -   `from_date` / `to_date` — inclusive bounds on the deposit's received
        timestamp. Accept an ISO 8601 date-time or a date-only `YYYY-MM-DD`
        string (a date-only `to_date` is treated as end-of-day).


        The response is an object with a `deposits[]` array plus page-based
        pagination (`total`, `page`, `limit`, `total_pages`). Each deposit has
        the same shape as `GET
        /v1/virtual-accounts/{virtual_account_id}/deposits`. All money values
        are decimal strings.


        **Example response (200):**


        ```json

        {
          "deposits": [
            {
              "id": "7f1e9c2a-3b4d-4e5f-8a90-112233445566",
              "virtual_account_id": "550e8400-e29b-41d4-a716-446655440000",
              "amount": "1000.00",
              "currency": "USD",
              "status": "COMPLETED",
              "sender": {
                "name": "Acme Corp",
                "account_number": "****6789",
                "address": "123 Market St, San Francisco, CA"
              },
              "recipient": {
                "name": "Jane Q Doe",
                "company_name": "Doe Holdings LLC",
                "country": "US"
              },
              "payment_rail": "WIRE",
              "settlement_tx_hash": null,
              "source": {
                "name": "Acme Corp",
                "account_number": "****6789",
                "address": "123 Market St, San Francisco, CA",
                "payment_rail": "WIRE",
                "reference_number": "REF-998877",
                "imad": "20260625MMQFMP0100001",
                "omad": null,
                "trace_number": null
              },
              "fees": {
                "base_fees": {
                  "fixed_fee": "2.50",
                  "percentage_fee": "0.00",
                  "fx_markup": "0.00"
                },
                "client_markup": {
                  "fixed_fee": "1.00",
                  "percentage_fee": "0.00",
                  "fx_markup": "0.00"
                },
                "total_fees": "3.50"
              },
              "net_amount": "996.50",
              "net_currency": "USD",
              "created_at": "2026-06-24T18:05:32.000Z",
              "updated_at": "2026-06-24T18:07:10.000Z",
              "metadata": {
                "invoice_id": "INV-2026-0042"
              }
            }
          ],
          "total": 42,
          "page": 1,
          "limit": 10,
          "total_pages": 5
        }

        ```
      operationId: get_v1-virtual-accounts-deposits
      parameters:
        - in: header
          name: X-Api-Version
          required: false
          description: >-
            Optional. The date-versioned API version to apply for this request
            (e.g. `2026-04-14`). When sent it always wins, even over your pinned
            account default. When omitted, the API uses your account's pinned
            version if set, otherwise a baseline default.
          schema:
            type: string
            example: '2026-06-01'
        - in: query
          name: page
          required: false
          description: 1-indexed page number.
          schema:
            type: integer
            minimum: 1
            default: 1
        - in: query
          name: limit
          required: false
          description: Page size (1-100).
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - in: query
          name: status
          required: false
          description: Filter by deposit status.
          schema:
            type: string
            enum:
              - PENDING
              - COMPLETED
              - FAILED
              - REFUNDED
              - KYT_PENDING
              - KYT_REJECTED
        - in: query
          name: virtual_account_id
          required: false
          description: Restrict the feed to one virtual account.
          schema:
            type: string
            format: uuid
        - in: query
          name: from_date
          required: false
          description: >-
            Inclusive lower bound on the deposit's received timestamp. ISO 8601
            date-time or a date-only `YYYY-MM-DD` string.
          schema:
            type: string
        - in: query
          name: to_date
          required: false
          description: >-
            Inclusive upper bound on the deposit's received timestamp. ISO 8601
            date-time or a date-only `YYYY-MM-DD` string (date-only is treated
            as end-of-day).
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                description: Page-based list envelope.
                properties:
                  deposits:
                    type: array
                    items:
                      $ref: '#/components/schemas/Deposit'
                  total:
                    type: integer
                    description: Total deposits matching the filters.
                  page:
                    type: integer
                  limit:
                    type: integer
                  total_pages:
                    type: integer
                required:
                  - deposits
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
          apiKeyAuth: []
components:
  schemas:
    Deposit:
      type: object
      description: >-
        An inbound deposit received by a virtual account, as returned by the
        deposit read endpoints. Money values are decimal strings. Prefer the
        unified `source` object (it carries rail-specific tracking ids such as
        `imad`/`omad` for wires and `trace_number` for ACH) over the legacy
        `sender`.
      properties:
        id:
          type: string
          format: uuid
          description: Deposit UUID.
        virtual_account_id:
          type: string
          format: uuid
          description: UUID of the virtual account that received this deposit.
        amount:
          type: string
          description: Gross deposit amount (decimal string).
        currency:
          type: string
          description: Deposit currency.
        status:
          type: string
          enum:
            - PENDING
            - COMPLETED
            - FAILED
            - REFUNDED
            - KYT_PENDING
            - KYT_REJECTED
          description: Deposit status (UPPERCASE).
        sender:
          type:
            - object
            - 'null'
          description: >-
            Legacy counterparty shape (name, account_number, address only).
            Prefer `source`.
          properties:
            name:
              type:
                - string
                - 'null'
            account_number:
              type:
                - string
                - 'null'
            address:
              type:
                - string
                - 'null'
        recipient:
          type:
            - object
            - 'null'
          description: Recipient (the VA owner) summary.
          properties:
            name:
              type:
                - string
                - 'null'
            company_name:
              type:
                - string
                - 'null'
            country:
              type:
                - string
                - 'null'
        payment_rail:
          type:
            - string
            - 'null'
          description: Legacy top-level rail; mirrored on `source.payment_rail`.
        settlement_tx_hash:
          type:
            - string
            - 'null'
          description: On-chain settlement transaction hash, when applicable.
        source:
          type:
            - object
            - 'null'
          description: >-
            Unified counterparty / wire-tracking shape. Rail-specific
            identifiers are present only when relevant: ACT wires populate
            `reference_number`; Fedwire wires populate `imad`/`omad`; ACH
            populates `trace_number`.
          properties:
            name:
              type:
                - string
                - 'null'
            account_number:
              type:
                - string
                - 'null'
            address:
              type:
                - string
                - 'null'
            payment_rail:
              type:
                - string
                - 'null'
              description: >-
                The rail the deposit arrived on. `"wire"` on every wire-rail
                deposit observed in sandbox; `null` when not yet resolved.
            reference_number:
              type:
                - string
                - 'null'
            imad:
              type:
                - string
                - 'null'
              description: >-
                IMAD (Input Message Accountability Data): the Fedwire
                inbound-wire tracking identifier. Format varies by originating
                bank and differs between sandbox and production, so do not rely
                on a fixed shape or length. `null` on non-wire deposits.
            omad:
              type:
                - string
                - 'null'
              description: >-
                OMAD (Output Message Accountability Data): the Fedwire
                outbound-wire tracking identifier. Format varies by originating
                bank and differs between sandbox and production, so do not rely
                on a fixed shape or length. `null` on non-wire deposits.
            trace_number:
              type:
                - string
                - 'null'
        fees:
          $ref: '#/components/schemas/DepositFees'
        net_amount:
          type: string
          description: Amount after fees (decimal string).
        net_currency:
          type: string
          description: Currency of `net_amount` (3-letter ISO code).
        created_at:
          type: string
          description: ISO 8601 timestamp.
        updated_at:
          type: string
          description: ISO 8601 timestamp.
        metadata:
          type: object
          description: >-
            Customer-attached metadata, snapshotted from the parent VA at
            deposit creation.
          additionalProperties: true
      required:
        - id
        - virtual_account_id
        - amount
        - currency
        - status
        - created_at
        - updated_at
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
        statusCode:
          type: number
        error:
          type: string
        timestamp:
          type: string
        path:
          type: string
        details: {}
      required:
        - message
    DepositFees:
      type: object
      description: >-
        Deposit fee breakdown. `total_fees` equals the per-component sum of
        `base_fees` + `client_markup`.
      properties:
        base_fees:
          $ref: '#/components/schemas/DepositFeeBreakdown'
        client_markup:
          $ref: '#/components/schemas/DepositFeeBreakdown'
        total_fees:
          type: string
          description: Sum of all fee components (decimal string).
      required:
        - base_fees
        - client_markup
        - total_fees
    DepositFeeBreakdown:
      type: object
      description: >-
        One leaf of the deposit fee breakdown. All values are decimal strings;
        `fx_markup` may be negative.
      properties:
        fixed_fee:
          type: string
          description: Fixed fee component (decimal string, >= 0).
        percentage_fee:
          type: string
          description: Percentage fee component as a dollar amount (decimal string, >= 0).
        fx_markup:
          type: string
          description: >-
            FX markup component as a dollar amount (decimal string; may be
            negative).
      required:
        - fixed_fee
        - percentage_fee
        - fx_markup
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Access token from `POST /auth` (the `data.access_token` value).
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key issued by Kira. Required on every request, including `/auth`.

````