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

# getTokenAccountsByOwners

> 一次查询最多 250 个钱包持有的同一代币余额。

Get token balances for multiple wallets in a single request with **getTokenAccountsByOwners**. Powered by **Ridge DB**, our custom-built client designed for high-performance token account queries. Instead of making hundreds of individual requests, query up to 250 wallets at once for any token mint.

Query up to 250 wallet addresses in one request to reduce API calls and latency.

* If a wallet has multiple accounts for the same mint, the response returns all of them.
* If a wallet has no token account, the response returns a clean zero balance instead of an error.
* Each account includes the slot when the balance was last updated, which helps with caching and change tracking.

请求配置和错误处理见 [RPC 快速入门](/cn/solana-rpc/quickstart)。计费见[积分与限制](/cn/solana-rpc/credits-and-rate-limits)。


## OpenAPI

````yaml gettokenaccountsbyowners post /
openapi: 3.1.0
info:
  title: Solana RPC
  version: 1.0.0
  description: Solana RPC HTTP method reference.
servers:
  - url: https://rpc-data.solanatracker.io
    description: Mainnet RPC endpoint
security: []
paths:
  /:
    post:
      summary: getTokenAccountsByOwners
      description: >-
        Query balances for one mint across up to 250 wallets in a single
        request.
      operationId: gettokenaccountsbyowners
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                jsonrpc:
                  allOf:
                    - type: string
                      description: The JSON-RPC protocol version.
                      enum:
                        - '2.0'
                      example: '2.0'
                      default: '2.0'
                id:
                  allOf:
                    - type: string
                      description: A unique identifier for the request.
                      example: '1'
                      default: '1'
                method:
                  allOf:
                    - type: string
                      description: The name of the RPC method to invoke.
                      enum:
                        - getTokenAccountsByOwners
                      example: getTokenAccountsByOwners
                      default: getTokenAccountsByOwners
                params:
                  allOf:
                    - type: array
                      description: Parameters for the batch token balance query.
                      default:
                        - - Bs88sAYgQehsK2fkzn6fxB6FgSJJPbxzAmcfQ3Eb6TWC
                          - BMLE4H5XLDS8WwCjEXCL9tmF4ZSNFnd5jmw2Xm9uG4To
                        - EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
                      items:
                        oneOf:
                          - type: array
                            description: >-
                              Array of owner wallet public keys to query (1-250
                              wallets). All pubkeys must be valid base-58
                              encoded Solana addresses.
                            minItems: 1
                            maxItems: 250
                            items:
                              type: string
                              description: >-
                                Owner wallet public key as a base-58 encoded
                                string.
                              example: Bs88sAYgQehsK2fkzn6fxB6FgSJJPbxzAmcfQ3Eb6TWC
                          - type: string
                            description: >-
                              The token mint public key (address) to query
                              balances for, as a base-58 encoded string.
                            example: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
              required:
                - jsonrpc
                - id
                - method
                - params
            examples:
              usdcBalances:
                summary: Request USDC balances for 2 wallets
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: getTokenAccountsByOwners
                  params:
                    - - Bs88sAYgQehsK2fkzn6fxB6FgSJJPbxzAmcfQ3Eb6TWC
                      - BMLE4H5XLDS8WwCjEXCL9tmF4ZSNFnd5jmw2Xm9uG4To
                    - EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
              multipleWallets:
                summary: Request balances for multiple wallets
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: getTokenAccountsByOwners
                  params:
                    - - 7nKKqxgGvAFnqjDKWwGkPfApR8qPBvoT7gEcuLWgLcVR
                      - 3ZCZDvyFQswEezauPTHeR82yq5ghipa65s8rUVTPSM8v
                      - 8WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
                    - So11111111111111111111111111111111111111112
      responses:
        '200':
          description: >-
            Successfully retrieved token account balances for all requested
            owners.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jsonrpc:
                    allOf:
                      - type: string
                        description: The JSON-RPC protocol version.
                        enum:
                          - '2.0'
                        example: '2.0'
                  id:
                    allOf:
                      - type: string
                        description: Identifier matching the request.
                        example: '1'
                  result:
                    allOf:
                      - type: object
                        description: Token account balances with context information.
                        properties:
                          context:
                            type: object
                            description: Context information about the response.
                            properties:
                              slot:
                                type: integer
                                description: >-
                                  The current slot at which the query was
                                  processed.
                                example: 378770899
                              apiVersion:
                                type: string
                                description: The API version of the RPC server.
                                example: 3.0.0
                          value:
                            type: array
                            description: >-
                              Array of token account information for each owner.
                              Owners with multiple accounts will have multiple
                              entries. Owners without accounts will have one
                              entry with null account and zero balance.
                            items:
                              type: object
                              properties:
                                owner:
                                  type: string
                                  description: >-
                                    The owner wallet public key as a base-58
                                    encoded string.
                                  example: Bs88sAYgQehsK2fkzn6fxB6FgSJJPbxzAmcfQ3Eb6TWC
                                account:
                                  type: string
                                  description: >-
                                    The token account public key as a base-58
                                    encoded string. Null if the owner has no
                                    token account for this mint.
                                  example: EzewvqfZPbroCmuRiKFj3KoHQ1XkuDc8qJ9MYCTzcJUY
                                  nullable: true
                                amount:
                                  type: string
                                  description: >-
                                    The raw token amount as a string (without
                                    decimal adjustment).
                                  example: '540966303'
                                decimals:
                                  type: integer
                                  description: >-
                                    The number of decimals configured for the
                                    token mint.
                                  example: 6
                                uiAmount:
                                  type: number
                                  description: >-
                                    The token amount adjusted for decimals
                                    (human-readable format).
                                  example: 540.966303
                                uiAmountString:
                                  type: string
                                  description: >-
                                    The token amount as a string, adjusted for
                                    decimals.
                                  example: '540.966303'
                                slot:
                                  type: integer
                                  description: >-
                                    The slot at which this token account balance
                                    was last updated. Returns 0 if owner has no
                                    account.
                                  example: 370336402
              examples:
                successResponse:
                  summary: Response with token balances for 2 owners
                  value:
                    jsonrpc: '2.0'
                    id: 1
                    result:
                      context:
                        apiVersion: 3.0.0
                        slot: 378770899
                      value:
                        - account: 424L75FrM5LTbNrbrqyCfrR4gWBn5rtzzaEhiSiNLC1h
                          amount: '146120000068'
                          decimals: 6
                          owner: BMLE4H5XLDS8WwCjEXCL9tmF4ZSNFnd5jmw2Xm9uG4To
                          slot: 356527310
                          uiAmount: 146120.000068
                          uiAmountString: '146120.000068'
                        - account: EzewvqfZPbroCmuRiKFj3KoHQ1XkuDc8qJ9MYCTzcJUY
                          amount: '540966303'
                          decimals: 6
                          owner: Bs88sAYgQehsK2fkzn6fxB6FgSJJPbxzAmcfQ3Eb6TWC
                          slot: 370336402
                          uiAmount: 540.966303
                          uiAmountString: '540.966303'
                multipleAccountsPerOwner:
                  summary: Response when owner has multiple token accounts
                  value:
                    jsonrpc: '2.0'
                    id: 1
                    result:
                      context:
                        apiVersion: 3.0.0
                        slot: 378770899
                      value:
                        - account: Account1pubkey111111111111111111111111111
                          amount: '1000000000'
                          decimals: 6
                          owner: Owner1pubkey1111111111111111111111111111111
                          slot: 356527310
                          uiAmount: 1000
                          uiAmountString: '1000'
                        - account: Account2pubkey222222222222222222222222222
                          amount: '500000000'
                          decimals: 6
                          owner: Owner1pubkey1111111111111111111111111111111
                          slot: 356527305
                          uiAmount: 500
                          uiAmountString: '500'
                noAccountResponse:
                  summary: Response when owner has no token account
                  value:
                    jsonrpc: '2.0'
                    id: 1
                    result:
                      context:
                        apiVersion: 3.0.0
                        slot: 378770899
                      value:
                        - account: null
                          amount: '0'
                          decimals: 0
                          owner: OwnerWithNoAccount111111111111111111111111
                          slot: 0
                          uiAmount: 0
                          uiAmountString: '0'
        '400':
          description: Bad Request - Invalid request parameters or malformed request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jsonrpc:
                    allOf:
                      - type: string
                        description: The JSON-RPC protocol version.
                        enum:
                          - '2.0'
                        example: '2.0'
                  error:
                    allOf:
                      - type: object
                        properties:
                          code:
                            type: integer
                            description: The error code.
                            example: -32602
                          message:
                            type: string
                            description: The error message.
                          data:
                            type: object
                            description: Additional data about the error.
                  id:
                    allOf:
                      - type: string
                        description: Identifier matching the request.
                        example: '1'
                refIdentifier: '#/components/schemas/ErrorResponse'
              examples:
                invalidPubkey:
                  summary: Invalid owner pubkey
                  value:
                    jsonrpc: '2.0'
                    id: 1
                    error:
                      code: -32602
                      message: >-
                        Invalid owner pubkey at index 0:
                        Xs88sAYgQehsK2fkzn6fxB6FgSJJPbxzAmcfQ3Eb6TWC
                emptyArray:
                  summary: Empty owners array
                  value:
                    jsonrpc: '2.0'
                    id: 1
                    error:
                      code: -32602
                      message: Owners array cannot be empty
                tooManyOwners:
                  summary: Too many owners
                  value:
                    jsonrpc: '2.0'
                    id: 1
                    error:
                      code: -32602
                      message: 'Too many owners: 251 (max 250)'
                invalidMint:
                  summary: Invalid mint pubkey
                  value:
                    jsonrpc: '2.0'
                    id: 1
                    error:
                      code: -32602
                      message: Invalid mint pubkey
        '401':
          description: Unauthorized - Invalid or missing API key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jsonrpc:
                    allOf:
                      - type: string
                        description: The JSON-RPC protocol version.
                        enum:
                          - '2.0'
                        example: '2.0'
                  error:
                    allOf:
                      - type: object
                        properties:
                          code:
                            type: integer
                            description: The error code.
                            example: -32602
                          message:
                            type: string
                            description: The error message.
                          data:
                            type: object
                            description: Additional data about the error.
                  id:
                    allOf:
                      - type: string
                        description: Identifier matching the request.
                        example: '1'
                refIdentifier: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    jsonrpc: '2.0'
                    error:
                      code: -32001
                      message: Unauthorized
                    id: 1
        '429':
          description: Too Many Requests - Rate limit exceeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jsonrpc:
                    allOf:
                      - type: string
                        description: The JSON-RPC protocol version.
                        enum:
                          - '2.0'
                        example: '2.0'
                  error:
                    allOf:
                      - type: object
                        properties:
                          code:
                            type: integer
                            description: The error code.
                            example: -32602
                          message:
                            type: string
                            description: The error message.
                          data:
                            type: object
                            description: Additional data about the error.
                  id:
                    allOf:
                      - type: string
                        description: Identifier matching the request.
                        example: '1'
                refIdentifier: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    jsonrpc: '2.0'
                    error:
                      code: -32005
                      message: Too many requests
                    id: 1
        '500':
          description: Internal Server Error - An error occurred on the server.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jsonrpc:
                    allOf:
                      - type: string
                        description: The JSON-RPC protocol version.
                        enum:
                          - '2.0'
                        example: '2.0'
                  error:
                    allOf:
                      - type: object
                        properties:
                          code:
                            type: integer
                            description: The error code.
                            example: -32602
                          message:
                            type: string
                            description: The error message.
                          data:
                            type: object
                            description: Additional data about the error.
                  id:
                    allOf:
                      - type: string
                        description: Identifier matching the request.
                        example: '1'
                refIdentifier: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    jsonrpc: '2.0'
                    error:
                      code: -32603
                      message: Internal error
                    id: 1
        '503':
          description: Service Unavailable - The service is temporarily unavailable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jsonrpc:
                    allOf:
                      - type: string
                        description: The JSON-RPC protocol version.
                        enum:
                          - '2.0'
                        example: '2.0'
                  error:
                    allOf:
                      - type: object
                        properties:
                          code:
                            type: integer
                            description: The error code.
                            example: -32602
                          message:
                            type: string
                            description: The error message.
                          data:
                            type: object
                            description: Additional data about the error.
                  id:
                    allOf:
                      - type: string
                        description: Identifier matching the request.
                        example: '1'
                refIdentifier: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    jsonrpc: '2.0'
                    error:
                      code: -32002
                      message: Service unavailable
                    id: 1
        '504':
          description: Gateway Timeout - The request timed out.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jsonrpc:
                    allOf:
                      - type: string
                        description: The JSON-RPC protocol version.
                        enum:
                          - '2.0'
                        example: '2.0'
                  error:
                    allOf:
                      - type: object
                        properties:
                          code:
                            type: integer
                            description: The error code.
                            example: -32602
                          message:
                            type: string
                            description: The error message.
                          data:
                            type: object
                            description: Additional data about the error.
                  id:
                    allOf:
                      - type: string
                        description: Identifier matching the request.
                        example: '1'
                refIdentifier: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    jsonrpc: '2.0'
                    error:
                      code: -32003
                      message: Gateway timeout
                    id: 1
      security:
        - ApiKeyQuery: []
components:
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key

````