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

# List organization balances

> Returns the balances of every wallet the organization holds: every Etherfuse token and supported stablecoin each wallet holds, with the value of each in the asset's own fiat currency and in USD. We list only the organization's own wallets, not the wallets of its customer organizations.

We store each wallet's balances and read the wallet from the chain at most once an hour. This call reads only the organization's most recently used wallets: the ones in its latest orders, then the ones added most recently, up to a limit. When we last read one of those more than an hour ago, this call starts a new read and returns the wallet with `status` `updating` and the balances we stored before. Call again a few seconds later for the new balances. Other wallets we last read more than an hour ago come back with `status` `stale`; read one of them with [Get payment account balances](/v2/api-reference/assets/get-payment-account-balances). An embedded wallet we have not created yet is left out.

Values use the current price and FX rate, so two calls seconds apart can differ for the same stored balance.



## OpenAPI

````yaml https://api.etherfuse.com/openapi-v2.json get /organization/{organizationId}/balances
openapi: 3.1.0
info:
  title: Etherfuse FX API
  description: >-
    Partner-facing ramp API, version 2: payment accounts, quotes, orders and
    webhooks.
  license:
    name: Proprietary
  version: 2.0.0
servers:
  - url: https://api.sand.etherfuse.com
    description: Sandbox
security:
  - ApiKeyAuth: []
tags:
  - name: Payment Accounts
    description: >-
      Register the bank accounts and wallets that money moves from and to, and
      read their readiness per rail.
  - name: Quotes
    description: Price a transfer between two registered payment accounts.
  - name: Orders
    description: Create orders from quotes and track them.
  - name: Webhook Subscriptions
    description: Subscribe to webhook events.
  - name: Webhook Events
    description: Payloads Etherfuse sends to your webhook subscriptions.
  - name: Sandbox
    description: Endpoints that work only in sandbox, for testing.
  - name: Assets
    description: The markets and tokens a quote can use, and the balances of a wallet.
  - name: Authentication
    description: >-
      Partner JWT authentication: exchange a JWT for an access token, or launch
      a user into the app.
  - name: KYC
    description: >-
      Submit a customer's verification data, documents and questionnaire
      answers, import a verification they already passed elsewhere, and check
      where their KYC stands.
  - name: KYB
    description: Check where a business organization's KYB stands.
  - name: Lookup
    description: >-
      Public reference data: exchange rates, stablebonds, bond costs, country
      codes.
  - name: Organizations
    description: >-
      Your organization, your default partner fee, and the customer
      organizations you create.
  - name: Members
    description: >-
      The people who belong to a customer business organization and complete its
      KYB.
  - name: Statements
    description: >-
      Monthly revenue share statements for closed months, as a list or as a CSV
      or PDF download.
