Cómo consultar la identidad de una billetera de Solana

La API de billeteras está en fase beta. Los endpoints y los formatos de respuesta pueden cambiar.

Descripción general

El endpoint de identidad de billeteras identifica direcciones de billeteras conocidas en Solana, incluidos exchanges centralizados, protocolos DeFi, instituciones y otras entidades reconocidas. Úsalo para cumplimiento normativo, análisis y para mostrar nombres legibles para las direcciones conocidas. Tanto el endpoint individual (GET /v1/wallet/{wallet}/identity) como el endpoint por lotes (POST /v1/wallet/batch-identity, hasta 100 entradas) aceptan dominios SNS .sol y TLD personalizados de ANS (p. ej., .bonk, .poor, .abc), además de direcciones de Solana sin procesar. La resolución de dominios solo está disponible en mainnet. Este endpoint usa el mismo sistema de identidad que impulsa Orb, el explorador de bloques de Solana de Helius. La base de datos incluye más de 32,500 etiquetas de nombre (nombres principales legibles, incluidos más de 3,000 programas) y más de 21.5 millones de etiquetas de categoría (propiedades categóricas como “Dirección de depósito de Binance” o “Teléfono Seeker”), y crece continuamente. Tanto el endpoint individual (GET /v1/wallet/{wallet}/identity) como el endpoint por lotes (POST /v1/wallet/batch-identity) requieren un plan de pago. Las solicitudes realizadas con una clave de API del plan gratuito devuelven 403 Forbidden. Consulta Requisitos del plan para ver la tabla de cobertura completa.

Cuándo usarla

Usa la API de identidad de billeteras cuando necesites:

Identificar billeteras de exchanges: determina si una billetera pertenece a Binance, Coinbase, Kraken u otros.
Rastrear la actividad de protocolos: identifica billeteras de protocolos DeFi y direcciones de tesorería.
Cumplimiento normativo y AML: marca transacciones que involucren entidades conocidas.
Análisis: clasifica los tipos de billetera en tu canalización de datos.
Experiencia de usuario: muestra “Enviado a Binance 1” en lugar de una dirección sin procesar.
Procesamiento por lotes: consulta cientos de direcciones de manera eficiente.

Inicio rápido

Consulta de una sola billetera

Consulta la información de identidad de una sola dirección de billetera:

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 nombre de dominio

También puedes pasar directamente un dominio SNS .sol o un TLD personalizado de ANS. El endpoint resuelve el dominio y devuelve la identidad de la dirección del propietario:

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"

La respuesta del endpoint individual es el objeto de identidad estándar para la dirección resuelta; no incluye ningún marcador inputDomain. Si necesitas correlacionar las entradas con los resultados, por ejemplo, al consultar muchos dominios a la vez, usa el endpoint por lotes.

La resolución de dominios solo está disponible en mainnet. En devnet/testnet, una entrada de dominio en este endpoint devuelve 400. Las resoluciones positivas se almacenan en caché hasta 2 horas, por lo que un dominio transferido recientemente puede resolverse durante un breve periodo con la identidad de su propietario anterior.

Consulta por lotes (hasta 100 entradas)

Consulta varias entradas en una sola solicitud para obtener un mejor rendimiento. Cada entrada puede ser una dirección o un nombre de dominio:

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

Una consulta individual exitosa devuelve el objeto de identidad de la dirección resuelta:

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

En una respuesta por lotes, cualquier entrada cuyo valor de entrada haya sido un nombre de dominio incluye un campo inputDomain adicional para que puedas correlacionar la respuesta con la solicitud original:

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

Cuando no se puede resolver un dominio de una solicitud por lotes, el lote no falla. La entrada se devuelve en la misma posición con address: null, type: "unknown" e unresolved: true. Se conserva el orden de la solicitud:

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

En el endpoint individual, se devuelve un error 404 si la billetera no tiene una entrada de identidad o si no se pudo resolver un dominio de entrada:

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

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

Categorías de identidad

Las billeteras y los programas se clasifican en categorías proporcionadas por la base de datos de identidades de Orb. Las cuentas y los programas usan conjuntos de categorías diferentes. Las siguientes tablas enumeran todas las categorías compatibles.

Account tag types

