如何使用 getTokenAccountsByOwner

​

常见用例

• 显示用户投资组合： 获取给定用户钱包地址的所有代币账户（以及余额），以显示其完整的代币投资组合。
• 应用逻辑： 在发起转账或其他交互之前，识别用户特定代币的账户。
• 验证： 检查某个所有者拥有的特定类型代币的账户。
• 索引代币持有者： 虽然对于全局索引效率较低，但可以用于查找已知所有者集合的账户。

​

请求参数

1. ownerPubkey (string, required): 要检索其代币账户的账户所有者的 base-58 编码公钥。
2. filter (object, required): 一个 JSON 对象，必须指定 /* INLINE_CODE_PLACEHOLDER_a4fd5a3d8817d1fb3b3b2abedaceb3fe / 或 / INLINE_CODE_PLACEHOLDER_d0e7ff6d24268cce4eba6844d37f400f */:
   • mint (string): 特定代币铸币的 base-58 编码公钥。如果提供，将仅返回由 ownerPubkey 拥有的此铸币的代币账户。
   • programId (string): 管理账户的代币程序的 base-58 编码公钥。常见值有：
     • SPL 代币程序: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
     • Token-2022 程序: TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb
3. options (object, optional): 一个可选的配置对象，可以包括：
   • commitment (string, optional): 指定 承诺级别。
   • encoding (string, optional): 账户数据的编码。建议使用 "jsonParsed"。其他选项： "base64", "base64+zstd"。默认为 "base64"。
   • dataSlice (object, optional): 要检索账户数据的特定切片（offset: usize, length: usize）。仅适用于 base58, base64, 或 base64+zstd 编码。
   • minContextSlot (u64, optional): 查询的最低槽位。

​

响应结构

• 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): 原始账户数据的字节长度。

{
  "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>

​

开发者提示

• 过滤要求： 您必须在过滤器中提供 mint 或 programId。如果没有其中一个主要过滤器，不可能查询所有令牌类型的所有所有者令牌账户。
• 关联令牌账户： 此方法将返回由公钥拥有的所有令牌账户，包括标准的关联令牌账户（ATAs）和他们可能拥有的任何其他 SPL 令牌账户（例如，来自旧的钱包实现或自定义设置）。
• 编码： 强烈推荐为 encoding 选项使用 "jsonParsed"。它将二进制账户数据解码为更可用的 JSON 结构。
• 性能： 如果所有者拥有大量令牌账户（尤其是仅按 programId 过滤时），响应可能会很大。对于这种情况，使用 getTokenAccountsByOwnerV2 提供内置分页支持。
• Token-2022（令牌扩展）： 如果您使用 Token-2022 程序（支持传输费用、利息等扩展）创建的令牌，请确保使用正确的 programId：TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb。

​

大型代币组合的分页

• 基于游标的分页：设置 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");
}

​

相关方法