Cách tra cứu danh tính ví Solana

Wallet API đang ở giai đoạn Beta. Các điểm cuối và định dạng phản hồi có thể thay đổi.

Tổng quan

Điểm cuối Wallet Identity xác định các địa chỉ ví đã biết trên Solana, bao gồm sàn giao dịch tập trung, giao thức DeFi, tổ chức và các thực thể được công nhận khác. Hãy sử dụng điểm cuối này cho mục đích tuân thủ, phân tích và hiển thị tên dễ đọc cho các địa chỉ đã biết. Cả điểm cuối đơn (GET /v1/wallet/{wallet}/identity) và hàng loạt (POST /v1/wallet/batch-identity, tối đa 100 mục) đều chấp nhận tên miền SNS .sol và TLD tùy chỉnh ANS (ví dụ: .bonk, .poor, .abc), ngoài địa chỉ Solana thô. Việc phân giải tên miền chỉ hỗ trợ mainnet. Điểm cuối này sử dụng cùng hệ thống danh tính vận hành Orb, trình khám phá khối Solana của Helius. Cơ sở dữ liệu bao gồm hơn 32.500 nhãn (tên chính dễ đọc, bao gồm hơn 3.000 chương trình) và hơn 21,5 triệu thẻ (các thuộc tính phân loại như “địa chỉ nạp tiền Binance” hoặc “Seeker Phone”), đồng thời liên tục được mở rộng. Cả điểm cuối đơn (GET /v1/wallet/{wallet}/identity) và hàng loạt (POST /v1/wallet/batch-identity) đều yêu cầu gói trả phí. Các yêu cầu sử dụng khóa API của gói Free sẽ trả về 403 Forbidden. Xem Yêu cầu về gói để biết bảng phạm vi hỗ trợ đầy đủ.

Khi nào nên sử dụng

Sử dụng Wallet Identity API khi cần:

Xác định ví của sàn giao dịch: xác định một ví có thuộc Binance, Coinbase, Kraken hoặc sàn khác hay không.
Theo dõi hoạt động giao thức: xác định ví của giao thức DeFi và địa chỉ kho bạc.
Tuân thủ và AML: gắn cờ các giao dịch liên quan đến thực thể đã biết.
Phân tích: phân loại các loại ví trong quy trình dữ liệu.
Trải nghiệm người dùng: hiển thị “Đã gửi đến Binance 1” thay cho địa chỉ thô.
Xử lý hàng loạt: tra cứu hàng trăm địa chỉ một cách hiệu quả.

Bắt đầu nhanh

Tra cứu một ví

Tra cứu thông tin danh tính của một địa chỉ ví:

JavaScript
Python
cURL

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");

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

curl "https://api.helius.xyz/v1/wallet/HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664/identity?api-key=YOUR_API_KEY"

Tra cứu theo tên miền

Bạn cũng có thể truyền trực tiếp tên miền SNS .sol hoặc TLD tùy chỉnh ANS — điểm cuối sẽ phân giải tên miền và trả về danh tính của địa chỉ chủ sở hữu:

JavaScript
Python
cURL

// Works identically — the endpoint resolves the domain first.
const identity = await getWalletIdentity("toly.sol");

// ANS custom TLD
await getWalletIdentity("miester.bonk");

# Works identically — the endpoint resolves the domain first.
identity = get_wallet_identity("toly.sol")

# ANS custom TLD
get_wallet_identity("miester.bonk")

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

Phản hồi của điểm cuối đơn là đối tượng danh tính tiêu chuẩn cho địa chỉ đã phân giải — không có dấu hiệu inputDomain. Nếu cần đối chiếu dữ liệu đầu vào với đầu ra (ví dụ: khi tra cứu nhiều tên miền cùng lúc), hãy sử dụng điểm cuối hàng loạt.

Việc phân giải tên miền chỉ hỗ trợ mainnet. Trên devnet/testnet, dữ liệu đầu vào là tên miền gửi đến điểm cuối này sẽ trả về 400. Các kết quả phân giải thành công được lưu vào bộ nhớ đệm tối đa 2 giờ, vì vậy một tên miền vừa được chuyển nhượng có thể tạm thời phân giải thành danh tính của chủ sở hữu trước đó.

Tra cứu hàng loạt (tối đa 100 mục)

Tra cứu nhiều mục trong một yêu cầu để đạt hiệu suất tốt hơn. Mỗi mục có thể là một địa chỉ hoặc tên miền:

