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

# 如何查找Solana钱包身份

> 通过地址或SNS/ANS域识别已知的Solana钱包。一次查找单个条目或批量处理最多100个地址和域。

<Note>
  Wallet API 处于测试阶段。端点和响应格式可能会发生变化。
</Note>

## 概述

Wallet Identity 端点用于识别 Solana 上已知的钱包地址，包括中心化交易所、DeFi 协议、机构和其他公认的实体。可用于合规、分析和显示已知地址的人类可读名称。

单个 (`GET /v1/wallet/{wallet}/identity`) 及批量 (`POST /v1/wallet/batch-identity`, 最多100个条目) 端点接收 **SNS `.sol` 域名** 和 **ANS 自定义 TLD** (例如 `.bonk`, `.poor`, `.abc`) 以及原始 Solana 地址。域名解析仅限主网。

此端点使用与 [Orb](https://orbmarkets.io/) 和 Helius Solana 区块浏览器相同的身份系统。数据库包含超过 32,500 个标签（人类可读的主要名称，包括 3,000 多个程序）和超过 2150 万个标签（如“Binance 存款地址”或“Seeker Phone”这样的分类属性），并在不断增长中。

单个 (`GET /v1/wallet/{wallet}/identity`) 和批量 (`POST /v1/wallet/batch-identity`) 端点都需要付费计划。使用免费计划 API 密钥进行的请求将返回 `403 Forbidden`。查看[计划要求](/zh/wallet-api/overview#plan-requirements)以获取完整的覆盖表。

## 何时使用

当您需要以下操作时，使用钱包身份 API：

* **识别交易所钱包**：确定钱包是否属于 Binance、Coinbase、Kraken 等。
* **跟踪协议活动**：识别 DeFi 协议钱包和资金地址。
* **合规性和AML**：标记涉及已知实体的交易。
* **分析**：在数据管道中分类钱包类型。
* **用户体验**：显示“发送到 Binance 1”而不是原始地址。
* **批处理**：高效查找数百个地址。

## 快速入门

### 单钱包查找

查找单个钱包地址的身份信息：

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"system"}
    const getWalletIdentity = async (address) => {
      const url = `https://api.helius.xyz/v1/wallet/${address}/identity?api-key=YOUR_API_KEY`;

      const response = await fetch(url);
      if (!response.ok) {
        if (response.status === 404) {
          console.log("No identity found for this address");
          return null;
        }
        throw new Error(`HTTP error! status: ${response.status}`);
      }

      const identity = await response.json();
      console.log(`Found: ${identity.name} (${identity.category})`);
      return identity;
    };

    // Example: Binance wallet
    getWalletIdentity("HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664");
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    import requests

    def get_wallet_identity(address: str):
        url = f"https://api.helius.xyz/v1/wallet/{address}/identity"
        headers = {"X-Api-Key": "YOUR_API_KEY"}

        response = requests.get(url, headers=headers)

        if response.status_code == 404:
            print("No identity found for this address")
            return None

        response.raise_for_status()
        identity = response.json()
        print(f"Found: {identity['name']} ({identity['category']})")
        return identity

    # Example: Binance wallet
    get_wallet_identity("HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664")
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"system"}
    curl "https://api.helius.xyz/v1/wallet/HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664/identity?api-key=YOUR_API_KEY"
    ```
  </Tab>
</Tabs>

#### 按域名查找

您还可以直接传递 SNS `.sol` 域或 ANS 自定义 TLD — 端点将解析该域并返回所有者地址的身份信息：

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"system"}
    // Works identically — the endpoint resolves the domain first.
    const identity = await getWalletIdentity("toly.sol");

    // ANS custom TLD
    await getWalletIdentity("miester.bonk");
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    # Works identically — the endpoint resolves the domain first.
    identity = get_wallet_identity("toly.sol")

    # ANS custom TLD
    get_wallet_identity("miester.bonk")
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"system"}
    # SNS (.sol) domain
    curl "https://api.helius.xyz/v1/wallet/toly.sol/identity?api-key=YOUR_API_KEY"

    # ANS custom TLD
    curl "https://api.helius.xyz/v1/wallet/miester.bonk/identity?api-key=YOUR_API_KEY"
    ```
  </Tab>
</Tabs>

单端点响应是**已解析**地址的标准身份对象 — 没有 `inputDomain` 标记。如果需要将输入与输出相关联（例如，同时查找多个域时），请使用批处理端点。

<Note>
  域名解析仅适用于主网。在开发网络/测试网络中，输入此端点的域名将返回 `400`。正向解析最多缓存2小时，因此最近转移的域名可能会暂时解析为前所有者的身份。
</Note>

### 批量查询（最多 100 个条目）

