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

# Get recorded activity totals

> Read Stableyard's accounting totals for a UPA's recorded activity.

Returns Stableyard's accounting projection of recorded account activity and current Vault-payment reservations. These values are not spendable wallet, escrow or Vault custody balances, and must not be used to authorize spend. Query the relevant wallet, escrow or Vault source for actual custody.

See [Transactions](/payments/transactions).


## OpenAPI

````yaml openapi.json GET /v2/accounts/{accountId}/balances
openapi: 3.1.0
info:
  title: Stableyard Partner API
  version: 2.0.0-staging
  x-stableyard-api-version: '2026-09-09'
  x-stableyard-supported-api-versions:
    - '2026-09-09'
  summary: Backend API for UPAs, Payments, activity, and optional financial products.
  description: >

    Use this API from a trusted partner backend with an app ID and app secret.


    ## Recommended integration


    1. Call `GET /v2/partners/config` to verify credentials and discover enabled
    capabilities.

    2. Create a UPA only when your product needs a persistent Stableyard
    account.

    3. Create a receive or send Payment with `POST /v2/payments`.

    4. Redirect a payer to the returned `paymentUrl` or pass the Payment
    credentials to an official Stableyard interface SDK.

    5. Process signed webhooks and fetch the Payment by ID for reconciliation.


    Checkout execution and account-bound browser endpoints are intentionally
    documented in the separate Interfaces & SDKs reference. Console endpoints
    are dashboard implementation details and are not part of the partner
    integration contract.
  x-stableyard-documentation-surface: partner
servers:
  - url: https://prod-api.stableyard.fi
    description: Production
  - url: https://staging-api-v2.stableyard.fi
    description: Staging
  - url: http://localhost:3001
    description: Local
security: []
tags:
  - name: Authentication
    x-displayName: API authentication
    description: Verify your app ID and app secret before calling UPA APIs.
  - name: Accounts
    x-displayName: UPA Accounts
    description: Create Universal Payment Accounts and manage account settings.
  - name: Deposit Addresses
    description: Create reusable receive addresses and verify inbound deposits.
  - name: Identity & KYC
    description: >-
      Verify the UPA email and run provider-neutral identity verification.
      Managed vaults and fiat payment rails use this same verified UPA identity.
  - name: Vaults
    description: >-
      Create Safe/Zodiac controlled stablecoin vaults and manage policy updates
      for accounts.
  - name: Payments
    description: >-
      Create escrow-first payments, issue partner-authenticated send
      instructions or executions, power public checkout, and reconcile
      collection through final account settlement.
  - name: Balances & Transactions
    description: >-
      Read Stableyard-posted financial activity. Balances are ledger projections
      of activity Stableyard processed; they are not live balances of externally
      controlled wallets.
paths:
  /v2/accounts/{accountId}/balances:
    get:
      tags:
        - Balances & Transactions
      summary: Get recorded activity totals
      description: >-
        Return Stableyard's accounting projection for recorded account activity
        and current Vault-payment reservations. These values are not spendable
        wallet, escrow, or Vault custody balances.
      operationId: getAccountBalancesByAccountId
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: string
            example: acct_123
          description: Canonical account id returned by the Accounts API.
        - name: Stableyard-Version
          in: header
          required: false
          schema:
            type: string
            enum:
              - '2026-09-09'
          description: >-
            Optional contract-version assertion. Omit it to use the app
            environment's pinned version. A different supported version is
            accepted only after that environment is explicitly migrated.
      responses:
        '200':
          description: Balances
          headers:
            Stableyard-Version:
              description: >-
                Effective date-based Stableyard API contract version for this
                response.
              schema:
                type: string
                enum:
                  - '2026-09-09'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancesResponse'
              examples:
                example:
                  summary: Get recorded activity totals 200 response
                  value:
                    accountId: acct_123
                    balanceType: recorded_activity_projection
                    custodyScope: not_a_custody_balance
                    activityTotals:
                      - asset:
                          chainId: 42161
                          tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
                          symbol: USDC
                          decimals: 6
                          kind: token
                        netRecordedFlowAtomic: '-600000'
                        reservedForVaultPaymentsAtomic: '0'
                        source: ledger
                        observedAt: '2026-08-28T10:00:00.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '424':
          $ref: '#/components/responses/FailedDependency'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - partnerBasicAuth: []