JavaScript
Python
cURL

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}`);
  });
});

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']}")

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"
    ]
  }'

Định dạng phản hồi

Một lần tra cứu đơn thành công sẽ trả về đối tượng danh tính của địa chỉ đã phân giải:

{
  "address": "HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664",
  "type": "exchange",
  "name": "Binance 1",
  "category": "Centralized Exchange",
  "tags": ["Centralized Exchange"]
}

Trong phản hồi hàng loạt, mọi mục có dữ liệu đầu vào là tên miền đều chứa thêm trường inputDomain để bạn có thể đối chiếu phản hồi với yêu cầu ban đầu:

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

Khi không thể phân giải một tên miền trong yêu cầu hàng loạt, toàn bộ lô sẽ không thất bại — mục đó được trả về đúng vị trí với address: null, type: "unknown" và unresolved: true. Thứ tự yêu cầu được giữ nguyên:

{
  "address": null,
  "type": "unknown",
  "inputDomain": "nonexistent-xyz.sol",
  "unresolved": true
}

Trên điểm cuối đơn, mã 404 được trả về nếu ví không có mục danh tính hoặc không thể phân giải dữ liệu đầu vào là tên miền:

{
  "error": "No identity information available for this address",
  "code": 404
}

{
  "error": "Domain 'nonexistent-xyz.sol' could not be resolved",
  "code": 404
}

Danh mục danh tính

Ví và chương trình được phân loại bằng các danh mục từ cơ sở dữ liệu danh tính Orb. Tài khoản và chương trình sử dụng các tập hợp danh mục riêng biệt. Các bảng dưới đây liệt kê mọi danh mục được hỗ trợ.

Account tag types

Danh mục	Mô tả	Ví dụ
Sàn giao dịch tập trung	Ví CEX và ví nóng	Binance 1, Coinbase 1, Kraken, OKX Exchange 1, Bybit Hot Wallet
Cầu nối chuỗi chéo	Địa chỉ của giao thức cầu nối	Wormhole Bridge, AllBridge, Portal Bridge, deBridge
DeFi	Địa chỉ của giao thức DeFi	Jupiter, Raydium, Orca, Marinade Finance, Kamino
Người có ảnh hưởng chính	Các cá nhân và người có ảnh hưởng nổi bật	Anatoly Yakovenko, Raj Gokal
Nhà tạo lập thị trường	Các công ty tạo lập thị trường	Jump Trading, Wintermute, GSR Markets
Công ty giao dịch	Các công ty tự doanh	Alameda Research, DRW Trading
Trình xác thực	Địa chỉ trình xác thực và nhóm stake	Coinbase Validator, Jito Validator, Figment Validator
Kho bạc	Kho bạc của dự án và giao thức	Marinade Treasury, Helium Treasury, Solana Foundation Treasury
DAO	Các tổ chức tự trị phi tập trung	Mango DAO, Grape DAO, MonkeDAO Treasury
NFT	Các thị trường và dự án NFT	Magic Eden, Tensor, OpenSea Solana, DeGods Treasury
Nhóm stake	Địa chỉ nhóm staking thanh khoản	Marinade Stake Pool, Jito Stake Pool, BlazeStake
Đa chữ ký	Ví đa chữ ký	Squads Multisig, Solana Foundation Multisig
Oracle	Nhà cung cấp nguồn cấp giá và oracle	Pyth Network, Switchboard Oracle, Chainlink Solana
Trò chơi	Các dự án trò chơi và GameFi	Star Atlas, Aurory, Genopets Treasury
Thanh toán	Đơn vị xử lý thanh toán	Solana Pay, Sphere, Helio Pay
Công cụ	Công cụ và tiện ích dành cho nhà phát triển	Phantom Wallet, Backpack, Solflare Wallet
Airdrop	Địa chỉ phân phối airdrop	Jupiter Airdrop, Pyth Airdrop Distributor
Quản trị	Địa chỉ chương trình quản trị	Realms Governance, SPL Governance
Thẩm quyền	Cơ quan có thẩm quyền và quản trị viên của chương trình	Token Program Authority, Metaplex Authority
Jito	Địa chỉ dành riêng cho Jito	Jito Tip 1, Jito Tip 2, Jito MEV Payment
Memecoin	Các dự án memecoin	Bonk Treasury, Dogwifhat, Book of Meme
Sòng bạc và cờ bạc	Các dApp cờ bạc và sòng bạc	Stake.com Hot Wallet, Rollbit, DexSport
DePIN	Cơ sở hạ tầng vật lý phi tập trung	Helium Network, Render Network, Hivemapper
AMM độc quyền	Các triển khai AMM tùy chỉnh	Phoenix DEX, GooseFX
Restaking	Các giao thức restaking	Solayer, Fragmetric
Kho lưu trữ	Địa chỉ kho lưu trữ và lưu ký	Solend Vault, Tulip Vault, Francium Vault
Phí	Địa chỉ thu phí	Jupiter Fee Collector, Raydium Fees
Gây quỹ	Địa chỉ gây quỹ và ICO	Token Sale Wallet, Fundraise Multisig
Phân phối khối khởi nguyên	Địa chỉ phân phối khởi nguyên	Solana Genesis Distribution
Nguồn cung không lưu hành	Địa chỉ token không lưu hành	Team Vesting Wallet, Foundation Reserve
Gửi giao dịch	Dịch vụ gửi giao dịch	Jito Tip 1, Jito Tip 2, Helius Sender Tip 1
Hệ thống	Các chương trình hệ thống Solana	System Program, Config Program
X402	Địa chỉ giao thức X402	X402 Protocol
Khác	Các địa chỉ đã biết chưa được phân loại	Nhiều ví đã biết

Malicious categories

Danh mục	Mô tả	Ví dụ
Kẻ khai thác lỗ hổng, tin tặc và lừa đảo	Các địa chỉ khai thác lỗ hổng và tấn công đã biết	Wormhole Exploiter Wallet, SagaDAO Hacker Wallet, Mango Exploiter
Tin tặc	Địa chỉ tin tặc đã được xác nhận	Solana Hack 2022, DeFi Protocol Hacker
Kẻ rug pull	Thủ phạm thực hiện rug pull	Squid Game Token Rugger, Known Rug Pull Wallet
Kẻ lừa đảo	Địa chỉ lừa đảo đã được xác nhận	Fake Airdrop Scammer, Phishing Scam Wallet
Spam	Người tạo token spam	Spam Token Creator, Airdrop Spammer

Program categories

Các chương trình (hợp đồng thông minh) được phân loại riêng:

Danh mục	Mô tả	Ví dụ
Hoán đổi	Giao thức hoán đổi token	Jupiter, Raydium, Orca
DeFi	Các giao thức DeFi nói chung	Drift, Mango
Vay và cho vay	Giao thức cho vay	Solend, MarginFi
NFT	Thị trường NFT	Magic Eden, Tensor
Staking	Chương trình staking	Marinade, Jito
Cầu nối	Cầu nối chuỗi chéo	Wormhole, AllBridge
Trình tổng hợp	Trình tổng hợp DEX	Jupiter Aggregator
Hợp đồng vĩnh cửu	Hợp đồng tương lai vĩnh cửu	Drift, Mango
Oracle	Nhà cung cấp oracle	Pyth, Switchboard
Bệ phóng	Bệ phóng token	Raydium Launchpad
Quản trị	Chương trình quản trị	SPL Governance
Trò chơi hoặc sòng bạc	Chương trình trò chơi	Star Atlas
Thị trường dự đoán	Thị trường dự đoán	Drift Predictions
Thanh toán	Giao thức thanh toán	Solana Pay
Quyền riêng tư	Giao thức quyền riêng tư	Elusiv
Nén	Nén trạng thái	Bubblegum
Cơ sở hạ tầng	Cơ sở hạ tầng cốt lõi	Metaplex
Công cụ	Công cụ dành cho nhà phát triển	Clockwork
RWA	Tài sản trong thế giới thực	Ondo Finance
DePIN	Cơ sở hạ tầng phi tập trung	Helium, Render
DeSci	Khoa học phi tập trung	VitaDAO
Airdrop	Chương trình airdrop	Trình phân phối Merkle
Web3	Ứng dụng Web3	Nhiều loại
Gốc	Chương trình gốc của Solana	System Program
AMM độc quyền	Thiết kế AMM tùy chỉnh	Phoenix
Bot bắn tỉa giao dịch	Bot giao dịch	Bot MEV
Bot chênh lệch giá hoặc sandwich	Bot MEV và chênh lệch giá	Gói Jito
Spam	Chương trình spam	Token spam
Khác	Chương trình chưa được phân loại	Nhiều loại

Trường hợp sử dụng

Gắn cờ các khoản nạp vào sàn giao dịch

Xác định thời điểm tiền được gửi đến một sàn giao dịch tập trung:

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;
};

Hiển thị tên dễ đọc

Hiển thị tên thân thiện trong giao diện người dùng thay cho địa chỉ:

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"

Xử lý hàng loạt các đối tác giao dịch

Xác định hiệu quả tất cả đối tác trong danh sách giao dịch:

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"
  }));
};

Các phương pháp hay nhất

Sử dụng điểm cuối hàng loạt cho nhiều lần tra cứu. Khi tra cứu nhiều hơn một địa chỉ, POST /v1/wallet/batch-identity nhanh hơn đáng kể so với việc gửi từng yêu cầu riêng lẻ.
Xử lý phản hồi 404 phù hợp. Không phải ví nào cũng có thông tin danh tính. Nếu không có, hãy hiển thị địa chỉ thô.
Lưu kết quả vào bộ nhớ đệm. Dữ liệu danh tính ít khi thay đổi. Hãy lưu vào bộ nhớ đệm cục bộ để giảm số lệnh gọi API.
Tuân thủ giới hạn kích thước lô. Điểm cuối hàng loạt hỗ trợ tối đa 100 mục cho mỗi yêu cầu. Hãy chia các tập dữ liệu lớn hơn thành các lô phù hợp.

Lỗi thường gặp

Mã lỗi	Mô tả	Giải pháp
400	Địa chỉ ví hoặc định dạng tên miền không hợp lệ, hoặc sử dụng tên miền trên mạng không phải mainnet	Xác minh dữ liệu đầu vào là địa chỉ Solana base58 hợp lệ hoặc tên miền có định dạng đúng (ví dụ: `toly.sol`), đồng thời bảo đảm bạn đang nhắm đến mainnet
401	Thiếu khóa API hoặc khóa API không hợp lệ	Kiểm tra để bảo đảm khóa API được đưa vào yêu cầu
403	Điểm cuối yêu cầu gói trả phí	Tính năng tra cứu danh tính không có trong gói Free. Hãy nâng cấp gói lên cấp trả phí
404	Không tìm thấy danh tính hoặc không thể phân giải tên miền	Chỉ áp dụng cho điểm cuối đơn — ví không có mục danh tính hoặc tên miền không tồn tại. Trong yêu cầu hàng loạt, các tên miền không thể phân giải được trả về dưới dạng mục `unresolved: true` thay vì mã 404
429	Vượt quá giới hạn tốc độ	Giảm tần suất yêu cầu hoặc nâng cấp gói

Các bước tiếp theo

Funding Source

Truy vết nguồn ban đầu cấp tiền cho ví — các loại nguồn cấp tiền sử dụng lại những danh mục danh tính này.

Wallet API Overview

Tất cả điểm cuối Wallet API và các quy ước dùng chung.

API Reference

Lược đồ yêu cầu và phản hồi cho thao tác tra cứu danh tính.

Bắt đầu

Truyền phát dữ liệu & lắng nghe sự kiện

API dữ liệu & RPC

Giao dịch

Gửi giao dịch

Ví dưới dạng dịch vụ

Quyền riêng tư

Tài nguyên

Cách tra cứu danh tính ví Solana

Tổng quan

Khi nào nên sử dụng

Bắt đầu nhanh

Tra cứu một ví

Tra cứu theo tên miền

Tra cứu hàng loạt (tối đa 100 mục)

Định dạng phản hồi

Danh mục danh tính

Trường hợp sử dụng

Gắn cờ các khoản nạp vào sàn giao dịch

Hiển thị tên dễ đọc

Xử lý hàng loạt các đối tác giao dịch

Các phương pháp hay nhất

Lỗi thường gặp

Các bước tiếp theo

Funding Source

Wallet API Overview

API Reference

​Tổng quan

​Khi nào nên sử dụng

​Bắt đầu nhanh

​Tra cứu một ví

​Tra cứu theo tên miền

​Tra cứu hàng loạt (tối đa 100 mục)

​Định dạng phản hồi

​Danh mục danh tính

​Trường hợp sử dụng

​Gắn cờ các khoản nạp vào sàn giao dịch

​Hiển thị tên dễ đọc

​Xử lý hàng loạt các đối tác giao dịch

​Các phương pháp hay nhất

​Lỗi thường gặp

​Các bước tiếp theo

Funding Source

Wallet API Overview

API Reference

Tổng quan

Khi nào nên sử dụng

Bắt đầu nhanh

Tra cứu một ví

Tra cứu theo tên miền

Tra cứu hàng loạt (tối đa 100 mục)

Định dạng phản hồi

Danh mục danh tính

Trường hợp sử dụng

Gắn cờ các khoản nạp vào sàn giao dịch

Hiển thị tên dễ đọc

Xử lý hàng loạt các đối tác giao dịch

Các phương pháp hay nhất

Lỗi thường gặp

Các bước tiếp theo