> ## 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.
# Cómo consultar la identidad de una billetera de Solana
> Identifica billeteras conocidas de Solana mediante su dirección o dominio SNS/ANS. Consulta entradas individuales o procesa en lotes hasta 100 direcciones y dominios a la vez.
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](https://orbmarkets.io/), 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](/docs/es/wallet-api/overview#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 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 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 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"
```
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 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 de respuesta
Una consulta individual exitosa devuelve el objeto de identidad de la dirección resuelta:
```json theme={"system"}
{
"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:
```json theme={"system"}
{
"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:
```json theme={"system"}
{
"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:
```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
}
```
### 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.
| 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 |
| 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 |
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:
```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;
};
```
### Mostrar nombres legibles
Muestra nombres descriptivos en tu interfaz de usuario en lugar de direcciones:
```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"
```
### Procesar por lotes las contrapartes de transacciones
Identifica de manera eficiente todas las contrapartes de una lista de transacciones:
```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"
}));
};
```
## 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](https://dashboard.helius.dev) 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
Rastrea quién financió originalmente una billetera; los tipos de financiadores reutilizan estas categorías de identidad.
Todos los endpoints de la API de billeteras y las convenciones compartidas.
Esquemas de solicitud y respuesta para la consulta de identidad.