> ## 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개의 주소 및 도메인을 한 번에 일괄 처리.
Wallet API는 베타 버전입니다. 엔드포인트 및 응답 형식은 변경될 수 있습니다.
## 개요
Wallet Identity 엔드포인트는 Solana의 알려진 지갑 주소, 중앙화된 거래소, DeFi 프로토콜, 기관 및 기타 인식된 엔티티를 식별합니다. 이를 준수, 분석 및 알려진 주소의 사람이 읽을 수 있는 이름 표시를 위해 사용하세요.
단일 (`GET /v1/wallet/{wallet}/identity`) 및 배치 (`POST /v1/wallet/batch-identity`, 최대 100개 항목) 엔드포인트는 원시 Solana 주소 외에도 **SNS `.sol` 도메인** 및 **ANS 커스텀 TLD** (예: `.bonk`, `.poor`, `.abc`)를 허용합니다. 도메인 해상도는 메인넷 전용입니다.
이 엔드포인트는 Helius Solana 블록 탐색기인 [Orb](https://orbmarkets.io/)를 구동하는 동일한 신원 시스템을 사용합니다. 데이터베이스에는 32,500개 이상의 레이블(사람이 읽을 수 있는 주요 이름, 3,000개 이상의 프로그램 포함)과 21.5M 이상의 태그(예: "Binance 입금 주소" 또는 "Seeker Phone"과 같은 범주 속성)가 포함되어 있으며 지속적으로 증가하고 있습니다.
단일 (`GET /v1/wallet/{wallet}/identity`) 및 배치 (`POST /v1/wallet/batch-identity`) 엔드포인트는 유료 플랜이 필요합니다. Free-plan API 키로 요청을 하면 `403 Forbidden`가 반환됩니다. 전체 적용 범위 표는 [플랜 요구 사항](/docs/ko/wallet-api/overview#플랜-요구-사항)을 참조하세요.
## 사용 시점
Wallet Identity API를 사용할 때:
* **거래소 지갑 식별**: 지갑이 Binance, Coinbase, Kraken 등에 속해 있는지 확인.
* **프로토콜 활동 추적**: DeFi 프로토콜 지갑 및 재무 주소 식별.
* **준법 및 AML**: 알려진 엔티티와 관련된 거래 플래그 표시.
* **분석**: 데이터 파이프라인에서 지갑 유형 분류.
* **사용자 경험**: 원시 주소 대신 "Sent to Binance 1"을 표시.
* **일괄 처리**: 수백 개의 주소를 효율적으로 조회.
## 빠른 시작
### 단일 지갑 조회
단일 지갑 주소에 대한 신원 정보를 조회합니다:
```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"
```
#### 도메인 이름으로 조회
SNS `.sol` 도메인이나 ANS 커스텀 TLD를 직접 전달할 수도 있습니다 — 엔드포인트가 도메인을 해석하고 소유자 주소의 신원을 반환합니다:
```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"
```
단일 엔드포인트 응답은 **해석된** 주소에 대한 표준 신원 객체입니다 — `inputDomain` 표시가 없습니다. 여러 도메인을 한 번에 조회할 경우 입력과 출력을 연관시킬 필요가 있다면 배치 엔드포인트를 사용하세요.
도메인 해상도는 메인넷 전용입니다. devnet/testnet에서는 이 엔드포인트에 도메인을 입력하면 `400`가 반환됩니다. 긍정적인 해상도는 최대 2시간 동안 캐시되므로 최근에 전송된 도메인이 잠시 동안 이전 소유자의 신원으로 해석될 수 있습니다.
### 배치 조회 (최대 100개 항목)
더 나은 성능을 위해 한 번의 요청으로 여러 항목을 조회합니다. 각 항목은 주소 또는 도메인 이름일 수 있습니다:
```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"
]
}'
```
## 응답 형식
성공적인 단일 조회는 해석된 주소에 대한 신원 객체를 반환합니다:
```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 신원 데이터베이스에 의해 카테고리로 분류됩니다. 계정 및 프로그램은 별도의 카테고리 세트를 사용합니다. 아래 표는 모든 지원 카테고리를 나열합니다.
| 카테고리 | 설명 | 예시 |
| ---------- | ----------------- | --------------------------------------------------------------- |
| 중앙화 거래소 | 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 |
| 기타 | 분류되지 않은 알려진 주소 | 다양한 알려진 지갑 |
| 카테고리 | 설명 | 예시 |
| --------------- | ----------------- | ----------------------------------------------------------------- |
| 익스플로이터, 해커 및 사기 | 알려진 익스플로잇 및 해킹 주소 | Wormhole Exploiter Wallet, SagaDAO Hacker Wallet, Mango Exploiter |
| 해커 | 확인된 해커 주소 | Solana Hack 2022, DeFi Protocol Hacker |
| 러거 | 러그 풀 가해자 | Squid Game Token Rugger, Known Rug Pull Wallet |
| 사기꾼 | 확인된 사기 주소 | Fake Airdrop Scammer, Phishing Scam Wallet |
| 스팸 | 스팸 토큰 생성자 | Spam Token Creator, Airdrop Spammer |
프로그램(스마트 계약)은 별도로 분류됩니다:
| 카테고리 | 설명 | 예시 |
| -------------- | ---------------- | ---------------------- |
| 스왑 | 토큰 스왑 프로토콜 | 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 애플리케이션 | Various |
| 네이티브 | Solana 네이티브 프로그램 | System Program |
| 독점 AMM | 맞춤형 AMM 디자인 | Phoenix |
| 트레이딩 스나이퍼 | 트레이딩 봇 | MEV bots |
| 차익거래 또는 샌드위치 봇 | MEV 및 차익 봇 | Jito bundles |
| 스팸 | 스팸 프로그램 | Spam tokens |
| 기타 | 분류되지 않은 프로그램 | Various |
## 사용 예
### 거래소 입금 플래그 설정
자금이 중앙화된 거래소로 송금될 때 식별합니다:
```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;
};
```
### 사람이 읽을 수 있는 이름 표시
UI에서 주소 대신 친숙한 이름을 표시합니다:
```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 주소 또는 올바른 도메인인지 확인하고 메인넷을 대상으로 하고 있는지 확인하세요 |
| 401 | 누락되었거나 유효하지 않은 API 키 | 요청에 API 키가 포함되어 있는지 확인하세요 |
| 403 | 엔드포인트에 유료 플랜 필요 | 신원 조회는 Free 플랜에서 사용할 수 없습니다. [플랜 업그레이드](https://dashboard.helius.dev)하여 유료 플랜으로 전환하세요 |
| 404 | 신원이 발견되지 않음, 또는 도메인을 해석할 수 없음 | 단일 엔드포인트 전용 — 지갑에 신원 항목이 없거나 해당 도메인이 존재하지 않습니다. 배치 요청에서는 해석되지 않는 도메인이 404 대신 `unresolved: true` 항목으로 반환됩니다 |
| 429 | 속도 제한 초과 | 요청 빈도를 줄이거나 플랜을 업그레이드하세요 |
## 다음 단계
지갑에 자금을 제공한 사람 추적 — 자금 제공자 유형은 이 신원 카테고리를 재사용합니다.
모든 지갑 API 엔드포인트와 공유 규칙.
신원 조회를 위한 요청 및 응답 스키마.