在单个请求中查询多个条目以提高性能。每个条目可以是一个地址或域名：

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"system"}
    const batchIdentityLookup = async (addresses) => {
      const url = "https://api.helius.xyz/v1/wallet/batch-identity?api-key=YOUR_API_KEY";

      const response = await fetch(url, {
        method: "POST",
        headers: {
          "Content-Type": "application/json"
        },
        body: JSON.stringify({ addresses })
      });

      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }

      const identities = await response.json();
      return identities;
    };

    // Example: Mix addresses and domains in a single request
    const addresses = [
      "HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664", // Binance (address)
      "toly.sol",                                      // SNS domain
      "miester.bonk"                                   // ANS custom TLD
    ];

    batchIdentityLookup(addresses).then(identities => {
      identities.forEach(identity => {
        if (identity.unresolved) {
          console.log(`${identity.inputDomain}: could not be resolved`);
          return;
        }
        const label = identity.inputDomain
          ? `${identity.inputDomain} → ${identity.address}`
          : identity.address;
        console.log(`${label}: ${identity.name}`);
      });
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    import requests

    def batch_identity_lookup(addresses: list[str]):
        url = "https://api.helius.xyz/v1/wallet/batch-identity"
        headers = {
            "X-Api-Key": "YOUR_API_KEY",
            "Content-Type": "application/json"
        }

        response = requests.post(
            url,
            headers=headers,
            json={"addresses": addresses}
        )

        response.raise_for_status()
        return response.json()

    # Example: Mix addresses and domains in a single request
    addresses = [
        "HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664",  # Binance (address)
        "toly.sol",                                       # SNS domain
        "miester.bonk"                                    # ANS custom TLD
    ]

    identities = batch_identity_lookup(addresses)
    for identity in identities:
        if identity.get("unresolved"):
            print(f"{identity['inputDomain']}: could not be resolved")
            continue
        label = f"{identity['inputDomain']} -> {identity['address']}" if identity.get("inputDomain") else identity["address"]
        print(f"{label}: {identity['name']}")
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"system"}
    curl -X POST "https://api.helius.xyz/v1/wallet/batch-identity?api-key=YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "addresses": [
          "HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664",
          "toly.sol",
          "miester.bonk"
        ]
      }'
    ```
  </Tab>
</Tabs>

## 响应格式

成功的单次查询返回解析地址的身份对象：

```json theme={"system"}
{
  "address": "HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664",
  "type": "exchange",
  "name": "Binance 1",
  "category": "Centralized Exchange",
  "tags": ["Centralized Exchange"]
}
```

在**批量**响应中，任何输入为域名的条目都会携带额外的 `inputDomain` 字段，以便将响应与原始请求关联：

```json theme={"system"}
{
  "address": "7v91N7iZ9mNicL8WfG6cgSCKyRXydQjLh6UYBWwm6y1Q",
  "type": "wallet",
  "name": "toly",
  "category": "Key Opinion Leader",
  "tags": ["Key Opinion Leader"],
  "inputDomain": "toly.sol"
}
```

当批量请求中的域名无法解析时，批次不会失败——条目以 `address: null`, `type: "unknown"` 和 `unresolved: true` 返回。请求顺序得到保留：

```json theme={"system"}
{
  "address": null,
  "type": "unknown",
  "inputDomain": "nonexistent-xyz.sol",
  "unresolved": true
}
```

在**单次**端点上，如果钱包没有身份条目**或**域名输入无法解析，则返回404：

```json theme={"system"}
{
  "error": "No identity information available for this address",
  "code": 404
}
```

```json theme={"system"}
{
  "error": "Domain 'nonexistent-xyz.sol' could not be resolved",
  "code": 404
}
```

### 身份类别

钱包和程序被分类到由 Orb 身份数据库支持的类别中。账户和程序使用不同的类别集合。下表列出了每个支持的类别。

<AccordionGroup>
  <Accordion title="账户标签类型">
    | 类别     | 描述            | 示例                                                              |
    | ------ | ------------- | --------------------------------------------------------------- |
    | 中心化交易所 | CEX 钱包和热钱包    | Binance 1, Coinbase 1, Kraken, OKX Exchange 1, Bybit Hot Wallet |
    | 跨链桥    | 桥接协议地址        | Wormhole Bridge, AllBridge, Portal Bridge, deBridge             |
    | DeFi   | DeFi 协议地址     | Jupiter, Raydium, Orca, Marinade Finance, Kamino                |
    | 关键意见领袖 | 知名个人和影响者      | Anatoly Yakovenko, Raj Gokal                                    |
    | 市场制造商  | 做市公司          | Jump Trading, Wintermute, GSR Markets                           |
    | 交易公司   | 自营交易公司        | Alameda Research, DRW Trading                                   |
    | 验证者    | 验证者和质押池地址     | Coinbase Validator, Jito Validator, Figment Validator           |
    | 财库     | 项目和协议资金       | Marinade Treasury, Helium Treasury, Solana Foundation Treasury  |
    | DAO    | 去中心化自治组织      | Mango DAO, Grape DAO, MonkeDAO Treasury                         |
    | NFT    | NFT 市场和项目     | Magic Eden, Tensor, OpenSea Solana, DeGods Treasury             |
    | 质押池    | 流动性质押池地址      | Marinade Stake Pool, Jito Stake Pool, BlazeStake                |
    | 多签     | 多重签名钱包        | Squads Multisig, Solana Foundation Multisig                     |
    | 预言机    | 价格馈送和预言机提供者   | Pyth Network, Switchboard Oracle, Chainlink Solana              |
    | 游戏     | 游戏和 GameFi 项目 | Star Atlas, Aurory, Genopets Treasury                           |
    | 支付     | 支付处理器         | Solana Pay, Sphere, Helio Pay                                   |
    | 工具     | 开发者工具和实用程序    | Phantom Wallet, Backpack, Solflare Wallet                       |
    | 空投     | 空投分发地址        | Jupiter Airdrop, Pyth Airdrop Distributor                       |
    | 治理     | 治理程序地址        | Realms Governance, SPL Governance                               |
    | 授权     | 程序授权和管理员      | Token Program Authority, Metaplex Authority                     |
    | Jito   | Jito 专用地址     | Jito Tip 1, Jito Tip 2, Jito MEV Payment                        |
    | 表情币    | 表情币项目         | Bonk Treasury, Dogwifhat, Book of Meme                          |
    | 赌场和博彩  | 博彩和赌场 dApps   | Stake.com Hot Wallet, Rollbit, DexSport                         |
    | DePIN  | 去中心化物理基础设施    | Helium Network, Render Network, Hivemapper                      |
    | 专有 AMM | 自定义 AMM 实现    | Phoenix DEX, GooseFX                                            |
    | 再质押    | 再质押协议         | Solayer, Fragmetric                                             |
    | 保险库    | 保险库和托管地址      | Solend Vault, Tulip Vault, Francium Vault                       |
    | 费用     | 费用收集地址        | Jupiter Fee Collector, Raydium Fees                             |
    | 融资     | 融资和 ICO 地址    | Token Sale Wallet, Fundraise Multisig                           |
    | 创世区块分发 | 创世分发地址        | Solana Genesis Distribution                                     |
    | 非流通供应  | 非流通代币地址       | Team Vesting Wallet, Foundation Reserve                         |
    | 交易发送   | 交易发送服务        | Jito Tip 1, Jito Tip 2, Helius Sender Tip 1                     |
    | 系统     | Solana 系统程序   | System Program, Config Program                                  |
    | X402   | X402 协议地址     | X402 Protocol                                                   |
    | 其他     | 未分类的已知地址      | 各种已知钱包                                                          |
  </Accordion>

  <Accordion title="恶意类别">
    | 类别        | 描述         | 示例                                                                |
    | --------- | ---------- | ----------------------------------------------------------------- |
    | 利用者、黑客和骗局 | 已知的利用和黑客地址 | Wormhole Exploiter Wallet, SagaDAO Hacker Wallet, Mango Exploiter |
    | 黑客        | 确认的黑客地址    | Solana Hack 2022, DeFi Protocol Hacker                            |
    | 拉盘者       | 拉盘行为的实施者   | Squid Game Token Rugger, 已知拉盘钱包                                   |
    | 骗子        | 确认的骗局地址    | 假空投骗局, 钓鱼骗局钱包                                                     |
    | 垃圾        | 垃圾代币创建者    | 垃圾代币创建者, 空投垃圾邮件发送者                                                |
  </Accordion>

  <Accordion title="程序类别">
    程序（智能合约）单独分类：

    | 类别        | 描述         | 示例                     |
    | --------- | ---------- | ---------------------- |
    | 交换        | 代币交换协议     | Jupiter, Raydium, Orca |
    | DeFi      | 一般DeFi协议   | Drift, Mango           |
    | 借贷        | 借贷协议       | Solend, MarginFi       |
    | NFT       | NFT市场      | Magic Eden, Tensor     |
    | 质押        | 质押程序       | Marinade, Jito         |
    | 桥接        | 跨链桥        | Wormhole, AllBridge    |
    | 聚合器       | DEX聚合器     | Jupiter Aggregator     |
    | 永续合约      | 永续期货       | Drift, Mango           |
    | 预言机       | 预言机提供者     | Pyth, Switchboard      |
    | 启动板       | 代币启动板      | Raydium Launchpad      |
    | 治理        | 治理程序       | SPL Governance         |
    | 游戏或赌场     | 游戏程序       | Star Atlas             |
    | 预测市场      | 预测市场       | Drift Predictions      |
    | 支付        | 支付协议       | Solana Pay             |
    | 隐私        | 隐私协议       | Elusiv                 |
    | 压缩        | 状态压缩       | Bubblegum              |
    | 基础设施      | 核心基础设施     | Metaplex               |
    | 工具        | 开发者工具      | Clockwork              |
    | RWA       | 实物资产       | Ondo Finance           |
    | DePIN     | 去中心化基础设施   | Helium, Render         |
    | DeSci     | 去中心化科学     | VitaDAO                |
    | 空投        | 空投程序       | Merkle distributors    |
    | Web3      | Web3应用程序   | 各种                     |
    | 原生        | Solana原生程序 | System Program         |
    | 专有AMM     | 自定义AMM设计   | Phoenix                |
    | 交易狙击手     | 交易机器人      | MEV bots               |
    | 套利或三明治机器人 | MEV和套利机器人  | Jito bundles           |
    | 垃圾        | 垃圾程序       | 垃圾代币                   |
    | 其他        | 未分类程序      | 各种                     |
  </Accordion>
</AccordionGroup>

## 使用案例

### 标记交易所存款

识别资金何时被发送到中心化交易所：

```javascript theme={"system"}
const checkIfExchange = async (address) => {
  try {
    const identity = await getWalletIdentity(address);
    if (identity && identity.category === "Centralized Exchange") {
      console.log(`Funds sent to ${identity.name}`);
      return true;
    }
  } catch (error) {
    // Not a known exchange
  }
  return false;
};
```

### 显示可读名称

在你的用户界面中显示友好名称而不是地址：

```javascript theme={"system"}
const getDisplayName = async (address) => {
  try {
    const identity = await getWalletIdentity(address);
    return identity ? identity.name : shortenAddress(address);
  } catch (error) {
    return shortenAddress(address);
  }
};

