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

# How to Look Up a Solana Wallet Identity

> Identify known Solana wallets by address or SNS/ANS domain. Look up single entries or batch process up to 100 addresses and domains at once.

> [!NOTE]
>
> The Wallet API is in Beta. Endpoints and response formats may change.

## Overview

The Wallet Identity endpoint identifies known wallet addresses on Solana, including centralized exchanges, DeFi protocols, institutions, and other recognized entities. Use it for compliance, analytics, and displaying human-readable names for known addresses.

Both the single (`GET /v1/wallet/{wallet}/identity`) and batch (`POST /v1/wallet/batch-identity`, up to 100 entries) endpoints accept **SNS `.sol` domains** and **ANS custom TLDs** (e.g. `.bonk`, `.poor`, `.abc`) in addition to raw Solana addresses. Domain resolution is mainnet-only.

This endpoint uses the same identity system that powers [Orb](https://orbmarkets.io/), the Helius Solana block explorer. The database includes 32,500+ labels (human-readable primary names, including 3,000+ programs) and 21.5M+ tags (categorical properties like "Binance deposit address" or "Seeker Phone"), and is continuously growing.

Both the single (`GET /v1/wallet/{wallet}/identity`) and batch (`POST /v1/wallet/batch-identity`) endpoints require a paid plan. Requests made with a Free-plan API key return `403 Forbidden`. See [Plan requirements](https://www.helius.dev/docs/wallet-api/overview.md#plan-requirements) for the full coverage table.

## When to use this

Use the Wallet Identity API when you need to:

* **Identify exchange wallets**: determine if a wallet belongs to Binance, Coinbase, Kraken, and others.
* **Track protocol activity**: identify DeFi protocol wallets and treasury addresses.
* **Compliance and AML**: flag transactions involving known entities.
* **Analytics**: categorize wallet types in your data pipeline.
* **User experience**: display "Sent to Binance 1" instead of a raw address.
* **Batch processing**: look up hundreds of addresses efficiently.

## Quickstart

### Single wallet lookup

Look up identity information for a single wallet address:

> [tab] JavaScript
>
> ```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");
> ```

> [tab] Python
>
> ```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")
> ```

> [tab] cURL
>
> ```bash theme={"system"}
> curl "https://api.helius.xyz/v1/wallet/HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664/identity?api-key=YOUR_API_KEY"
> ```

#### Look up by domain name

You can also pass an SNS `.sol` domain or an ANS custom TLD directly — the endpoint resolves the domain and returns the identity of the owner address:

> [tab] JavaScript
>
> ```javascript theme={"system"}
> // Works identically — the endpoint resolves the domain first.
> const identity = await getWalletIdentity("toly.sol");
>
> // ANS custom TLD
> await getWalletIdentity("miester.bonk");
> ```

> [tab] Python
>
> ```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")
> ```

> [tab] cURL
>
> ```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"
> ```

The single-endpoint response is the standard identity object for the **resolved** address — there is no `inputDomain` marker. If you need to correlate inputs with outputs (for example, when looking up many domains at once), use the batch endpoint.

> [!NOTE]
>
> Domain resolution is mainnet-only. On devnet/testnet, a domain input to this endpoint returns `400`. Positive resolutions are cached for up to 2 hours, so a recently-transferred domain may briefly resolve to the prior owner's identity.

### Batch lookup (up to 100 entries)

Look up multiple entries in a single request for better performance. Each entry can be either an address or a domain name:

> [tab] JavaScript
>
> ```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}`);
>   });
> });
> ```

> [tab] Python
>
> ```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']}")
> ```

> [tab] cURL
>
> ```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"
>     ]
>   }'
> ```

## Response format

A successful single lookup returns the identity object for the resolved address:

```json theme={"system"}
{
  "address": "HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664",
  "type": "exchange",
  "name": "Binance 1",
  "category": "Centralized Exchange",
  "tags": ["Centralized Exchange"]
}
```

In a **batch** response, any entry whose input was a domain name carries an additional `inputDomain` field so you can correlate the response back to the original request:

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

When a domain in a batch request cannot be resolved, the batch does not fail — the entry is returned in place with `address: null`, `type: "unknown"`, and `unresolved: true`. Request order is preserved:

```json theme={"system"}
{
  "address": null,
  "type": "unknown",
  "inputDomain": "nonexistent-xyz.sol",
  "unresolved": true
}
```

On the **single** endpoint, a 404 is returned if the wallet has no identity entry **or** if a domain input could not be resolved:

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

### Identity categories

Wallets and programs are classified into categories powered by the Orb identity database. Accounts and programs use separate category sets. The tables below list every supported category.

> [accordion] Account tag types
>
> | Category | Description | Examples |
> | - | - | - |
> | Centralized Exchange | CEX wallets and hot wallets | Binance 1, Coinbase 1, Kraken, OKX Exchange 1, Bybit Hot Wallet |
> | Cross-chain Bridge | Bridge protocol addresses | Wormhole Bridge, AllBridge, Portal Bridge, deBridge |
> | DeFi | DeFi protocol addresses | Jupiter, Raydium, Orca, Marinade Finance, Kamino |
> | Key Opinion Leader | Notable individuals and influencers | Anatoly Yakovenko, Raj Gokal |
> | Market Maker | Market making firms | Jump Trading, Wintermute, GSR Markets |
> | Trading Firm | Proprietary trading firms | Alameda Research, DRW Trading |
> | Validator | Validator and stake pool addresses | Coinbase Validator, Jito Validator, Figment Validator |
> | Treasury | Project and protocol treasuries | Marinade Treasury, Helium Treasury, Solana Foundation Treasury |
> | DAO | Decentralized autonomous organizations | Mango DAO, Grape DAO, MonkeDAO Treasury |
> | NFT | NFT marketplaces and projects | Magic Eden, Tensor, OpenSea Solana, DeGods Treasury |
> | Stake Pool | Liquid staking pool addresses | Marinade Stake Pool, Jito Stake Pool, BlazeStake |
> | Multisig | Multi-signature wallets | Squads Multisig, Solana Foundation Multisig |
> | Oracle | Price feed and oracle providers | Pyth Network, Switchboard Oracle, Chainlink Solana |
> | Game | Gaming and GameFi projects | Star Atlas, Aurory, Genopets Treasury |
> | Payments | Payment processors | Solana Pay, Sphere, Helio Pay |
> | Tools | Developer tools and utilities | Phantom Wallet, Backpack, Solflare Wallet |
> | Airdrop | Airdrop distribution addresses | Jupiter Airdrop, Pyth Airdrop Distributor |
> | Governance | Governance program addresses | Realms Governance, SPL Governance |
> | Authority | Program authorities and admins | Token Program Authority, Metaplex Authority |
> | Jito | Jito-specific addresses | Jito Tip 1, Jito Tip 2, Jito MEV Payment |
> | Memecoin | Memecoin projects | Bonk Treasury, Dogwifhat, Book of Meme |
> | Casino & Gambling | Gambling and casino dApps | Stake.com Hot Wallet, Rollbit, DexSport |
> | DePIN | Decentralized physical infrastructure | Helium Network, Render Network, Hivemapper |
> | Proprietary AMM | Custom AMM implementations | Phoenix DEX, GooseFX |
> | Restaking | Restaking protocols | Solayer, Fragmetric |
> | Vault | Vault and custody addresses | Solend Vault, Tulip Vault, Francium Vault |
> | Fees | Fee collection addresses | Jupiter Fee Collector, Raydium Fees |
> | Fundraise | Fundraising and ICO addresses | Token Sale Wallet, Fundraise Multisig |
> | Genesis Block Distribution | Genesis distribution addresses | Solana Genesis Distribution |
> | Non-Circulating Supply | Non-circulating token addresses | Team Vesting Wallet, Foundation Reserve |
> | Transaction Sending | Transaction sending services | Jito Tip 1, Jito Tip 2, Helius Sender Tip 1 |
> | System | Solana system programs | System Program, Config Program |
> | X402 | X402 protocol addresses | X402 Protocol |
> | Other | Uncategorized known addresses | Various known wallets |

> [accordion] Malicious categories
>
> | Category | Description | Examples |
> | - | - | - |
> | Exploiter, Hackers & Scams | Known exploit and hack addresses | Wormhole Exploiter Wallet, SagaDAO Hacker Wallet, Mango Exploiter |
> | Hacker | Confirmed hacker addresses | Solana Hack 2022, DeFi Protocol Hacker |
> | Rugger | Rug pull perpetrators | Squid Game Token Rugger, Known Rug Pull Wallet |
> | Scammer | Confirmed scam addresses | Fake Airdrop Scammer, Phishing Scam Wallet |
> | Spam | Spam token creators | Spam Token Creator, Airdrop Spammer |

> [accordion] Program categories
>
> Programs (smart contracts) are classified separately:
>
> | Category | Description | Examples |
> | - | - | - |
> | Swap | Token swap protocols | Jupiter, Raydium, Orca |
> | DeFi | General DeFi protocols | Drift, Mango |
> | Borrow Lend | Lending protocols | Solend, MarginFi |
> | NFT | NFT marketplaces | Magic Eden, Tensor |
> | Staking | Staking programs | Marinade, Jito |
> | Bridge | Cross-chain bridges | Wormhole, AllBridge |
> | Aggregator | DEX aggregators | Jupiter Aggregator |
> | Perpetuals | Perpetual futures | Drift, Mango |
> | Oracle | Oracle providers | Pyth, Switchboard |
> | Launchpad | Token launchpads | Raydium Launchpad |
> | Governance | Governance programs | SPL Governance |
> | Game or Casino | Gaming programs | Star Atlas |
> | Prediction Market | Prediction markets | Drift Predictions |
> | Payments | Payment protocols | Solana Pay |
> | Privacy | Privacy protocols | Elusiv |
> | Compression | State compression | Bubblegum |
> | Infrastructure | Core infrastructure | Metaplex |
> | Tools | Developer tools | Clockwork |
> | RWA | Real-world assets | Ondo Finance |
> | DePIN | Decentralized infrastructure | Helium, Render |
> | DeSci | Decentralized science | VitaDAO |
> | Airdrop | Airdrop programs | Merkle distributors |
> | Web3 | Web3 applications | Various |
> | Native | Solana native programs | System Program |
> | Proprietary AMM | Custom AMM designs | Phoenix |
> | Trading Sniper | Trading bots | MEV bots |
> | Arbitrage or Sandwich Bot | MEV and arb bots | Jito bundles |
> | Spam | Spam programs | Spam tokens |
> | Other | Uncategorized programs | Various |

## Use cases

### Flag exchange deposits

Identify when funds are sent to a centralized exchange:

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

### Display human-readable names

Show friendly names in your UI instead of addresses:

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

### Batch process transaction counterparties

Efficiently identify all counterparties in a list of transactions:

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

## Best practices

* **Use the batch endpoint for multiple lookups.** When looking up more than one address, `POST /v1/wallet/batch-identity` is significantly faster than making individual requests.
* **Handle 404 responses gracefully.** Not all wallets have identity information. Fall back to displaying the raw address.
* **Cache results.** Identity data changes infrequently. Cache locally to reduce API calls.
* **Respect the batch size limit.** The batch endpoint supports up to 100 entries per request. Chunk larger datasets accordingly.

## Common errors

| Error Code | Description | Solution |
| - | - | - |
| 400 | Invalid wallet address or domain format, or domain input on non-mainnet | Verify the input is a valid base58 Solana address or a well-formed domain (e.g. `toly.sol`), and that you're targeting mainnet |
| 401 | Missing or invalid API key | Check your API key is included in the request |
| 403 | Endpoint requires a paid plan | Identity lookups are not available on the Free plan. [Upgrade your plan](https://dashboard.helius.dev) to a paid tier |
| 404 | No identity found, or domain could not be resolved | Single endpoint only — the wallet has no identity entry, or the domain does not exist. In batch requests, unresolvable domains are returned as `unresolved: true` entries rather than 404 |
| 429 | Rate limit exceeded | Reduce request frequency or upgrade your plan |

## Next steps

> [card] [Funding Source](https://www.helius.dev/docs/wallet-api/funded-by.md)
>
> Trace who originally funded a wallet — funder types reuse these identity categories.

> [card] [Wallet API Overview](https://www.helius.dev/docs/wallet-api/overview.md)
>
> All Wallet API endpoints and shared conventions.

> [card] [API Reference](https://www.helius.dev/docs/api-reference/wallet-api/identity.md)
>
> Request and response schemas for identity lookup.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.