paths:
  /organization/{organizationId}/balances:
    get:
      tags:
        - Assets
      summary: List organization balances
      description: >-
        Returns the balances of every wallet the organization holds: every
        Etherfuse token and supported stablecoin each wallet holds, with the
        value of each in the asset's own fiat currency and in USD. We list only
        the organization's own wallets, not the wallets of its customer
        organizations.


        We store each wallet's balances and read the wallet from the chain at
        most once an hour. This call reads only the organization's most recently
        used wallets: the ones in its latest orders, then the ones added most
        recently, up to a limit. When we last read one of those more than an
        hour ago, this call starts a new read and returns the wallet with
        `status` `updating` and the balances we stored before. Call again a few
        seconds later for the new balances. Other wallets we last read more than
        an hour ago come back with `status` `stale`; read one of them with [Get
        payment account
        balances](/v2/api-reference/assets/get-payment-account-balances). An
        embedded wallet we have not created yet is left out.


        Values use the current price and FX rate, so two calls seconds apart can
        differ for the same stored balance.
      operationId: v2ListOrganizationBalances
      parameters:
        - name: organizationId
          in: path
          description: >-
            The organization this call acts for: your API key's organization or
            one of its customer organizations. Any other id returns `404`
            `not-found`.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The organization's wallets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationBalances'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/OrganizationNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    OrganizationBalances:
      type: object
      required:
        - wallets
      properties:
        wallets:
          type: array
          items:
            $ref: '#/components/schemas/PaymentAccountBalances'
          description: One entry per wallet payment account.
    PaymentAccountBalances:
      type: object
      required:
        - paymentAccountId
        - chain
        - observedAt
        - updatedAt
        - status
        - balances
      properties:
        address:
          type: string
          description: The address we read. We leave it out for an embedded wallet.
        balances:
          type: array
          items:
            $ref: '#/components/schemas/WalletBalance'
          description: >-
            One entry per held asset. Empty when the wallet holds none, or when
            we haven't read

            it yet.
        chain:
          $ref: '#/components/schemas/Chain'
        observedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When we last read the wallet from the chain. Null until our first
            read finishes.
        paymentAccountId:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/WalletBalancesStatus'
        updatedAt:
          type: string
          format: date-time
          description: >-
            When the stored balances last changed, from a chain read or a
            completed order. Use

            it to keep the newer of two copies of a wallet's balances.
      example:
        address: 3XnhVzKqNTz2wpNjyhbCsSFvz4Y6VNSVaVNhFTNGmqxr
        balances:
          - amountInFiat: '1932.551274'
            amountInUsd: '105.214877'
            balance: '1500.123456'
            currency: mxn
            identifier: CETES7CKqqKQizuSN6iWQwmTeFRjbJR6Vw2XRKfEDR8f
            symbol: cetes
            tokenKind: bond
        chain: solana
        observedAt: '2026-10-07T12:00:00Z'
        paymentAccountId: c3d4e5f6-a7b8-9012-cdef-123456789012
        status: current
        updatedAt: '2026-10-07T12:20:00Z'
    Problem:
      type: object
      description: >-
        RFC 9457 problem details. Every v2 error uses this body with content
        type

        `application/problem+json`. `errors` is present only on
        `validation-error`. `required`

        and `missing` are present only on `registration-info-required`.
      required:
        - type
        - title
        - status
        - detail
        - instance
      properties:
        detail:
          type: string
          description: Human-readable explanation of this occurrence. Do not parse it.
          example: >-
            quote 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b has expired or does not
            exist
        errors:
          type: array
          items:
            $ref: '#/components/schemas/FieldViolation'
          description: Present on `validation-error`. One entry per invalid field.
        instance:
          type: string
          description: Unique identifier for this occurrence. Quote it to support.
          example: >-
            tag:etherfuse.com,2026-08-28:R2-10120/0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d
        missing:
          type: array
          items:
            type: string
          description: >-
            Present on `registration-info-required`. The required fields you
            must still send, as JSON Pointers into the request.
        required:
          type: array
          items:
            type: string
          description: >-
            Present on `registration-info-required`. Every registration field
            the route requires, as JSON Pointers into the request, for example
            `#/registrationInfo/taxId`.
        status:
          type: integer
          format: int32
          description: The HTTP status code.
          example: 400
          minimum: 0
        title:
          type: string
          description: Short summary of the problem type.
          example: Quote expired
        traceId:
          type: string
          description: >-
            Trace ID of the request, 32 hex characters, the same value as the
            `X-Trace-Id`

            response header. Quote it to support. Absent when tracing is
            unavailable.
          example: 4bf92f3577b34da6a3ce929d0e0e4736
        type:
          type: string
          format: uri
          description: >-
            `https://docs.etherfuse.com/ramp/v2/errors/` followed by the problem
            slug, for example

            `https://docs.etherfuse.com/ramp/v2/errors/quote-expired`. Switch on
            this value.
          example: https://docs.etherfuse.com/ramp/v2/errors/quote-expired
    WalletBalance:
      type: object
      required:
        - symbol
        - tokenKind
        - identifier
        - balance
        - currency
        - amountInFiat
        - amountInUsd
      properties:
        amountInFiat:
          type: string
          format: decimal
          description: >-
            Value of the held amount in `currency`, to six decimal places.
            Stablebond values use

            the bond price we read from the chain.
        amountInUsd:
          type: string
          format: decimal
          description: >-
            Value of the held amount in USD, to six decimal places, using the
            same asset price as

            amountInFiat and the current FX rate.
        balance:
          type: string
          format: decimal
          description: >-
            Held amount, at the asset's own decimal precision. A decimal string,
            so no

            precision is lost.
        currency:
          type: string
          description: >-
            The fiat currency this asset is denominated in (e.g. "mxn" for
            CETES, "brl" for

            TESOURO)
        identifier:
          type: string
          description: >-
            Chain-specific asset identifier: the mint on Solana, the contract on
            EVM chains,

            "CODE:ISSUER" on Stellar
        symbol:
          type: string
          description: Asset symbol (e.g. "cetes")
        tokenKind:
          $ref: '#/components/schemas/WalletTokenKind'
    Chain:
      type: string
      description: The chain a wallet is on.
      enum:
        - stellar
        - solana
        - base
        - polygon
        - monad
        - avalanche
    WalletBalancesStatus:
      type: string
      enum:
        - current
        - updating
        - failed
        - stale
    FieldViolation:
      type: object
      required:
        - detail
        - pointer
      properties:
        detail:
          type: string
          description: What is wrong with the field.
          example: This field is required.
        pointer:
          type: string
          description: >-
            JSON Pointer to the field in the request, for example
            `#/accountDetails/clabe`.
          example: '#/accountDetails/clabe'
    WalletTokenKind:
      type: string
      enum:
        - bond
        - principal_token
        - stablecoin
  responses:
    InvalidRequest:
      description: >-
        `invalid-request`: a path, query or body value is malformed, or
        `pageSize` is 0 or over 100.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unauthorized:
      description: >-
        `unauthorized`: the `Authorization` header is missing, not ASCII, or
        does not hold a valid API key.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    OrganizationNotFound:
      description: '`not-found`: your API key cannot act for this organization.'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    InternalError:
      description: >-
        `internal-error`: an unexpected error on our side. Retry with backoff,
        and quote `instance` to support if it persists.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    ServiceUnavailable:
      description: >-
        `service-unavailable`: a provider or chain we depend on did not answer
        in time. Retry with backoff.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key sent in the Authorization header, with no `Bearer` prefix.

````

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