> ## 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.
# Cách tra cứu danh tính ví Solana
> Xác định các ví Solana đã biết theo địa chỉ hoặc tên miền SNS/ANS. Tra cứu từng mục hoặc xử lý hàng loạt tối đa 100 địa chỉ và tên miền cùng lúc.
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](https://orbmarkets.io/), 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](/docs/vi/wallet-api/overview#yêu-cầu-về-gói-dịch-vụ) để 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 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");
```
```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")
```
```bash theme={"system"}
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 theme={"system"}
// Works identically — the endpoint resolves the domain first.
const identity = await getWalletIdentity("toly.sol");
// ANS custom TLD
await getWalletIdentity("miester.bonk");
```
```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")
```
```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"
```
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 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}`);
});
});
```
```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']}")
```
```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"
]
}'
```
## Đị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:
```json theme={"system"}
{
"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:
```json theme={"system"}
{
"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:
```json theme={"system"}
{
"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:
```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
}
```
### 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ợ.
| 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 |
| 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 |
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:
```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;
};
```
### 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ỉ:
```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"
```
### 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:
```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"
}));
};
```
## 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](https://dashboard.helius.dev) 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
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.
Tất cả điểm cuối Wallet API và các quy ước dùng chung.
Lược đồ yêu cầu và phản hồi cho thao tác tra cứu danh tính.