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

# Как определить владельца кошелька Solana

> Определяйте известные кошельки Solana по адресу или домену SNS/ANS. Выполняйте поиск по отдельным записям или обрабатывайте пакетами до 100 адресов и доменов одновременно.

<Note>
  Wallet API находится на этапе бета-тестирования. Эндпоинты и форматы ответов могут измениться.
</Note>

## Обзор

Эндпоинт Wallet Identity идентифицирует известные адреса кошельков в Solana, включая централизованные биржи, протоколы DeFi, организации и другие распознаваемые сущности. Используйте его для обеспечения соответствия требованиям, аналитики и отображения понятных пользователю названий известных адресов.

Эндпоинты для одиночного (`GET /v1/wallet/{wallet}/identity`) и пакетного поиска (`POST /v1/wallet/batch-identity`, до 100 записей) принимают **домены SNS `.sol`** и **пользовательские TLD ANS** (например, `.bonk`, `.poor`, `.abc`), а также необработанные адреса Solana. Разрешение доменов доступно только в основной сети.

Этот эндпоинт использует ту же систему идентификации, на которой работает [Orb](https://orbmarkets.io/) — обозреватель блоков Solana от Helius. База данных содержит более 32 500 меток (понятных пользователю основных названий, включая более 3 000 программ) и более 21,5 млн тегов (категориальных свойств, таких как «адрес для пополнения Binance» или «телефон Seeker») и непрерывно пополняется.

Для эндпоинтов одиночного (`GET /v1/wallet/{wallet}/identity`) и пакетного поиска (`POST /v1/wallet/batch-identity`) требуется платный тариф. Запросы с ключом API бесплатного тарифа возвращают `403 Forbidden`. Полную таблицу доступности см. в разделе [Требования к тарифу](/docs/ru/wallet-api/overview#требования-к-тарифному-плану).

## Когда использовать

Используйте Wallet Identity API, когда вам необходимо:

* **Определять кошельки бирж**: выяснять, принадлежит ли кошелек Binance, Coinbase, Kraken или другой бирже.
* **Отслеживать активность протоколов**: определять кошельки протоколов DeFi и адреса казначейств.
* **Обеспечивать соответствие требованиям и AML**: отмечать транзакции с участием известных сущностей.
* **Выполнять аналитику**: классифицировать типы кошельков в конвейере данных.
* **Улучшать пользовательский интерфейс**: отображать «Отправлено на Binance 1» вместо необработанного адреса.
* **Выполнять пакетную обработку**: эффективно искать сотни адресов.

## Быстрый старт

### Поиск одного кошелька

Получите идентификационные данные для одного адреса кошелька:

<Tabs>
  <Tab title="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>

  <Tab title="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>

  <Tab title="cURL">
    ```bash theme={"system"}
    curl "https://api.helius.xyz/v1/wallet/HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664/identity?api-key=YOUR_API_KEY"
    ```
  </Tab>
</Tabs>

#### Поиск по доменному имени

Вы также можете напрямую передать домен SNS `.sol` или пользовательский TLD ANS — эндпоинт разрешит домен и вернет идентификационные данные адреса владельца:

<Tabs>
  <Tab title="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>

  <Tab title="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>

  <Tab title="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"
    ```
  </Tab>
</Tabs>

Ответ эндпоинта одиночного поиска представляет собой стандартный объект идентификации для **разрешенного** адреса — маркер `inputDomain` отсутствует. Если необходимо сопоставить входные данные с результатами, например при одновременном поиске нескольких доменов, используйте эндпоинт пакетного поиска.

<Note>
  Разрешение доменов доступно только в основной сети. В devnet/testnet передача домена этому эндпоинту возвращает `400`. Успешные результаты разрешения кешируются на срок до 2 часов, поэтому недавно переданный домен может некоторое время разрешаться в идентификационные данные предыдущего владельца.
</Note>

### Пакетный поиск (до 100 записей)

Чтобы повысить производительность, ищите несколько записей одним запросом. Каждая запись может быть адресом или доменным именем:

<Tabs>
  <Tab title="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>

  <Tab title="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>

  <Tab title="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"
        ]
      }'
    ```
  </Tab>
</Tabs>

## Формат ответа

При успешном одиночном поиске возвращается объект идентификации разрешенного адреса:

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

В **пакетном** ответе каждая запись, для которой в качестве входных данных использовалось доменное имя, содержит дополнительное поле `inputDomain`. Оно позволяет сопоставить ответ с исходным запросом:

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

Если домен из пакетного запроса не удается разрешить, весь пакет не завершается с ошибкой. Запись возвращается на своем месте с `address: null`, `type: "unknown"` и `unresolved: true`. Порядок запросов сохраняется:

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

Эндпоинт **одиночного** поиска возвращает ошибку 404, если для кошелька нет идентификационной записи **или** если переданный домен не удалось разрешить:

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

### Категории идентификации

Кошельки и программы распределяются по категориям на основе базы идентификационных данных Orb. Для учетных записей и программ используются разные наборы категорий. В таблицах ниже перечислены все поддерживаемые категории.

<AccordionGroup>
  <Accordion title="Account tag types">
    | Категория | Описание | Примеры |
    | - | - | - |
    | Централизованная биржа | Кошельки CEX и горячие кошельки | Binance 1, Coinbase 1, Kraken, OKX Exchange 1, Bybit Hot Wallet |
    | Межсетевой мост | Адреса протоколов мостов | Wormhole Bridge, AllBridge, Portal Bridge, deBridge |
    | DeFi | Адреса протоколов DeFi | Jupiter, Raydium, Orca, Marinade Finance, Kamino |
    | Лидер мнений | Известные лица и инфлюенсеры | Anatoly Yakovenko, Raj Gokal |
    | Маркетмейкер | Маркетмейкерские компании | Jump Trading, Wintermute, GSR Markets |
    | Торговая компания | Компании, торгующие за свой счет | Alameda Research, DRW Trading |
    | Валидатор | Адреса валидаторов и пулов стейкинга | Coinbase Validator, Jito Validator, Figment Validator |
    | Казначейство | Казначейства проектов и протоколов | Marinade Treasury, Helium Treasury, Solana Foundation Treasury |
    | DAO | Децентрализованные автономные организации | Mango DAO, Grape DAO, MonkeDAO Treasury |
    | NFT | Маркетплейсы и проекты NFT | Magic Eden, Tensor, OpenSea Solana, DeGods Treasury |
    | Пул стейкинга | Адреса пулов ликвидного стейкинга | Marinade Stake Pool, Jito Stake Pool, BlazeStake |
    | Мультиподпись | Кошельки с мультиподписью | Squads Multisig, Solana Foundation Multisig |
    | Оракул | Поставщики ценовых данных и оракулов | Pyth Network, Switchboard Oracle, Chainlink Solana |
    | Игра | Игровые проекты и проекты GameFi | Star Atlas, Aurory, Genopets Treasury |
    | Платежи | Обработчики платежей | Solana Pay, Sphere, Helio Pay |
    | Инструменты | Инструменты и утилиты для разработчиков | Phantom Wallet, Backpack, Solflare Wallet |
    | Аирдроп | Адреса распространения аирдропов | Jupiter Airdrop, Pyth Airdrop Distributor |
    | Управление | Адреса программ управления | Realms Governance, SPL Governance |
    | Полномочия | Уполномоченные адреса и администраторы программ | Token Program Authority, Metaplex Authority |
    | Jito | Адреса, относящиеся к Jito | Jito Tip 1, Jito Tip 2, Jito MEV Payment |
    | Мемкоин | Проекты мемкоинов | Bonk Treasury, Dogwifhat, Book of Meme |
    | Казино и азартные игры | dApp для азартных игр и казино | Stake.com Hot Wallet, Rollbit, DexSport |
    | DePIN | Децентрализованная физическая инфраструктура | Helium Network, Render Network, Hivemapper |
    | Собственный AMM | Пользовательские реализации AMM | Phoenix DEX, GooseFX |
    | Рестейкинг | Протоколы рестейкинга | Solayer, Fragmetric |
    | Хранилище | Адреса хранилищ и кастодиального хранения | Solend Vault, Tulip Vault, Francium Vault |
    | Комиссии | Адреса сбора комиссий | Jupiter Fee Collector, Raydium Fees |
    | Сбор средств | Адреса сбора средств и ICO | Token Sale Wallet, Fundraise Multisig |
    | Распределение генезис-блока | Адреса первоначального распределения | Solana Genesis Distribution |
    | Нециркулирующее предложение | Адреса токенов вне обращения | Team Vesting Wallet, Foundation Reserve |
    | Отправка транзакций | Сервисы отправки транзакций | Jito Tip 1, Jito Tip 2, Helius Sender Tip 1 |
    | Система | Системные программы Solana | System Program, Config Program |
    | X402 | Адреса протокола X402 | X402 Protocol |
    | Другое | Известные адреса без категории | Различные известные кошельки |
  </Accordion>

  <Accordion title="Malicious categories">
    | Категория | Описание | Примеры |
    | - | - | - |
    | Эксплуататоры, хакеры и мошенники | Известные адреса, связанные с эксплуатацией уязвимостей и взломами | Wormhole Exploiter Wallet, SagaDAO Hacker Wallet, Mango Exploiter |
    | Хакер | Подтвержденные адреса хакеров | Solana Hack 2022, DeFi Protocol Hacker |
    | Организатор рагпула | Организаторы рагпулов | Squid Game Token Rugger, Known Rug Pull Wallet |
    | Мошенник | Подтвержденные мошеннические адреса | Fake Airdrop Scammer, Phishing Scam Wallet |
    | Спам | Создатели спам-токенов | Spam Token Creator, Airdrop Spammer |
  </Accordion>

  <Accordion title="Program categories">
    Программы (смарт-контракты) классифицируются отдельно:

    | Категория | Описание | Примеры |
    | - | - | - |
    | Обмен | Протоколы обмена токенов | Jupiter, Raydium, Orca |
    | DeFi | Протоколы DeFi общего назначения | Drift, Mango |
    | Кредитование | Протоколы кредитования | Solend, MarginFi |
    | NFT | Маркетплейсы NFT | Magic Eden, Tensor |
    | Стейкинг | Программы стейкинга | Marinade, Jito |
    | Мост | Межсетевые мосты | Wormhole, AllBridge |
    | Агрегатор | Агрегаторы DEX | Jupiter Aggregator |
    | Бессрочные контракты | Бессрочные фьючерсы | Drift, Mango |
    | Оракул | Поставщики оракулов | Pyth, Switchboard |
    | Лаунчпад | Платформы запуска токенов | Raydium Launchpad |
    | Управление | Программы управления | SPL Governance |
    | Игра или казино | Игровые программы | Star Atlas |
    | Рынок прогнозов | Рынки прогнозов | Drift Predictions |
    | Платежи | Платежные протоколы | Solana Pay |
    | Конфиденциальность | Протоколы конфиденциальности | Elusiv |
    | Сжатие | Сжатие состояния | Bubblegum |
    | Инфраструктура | Основная инфраструктура | Metaplex |
    | Инструменты | Инструменты для разработчиков | Clockwork |
    | RWA | Активы реального мира | Ondo Finance |
    | DePIN | Децентрализованная инфраструктура | Helium, Render |
    | DeSci | Децентрализованная наука | VitaDAO |
    | Аирдроп | Программы аирдропов | Распределители Merkle |
    | Web3 | Приложения Web3 | Различные |
    | Нативная программа | Нативные программы Solana | System Program |
    | Собственный AMM | Пользовательские реализации AMM | Phoenix |
    | Торговый снайпер | Торговые боты | Боты MEV |
    | Арбитражный или сэндвич-бот | Боты MEV и арбитражные боты | Пакеты Jito |
    | Спам | Спам-программы | Спам-токены |
    | Другое | Программы без категории | Различные |
  </Accordion>
</AccordionGroup>

## Варианты использования

### Пометка пополнений бирж

Определяйте случаи отправки средств на централизованную биржу:

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

### Отображение понятных пользователю названий

Показывайте в пользовательском интерфейсе понятные названия вместо адресов:

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

### Пакетная обработка контрагентов транзакций

Эффективно определяйте всех контрагентов в списке транзакций:

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

## Рекомендации

* **Используйте эндпоинт пакетного поиска для нескольких операций.** При поиске нескольких адресов `POST /v1/wallet/batch-identity` работает значительно быстрее отдельных запросов.
* **Корректно обрабатывайте ответы 404.** Идентификационные данные доступны не для всех кошельков. Если они отсутствуют, отображайте необработанный адрес.
* **Кешируйте результаты.** Идентификационные данные изменяются редко. Кешируйте их локально, чтобы сократить количество вызовов API.
* **Соблюдайте ограничение размера пакета.** Эндпоинт пакетного поиска поддерживает до 100 записей на запрос. Разделяйте более крупные наборы данных на соответствующие части.

## Распространенные ошибки

| Код ошибки | Описание | Решение |
| - | - | - |
| 400 | Недопустимый формат адреса кошелька или домена либо передача домена не в основной сети | Убедитесь, что входные данные являются допустимым адресом Solana в формате base58 или корректным доменом (например, `toly.sol`), а запрос направляется в основную сеть |
| 401 | Ключ API отсутствует или недействителен | Убедитесь, что ключ API включен в запрос |
| 403 | Для эндпоинта требуется платный тариф | Поиск идентификационных данных недоступен на бесплатном тарифе. [Перейдите на платный тариф](https://dashboard.helius.dev) |
| 404 | Идентификационные данные не найдены или домен не удалось разрешить | Только для эндпоинта одиночного поиска: для кошелька нет идентификационной записи или домен не существует. В пакетных запросах неразрешимые домены возвращаются как записи `unresolved: true`, а не как ошибка 404 |
| 429 | Превышено ограничение частоты запросов | Уменьшите частоту запросов или перейдите на другой тариф |

## Дальнейшие действия

<CardGroup cols={3}>
  <Card title="Funding Source" icon="money-bill-transfer" href="/docs/ru/wallet-api/funded-by">
    Определите, кто изначально пополнил кошелек: типы источников финансирования используют те же категории идентификации.
  </Card>

  <Card title="Wallet API Overview" icon="wallet" href="/docs/ru/wallet-api/overview">
    Все эндпоинты Wallet API и общие соглашения.
  </Card>

  <Card title="API Reference" icon="code" href="/docs/ru/api-reference/wallet-api/identity">
    Схемы запросов и ответов для поиска идентификационных данных.
  </Card>
</CardGroup>


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