Como Consultar a Identidade de uma Carteira Solana

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

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

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

Formato da resposta

Uma consulta única bem-sucedida retorna o objeto de identidade para o endereço resolvido:

{
  "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:

{
  "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:

{
  "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:

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

{
  "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.

Tipos de tags de contas

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

Categorias maliciosas

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

Categorias de programa

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:

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:

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:

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

Fonte de Financiamento

Rastreie quem financiou originalmente uma carteira — tipos de financiadores reutilizam essas categorias de identidade.

Visão Geral da Wallet API

Todos os endpoints da Wallet API e convenções compartilhadas.

Referência da API

Esquemas de solicitação e resposta para consulta de identidade.

Primeiros Passos

Transmissão de Dados & Escuta de Eventos

APIs de Dados & RPCs

Negociação

Envio de Transações

Carteira como Serviço

Guias

Recursos

Como Consultar a Identidade de uma Carteira Solana

Visão Geral

Quando usar isso

Início Rápido

Consulta de uma única carteira

Consultar por nome de domínio

Consulta em lote (até 100 entradas)

Formato da resposta

Categorias de identidade

Casos de uso

Marcar depósitos de exchange

Exibir nomes legíveis

Processamento em lote de contrapartes de transações

Melhores práticas

Erros comuns

Próximos passos

Fonte de Financiamento

Visão Geral da Wallet API

Referência da API

​Visão Geral

​Quando usar isso

​Início Rápido

​Consulta de uma única carteira

​Consultar por nome de domínio

​Consulta em lote (até 100 entradas)

​Formato da resposta

​Categorias de identidade

​Casos de uso

​Marcar depósitos de exchange

​Exibir nomes legíveis

​Processamento em lote de contrapartes de transações

​Melhores práticas

​Erros comuns

​Próximos passos

Fonte de Financiamento

Visão Geral da Wallet API

Referência da API

Visão Geral

Quando usar isso

Início Rápido

Consulta de uma única carteira

Consultar por nome de domínio

Consulta em lote (até 100 entradas)

Formato da resposta

Categorias de identidade

Casos de uso

Marcar depósitos de exchange

Exibir nomes legíveis

Processamento em lote de contrapartes de transações

Melhores práticas

Erros comuns

Próximos passos