如何使用 getTokenAccountsByOwner

getTokenAccountsByOwner RPC 方法用于检索特定公钥拥有的所有 SPL 代币账户。对于需要显示用户代币持有情况或与其各种代币账户交互的钱包和应用程序而言，这是一种基础方法。你必须使用特定代币的 mint 或 programId（例如 SPL Token Program 或 Token-2022 Program）来筛选查询。对于拥有大量代币资产的钱包，建议使用 getTokenAccountsByOwnerV2。它支持基于游标的分页，并且可以配置页面大小，每个请求最多返回 10,000 个账户。

常见用例

显示用户资产组合： 获取给定用户钱包地址的所有代币账户（以及相应余额），以显示其完整的代币资产组合。
应用程序逻辑： 在发起转账或其他交互之前，识别用户针对特定铸币的代币账户。
验证： 检查所有者持有哪些特定类型代币的代币账户。
索引代币持有者： 虽然对于全局索引来说，其效率不如其他方法，但可用于查找一组已知所有者的账户。

请求参数

ownerPubkey（字符串，必需）：要检索其代币账户的账户所有者的 base-58 编码公钥。
filter（对象，必需）：一个必须指定 mint 或 programId 的 JSON 对象：
- mint（字符串）：特定代币铸币的 base-58 编码公钥。如果提供此参数，则仅返回由 ownerPubkey 拥有且属于该铸币的代币账户。
- programId（字符串）：管理这些账户的 Token Program 的 base-58 编码公钥。常用值包括：
  - SPL Token Program：TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
  - Token-2022 Program：TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb
options（对象，可选）：可选的配置对象，可包含：
- commitment（字符串，可选）：指定确认级别。
- encoding（字符串，可选）：账户数据的编码格式。强烈建议使用 "jsonParsed"。其他选项："base64"、"base64+zstd"。默认为 "base64"。
- dataSlice（对象，可选）：用于检索账户数据的特定切片（offset：usize，length：usize）。仅适用于 base58、base64 或 base64+zstd 编码。
- minContextSlot（u64，可选）：查询的最小时隙。

响应结构

JSON-RPC 响应中的 result.value 字段是一个对象数组。每个对象对应一个由 ownerPubkey 拥有且与 filter 匹配的 SPL 代币账户。 value 数组中的每个对象包含：

pubkey（字符串）：代币账户本身的 base-58 编码公钥。
account（对象）：代币账户的详细信息：
- lamports（u64）：用于免租的 lamport 余额。
- owner（字符串）：拥有该账户的程序（例如 Token Program 公钥）。
- data：账户数据。如果使用 "jsonParsed" 编码，则包含：
  - program（字符串）：例如 "spl-token"。
  - parsed：包含结构化信息的对象：
    - info：详细信息，例如：
      - mint（字符串）：代币的铸币地址。
      - owner（字符串）：代币账户的所有者（应与请求中的 ownerPubkey 匹配）。
      - tokenAmount（对象）：代币余额（amount、decimals、uiAmount、uiAmountString）。
      - state（字符串）：代币账户的状态（例如 "initialized"）。
      - isNative（布尔值）：账户是否持有封装 SOL。
      - delegate（字符串，可选）：设置委托后对应的委托地址。
      - delegatedAmount（对象，可选）：设置委托后对应的委托金额。
    - type（字符串）：例如 "account"。
- executable（布尔值）：账户是否可执行。
- rentEpoch（u64）：下一次应付租金的纪元。
- space（u64，如果不是 jsonParsed）：原始账户数据的字节长度。

响应示例（使用 jsonParsed 编码，并按 programId 筛选）：

{
  "jsonrpc": "2.0",
  "result": {
    "context": {
      "slot": 183459000
    },
    "value": [
      {
        "pubkey": "AssociatedTokenAccountPubkey1...",
        "account": {
          "data": {
            "program": "spl-token",
            "parsed": {
              "info": {
                "isNative": false,
                "mint": "SomeTokenMintPubkey...",
                "owner": "OwnerPubkeyProvidedInRequest...",
                "state": "initialized",
                "tokenAmount": {
                  "amount": "1000000000", // 1 token if decimals is 9
                  "decimals": 9,
                  "uiAmount": 1.0,
                  "uiAmountString": "1.0"
                }
              },
              "type": "account"
            },
            "space": 165
          },
          "executable": false,
          "lamports": 2039280,
          "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
          "rentEpoch": 380
        }
      },
      {
        "pubkey": "AnotherAssociatedTokenAccountPubkey...",
        "account": {
          // ... similar structure for another token owned by the same owner
        }
      }
    ]
  },
  "id": 1
}

代码示例

# Replace <OWNER_PUBKEY> and <TOKEN_MINT_PUBKEY> or <TOKEN_PROGRAM_ID>

# Example filtering by programId (SPL Token Program)
curl -X POST -H "Content-Type: application/json" -d \
  '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getTokenAccountsByOwner",
    "params": [
      "<OWNER_PUBKEY>",
      { "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
      { "encoding": "jsonParsed" }
    ]
  }' \
  <YOUR_RPC_URL>

# Example filtering by a specific mint
curl -X POST -H "Content-Type: application/json" -d \
  '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getTokenAccountsByOwner",
    "params": [
      "<OWNER_PUBKEY>",
      { "mint": "<SPECIFIC_TOKEN_MINT_PUBKEY>" },
      { "encoding": "jsonParsed", "commitment": "confirmed" }
    ]
  }' \
  <YOUR_RPC_URL>