Categoría	Descripción	Ejemplos
Exchange centralizado	Billeteras de CEX y billeteras calientes	Binance 1, Coinbase 1, Kraken, OKX Exchange 1, Bybit Hot Wallet
Puente entre cadenas	Direcciones de protocolos de puente	Wormhole Bridge, AllBridge, Portal Bridge, deBridge
DeFi	Direcciones de protocolos DeFi	Jupiter, Raydium, Orca, Marinade Finance, Kamino
Líder de opinión clave	Personas e influencers destacados	Anatoly Yakovenko, Raj Gokal
Creador de mercado	Empresas creadoras de mercado	Jump Trading, Wintermute, GSR Markets
Firma de trading	Firmas de trading por cuenta propia	Alameda Research, DRW Trading
Validador	Direcciones de validadores y pools de staking	Coinbase Validator, Jito Validator, Figment Validator
Tesorería	Tesorerías de proyectos y protocolos	Marinade Treasury, Helium Treasury, Solana Foundation Treasury
DAO	Organizaciones autónomas descentralizadas	Mango DAO, Grape DAO, MonkeDAO Treasury
NFT	Mercados y proyectos de NFT	Magic Eden, Tensor, OpenSea Solana, DeGods Treasury
Pool de staking	Direcciones de pools de staking líquido	Marinade Stake Pool, Jito Stake Pool, BlazeStake
Multifirma	Billeteras multifirma	Squads Multisig, Solana Foundation Multisig
Oráculo	Proveedores de fuentes de precios y oráculos	Pyth Network, Switchboard Oracle, Chainlink Solana
Juego	Proyectos de juegos y GameFi	Star Atlas, Aurory, Genopets Treasury
Pagos	Procesadores de pagos	Solana Pay, Sphere, Helio Pay
Herramientas	Herramientas y utilidades para desarrolladores	Phantom Wallet, Backpack, Solflare Wallet
Airdrop	Direcciones de distribución de airdrops	Jupiter Airdrop, Pyth Airdrop Distributor
Gobernanza	Direcciones de programas de gobernanza	Realms Governance, SPL Governance
Autoridad	Autoridades y administradores de programas	Token Program Authority, Metaplex Authority
Jito	Direcciones específicas de Jito	Jito Tip 1, Jito Tip 2, Jito MEV Payment
Memecoin	Proyectos de memecoins	Bonk Treasury, Dogwifhat, Book of Meme
Casino y apuestas	dApps de apuestas y casinos	Stake.com Hot Wallet, Rollbit, DexSport
DePIN	Infraestructura física descentralizada	Helium Network, Render Network, Hivemapper
AMM propietario	Implementaciones personalizadas de AMM	Phoenix DEX, GooseFX
Restaking	Protocolos de restaking	Solayer, Fragmetric
Bóveda	Direcciones de bóvedas y custodia	Solend Vault, Tulip Vault, Francium Vault
Comisiones	Direcciones de cobro de comisiones	Jupiter Fee Collector, Raydium Fees
Recaudación de fondos	Direcciones de recaudación de fondos e ICO	Token Sale Wallet, Fundraise Multisig
Distribución del bloque génesis	Direcciones de distribución del bloque génesis	Solana Genesis Distribution
Suministro no circulante	Direcciones de tokens no circulantes	Team Vesting Wallet, Foundation Reserve
Envío de transacciones	Servicios de envío de transacciones	Jito Tip 1, Jito Tip 2, Helius Sender Tip 1
Sistema	Programas del sistema de Solana	System Program, Config Program
X402	Direcciones del protocolo X402	X402 Protocol
Otro	Direcciones conocidas sin categoría	Varias billeteras conocidas

Malicious categories

Categoría	Descripción	Ejemplos
Explotadores, hackers y estafas	Direcciones conocidas de exploits y ataques	Wormhole Exploiter Wallet, SagaDAO Hacker Wallet, Mango Exploiter
Hacker	Direcciones confirmadas de hackers	Solana Hack 2022, DeFi Protocol Hacker
Autor de rug pull	Autores de rug pulls	Squid Game Token Rugger, Known Rug Pull Wallet
Estafador	Direcciones confirmadas de estafadores	Fake Airdrop Scammer, Phishing Scam Wallet
Spam	Creadores de tokens de spam	Spam Token Creator, Airdrop Spammer

Program categories

Los programas (contratos inteligentes) se clasifican por separado:

Categoría	Descripción	Ejemplos
Intercambio	Protocolos de intercambio de tokens	Jupiter, Raydium, Orca
DeFi	Protocolos DeFi generales	Drift, Mango
Préstamos	Protocolos de préstamos	Solend, MarginFi
NFT	Mercados de NFT	Magic Eden, Tensor
Staking	Programas de staking	Marinade, Jito
Puente	Puentes entre cadenas	Wormhole, AllBridge
Agregador	Agregadores de DEX	Jupiter Aggregator
Perpetuos	Futuros perpetuos	Drift, Mango
Oráculo	Proveedores de oráculos	Pyth, Switchboard
Plataforma de lanzamiento	Plataformas de lanzamiento de tokens	Raydium Launchpad
Gobernanza	Programas de gobernanza	SPL Governance
Juego o casino	Programas de juegos	Star Atlas
Mercado de predicción	Mercados de predicción	Drift Predictions
Pagos	Protocolos de pago	Solana Pay
Privacidad	Protocolos de privacidad	Elusiv
Compresión	Compresión de estado	Bubblegum
Infraestructura	Infraestructura principal	Metaplex
Herramientas	Herramientas para desarrolladores	Clockwork
RWA	Activos del mundo real	Ondo Finance
DePIN	Infraestructura descentralizada	Helium, Render
DeSci	Ciencia descentralizada	VitaDAO
Airdrop	Programas de airdrop	Distribuidores de Merkle
Web3	Aplicaciones Web3	Varias
Nativo	Programas nativos de Solana	System Program
AMM propietario	Diseños personalizados de AMM	Phoenix
Francotirador de trading	Bots de trading	Bots de MEV
Bot de arbitraje o sándwich	Bots de MEV y arbitraje	Paquetes de Jito
Spam	Programas de spam	Tokens de spam
Otro	Programas sin categoría	Varios