// Usage in UI
const displayName = await getDisplayName("HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664");
// Returns: "Binance 1" instead of "HXsKP...G664"
```

### 批处理交易对手

高效识别交易列表中的所有对手方：

```javascript theme={"system"}
const identifyTransactionCounterparties = async (transactions) => {
  // Extract all unique addresses
  const addresses = [...new Set(
    transactions.map(tx => tx.counterparty)
  )];

  // Batch lookup (up to 100 at a time)
  const allIdentities = [];
  for (let i = 0; i < addresses.length; i += 100) {
    const chunk = addresses.slice(i, i + 100);
    const identities = await batchIdentityLookup(chunk);
    allIdentities.push(...identities);
  }

  // Create a map for quick lookup
  const identityMap = new Map(
    allIdentities.map(id => [id.address, id])
  );

  // Enrich transactions with identity info
  return transactions.map(tx => ({
    ...tx,
    counterpartyName: identityMap.get(tx.counterparty)?.name || "Unknown"
  }));
};
```

## 最佳实践

* **使用批处理端点进行多个查询。** 查询多个地址时，`POST /v1/wallet/batch-identity` 比逐个请求快得多。
* **优雅处理404响应。** 并非所有钱包都有身份信息。显示原始地址作为备用。
* **缓存结果。** 身份数据很少改变。本地缓存以减少API调用。
* **遵守批处理大小限制。** 批处理端点每个请求支持最多100个条目。相应地分块较大数据集。

## 常见错误

| 错误代码 | 描述                   | 解决方案                                                                 |
| ---- | -------------------- | -------------------------------------------------------------------- |
| 400  | 无效的钱包地址或域格式，或在非主网输入域 | 确认输入是有效的 base58 Solana 地址或格式良好的域（例如 `toly.sol`），并且您正在目标主网            |
| 401  | 缺失或无效的 API 密钥        | 确保在请求中包含您的 API 密钥                                                    |
| 403  | 端点需要付费计划             | 身份查询不在免费计划中可用。 [升级您的计划](https://dashboard.helius.dev) 至付费层           |
| 404  | 未找到身份，或域无法解析         | 仅限单一端点——钱包没有身份条目，或域不存在。在批处理请求中，不可解析的域以 `unresolved: true` 项返回，而不是404 |
| 429  | 超出速率限制               | 减少请求频率或升级您的计划                                                        |

## 后续步骤

<CardGroup cols={3}>
  <Card title="资金来源" icon="money-bill-transfer" href="/zh/wallet-api/funded-by">
    追踪最初是谁资助了一个钱包——资助者类型重用这些身份类别。
  </Card>

  <Card title="钱包API概览" icon="wallet" href="/zh/wallet-api/overview">
    所有钱包API端点和共享约定。
  </Card>

  <Card title="API参考" icon="code" href="/zh/api-reference/wallet-api/identity">
    身份查找的请求和响应模式。
  </Card>
</CardGroup>