const { Connection, PublicKey } = require('@solana/web3.js');

async function findOwnerTokenAccounts(ownerAddress, filter, encoding = 'jsonParsed') {
  // Replace with your RPC endpoint
  const connection = new Connection('https://mainnet.helius-rpc.com/?api-key=<api-key>');
  const ownerPubKey = new PublicKey(ownerAddress);

  try {
    let actualFilter;
    if (filter.mint) {
      actualFilter = { mint: new PublicKey(filter.mint) };
    } else if (filter.programId) {
      actualFilter = { programId: new PublicKey(filter.programId) };
    } else {
      console.error("Filter must contain either 'mint' or 'programId'");
      return;
    }

    const accounts = await connection.getTokenAccountsByOwner(
      ownerPubKey,
      actualFilter,
      { encoding }
    );

    console.log(`Found ${accounts.value.length} token accounts for owner ${ownerAddress}:`);
    accounts.value.forEach(accInfo => {
      console.log(`  Token Account: ${accInfo.pubkey.toBase58()}`);
      if (encoding === 'jsonParsed' && accInfo.account.data.parsed) {
        console.log(`    Mint: ${accInfo.account.data.parsed.info.mint}`);
        console.log(`    Balance: ${accInfo.account.data.parsed.info.tokenAmount.uiAmountString}`);
      }
      // console.log(JSON.stringify(accInfo, null, 2)); // For full details
    });

  } catch (error) {
    console.error(`Error fetching token accounts for owner ${ownerAddress}:`, error);
  }
}

// Replace with an actual owner's public key
const exampleOwner = 'HXtBm8XZbxaTt41uqaKhwUAa6Z1aPyvJdsZVENiWsetg'; // Example wallet address

// Example 1: Find all SPL Token Program accounts owned by `exampleOwner`
findOwnerTokenAccounts(exampleOwner, { programId: 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA' });

// Example 2: Find USDC token accounts owned by `exampleOwner`
// const usdcMint = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
// findOwnerTokenAccounts(exampleOwner, { mint: usdcMint });

// Example 3: Find Token-2022 Program accounts owned by `exampleOwner`
// findOwnerTokenAccounts(exampleOwner, { programId: 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb' });

开发者提示

筛选条件要求： 你必须在筛选条件中提供 mint 或 programId。如果没有这些主要筛选条件之一，就无法跨所有代币类型查询某个所有者的全部代币账户。
关联代币账户： 此方法将返回该公钥拥有的所有代币账户，包括标准关联代币账户（ATA）以及该公钥可能拥有的任何其他 SPL 代币账户（例如来自较旧的钱包实现或自定义设置）。
编码： 强烈建议为 encoding 选项使用 "jsonParsed"。它会将二进制账户数据解码为更易使用的 JSON 结构。
性能： 如果所有者拥有大量代币账户（尤其是仅按 programId 筛选时），响应可能会很大。在这种情况下，请使用 getTokenAccountsByOwnerV2，它提供内置分页支持。
Token-2022（代币扩展）： 如果你使用由 Token-2022 程序创建的代币（该程序支持转账费、利息等扩展功能），请确保使用正确的 programId：TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb。

本指南详细介绍了 getTokenAccountsByOwner RPC 方法，帮助你高效检索任意 Solana 地址的代币账户信息。

大型代币资产组合的分页

对于持有大量代币的钱包，请使用 getTokenAccountsByOwnerV2，它提供：

基于游标的分页：设置 limit（1-10,000），并使用 paginationKey 浏览结果
增量更新：使用 changedSinceSlot，仅获取自特定时隙以来修改过的代币账户
更出色的性能：防止超时，并支持实时跟踪资产组合
分页行为：仅当未返回任何代币账户时，才表示分页结束。由于筛选，返回的账户数可能少于限制值——请继续分页，直到 paginationKey 为 null

// Example: Paginated query for all token accounts
const response = await fetch("https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "1",
    method: "getTokenAccountsByOwnerV2",
    params: [
      "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      { "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
      {
        encoding: "jsonParsed",
        limit: 1000
      }
    ]
  })
});

const data = await response.json();
console.log(`Found ${data.result.value.length} token accounts`);
if (data.result.paginationKey) {
  console.log("More results available, use paginationKey for next page");
  // Continue pagination even if fewer than limit accounts were returned
} else {
  console.log("End of pagination - no more token accounts available");
}

getTokenAccountsByOwnerV2

适用于大型资产组合、支持基于游标导航的分页版本

getTokenAccountBalance

获取特定代币账户的余额

从这里开始

实时数据

低延迟交易

历史数据与钱包数据

RPC 方法指南

生产环境就绪

使用 Orb

其他操作指南

如何使用 getTokenAccountsByOwner

常见用例

请求参数

响应结构

代码示例

开发者提示

大型代币资产组合的分页

相关方法

getTokenAccountsByOwnerV2

getTokenAccountBalance

​常见用例

​请求参数

​响应结构

​代码示例

​开发者提示

​大型代币资产组合的分页

​相关方法

getTokenAccountsByOwnerV2

getTokenAccountBalance

常见用例

请求参数

响应结构

代码示例

开发者提示

大型代币资产组合的分页

相关方法