> ## 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.
# Como Consultar a Identidade de uma Carteira Solana
> Identifique carteiras Solana conhecidas por endereço ou domínio SNS/ANS. Consulte entradas únicas ou processe em lote até 100 endereços e domínios de uma vez.
A Wallet API está em Beta. Os endpoints e formatos de resposta podem mudar.
## Visão Geral
O endpoint Identity da Carteira identifica endereços de carteiras conhecidos na Solana, incluindo exchanges centralizadas, protocolos DeFi, instituições e outras entidades reconhecidas. Use para conformidade, análise e exibição de nomes legíveis para endereços conhecidos.
Ambos os endpoints simples (`GET /v1/wallet/{wallet}/identity`) e em lote (`POST /v1/wallet/batch-identity`, até 100 entradas) aceitam **domínios SNS `.sol`** e **TLDs personalizados ANS** (por exemplo, `.bonk`, `.poor`, `.abc`) além de endereços Solana brutos. A resolução de domínio é apenas na mainnet.
Este endpoint usa o mesmo sistema de identidade que alimenta o [Orb](https://orbmarkets.io/), o explorador de blocos Solana Helius. O banco de dados inclui mais de 32.500 rótulos (nomes primários legíveis, incluindo mais de 3.000 programas) e mais de 21,5 milhões de tags (propriedades categóricas como "Endereço de depósito Binance" ou "Seeker Phone"), e está em contínuo crescimento.
Ambos os endpoints simples (`GET /v1/wallet/{wallet}/identity`) e em lote (`POST /v1/wallet/batch-identity`) requerem um plano pago. Solicitações feitas com uma chave de API do plano gratuito retornam `403 Forbidden`. Veja [Requisitos do plano](/docs/pt-BR/wallet-api/overview#plan-requirements) para a tabela de cobertura completa.
## Quando usar isso
Use a Wallet Identity API quando você precisar:
* **Identificar carteiras de exchange**: determinar se uma carteira pertence à Binance, Coinbase, Kraken, entre outras.
* **Acompanhar a atividade de protocolo**: identificar carteiras de protocolo DeFi e endereços de tesouraria.
* **Conformidade e AML**: sinalizar transações envolvendo entidades conhecidas.
* **Análises**: categorizar tipos de carteira no seu pipeline de dados.
* **Experiência do usuário**: exibir "Enviado para Binance 1" em vez de um endereço bruto.
* **Processamento em lote**: consultar centenas de endereços de forma eficiente.
## Início Rápido
### Consulta de uma única carteira
Consultar informações de identidade para um único endereço de carteira:
```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"
```
#### Consultar por nome de domínio
Você também pode passar um domínio SNS `.sol` ou um TLD personalizado ANS diretamente — o endpoint resolve o domínio e retorna a identidade do endereço proprietário:
```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"
```
A resposta do endpoint único é o objeto de identidade padrão para o endereço **resolvido** — não há marcador `inputDomain`. Se você precisar correlacionar entradas com saídas (por exemplo, ao consultar muitos domínios de uma vez), use o endpoint em lote.
A resolução de domínio é apenas na mainnet. No devnet/testnet, uma entrada de domínio para este endpoint retorna `400`. Resoluções positivas são armazenadas em cache por até 2 horas, então um domínio recentemente transferido pode brevemente resolver para a identidade do proprietário anterior.
### Consulta em lote (até 100 entradas)
Consulte várias entradas em uma única solicitação para melhor desempenho. Cada entrada pode ser um endereço ou um nome de domínio:
```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"
]
}'
```
## Formato da resposta
Uma consulta única bem-sucedida retorna o objeto de identidade para o endereço resolvido:
```json theme={"system"}
{
"address": "HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664",
"type": "exchange",
"name": "Binance 1",
"category": "Centralized Exchange",
"tags": ["Centralized Exchange"]
}
```
Em uma resposta **em lote**, qualquer entrada cuja entrada foi um nome de domínio carrega um campo `inputDomain` adicional para que você possa correlacionar a resposta com a solicitação original:
```json theme={"system"}
{
"address": "7v91N7iZ9mNicL8WfG6cgSCKyRXydQjLh6UYBWwm6y1Q",
"type": "wallet",
"name": "toly",
"category": "Key Opinion Leader",
"tags": ["Key Opinion Leader"],
"inputDomain": "toly.sol"
}
```
Quando um domínio em uma solicitação em lote não pode ser resolvido, o lote não falha — a entrada é retornada no lugar com `address: null`, `type: "unknown"` e `unresolved: true`. A ordem da solicitação é preservada:
```json theme={"system"}
{
"address": null,
"type": "unknown",
"inputDomain": "nonexistent-xyz.sol",
"unresolved": true
}
```
No **endpoint único**, um 404 é retornado se a carteira não tiver uma entrada de identidade **ou** se uma entrada de domínio não puder ser resolvida:
```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
}
```
### Categorias de identidade
Carteiras e programas são classificados em categorias alimentadas pelo banco de dados de identidade Orb. Contas e programas usam conjuntos de categorias separados. As tabelas abaixo listam cada categoria suportada.
| Categoria | Descrição | Exemplos |
| ---------------------------- | ---------------------------------------------- | --------------------------------------------------------------- |
| Exchange Centralizada | Carteiras CEX e carteiras quentes | Binance 1, Coinbase 1, Kraken, OKX Exchange 1, Bybit Hot Wallet |
| Ponte Cross-chain | Endereços de protocolo de ponte | Wormhole Bridge, AllBridge, Portal Bridge, deBridge |
| DeFi | Endereços de protocolo DeFi | Jupiter, Raydium, Orca, Marinade Finance, Kamino |
| Líder de Opinião | Indivíduos notáveis e influenciadores | Anatoly Yakovenko, Raj Gokal |
| Criador de Mercado | Empresas de criação de mercado | Jump Trading, Wintermute, GSR Markets |
| Empresa de Trading | Empresas de trading proprietárias | Alameda Research, DRW Trading |
| Validador | Endereços de validador e pool de participação | Coinbase Validator, Jito Validator, Figment Validator |
| Tesouraria | Tesourarias de projeto e protocolo | Marinade Treasury, Helium Treasury, Solana Foundation Treasury |
| DAO | Organizações autônomas descentralizadas | Mango DAO, Grape DAO, MonkeDAO Treasury |
| NFT | Mercados e projetos NFT | Magic Eden, Tensor, OpenSea Solana, DeGods Treasury |
| Pool de Participação | Endereços de pool de participação líquidos | Marinade Stake Pool, Jito Stake Pool, BlazeStake |
| Multisig | Carteiras multi-assinatura | Squads Multisig, Solana Foundation Multisig |
| Oracle | Provedores de preços e oráculos | Pyth Network, Switchboard Oracle, Chainlink Solana |
| Jogo | Projetos de jogos e GameFi | Star Atlas, Aurory, Genopets Treasury |
| Pagamentos | Processadores de pagamentos | Solana Pay, Sphere, Helio Pay |
| Ferramentas | Ferramentas e utilitários para desenvolvedores | Phantom Wallet, Backpack, Solflare Wallet |
| Airdrop | Endereços de distribuição de airdrop | Jupiter Airdrop, Pyth Airdrop Distributor |
| Governança | Endereços de programa de governança | Realms Governance, SPL Governance |
| Autoridade | Autoridades e administradores de programas | Token Program Authority, Metaplex Authority |
| Jito | Endereços específicos do Jito | Jito Tip 1, Jito Tip 2, Jito MEV Payment |
| Memecoin | Projetos de memecoin | Bonk Treasury, Dogwifhat, Book of Meme |
| Casino & Jogos de Azar | dApps de jogos de azar e cassino | Stake.com Hot Wallet, Rollbit, DexSport |
| DePIN | Infraestrutura física descentralizada | Helium Network, Render Network, Hivemapper |
| AMM Proprietário | Implementações de AMM personalizadas | Phoenix DEX, GooseFX |
| Re-staking | Protocolos de re-staking | Solayer, Fragmetric |
| Cofre | Endereços de cofre e custódia | Solend Vault, Tulip Vault, Francium Vault |
| Taxas | Endereços de coleta de taxas | Jupiter Fee Collector, Raydium Fees |
| Captação de recursos | Endereços de captação de recursos e ICO | Token Sale Wallet, Fundraise Multisig |
| Distribuição do Bloco Gênese | Endereços de distribuição do bloco gênese | Solana Genesis Distribution |
| Fornecimento Não-Circulante | Endereços de tokens não-circulantes | Carteira de Team Vesting, Foundation Reserve |
| Envio de Transações | Serviços de envio de transações | Jito Tip 1, Jito Tip 2, Helius Sender Tip 1 |
| Sistema | Programas do sistema Solana | System Program, Config Program |
| X402 | Endereços de protocolo X402 | X402 Protocol |
| Outros | Endereços conhecidos não categorizados | Diversas carteiras conhecidas |
| Categoria | Descrição | Exemplos |
| ---------------------------- | ----------------------------------------- | ----------------------------------------------------------------- |
| Explorador, Hackers & Golpes | Endereços conhecidos de exploração e hack | Wormhole Exploiter Wallet, SagaDAO Hacker Wallet, Mango Exploiter |
| Hacker | Endereços de hacker confirmados | Solana Hack 2022, DeFi Protocol Hacker |
| Rugger | Perpetradores de rug pull | Squid Game Token Rugger, Carteira de Rug Pull Conhecida |
| Golpista | Endereços de golpe confirmados | Fake Airdrop Scammer, Carteira de Golpe de Phishing |
| Spam | Criadores de tokens de spam | Criador de Token de Spam, Spammer de Airdrop |
Programas (smart contracts) são classificados separadamente:
| Categoria | Descrição | Exemplos |
| ------------------------------ | ---------------------------------- | ------------------------ |
| Swap | Protocolos de troca de tokens | Jupiter, Raydium, Orca |
| DeFi | Protocolos DeFi gerais | Drift, Mango |
| Empréstimo e Empréstimos | Protocolos de empréstimo | Solend, MarginFi |
| NFT | Mercados NFT | Magic Eden, Tensor |
| Staking | Programas de staking | Marinade, Jito |
| Ponte | Pontes cross-chain | Wormhole, AllBridge |
| Agregador | Agregadores DEX | Jupiter Aggregator |
| Perpetuals | Futuros perpétuos | Drift, Mango |
| Oracle | Provedores de oráculo | Pyth, Switchboard |
| Launchpad | Plataformas de lançamento de token | Raydium Launchpad |
| Governança | Programas de governança | SPL Governance |
| Jogo ou Cassino | Programas de jogos | Star Atlas |
| Mercado de Previsão | Mercados de previsão | Drift Predictions |
| Pagamentos | Protocolos de pagamento | Solana Pay |
| Privacidade | Protocolos de privacidade | Elusiv |
| Compressão | Compressão de estado | Bubblegum |
| Infraestrutura | Infraestrutura principal | Metaplex |
| Ferramentas | Ferramentas para desenvolvedores | Clockwork |
| RWA | Ativos do mundo real | Ondo Finance |
| DePIN | Infraestrutura descentralizada | Helium, Render |
| DeSci | Ciência descentralizada | VitaDAO |
| Airdrop | Programas de airdrop | Distribuidores de Merkle |
| Web3 | Aplicações Web3 | Vários |
| Nativo | Programas nativos Solana | System Program |
| AMM Proprietário | Designs de AMM personalizados | Phoenix |
| Sniper de Trading | Bots de trading | Bots de MEV |
| Bot de Arbitragem ou Sanduíche | Bots de MEV e arbitragem | Pacotes Jito |
| Spam | Programas de spam | Tokens de spam |
| Outro | Programas não categorizados | Vários |
## Casos de uso
### Marcar depósitos de exchange
Identifique quando fundos são enviados para uma exchange centralizada:
```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;
};
```
### Exibir nomes legíveis
Mostre nomes amigáveis na sua interface em vez de endereços:
```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"
```
### Processamento em lote de contrapartes de transações
Identifique de forma eficiente todas as contrapartes em uma lista de transações:
```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"
}));
};
```
## Melhores práticas
* **Use o endpoint em lote para várias consultas.** Ao consultar mais de um endereço, `POST /v1/wallet/batch-identity` é significativamente mais rápido do que fazer solicitações individuais.
* **Lide com respostas 404 de forma adequada.** Nem todas as carteiras têm informações de identidade. Volte a exibir o endereço bruto.
* **Cache dos resultados.** Os dados de identidade mudam raramente. Faça cache localmente para reduzir chamadas de API.
* **Respeite o limite de tamanho de lote.** O endpoint em lote suporta até 100 entradas por solicitação. Divida conjuntos de dados maiores de acordo.
## Erros comuns
| Código de Erro | Descrição | Solução |
| -------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 400 | Formato de endereço de carteira ou domínio inválido, ou entrada de domínio em rede não-mainnet | Verifique se a entrada é um endereço base58 Solana válido ou um domínio bem formado (por exemplo, `toly.sol`), e se você está direcionando para a mainnet |
| 401 | Chave de API ausente ou inválida | Verifique se sua chave de API está incluída na solicitação |
| 403 | Endpoint requer um plano pago | Consultas de identidade não estão disponíveis no plano gratuito. [Atualize seu plano](https://dashboard.helius.dev) para um nível pago |
| 404 | Nenhuma identidade encontrada, ou domínio não pôde ser resolvido | Apenas no endpoint único — a carteira não tem entrada de identidade, ou o domínio não existe. Em solicitações em lote, domínios não resolvidos são retornados como entradas `unresolved: true` em vez de 404 |
| 429 | Limite de taxa excedido | Reduza a frequência das solicitações ou atualize seu plano |
## Próximos passos
Rastreie quem financiou originalmente uma carteira — tipos de financiadores reutilizam essas categorias de identidade.
Todos os endpoints da Wallet API e convenções compartilhadas.
Esquemas de solicitação e resposta para consulta de identidade.