Casos de uso

Marcar depósitos en exchanges

Identifica cuándo se envían fondos a un exchange centralizado:

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

Mostrar nombres legibles

Muestra nombres descriptivos en tu interfaz de usuario en lugar de direcciones:

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"

Procesar por lotes las contrapartes de transacciones

Identifica de manera eficiente todas las contrapartes de una lista de transacciones:

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"
  }));
};

Prácticas recomendadas

Usa el endpoint por lotes para varias consultas. Cuando consultes más de una dirección, POST /v1/wallet/batch-identity es considerablemente más rápido que realizar solicitudes individuales.
Gestiona correctamente las respuestas 404. No todas las billeteras tienen información de identidad. Como alternativa, muestra la dirección sin procesar.
Almacena los resultados en caché. Los datos de identidad cambian con poca frecuencia. Almacénalos localmente en caché para reducir las llamadas a la API.
Respeta el límite de tamaño del lote. El endpoint por lotes admite hasta 100 entradas por solicitud. Divide los conjuntos de datos más grandes según corresponda.

Errores comunes

Código de error	Descripción	Solución
400	Dirección de billetera o formato de dominio no válido, o entrada de dominio fuera de mainnet	Verifica que la entrada sea una dirección de Solana base58 válida o un dominio con el formato correcto (p. ej., `toly.sol`), y que estés usando mainnet
401	Falta la clave de API o no es válida	Comprueba que tu clave de API esté incluida en la solicitud
403	El endpoint requiere un plan de pago	Las consultas de identidad no están disponibles en el plan gratuito. Actualiza tu plan a un nivel de pago
404	No se encontró ninguna identidad o no se pudo resolver el dominio	Solo para el endpoint individual: la billetera no tiene una entrada de identidad o el dominio no existe. En las solicitudes por lotes, los dominios que no se pueden resolver se devuelven como entradas `unresolved: true` en lugar de un error 404
429	Se superó el límite de solicitudes	Reduce la frecuencia de las solicitudes o actualiza tu plan

Próximos pasos

Funding Source

Rastrea quién financió originalmente una billetera; los tipos de financiadores reutilizan estas categorías de identidad.

Wallet API Overview

Todos los endpoints de la API de billeteras y las convenciones compartidas.

API Reference

Esquemas de solicitud y respuesta para la consulta de identidad.

Primeros pasos

Streaming de datos y escucha de eventos

API de datos y RPC

Trading

Envío de transacciones

Billetera como servicio

Privacidad

Recursos

Cómo consultar la identidad de una billetera de Solana

Descripción general

Cuándo usarla

Inicio rápido

Consulta de una sola billetera

Consultar por nombre de dominio

Consulta por lotes (hasta 100 entradas)

Formato de respuesta

Categorías de identidad

Casos de uso

Marcar depósitos en exchanges

Mostrar nombres legibles

Procesar por lotes las contrapartes de transacciones

Prácticas recomendadas

Errores comunes

Próximos pasos

Funding Source

Wallet API Overview

API Reference

​Descripción general

​Cuándo usarla

​Inicio rápido

​Consulta de una sola billetera

​Consultar por nombre de dominio

​Consulta por lotes (hasta 100 entradas)

​Formato de respuesta

​Categorías de identidad

​Casos de uso

​Marcar depósitos en exchanges

​Mostrar nombres legibles

​Procesar por lotes las contrapartes de transacciones

​Prácticas recomendadas

​Errores comunes

​Próximos pasos

Funding Source

Wallet API Overview

API Reference

Descripción general

Cuándo usarla

Inicio rápido

Consulta de una sola billetera

Consultar por nombre de dominio

Consulta por lotes (hasta 100 entradas)

Formato de respuesta

Categorías de identidad

Casos de uso

Marcar depósitos en exchanges

Mostrar nombres legibles

Procesar por lotes las contrapartes de transacciones

Prácticas recomendadas

Errores comunes

Próximos pasos