@w3lib/solana-batch-call 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0
+
+首个版本：
+
+- 批量余额（SOL / SPL Token / Token-2022），指定代币时用 ATA + `getMultipleAccounts`，免费节点可用；扫描模式统计全部代币账户
+- 代币详情（字段可选），Metaplex 与 Token-2022 TokenMetadata 扩展
+- 资产列表 `getOwnerTokens`：持有人的全部代币，带 name / symbol，多账户合计，元数据分批读取、失败不影响余额
+- NFT 元数据、持有人、某地址持有的全部 NFT
+- JSON-RPC 自动合并、批量降级、429 重试，多节点故障切换，按创世区块哈希校验网络
+- 支持 URL、web3.js Connection、自定义传输

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 L
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,170 @@
-# Temporary Holding Version
+# @w3lib/solana-batch-call
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Solana 批量读取库：余额（SOL / SPL Token / Token-2022）、代币详情、NFT。不依赖 Solana SDK，直接发 JSON-RPC。
+
+```bash
+pnpm add @w3lib/solana-batch-call
+```
+
+- **一次请求查一批**：账户读取用 `getMultipleAccounts`（自动去重、按 100 个一组拆分、最多同时 3 个请求）；同一 tick 内发起的 RPC 调用合并成一个 JSON-RPC 批量请求
+- **免费节点也能查余额**：指定代币时在本地推导关联代币账户（ATA）地址，和 SOL 账户、mint 账户一起一次读完，不需要 `getTokenAccountsByOwner` 这类索引方法
+- **Token-2022**：余额、decimals、TokenMetadata 扩展里的 name / symbol / uri 都支持
+- **多节点故障切换**：限频、403、需要 API Key、不支持某方法等节点问题自动换下一个节点；节点不支持批量请求或限制批量大小时自动降级
+- **网络校验**：按创世区块哈希确认节点所在网络，不会把 devnet 的数据当成 mainnet 的返回
+- 结果字段都是字符串 / 数字 / 布尔 / null，可以直接 `JSON.stringify`
+
+## 快速上手
+
+```ts
+import { NATIVE_MINT, getBalances, getNftOwners, getNfts, getOwnerNfts, getOwnerTokens, getSolBalances, getTokens } from '@w3lib/solana-batch-call'
+
+// 资产列表：持有人拥有的全部代币（SOL 在第一位，带 name / symbol；需要支持索引方法的节点）
+await getOwnerTokens(owner, { provider: 'https://my-rpc.example' })
+// [
+//   { token: NATIVE_MINT, native: true,  name: 'Solana',   symbol: 'SOL',  formatted: '1.5',  accounts: 1, … },
+//   { token: USDC,        native: false, name: 'USD Coin', symbol: 'USDC', formatted: '1235', accounts: 2, … },  // 2 个代币账户合计
+//   ...
+// ]
+
+// 余额：SOL + 代币，带 decimals 换算（不传 provider 时使用内置的 mainnet 公共节点）
+await getBalances(owner, [NATIVE_MINT, USDC, PYUSD], { symbol: true })
+// [
+//   { token: NATIVE_MINT, native: true,  balance: '1500000000', decimals: 9, formatted: '1.5', tokenProgram: null, symbol: 'SOL', success: true },
+//   { token: USDC,        native: false, balance: '1234500000', decimals: 6, formatted: '1234.5', tokenProgram: 'Tokenkeg…', symbol: 'USDC', success: true },
+//   ...
+// ]
+
+// 多个地址的 SOL 余额
+await getSolBalances([addressA, addressB])
+
+// 代币详情，字段可选：name / symbol / uri / decimals / supply / tokenProgram / mintAuthority / freezeAuthority（默认 name、symbol、decimals）
+await getTokens([USDC, PYUSD], { fields: ['name', 'symbol', 'decimals', 'supply'] })
+// [{ address: USDC, native: false, name: 'USD Coin', symbol: 'USDC', decimals: 6, supply: '…', supplyFormatted: '…', success: true }, ...]
+
+// NFT
+await getNfts([mint])        // 名称、uri、所属集合（是否已认证）、版税、标准、创作者
+await getNftOwners([mint])   // 持有人
+await getOwnerNfts(owner)    // 某地址持有的全部 NFT（需要支持索引方法的节点）
+```
+
+| 函数 | SolanaClient 方法 | 说明 |
+| --- | --- | --- |
+| `getBalances(owner, mints?, opts)` | `balances` | SOL + SPL Token + Token-2022 余额；`symbol: true` 额外返回 symbol；不传 mints 返回全部持仓 |
+| `getOwnerTokens(owner, opts)` | `ownerTokens` | 持有人的全部代币（资产列表），带 name / symbol；默认不含 NFT 和余额为 0 的账户 |
+| `getSolBalances(addresses, opts)` | `solBalances` | 多个地址的 SOL 余额 |
+| `getTokens(mints, opts)` | `tokens` | 代币详情，`fields` 选择字段，结果类型随之收窄 |
+| `getNfts(mints, opts)` | `nfts` | NFT 元数据（Metaplex；Token-2022 NFT 取扩展） |
+| `getNftOwners(mints, opts)` | `nftOwners` | NFT 持有人 |
+| `getOwnerNfts(owner, opts)` | `ownerNfts` | 某地址持有的全部 NFT |
+| — | `accounts(addresses)` | 批量读原始账户（`AccountInfo \| null`） |
+| — | `request(method, params)` | 直接发 JSON-RPC（同样参与合并与故障切换） |
+
+## 资产列表
+
+`getOwnerTokens(owner)` 扫描持有人的全部代币账户（Token + Token-2022），同一代币的多个账户合计，返回：
+
+- 第一项是 SOL，之后是 SPL Token、Token-2022 的代币（各自按节点返回的顺序；库里没有价格信息，不按价值排序）
+- 每项带 `accounts`（代币账户数量）；默认还带 `name` / `symbol` / `metadataStatus`（`ok` 读到了、`missing` 确认没有元数据、`failed` 节点问题没读到），`metadata: false` 时不读元数据、不返回这三个字段
+- Wrapped SOL 代币账户单独列出（`token` 同样是 `So111…112`，`native: false`），与原生 SOL 那一项区分
+- 默认不含 NFT 和余额为 0 的代币账户（已清空的 ATA），用 `includeNfts` / `includeZero` 打开；`includeNative: false` 不返回 SOL。NFT 的判断按 mint 汇总：精度 0、合计数量 1（与 `getOwnerNfts` 一致）
+
+持仓很多时读元数据较慢：读取账户最多同时 3 个请求、每个 100 个地址，以避免限频（实测 4000 个代币在官方节点上约 80 秒，不读元数据约 4 秒）。可以先用 `metadata: false` 拿到列表，再对需要展示的代币调用 `getTokens`。元数据读取遇到限频等节点问题时不再继续请求，对应代币的 `metadataStatus` 为 `failed`、`name` / `symbol` 为 `null`，余额列表照常返回；之后可以对这些代币单独重查。
+
+需要支持 `getTokenAccountsByOwner` 的节点，内置的免费公共节点大多不支持。
+
+## 余额的两种模式
+
+| | 指定 mints（默认） | 扫描（不传 mints，或 `scan: true`） |
+| --- | --- | --- |
+| 实现 | 本地推导 ATA + 一次 `getMultipleAccounts` | `getTokenAccountsByOwner`（Token / Token-2022 各一次） |
+| 统计范围 | 只统计 **ATA** 里的余额 | 该地址的**全部**代币账户，同一代币多个账户合计 |
+| 免费公共节点 | 可用 | 大多不支持，需要自己的节点（Helius、QuickNode、Triton 等） |
+
+普通钱包的代币都在 ATA 里，用默认模式即可。交易所、托管类地址常有非 ATA 的代币账户，默认模式会少算，需要 `scan: true`。
+
+其他规则：
+
+- **主币**：`So111…112`（`NATIVE_MINT`，Wrapped SOL 的 mint）和 `11111…1`（System Program）按原生 SOL 查询（lamports，9 位精度）；此时 Wrapped SOL 代币账户里的余额不单独列出。可用 `nativeMints` 配置，传 `[SYSTEM_PROGRAM_ID]` 时 `So111…112` 按普通代币（Wrapped SOL）查询
+- **缓存**：decimals、所属程序永久缓存；name、symbol 来自可修改的元数据，缓存 1 小时（确认没有元数据的代币同样缓存，不会每次重查）。按网络共享（各函数共用）；自定义节点且没指定 `cluster` 时只在该客户端内缓存。最多 5 万个代币，超出淘汰最早的
+- **大数**：lamports 等 u64 超过 2⁵³ 时不会丢精度
+- **失败**：mint 不存在、地址非法等只让该项 `success: false`；节点不可用等整个请求失败时才抛错
+
+## 节点
+
+```ts
+import { SolanaClient } from '@w3lib/solana-batch-call'
+
+new SolanaClient()                                              // 内置 mainnet 公共节点
+new SolanaClient(undefined, { cluster: 'devnet' })              // 内置 devnet 节点
+new SolanaClient('https://my-rpc.example')                      // 自己的节点
+new SolanaClient(['https://rpc-1.example', 'https://rpc-2.example']) // 主节点 + 备用节点
+new SolanaClient(connection)                                    // @solana/web3.js 的 Connection（使用其 rpcEndpoint）
+new SolanaClient({ request: (method, params) => myRpc(method, params) }) // 自定义传输
+
+// 独立函数的节点参数相同
+await getBalances(owner, mints, { provider: 'https://my-rpc.example', cluster: 'mainnet' })
+```
+
+**内置公共节点**（`DEFAULT_RPC_URLS`）：mainnet 依次是 publicnode 和官方节点。2026-10 实测：
+
+- publicnode：放行跨域、支持批量请求，但不支持 `getTokenAccountsByOwner`、`getTokenLargestAccounts` 等需要索引的方法
+- 官方节点 `api.mainnet-beta.solana.com`：对带浏览器 `Origin` 的请求返回 403，只能在服务端使用；限频较严
+
+所以扫描持仓、`getNftOwners`、`getOwnerNfts` 在内置节点上可能不可用，生产环境建议传入自己的节点。
+
+**传输层行为**（`HttpRpc`）：
+
+- 收集窗口（`batchWait`，默认 0 即同一 tick）内的调用合并成一个批量请求，最多 `maxBatchSize`（默认 20）条
+- 节点不支持批量请求时自动改为逐条并发；返回 “Batch of more than N” 时按 N 缩小批量；请求体过大（413）时批量减半。批量请求被限频或拒绝访问时不会降级（降级只会让限频更严重）
+- HTTP 429 和 JSON-RPC 错误码 429 都会退避重试（`retries`，默认 2；传入多个自定义节点时为 0，直接换节点；内置节点保留重试），批量里只重试被限频的那几条
+- 单次请求超时 `timeout`，默认 10 秒
+
+**故障切换**（多节点时）：网络错误、超时、限频、403、需要 API Key、请求被拦截等节点问题换下一个节点，出错节点冷却 `cooldown`（默认 30 秒）；参数错误等确定性错误直接抛出（`RpcError`，`isNodeFault(err)` 可判断）。
+
+**网络校验**：传了 `cluster`，或传了多个节点时，会用 `getGenesisHash` 确认每个节点所在的网络，不一致时报 `NetworkMismatchError`（多节点时换下一个节点）。校验与请求并行发出，结果按节点缓存，每个节点只多一次请求；内置节点不校验。`await client.getCluster()` 返回节点所在网络。
+
+## 配置
+
+```ts
+new SolanaClient(provider?, {
+  cluster: 'mainnet',          // 'mainnet' | 'devnet' | 'testnet'
+  commitment: 'confirmed',     // 'processed' | 'confirmed' | 'finalized'
+  nativeMints: [NATIVE_MINT, SYSTEM_PROGRAM_ID],
+  timeout: 10_000,
+  maxBatchSize: 20,
+  batchWait: 0,
+  batch: true,                 // false：不合并成批量请求
+  retries: 2,
+  cooldown: 30_000,
+  headers: { 'x-api-key': '…' },
+  fetch: customFetch,          // 需要代理等场景
+})
+```
+
+在 Node 里通过代理访问节点时：Node 自带的 `fetch` 默认不读 `HTTPS_PROXY`，Node 24+ 可以设置 `NODE_USE_ENV_PROXY=1`，或者通过 `fetch` 选项传入自定义实现。
+
+## 工具函数
+
+```ts
+import {
+  getAssociatedTokenAddress, // ATA 地址
+  getMetadataAddress,        // Metaplex 元数据账户地址
+  findProgramAddress,        // 通用 PDA 推导（与 web3.js findProgramAddressSync 相同）
+  isAddress,
+  parseMint, parseTokenAccount, parseMetaplexMetadata, // 账户数据解析
+  formatAmount,
+  TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, NATIVE_MINT, GENESIS_HASHES,
+} from '@w3lib/solana-batch-call'
+```
+
+## 开发
+
+```bash
+pnpm test        # 单元测试（模拟节点，不需要网络）
+pnpm test:live   # 连真实节点（SOLANA_RPC 指定支持索引方法的节点；需要代理时加 NODE_USE_ENV_PROXY=1）
+pnpm build
+```
+
+## License
+
+MIT