components:
  schemas:
    BalancesResponse:
      type: object
      required:
        - accountId
        - balanceType
        - custodyScope
        - activityTotals
      properties:
        accountId:
          type: string
          example: acct_123
        balanceType:
          type: string
          enum:
            - recorded_activity_projection
          description: >-
            An accounting projection from Stableyard-posted events, not a live
            custody balance.
        custodyScope:
          type: string
          enum:
            - not_a_custody_balance
          description: >-
            The response must not be used to authorize spend. Query the relevant
            wallet, escrow, or Vault source for actual custody.
        activityTotals:
          type: array
          items:
            type: object
            required:
              - asset
              - netRecordedFlowAtomic
              - reservedForVaultPaymentsAtomic
              - source
              - observedAt
            properties:
              asset:
                $ref: '#/components/schemas/Asset'
              netRecordedFlowAtomic:
                type: string
                pattern: ^-?[0-9]+$
                example: '-600000'
                description: >-
                  Signed cumulative net amount reflected by Stableyard-posted
                  accounting events. It may be negative when an externally
                  funded wallet or Vault sends value before Stableyard records a
                  corresponding inflow, and may remain positive after funds are
                  swept to an external settlement wallet.
              reservedForVaultPaymentsAtomic:
                type: string
                example: '0'
                description: >-
                  Amount currently reserved or submitted for authorized Vault
                  payments. This is reservation context, not a deduction from a
                  spendable balance.
              source:
                type: string
                example: ledger
              observedAt:
                type: string
                format: date-time
                description: >-
                  Time the recorded activity projection last changed. Repeated
                  synthetic zero totals retain their original timestamp.
    Asset:
      type: object
      required:
        - chainId
        - tokenAddress
        - symbol
        - decimals
      properties:
        chainId:
          type: integer
          enum:
            - 42161
            - 1
            - 8453
            - 137
            - 56
            - 43114
            - 4663
            - 4217
            - 10103
            - 10002
            - 728126428
            - 10001
          description: >-
            Supported deposit chain IDs: Arbitrum=42161, Ethereum=1, Base=8453,
            Polygon=137, BNB Smart Chain=56, Avalanche=43114, Robinhood
            Chain=4663, Tempo=4217, Solana=10103, Movement=10002,
            Tron=728126428, Bitcoin=10001.
        tokenAddress:
          type: string
          description: >-
            Contract/mint address for tokens, the EVM zero address for native
            EVM assets, native for BTC, or the Solana System Program address for
            SOL.
          example: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
        symbol:
          type: string
          enum:
            - USDC
            - USDT
            - THBT
            - JPYC
            - USDG
            - BTC
            - ETH
            - POL
            - BNB
            - SOL
        decimals:
          type: integer
          enum:
            - 6
            - 8
            - 9
            - 18
        kind:
          type: string
          enum:
            - token
            - native
          description: >-
            Present on deposit-address supportedAssets entries to distinguish
            contract tokens from native gas assets.
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
          properties:
            code:
              type: string
              minLength: 1
              maxLength: 128
              example: bad_request
            message:
              type: string
              minLength: 1
              maxLength: 1000
              example: The request is invalid
            details: {}
  responses:
    BadRequest:
      description: Bad request
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: BadRequest response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
    Unauthorized:
      description: Unauthorized
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: Unauthorized response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
    Forbidden:
      description: The app secret does not include the required scope
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: Forbidden response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
    NotFound:
      description: Not found
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: NotFound response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
    Conflict:
      description: Conflict
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: Conflict response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
    FailedDependency:
      description: Required chain, network, or provider configuration is missing
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: FailedDependency response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
    TooManyRequests:
      description: >-
        Rate limit, payment-option limit, selection cooldown, or temporary abuse
        block
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
        Retry-After:
          description: Seconds until the caller should retry.
          schema:
            type: integer
            minimum: 1
        RateLimit-Limit:
          description: Quota for the most constrained policy.
          schema:
            type: integer
            minimum: 1
        RateLimit-Remaining:
          description: Requests remaining in that policy window.
          schema:
            type: integer
            minimum: 0
        RateLimit-Reset:
          description: Seconds until that policy window resets.
          schema:
            type: integer
            minimum: 0
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: TooManyRequests response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
  securitySchemes:
    partnerBasicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic auth. Username is the Stableyard app ID. Password is the app
        secret. The optional Stableyard-Version request header must match the
        environment pin.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.