Solana 지갑 신원 조회 방법

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를 구동하는 동일한 신원 시스템을 사용합니다. 데이터베이스에는 32,500개 이상의 레이블(사람이 읽을 수 있는 주요 이름, 3,000개 이상의 프로그램 포함)과 21.5M 이상의 태그(예: “Binance 입금 주소” 또는 “Seeker Phone”과 같은 범주 속성)가 포함되어 있으며 지속적으로 증가하고 있습니다. 단일 (GET /v1/wallet/{wallet}/identity) 및 배치 (POST /v1/wallet/batch-identity) 엔드포인트는 유료 플랜이 필요합니다. Free-plan API 키로 요청을 하면 403 Forbidden가 반환됩니다. 전체 적용 범위 표는 플랜 요구 사항을 참조하세요.

사용 시점

Wallet Identity API를 사용할 때:

거래소 지갑 식별: 지갑이 Binance, Coinbase, Kraken 등에 속해 있는지 확인.
프로토콜 활동 추적: DeFi 프로토콜 지갑 및 재무 주소 식별.
준법 및 AML: 알려진 엔티티와 관련된 거래 플래그 표시.
분석: 데이터 파이프라인에서 지갑 유형 분류.
사용자 경험: 원시 주소 대신 “Sent to Binance 1”을 표시.
일괄 처리: 수백 개의 주소를 효율적으로 조회.

빠른 시작

단일 지갑 조회

단일 지갑 주소에 대한 신원 정보를 조회합니다:

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"

도메인 이름으로 조회

SNS .sol 도메인이나 ANS 커스텀 TLD를 직접 전달할 수도 있습니다 — 엔드포인트가 도메인을 해석하고 소유자 주소의 신원을 반환합니다:

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"

단일 엔드포인트 응답은 해석된 주소에 대한 표준 신원 객체입니다 — inputDomain 표시가 없습니다. 여러 도메인을 한 번에 조회할 경우 입력과 출력을 연관시킬 필요가 있다면 배치 엔드포인트를 사용하세요.

도메인 해상도는 메인넷 전용입니다. devnet/testnet에서는 이 엔드포인트에 도메인을 입력하면 400가 반환됩니다. 긍정적인 해상도는 최대 2시간 동안 캐시되므로 최근에 전송된 도메인이 잠시 동안 이전 소유자의 신원으로 해석될 수 있습니다.

배치 조회 (최대 100개 항목)

더 나은 성능을 위해 한 번의 요청으로 여러 항목을 조회합니다. 각 항목은 주소 또는 도메인 이름일 수 있습니다:

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

응답 형식

성공적인 단일 조회는 해석된 주소에 대한 신원 객체를 반환합니다:

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

배치 응답에서는 입력이 도메인 이름인 항목에 추가적인 inputDomain 필드가 있어 응답을 원래 요청으로 다시 연결할 수 있습니다:

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

배치 요청에서 도메인을 해석할 수 없는 경우, 배치는 실패하지 않습니다 — 항목은 address: null, type: "unknown", unresolved: true와 함께 반환됩니다. 요청 순서는 유지됩니다:

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

단일 엔드포인트에서 지갑에 신원 항목이 없거나 도메인 입력을 해석할 수 없는 경우 404가 반환됩니다:

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

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

신원 카테고리

지갑 및 프로그램은 Orb 신원 데이터베이스에 의해 카테고리로 분류됩니다. 계정 및 프로그램은 별도의 카테고리 세트를 사용합니다. 아래 표는 모든 지원 카테고리를 나열합니다.

Account tag types

카테고리	설명	예시
중앙화 거래소	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
기타	분류되지 않은 알려진 주소	다양한 알려진 지갑

Malicious categories

카테고리	설명	예시
익스플로이터, 해커 및 사기	알려진 익스플로잇 및 해킹 주소	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

Program categories

프로그램(스마트 계약)은 별도로 분류됩니다:

카테고리	설명	예시
스왑	토큰 스왑 프로토콜	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

사용 예

거래소 입금 플래그 설정

자금이 중앙화된 거래소로 송금될 때 식별합니다:

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에서 주소 대신 친숙한 이름을 표시합니다:

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"

트랜잭션 상대방 일괄 처리

트랜잭션 목록에서 모든 상대방을 효율적으로 식별합니다:

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 플랜에서 사용할 수 없습니다. 플랜 업그레이드하여 유료 플랜으로 전환하세요
404	신원이 발견되지 않음, 또는 도메인을 해석할 수 없음	단일 엔드포인트 전용 — 지갑에 신원 항목이 없거나 해당 도메인이 존재하지 않습니다. 배치 요청에서는 해석되지 않는 도메인이 404 대신 `unresolved: true` 항목으로 반환됩니다
429	속도 제한 초과	요청 빈도를 줄이거나 플랜을 업그레이드하세요

다음 단계

자금 출처

지갑에 자금을 제공한 사람 추적 — 자금 제공자 유형은 이 신원 카테고리를 재사용합니다.

지갑 API 개요

모든 지갑 API 엔드포인트와 공유 규칙.

API 참조

신원 조회를 위한 요청 및 응답 스키마.

시작하기

데이터 스트리밍 및 이벤트 수신

데이터 API 및 RPC

거래

거래 보내기

서비스로서의 지갑

안내서

리소스

Solana 지갑 신원 조회 방법

개요

사용 시점

빠른 시작

단일 지갑 조회

도메인 이름으로 조회

배치 조회 (최대 100개 항목)

응답 형식

신원 카테고리

사용 예

거래소 입금 플래그 설정

사람이 읽을 수 있는 이름 표시

트랜잭션 상대방 일괄 처리

모범 사례

일반 오류

다음 단계

자금 출처

지갑 API 개요

API 참조

​개요

​사용 시점

​빠른 시작

​단일 지갑 조회

​도메인 이름으로 조회

​배치 조회 (최대 100개 항목)

​응답 형식

​신원 카테고리

​사용 예

​거래소 입금 플래그 설정

​사람이 읽을 수 있는 이름 표시

​트랜잭션 상대방 일괄 처리

​모범 사례

​일반 오류

​다음 단계

자금 출처

지갑 API 개요

API 참조

개요

사용 시점

빠른 시작

단일 지갑 조회

도메인 이름으로 조회

배치 조회 (최대 100개 항목)

응답 형식

신원 카테고리

사용 예

거래소 입금 플래그 설정

사람이 읽을 수 있는 이름 표시

트랜잭션 상대방 일괄 처리

모범 사례

일반 오류

다음 단계