package/dist/address.d.ts

@@ -0,0 +1,14 @@
+/** 是否是合法的 Solana 地址（base58，32 字节） */
+export declare function isAddress(value: unknown): value is string;
+export declare function decodeAddress(address: string): Uint8Array;
+export declare function encodeAddress(bytes: Uint8Array): string;
+/**
+ * 推导 PDA（与 web3.js PublicKey.findProgramAddressSync 相同），返回地址。
+ * seeds 每项不超过 32 字节。
+ */
+export declare function findProgramAddress(seeds: Uint8Array[], programId: string): string;
+/** 关联代币账户（ATA）地址 */
+export declare function getAssociatedTokenAddress(owner: string, mint: string, tokenProgram: string): string;
+/** Metaplex Token Metadata 账户地址 */
+export declare function getMetadataAddress(mint: string): string;
+//# sourceMappingURL=address.d.ts.map

package/dist/address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../src/address.ts"],"names":[],"mappings":"AAMA,qCAAqC;AACrC,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CASzD;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAMzD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAEvD;AA2BD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAmBjF;AAED,oBAAoB;AACpB,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEnG;AAED,mCAAmC;AACnC,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKvD"}

package/dist/address.js

@@ -0,0 +1,81 @@
+import { ed25519 } from '@noble/curves/ed25519.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { base58 } from '@scure/base';
+import { ASSOCIATED_TOKEN_PROGRAM_ID, METADATA_PROGRAM_ID } from './constants.js';
+/** 是否是合法的 Solana 地址（base58，32 字节） */
+export function isAddress(value) {
+    if (typeof value !== 'string' || value.length < 32 || value.length > 44) {
+        return false;
+    }
+    try {
+        return base58.decode(value).length === 32;
+    }
+    catch {
+        return false;
+    }
+}
+export function decodeAddress(address) {
+    const bytes = base58.decode(address);
+    if (bytes.length !== 32) {
+        throw new Error(`Invalid Solana address: ${address}`);
+    }
+    return bytes;
+}
+export function encodeAddress(bytes) {
+    return base58.encode(bytes);
+}
+/** 32 字节是否在 ed25519 曲线上（PDA 必须不在曲线上） */
+function isOnCurve(bytes) {
+    try {
+        ed25519.Point.fromBytes(bytes);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const PDA_MARKER = new TextEncoder().encode('ProgramDerivedAddress');
+function concat(parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+// PDA 推导是纯计算但要做多次 sha256 + 曲线判断，结果缓存
+const pdaCache = new Map();
+/**
+ * 推导 PDA（与 web3.js PublicKey.findProgramAddressSync 相同），返回地址。
+ * seeds 每项不超过 32 字节。
+ */
+export function findProgramAddress(seeds, programId) {
+    const key = `${programId}:${seeds.map((s) => encodeAddress(s)).join(',')}`;
+    const cached = pdaCache.get(key);
+    if (cached) {
+        return cached;
+    }
+    const program = decodeAddress(programId);
+    for (let bump = 255; bump >= 0; bump--) {
+        const hash = sha256(concat([...seeds, new Uint8Array([bump]), program, PDA_MARKER]));
+        if (!isOnCurve(hash)) {
+            const address = encodeAddress(hash);
+            if (pdaCache.size > 10_000) {
+                pdaCache.clear();
+            }
+            pdaCache.set(key, address);
+            return address;
+        }
+    }
+    throw new Error('Unable to find a viable program address bump seed');
+}
+/** 关联代币账户（ATA）地址 */
+export function getAssociatedTokenAddress(owner, mint, tokenProgram) {
+    return findProgramAddress([decodeAddress(owner), decodeAddress(tokenProgram), decodeAddress(mint)], ASSOCIATED_TOKEN_PROGRAM_ID);
+}
+/** Metaplex Token Metadata 账户地址 */
+export function getMetadataAddress(mint) {
+    return findProgramAddress([new TextEncoder().encode('metadata'), decodeAddress(METADATA_PROGRAM_ID), decodeAddress(mint)], METADATA_PROGRAM_ID);
+}
+//# sourceMappingURL=address.js.map

package/dist/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","sourceRoot":"","sources":["../src/address.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,96 @@
+import { type Cluster } from './constants.js';
+import { type AccountInfo } from './layout.js';
+import { type RpcTransport } from './rpc.js';
+import { type RpcSource, type SourceOptions } from './source.js';
+import { type Commitment, type DefaultTokenField, type NftDetails, type NftOwner, type OwnedToken, type SolBalance, type TokenBalance, type TokenDetails, type TokenField } from './types.js';
+export interface ClientConfig extends SourceOptions {
+    /** 网络。不传 provider 时用于选择内置节点（默认 mainnet）；传了 provider 时用于校验节点所在网络 */
+    cluster?: Cluster;
+    /** 默认 'confirmed' */
+    commitment?: Commitment;
+    /** 视为原生 SOL 的 mint，默认 [So111…112（Wrapped SOL）, 11111…1（System Program）] */
+    nativeMints?: readonly string[];
+}
+export interface BalancesOptions {
+    /** 同时返回 symbol（代币查一次后缓存，主币为 SOL）。默认 false */
+    symbol?: boolean;
+    /**
+     * 用 getTokenAccountsByOwner 扫描持有人的全部代币账户（含非 ATA 账户、同一代币的多个账户合计）。
+     * 不传 mints 时总是扫描。注意：免费公共节点大多不支持这个方法，需要自己的节点。
+     */
+    scan?: boolean;
+}
+export interface OwnerTokensOptions {
+    /** 返回 name / symbol（代币查一次后缓存）。默认 true */
+    metadata?: boolean;
+    /** 第一项返回 SOL。默认 true */
+    includeNative?: boolean;
+    /** 包含余额为 0 的代币账户（如已清空但未关闭的 ATA）。默认 false */
+    includeZero?: boolean;
+    /** 包含 NFT（精度 0 且数量 1）。默认 false */
+    includeNfts?: boolean;
+}
+export interface TokensOptions<F extends TokenField = DefaultTokenField> {
+    /** 要返回的字段，默认 ['name', 'symbol', 'decimals'] */
+    fields?: readonly F[];
+}
+/** 测试用：清空代币信息缓存 */
+export declare function resetTokenMetaCache(): void;
+/**
+ * Solana 批量读取客户端。
+ *
+ * ```ts
+ * const sol = new SolanaClient()                                  // 内置公共节点（mainnet）
+ * const sol = new SolanaClient('https://my-rpc.example')          // 自己的节点
+ * const sol = new SolanaClient([connection, 'https://backup…'])   // web3.js Connection + 备用节点
+ *
+ * await sol.balances(owner, [NATIVE_MINT, USDC])
+ * await sol.tokens([USDC, PYUSD], { fields: ['name', 'symbol', 'decimals', 'supply'] })
+ * ```
+ *
+ * 同一 tick 内发起的 RPC 调用会合并成一个 JSON-RPC 批量请求；账户读取按 100 个一组用 getMultipleAccounts。
+ */
+export declare class SolanaClient {
+    #private;
+    readonly transport: RpcTransport;
+    constructor(provider?: RpcSource | readonly RpcSource[], config?: ClientConfig);
+    /** 节点所在网络（按创世区块哈希识别）；不是 mainnet / devnet / testnet 时为 null */
+    getCluster(): Promise<Cluster | null>;
+    /** 直接发 JSON-RPC 调用（同样参与自动合并与故障切换） */
+    request<T = unknown>(method: string, params?: readonly unknown[]): Promise<T>;
+    /**
+     * 批量读取账户（getMultipleAccounts，按 100 个一组，去重），结果与 addresses 一一对应。
+     * 账户不存在或地址非法时为 null。
+     */
+    accounts(addresses: readonly string[]): Promise<(AccountInfo | null)[]>;
+    /** 批量查多个地址的 SOL 余额（一次 getMultipleAccounts；账户不存在视为 0） */
+    solBalances(addresses: readonly string[]): Promise<SolBalance[]>;
+    /**
+     * 批量查余额（主币 SOL + SPL Token + Token-2022），返回原始余额、decimals 和换算后的数值。
+     *
+     * - 传 mints：本地推导 ATA，与主币账户、mint 账户一起用 getMultipleAccounts 一次读完，免费节点也能用
+     * - 不传 mints（或 scan: true）：用 getTokenAccountsByOwner 扫描全部代币账户，返回所有余额大于 0 的代币
+     */
+    balances(owner: string, mints?: readonly string[], options?: BalancesOptions): Promise<TokenBalance[]>;
+    /**
+     * 列出持有人拥有的全部代币（SOL 在第一位），带 name / symbol，适合做资产列表。
+     * 需要支持 getTokenAccountsByOwner 的节点（免费公共节点大多不支持）。
+     *
+     * - 默认不含 NFT（精度 0 且数量 1）和余额为 0 的代币账户（如已清空的 ATA），可用 includeNfts / includeZero 打开
+     * - accounts 是该代币的代币账户数量；大于 1 时余额为所有账户的合计
+     * - 顺序：SOL，然后 SPL Token 的代币，再然后 Token-2022 的代币（各自按节点返回的顺序；没有价格信息，不按价值排序）
+     */
+    ownerTokens(owner: string, options?: OwnerTokensOptions): Promise<OwnedToken[]>;
+    /**
+     * 批量查代币详情（一次 getMultipleAccounts），可以选择返回哪些字段。
+     * name / symbol / uri 优先取 Token-2022 TokenMetadata 扩展，其次 Metaplex 元数据。
+     */
+    tokens<const F extends TokenField = DefaultTokenField>(mints: readonly string[], options?: TokensOptions<F>): Promise<TokenDetails<F>[]>;
+    /** 批量查 NFT 元数据（Metaplex；Token-2022 NFT 取 TokenMetadata 扩展），一次 getMultipleAccounts */
+    nfts(mints: readonly string[]): Promise<NftDetails[]>;
+    /** 批量查 NFT 持有人：getTokenLargestAccounts（合并成一个批量请求）+ 一次 getMultipleAccounts */
+    nftOwners(mints: readonly string[]): Promise<NftOwner[]>;
+    /** 查某地址持有的全部 NFT（扫描代币账户：数量 1、精度 0），再批量读元数据。需要支持 getTokenAccountsByOwner 的节点 */
+    ownerNfts(owner: string): Promise<NftDetails[]>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}