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

# Lana API — ИИ-агент Solana

> Вызывайте Lana, ИИ-агента Solana, по HTTP: задавайте вопросы о кошельках, токенах, транзакциях и ценах и получайте ответ в потоковом режиме. Краткое руководство, справочник API и цены.

Lana API — это ИИ-агент Solana, которого вы вызываете по HTTP. Вы отправляете ему вопрос на обычном английском языке, а он находит для вас сведения о кошельках, токенах, транзакциях и ценах, а затем передает ответ в потоковом режиме.

Lana выполняет каждый поиск на стороне Helius, поэтому вам не нужно определять или запускать какие-либо инструменты. Сервис доступен на платных тарифах Helius (Developer и выше) по фиксированной цене за запрос: 10 000 кредитов для `lana-thinking` и 2 000 кредитов для `lana-fast`. См. раздел [Цены](#цены).

API устроен аналогично Anthropic Messages API, но SDK Anthropic с ним не работают. Вызывайте его напрямую по HTTP, как в примерах ниже. См. раздел [Отличия от Anthropic Messages API](#отличия-от-anthropic-messages-api).

Lana работает на моделях Claude от Anthropic. Ваши вопросы и беседа отправляются в Anthropic для генерации ответов.

> [!NOTE]
>
> Lana API находится на стадии бета-тестирования на конечной точке [Gatekeeper (Beta)](https://www.helius.dev/docs/ru/gatekeeper/overview.md), `beta.helius-rpc.com`. На `mainnet.helius-rpc.com` он пока недоступен. Во время бета-тестирования могут добавляться новые события и поля.

## О чем можно спрашивать Lana

Вопросы, которые ваши пользователи могут задавать о своих сделках и кошельках, с которыми они взаимодействуют:

* «Почему моя последняя транзакция завершилась с ошибкой?»
* «Какое проскальзывание произошло при этом обмене?»
* «Какие комиссии я заплатил за эту транзакцию?»
* «Откуда этот кошелек получил средства и куда их отправил?»
* «Связан ли этот кошелек с другим кошельком?»
* «Кто является крупнейшими держателями этого токена?»

Передайте кошелек пользователя в [`extensions.user_context.wallet`](#расширения), чтобы работали вопросы о «моем» кошельке или «моей последней транзакции».

## Краткое руководство

**1. Get an API key**

Скопируйте ключ API из [панели управления Helius](https://dashboard.helius.dev).

**2. Ask a question**

Замените `YOUR_API_KEY` и выполните:

```bash cURL theme={"system"}
curl -N https://beta.helius-rpc.com/v1/lana/messages \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "model": "lana-thinking",
    "stream": true,
    "messages": [
      { "role": "user", "content": "Who are the largest holders of EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v?" }
    ],
    "extensions": { "read_only": true }
  }'
```

`-N` заставляет curl выводить каждое событие сразу после его получения. Первое событие может поступить через 10 секунд.

**3. Read the answer**

Ответ представляет собой поток [событий](#потоковые-события):

```text theme={"system"}
event: message_start
data: {"type":"message_start","message":{"id":"msg_3f9c...","model":"lana-thinking"}}

event: tool_use
data: {"type":"tool_use","tool_use_id":"toolu_01...","name":"...","input":{"mint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}}

event: tool_result
data: {"type":"tool_result","tool_use_id":"toolu_01...","content":"{\"holders\":[..."}

event: content_block_delta
data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"The largest USDC holders are"}}

event: message_end
data: {"type":"message_end","stop_reason":"end_turn","usage":{"input_tokens":91200,"output_tokens":212,"tool_calls":1,"prompt_tokens":46100,"context_window":200000}}
```

Ответ состоит из фрагментов `text_delta` в порядке их поступления. `lana-thinking` также может отправлять фрагменты `thinking_delta`: это рассуждения Lana, поэтому показывайте их отдельно от ответа или пропускайте.

### Чтение потока в коде

Оба примера проверяют статус HTTP перед чтением тела в виде потока, ожидают `Retry-After` при `429` или `503`, выводят ответ по мере его поступления и останавливаются, если ход завершается с ошибкой или поток обрывается преждевременно.

```typescript TypeScript theme={"system"}
async function askLana(question: string): Promise<Response> {
  for (let attempt = 1; ; attempt++) {
    const res = await fetch("https://beta.helius-rpc.com/v1/lana/messages", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Api-Key": process.env.HELIUS_API_KEY!,
      },
      body: JSON.stringify({
        model: "lana-thinking",
        stream: true,
        messages: [{ role: "user", content: question }],
        extensions: { read_only: true },
      }),
    });
    if (res.ok) return res;

    // Errors before the stream starts arrive as a normal HTTP response, not as events.
    const body = await res.text();
    const retryable = (res.status === 429 && !body.includes("max usage reached")) || res.status === 503;
    if (!retryable || attempt === 3) throw new Error(`${res.status}: ${body}`);

    const retryAfterSeconds = Number(res.headers.get("Retry-After")) || 5;
    await new Promise((resolve) => setTimeout(resolve, retryAfterSeconds * 1000));
  }
}

const res = await askLana("What is the current price of SOL?");

const reader = res.body!.getReader();
const decoder = new TextDecoder();
let buffer = "";
let finished = false;

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });

  // Events are separated by a blank line.
  const frames = buffer.split("\n\n");
  buffer = frames.pop() ?? "";

  for (const frame of frames) {
    const data = frame.split("\n").find((line) => line.startsWith("data:"));
    if (!data) continue;
    const event = JSON.parse(data.slice(5));

    switch (event.type) {
      case "content_block_delta":
        if (event.delta.type === "text_delta") process.stdout.write(event.delta.text);
        break;
      case "message_end":
        if (event.stop_reason === "error") throw new Error("Lana turn failed");
        finished = true;
        break;
      case "error":
        throw new Error(`${event.error.type}: ${event.error.message}`);
      // Ignore every other event type, including ones added later.
    }
  }
}

// The connection closed without message_end or error.
if (!finished) throw new Error("Lana stream ended early");
```

```python Python theme={"system"}
import json
import os
import time

import requests

def ask_lana(question: str) -> requests.Response:
    attempt = 1
    while True:
        res = requests.post(
            "https://beta.helius-rpc.com/v1/lana/messages",
            headers={"X-Api-Key": os.environ["HELIUS_API_KEY"]},
            json={
                "model": "lana-thinking",
                "stream": True,
                "messages": [{"role": "user", "content": question}],
                "extensions": {"read_only": True},
            },
            stream=True,
            timeout=(10, 60),  # connect, read; keep the read timeout at 30 seconds or more
        )
        if res.status_code == 200:
            return res

        # Errors before the stream starts arrive as a normal HTTP response, not as events.
        retryable = (
            res.status_code == 429 and "max usage reached" not in res.text
        ) or res.status_code == 503
        if not retryable or attempt == 3:
            raise RuntimeError(f"{res.status_code}: {res.text}")

        time.sleep(int(res.headers.get("Retry-After", 5)))
        attempt += 1

res = ask_lana("What is the current price of SOL?")

finished = False
for line in res.iter_lines(decode_unicode=True):
    if not line or not line.startswith("data:"):
        continue
    event = json.loads(line[5:])

    if event["type"] == "content_block_delta" and event["delta"]["type"] == "text_delta":
        print(event["delta"]["text"], end="", flush=True)
    elif event["type"] == "message_end":
        if event["stop_reason"] == "error":
            raise RuntimeError("Lana turn failed")
        finished = True
    elif event["type"] == "error":
        raise RuntimeError(f'{event["error"]["type"]}: {event["error"]["message"]}')
    # Ignore every other event type, including ones added later.

# The connection closed without message_end or error.
if not finished:
    raise RuntimeError("Lana stream ended early")
```

## Отличия от Anthropic Messages API

* Доступны модели `lana-thinking` и `lana-fast`.
* Lana запускает собственные инструменты. `tools`, `tool_choice`, `temperature`, `top_p`, `top_k`, `stop_sequences` и `metadata` возвращают `400`.
* `system` добавляется к инструкциям Lana.
* `max_tokens` необязателен (значение по умолчанию и максимум — 8 192), а изображения должны быть представлены URL-адресами.
* События отличаются. Отсутствуют `content_block_start`, `content_block_stop`, `message_delta` и `message_stop`. Поток завершается событием `message_end` или `error`.
* `usage` добавляет `tool_calls`, `prompt_tokens` и `context_window`. `stop_reason` может иметь значение `error`.
* `extensions` используется только в Lana.

## Конечная точка и аутентификация

```text theme={"system"}
POST https://beta.helius-rpc.com/v1/lana/messages
```

Передайте ключ API Helius одним из следующих способов:

| Метод | Пример |
| - | - |
| Заголовок `X-Api-Key` (рекомендуется) | `X-Api-Key: YOUR_API_KEY` |
| Параметр запроса `api-key` | `https://beta.helius-rpc.com/v1/lana/messages?api-key=YOUR_API_KEY` |

`Authorization: Bearer` не работает на этой конечной точке и возвращает `401`.

`mainnet.helius-rpc.com` пока не обслуживает этот маршрут и возвращает `503`.

Отправляйте `Content-Type: application/json` с каждым запросом.

> [!WARNING]
>
> Ваш ключ API расходует кредиты тарифа. Вызывайте Lana со своего сервера, а не из браузера или приложения, которое вы распространяете среди пользователей.

## Тело запроса

Тело представляет собой объект JSON. Неизвестные поля отклоняются с ошибкой `400`, включая неизвестные поля внутри `extensions` и блоков содержимого.

**model** `string` *required*

`lana-thinking` или `lana-fast`. См. раздел [Модели](#модели).

**messages** `object[]` *required*

Беседа в хронологическом порядке, начиная с самого старого сообщения. Она должна содержать хотя бы одно сообщение, а последнее сообщение должно иметь `role: "user"`. См. раздел [Сообщения](#сообщения).

**max\_tokens** `integer` (default: 8192)

Максимальное количество выходных токенов, которое Lana может записать за один шаг модели: от `1` до `8192`. Ход с поиском занимает несколько шагов, поэтому общее значение `output_tokens` для хода может превышать `max_tokens`. При значении меньше 2 048 модель `lana-thinking` не выполняет рассуждения.

**stream** `boolean` (default: false)

`true` передает [события](#потоковые-события) в потоковом режиме. `false` возвращает один [ответ JSON](#непотоковый-ответ) после завершения хода.

**system** `string`

Дополнительные инструкции длиной от 1 до 10 000 символов, например «Ответь тремя пунктами». Они добавляются к собственным инструкциям Lana, а не заменяют их.

**extensions** `object`

Параметры только для Lana. См. раздел [Расширения](#расширения).

### Модели

| | `lana-thinking` | `lana-fast` |
| - | - | - |
| Лучше всего подходит для | Многоэтапного анализа | Быстрого поиска и отдельных фактов |
| Шагов поиска за ход | До 20 | До 4 |
| Поисков в интернете за ход | До 3 | До 2 |
| Загрузок веб-страниц за ход | До 2 | До 2 |
| Потоковая передача рассуждений | Иногда, как `thinking_delta`. Lana сама решает, когда рассуждать. | Нет |

`lana-thinking` выполняет рассуждения, только если `max_tokens` не меньше 2048.

### Сообщения

Каждое сообщение содержит `role` (`user` или `assistant`) и `content`:

```json theme={"system"}
{ "role": "user", "content": "How many holders does USDC have?" }
```

API не хранит беседы. Чтобы задать уточняющий вопрос, снова отправьте всю беседу, добавив новый вопрос в конец. Для ходов `assistant` достаточно текста ответа Lana:

```json theme={"system"}
{
  "model": "lana-thinking",
  "messages": [
    { "role": "user", "content": "What is the USDC mint on Solana?" },
    { "role": "assistant", "content": "The USDC mint is EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v." },
    { "role": "user", "content": "How many holders does it have?" }
  ]
}
```

Lana ищет только адреса, которые встречаются в беседе, в собственных результатах поиска или в `extensions.user_context.wallet`.

`content` — это непустая строка или непустой массив блоков:

| Блок | Допустим в | Структура |
| - | - | - |
| `text` | `user`, `assistant` | `{ "type": "text", "text": "..." }` |
| `image` | `user` | `{ "type": "image", "source": { "type": "url", "url": "https://..." } }` |
| `tool_use` | `assistant` | `{ "type": "tool_use", "id": "...", "name": "...", "input": {} }` |
| `tool_result` | `user` | `{ "type": "tool_result", "tool_use_id": "...", "content": "..." }` |

Изображения должны быть представлены URL-адресами. Изображения в формате Base64 не поддерживаются.

Блоки `tool_use` и `tool_result` не обязательны. Они позволяют воспроизводить результаты поиска из предыдущего хода в том виде, в котором их вернула Lana, чтобы Lana могла использовать их повторно. `tool_result` также принимает необязательное логическое значение `is_error`.

### Расширения

Все расширения необязательны.

| Поле | Тип | Значение по умолчанию | Назначение |
| - | - | - | - |
| `read_only` | boolean | `true` | Удаляет инструменты для переводов, обменов и запуска токенов. Оставьте значение `true`: в документации этого API не описан процесс отображения и подписания действий кошелька. |
| `output_format` | `"markdown"` \| `"plain"` | `"markdown"` | `plain` запрещает Lana использовать Markdown и удаляет маркеры `{{cite:N}}`. События `source` по-прежнему поступают. |
| `include_ui_schema` | boolean | `false` | Разрешает компоненты интерфейса в виде событий `ui_block` и `ui_schema`. |
| `include_followups` | boolean | `false` | Разрешает до 3 предложенных уточняющих вопросов. |
| `include_documents` | boolean | `false` | Разрешает загружаемые файлы CSV, JSON или текстовые файлы в виде событий `document`. |
| `enable_deep_scan` | boolean | `false` | Позволяет Lana читать до 10 000 транзакций из истории адреса (50 000 для подсчетов и итоговых значений), выполняя до 3 сканирований за ход. Только основная сеть. Без этого параметра Lana считывает до 100 транзакций за один поиск. Глубокое сканирование выполняется медленнее, но оплачивается по той же фиксированной цене. Оно учитывается в пятиминутном ограничении хода. |
| `user_context` | object | нет | Сведения о том, кто задает вопрос. См. ниже. |
| `attachments` | object\[] | нет | До 8 изображений, добавляемых к последнему сообщению пользователя. Блоки `image` в `messages` не учитываются в этом ограничении. Каждый элемент имеет вид `{ "url": "https://...", "kind": "image" }`. |

Параметры `include_*` делают вывод возможным. Lana сама решает, отправлять ли его.

`extensions` также принимает `progress_context` и `transaction_filter_context`. Они используются обозревателем [Orb](https://www.helius.dev/docs/ru/orb.md), и вам они не нужны.

Поля `user_context`:

| Поле | Тип | Назначение |
| - | - | - |
| `wallet` | string, до 128 символов | Адрес пользователя, чтобы работали запросы «мой кошелек» и «мой баланс». |
| `address_kind` | string, до 32 символов | `"wallet"` или `"token"`: определяет, чем является `wallet`. Требует `wallet`. |
| `time_zone` | string, до 64 символов | Часовой пояс IANA, например `"America/New_York"`, чтобы работали запросы со словом «сегодня». |
| `network` | `"mainnet"` \| `"devnet"` | Сеть, в которой выполняется поиск. По умолчанию используется основная сеть. |

## Потоковые события

При использовании `"stream": true` вы получаете статус `200` и `Content-Type: text/event-stream`. Каждое событие выглядит так:

```text theme={"system"}
event: <type>
data: <json>

```

`data` — это одна строка JSON. Ее `type` соответствует имени `event`.

Статус `200` и первые события поступают, когда Lana впервые отвечает (рассуждением, текстом ответа, поиском или файлом), но не позднее чем через 10 секунд. До этого ничего не отправляется, поэтому запрос, завершившийся с ошибкой в этом интервале, получает обычный [ответ с ошибкой](#до-начала-потока) и не тарифицируется. После этого, пока Lana работает, каждые 10 секунд поступает `ping`.

Установите тайм-аут чтения HTTP-клиента не менее 30 секунд. Значение по умолчанию 5 секунд, как в `httpx`, слишком мало: тайм-аут может истечь до получения первого байта или между двумя событиями.

События поступают в следующем порядке:

1. `message_start` — всегда первым.
2. Любая комбинация `content_block_delta`, `tool_use`, `tool_result`, `source`, `ui_block`, `document`, `progress_update` и `ping`.
3. `ui_schema` — не более одного раза.
4. `follow_up` — не более одного раза.
5. `message_end`, если ход завершен, или `error`, если он завершился с ошибкой. Это всегда последнее событие.

Могут добавляться новые типы событий и поля. Игнорируйте все неизвестные типы и поля.

| Событие | Значение | Пример `data` |
| - | - | - |
| `message_start` | Ход начался. | `{"type":"message_start","message":{"id":"msg_3f9c...","model":"lana-thinking"}}` |
| `content_block_delta` (`text_delta`) | Фрагмент ответа. | `{"type":"content_block_delta","delta":{"type":"text_delta","text":"SOL is trading at"}}` |
| `content_block_delta` (`thinking_delta`) | Фрагмент рассуждения. Только для `lana-thinking`, когда Lana выполняет рассуждения. | `{"type":"content_block_delta","delta":{"type":"thinking_delta","thinking":"I should check..."}}` |
| `tool_use` | Lana начала поиск. | `{"type":"tool_use","tool_use_id":"toolu_01...","name":"...","input":{"address":"..."}}` |
| `tool_result` | Поиск завершен. `content` содержит предварительный просмотр длиной до 500 символов. `is_error: true` означает ошибку; см. раздел [Ошибки инструментов](#ошибки-инструментов). | `{"type":"tool_result","tool_use_id":"toolu_01...","content":"{\"balance\":..."}` |
| `source` | Веб-страница, которую использовала Lana. `index` соответствует маркерам `{{cite:N}}` в ответе. `snippet` необязателен. | `{"type":"source","index":0,"url":"https://...","title":"...","snippet":"..."}` |
| `progress_update` | Короткая строка состояния во время длительного хода. Показывайте ее отдельно от ответа. `created_at` — время Unix в миллисекундах. | `{"type":"progress_update","id":"progress_8a1b...","message":"I'll check this wallet's recent swaps.","created_at":1760436000000}` |
| `ui_block` | Один компонент интерфейса. Требует `include_ui_schema`. `tool_use_id` необязателен. | `{"type":"ui_block","tool_use_id":"toolu_01...","component":"...","schema":{...}}` |
| `document` | Загружаемый файл. Требует `include_documents`. `format` имеет значение `csv`, `json` или `txt`. `tool_use_id` и `description` необязательны. | `{"type":"document","filename":"usdc-holders","format":"csv","content":"owner,amount\n...","description":"..."}` |
| `ui_schema` | Все компоненты интерфейса в виде одного дерева. Требует `include_ui_schema`. | `{"type":"ui_schema","schema":{...}}` |
| `follow_up` | Предлагаемые следующие вопросы. Требует `include_followups`. | `{"type":"follow_up","suggestions":["Show the top 10 holders' recent transfers"]}` |
| `message_end` | Ход завершен. См. разделы [Причины остановки](#причины-остановки) и [Использование](#использование). | `{"type":"message_end","stop_reason":"end_turn","usage":{"input_tokens":91200,"output_tokens":212,"tool_calls":1,"prompt_tokens":46100,"context_window":200000}}` |
| `error` | Ход завершился с ошибкой. См. раздел [Ошибки](#ошибки). | `{"type":"error","error":{"type":"overloaded_error","message":"Lana is temporarily overloaded. Retry the request shortly."}}` |
| `ping` | Сигнал активности каждые 10 секунд. Игнорируйте его. | `{"type":"ping"}` |

Советы по отображению потока:

* Используйте `tool_use` только для индикаторов выполнения. Имена инструментов и входные данные могут изменяться.
* При выводе `"markdown"` преобразуйте каждый `{{cite:N}}` в ссылку на `source` с соответствующим `index` или удалите его.
* `ui_block` и `ui_schema` содержат одни и те же компоненты. Lana может отправить только `ui_schema`, поэтому отображайте события `ui_block`, если они поступают, а в противном случае визуализируйте `ui_schema`.
* При поиске в интернете отправляется `tool_result` с текстом `Web search completed.` или `Web fetch completed.`. Страницы поступают в виде событий `source`.

### Ошибки инструментов

Ошибка поиска не приводит к ошибке всего хода. Lana обходит ее, и повторять запрос не нужно. `tool_result` содержит `is_error: true`, а `content` представляет собой JSON с коротким сообщением и `code`:

```json theme={"system"}
{ "error": "the data service failed (502)", "code": "upstream_unavailable" }
```

> [accordion] Tool error codes
>
> | `code` | Значение |
> | - | - |
> | `invalid_input` | Недопустимые аргументы поиска. |
> | `not_found` | Для этого поиска нет данных. Некоторые виды поиска вместо этого сообщают об отсутствующем элементе как об обычном результате, например `{"found": false}`. |
> | `rejected` | Сервис данных отклонил поиск. |
> | `rate_limited` | Сервис данных ограничивает частоту запросов. |
> | `upstream_timeout` | Истекло время ожидания сервиса данных. |
> | `upstream_unavailable` | Сервис данных завершился с ошибкой. |
> | `upstream_error` | Инструмент данных Helius завершился с ошибкой. |
> | `timeout` | Для поиска истекло отведенное время. |
> | `tool_failed` | Поиск не смог предоставить ответ. Причина указана в `error`. |
> | `internal` | Произошла непредвиденная ошибка. |
>
> Могут добавляться новые коды. Обрабатывайте неизвестный код как `internal`.

### Причины остановки

`stop_reason` присутствует в `message_end` и в ответе JSON:

| Значение | Описание |
| - | - |
| `end_turn` | Lana завершила ответ. |
| `max_tokens` | Ответ достиг ограничения `max_tokens` и может быть обрезан. |
| `tool_use` | Ход завершился на шаге поиска, обычно из-за ограничения количества шагов. |
| `error` | Ход завершился с ошибкой. Ответ неполный. |

### Использование

| Поле | Значение |
| - | - |
| `input_tokens` | Входные токены за весь ход. |
| `output_tokens` | Выходные токены за весь ход. |
| `tool_calls` | Поиски, выполненные за ход, включая некоторые из тех, которые не отображаются как `tool_use`. |
| `prompt_tokens` | Входные токены на последнем шаге модели. Используйте это значение, чтобы определить, насколько заполнен контекст. |
| `context_window` | Контекстное окно модели, в настоящее время `200000`. |

Собственные инструкции и инструменты поиска Lana занимают около 45 000 токенов на каждом шаге модели, поэтому `input_tokens` имеет большое значение даже для короткого вопроса. Цена устанавливается за запрос, поэтому количество токенов не влияет на стоимость.

## Непотоковый ответ

При использовании `"stream": false` после завершения хода вы получаете один объект JSON:

```json theme={"system"}
{
  "id": "msg_3f9c...",
  "type": "message",
  "role": "assistant",
  "model": "lana-thinking",
  "content": [
    { "type": "tool_use", "id": "toolu_01...", "name": "...", "input": { "mint": "So11111111111111111111111111111111111111112" } },
    { "type": "tool_result", "tool_use_id": "toolu_01...", "content": "{\"price\":..." },
    { "type": "text", "text": "SOL is trading at ..." }
  ],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 90800, "output_tokens": 96, "tool_calls": 1, "prompt_tokens": 45600, "context_window": 200000 }
}
```

Ответ состоит из блоков `text`, объединенных по порядку. Рассуждения и `progress_update` доступны только в потоковом режиме.

Следующие поля присутствуют, только если у них есть значение:

| Поле | Когда присутствует |
| - | - |
| `ui_schema` | `include_ui_schema` включен и есть что показать. |
| `documents` | `include_documents` включен и Lana создала файлы. Поля такие же, как у события `document`, за исключением `type`. |
| `follow_up` | `include_followups` включен и Lana предложила вопросы. Массив строк. |
| `sources` | Lana использовала веб-страницы. Поля такие же, как у события `source`, за исключением `type`. |
| `error` | `stop_reason` имеет значение `"error"`. Объект с `type` и `message`. |

## Ошибки

### До начала потока

Запрос, который завершается с ошибкой до начала ответа, возвращает статус, отличный от `200`, с обычным телом ошибки даже при использовании `"stream": true`. События не отправляются, а плата не взимается. Проверяйте статус HTTP перед чтением тела в виде потока.

При использовании `"stream": true` ответ начинается, когда Lana впервые отвечает, но не позднее чем через 10 секунд. Ход, завершившийся с ошибкой до этого момента, например из-за перегрузки модели или слишком длинной беседы, также обрабатывается здесь.

| Статус | Причина | Что делать |
| - | - | - |
| `400` | Недопустимое тело, например неизвестная модель или `max_tokens` больше 8 192. `message` указывает каждое недопустимое поле. | Исправьте запрос. |
| `401` | Ключ API отсутствует, недействителен или был передан как `Authorization: Bearer`. | Передайте ключ в `X-Api-Key` или `?api-key=`. |
| `403` | Ваш тариф не включает Lana (тариф Free) или настройки доступа ключа блокируют сервис. | Перейдите на тариф Developer или выше либо проверьте настройки доступа ключа в [панели управления Helius](https://dashboard.helius.dev). |
| `400`, тело `Bad Request` | Размер тела превышает 10 МБ. Gatekeeper отклоняет его до того, как Lana его получит. | Отправьте запрос меньшего размера, например с меньшим количеством сообщений или более короткими сообщениями. |
| `429`, тело `Too Many Requests` | Превышено [ограничение частоты запросов](https://www.helius.dev/docs/ru/billing/rate-limits.md) вашего тарифа. | Дождитесь времени из заголовка `Retry-After` (1 секунда), затем повторите запрос. |
| `429`, тело `max usage reached` | В вашем проекте закончились кредиты. | Добавьте кредиты или повысьте тариф. Заголовок `Retry-After` отсутствует; до выполнения этого действия повторные запросы будут завершаться с ошибкой. |
| `429`, `error.type` `rate_limit_error` | В вашем проекте уже выполняется около 3 запросов Lana. | Дождитесь времени из заголовка `Retry-After` (5 секунд), затем повторите запрос. |
| `503` | Lana работает на пределе доступной мощности или перезапускается. | Дождитесь времени из заголовка `Retry-After` (5 секунд при нехватке мощности, 30 секунд при перезапуске), затем повторите запрос. |
| `400`, `error.type` `context_overflow` | Беседа не помещается в контекстное окно. | Удалите старые сообщения или задайте более узкий вопрос. |
| `529`, `error.type` `overloaded_error` | Модель перегружена. `529` — статус, который Anthropic использует для этой ситуации; некоторые HTTP-клиенты его не распознают, поэтому обрабатывайте его как `503`. | Повторите запрос с экспоненциальной задержкой. |
| `500`, `502`, `504` | Ход завершился с ошибкой до первого вывода с типом `api_error`, `tool_error` или `timeout_error`. | Обработайте ошибку, как описано в разделе [Типы ошибок](#типы-ошибок). |

Первые два ответа `429` связаны с вашим тарифом, и в теле ответа указано, какое ограничение было достигнуто. Третий поступает от Lana и имеет тело JSON.

Если `429` или `503` поступает без заголовка `Retry-After`, подождите несколько секунд перед повторной попыткой.

Собственные ошибки Lana (`400` для недопустимого тела или `context_overflow`, `429` с `rate_limit_error`, `500`, `502`, `503`, `504` и `529`) имеют тело JSON. Ошибки Gatekeeper (`401`, `403`, `400` из-за слишком большого тела и связанные с тарифом ответы `429`) представляют собой обычный текст. Выбирайте ветвь обработки по `error.type`, а не по `message`:

```json theme={"system"}
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens: max_tokens must be <= 8192"
  }
}
```

### После начала потока

Статус уже равен `200`, поэтому при ошибке поток завершается финальным событием `error` либо событием `message_end` с `stop_reason: "error"`. В таком `message_end` нет объекта `error`; обрабатывайте его как `api_error`. Любой текст ответа перед ним является неполным. Покажите его как неполный или отбросьте.

### Без потоковой передачи

При использовании `"stream": false` неудачный ход возвращает один из следующих результатов:

* `200` с `stop_reason: "error"` и объектом `error`, если во время хода было создано какое-либо содержимое, включая результаты поиска. Всегда проверяйте `stop_reason`.
* Тело ошибки JSON, если ход ничего не создал. Статус соответствует `error.type`: `400` для `context_overflow`, `500` для `api_error`, `502` для `tool_error`, `504` для `timeout_error` или `529` для `overloaded_error` (статус, который Anthropic использует для перегруженной модели; некоторые HTTP-клиенты его не распознают, поэтому обрабатывайте его как `503`). Такие запросы не тарифицируются. Обрабатывайте их, как описано в разделе [Типы ошибок](#типы-ошибок).

### Типы ошибок

| `error.type` | Значение | Что делать |
| - | - | - |
| `invalid_request_error` | Недопустимый запрос. | Исправьте запрос. |
| `context_overflow` | Беседа и результаты поиска не помещаются в контекстное окно. | Удалите старые сообщения или задайте более узкий вопрос. |
| `overloaded_error` | Модель перегружена. | Повторите запрос с экспоненциальной задержкой. |
| `timeout_error` | Для хода истекло отведенное время. | Задайте более узкий вопрос или используйте `lana-fast`. |
| `tool_error` | Сервис поиска, от которого зависит Lana, завершился с ошибкой. | Повторите запрос с задержкой. |
| `rate_limit_error` | В вашем проекте выполняется около 3 запросов. | Повторите запрос по истечении времени из заголовка `Retry-After`. |
| `api_error` | На стороне Helius произошла ошибка Lana или сервис работает на пределе мощности. | Повторите запрос с задержкой. |

Обрабатывайте любой другой тип как `api_error`.

## Ограничения

| Ограничение | Значение |
| - | - |
| `max_tokens` | От 1 до 8 192 (по умолчанию 8 192) |
| `system` | До 10 000 символов |
| `extensions.attachments` | До 8 изображений |
| Тело запроса | 10 МБ |
| Контекстное окно | 200 000 токенов, из которых около 80% (после `max_tokens`) отводится для беседы и результатов поиска |
| Продолжительность хода | 5 минут |
| Ограничение частоты запросов | Ограничение частоты запросов DAS и Enhanced APIs вашего тарифа. См. раздел [Ограничения частоты запросов](https://www.helius.dev/docs/ru/billing/rate-limits.md#api-lana). |
| Одновременные запросы | Около 3 на проект. Дополнительные запросы могут получать `429`, пока один из выполняющихся запросов не завершится. |

Когда ход приближается к 5 минутам, Lana прекращает поиск и отвечает на основе уже полученных данных. Длительные ходы обычно заканчиваются частичным ответом с указанием недостающих сведений, а не ошибкой тайм-аута.

При потоковой передаче установите тайм-аут чтения HTTP-клиента не менее 30 секунд. Первый байт может поступить через 10 секунд, после чего `ping` поступает каждые 10 секунд, поэтому значительно более длительный интервал означает разрыв соединения. Значение по умолчанию 5 секунд, как в `httpx`, слишком мало. Без потоковой передачи данные не поступают до завершения хода, поэтому установите тайм-аут чтения больше 5 минут.

Если вы разорвете соединение, Lana остановит ход. Если поток запроса уже начался, плата все равно взимается.

Когда Lana работает на пределе мощности, новые запросы получают `503` до начала потоковой передачи. Они не тарифицируются. Повторите запрос по истечении времени из заголовка `Retry-After`.

## Цены

Каждый запрос оплачивается по фиксированной цене, которая зависит от модели:

| Модель | Кредитов за запрос |
| - | - |
| `lana-thinking` | **10 000** |
| `lana-fast` | **2 000** |

Цена одинакова для потоковых и непотоковых запросов и для всех платных тарифов (Developer и выше). Lana недоступна на тарифе Free.

Кредиты списываются с вашего тарифа. См. раздел [Кредиты](https://www.helius.dev/docs/ru/billing/credits.md#кредиты-lana-api).

### За что взимается плата

Плата взимается за каждый запрос, получивший HTTP `200`, независимо от режима передачи и результата хода. Запросы, завершившиеся с ошибкой до начала ответа, получают другой статус и не тарифицируются.

* Потоковый ход, завершившийся с событием `error`, или ход, от которого вы отключились после его начала, тарифицируется: статус уже был `200`.
* Запрос, отклоненный до начала хода (`400`, `401`, `403`, `429`, `503`), не тарифицируется.
* Ход, завершившийся с ошибкой до начала ответа (`400`, `5xx`), не тарифицируется независимо от режима передачи.

## Другие примеры

### Настройка тона и кошелька пользователя

```bash cURL theme={"system"}
curl https://beta.helius-rpc.com/v1/lana/messages \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "model": "lana-thinking",
    "system": "Answer in at most three bullet points.",
    "messages": [{ "role": "user", "content": "How did my wallet do this week?" }],
    "extensions": {
      "read_only": true,
      "user_context": {
        "wallet": "YOUR_WALLET_ADDRESS",
        "address_kind": "wallet",
        "time_zone": "America/New_York"
      }
    }
  }'
```

### Сканирование полной истории кошелька

```bash cURL theme={"system"}
curl -N https://beta.helius-rpc.com/v1/lana/messages \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "model": "lana-thinking",
    "stream": true,
    "messages": [{ "role": "user", "content": "Over the last 5,000 transactions of YOUR_WALLET_ADDRESS, which programs did it use most?" }],
    "extensions": { "read_only": true, "enable_deep_scan": true }
  }'
```

### Получение компонентов интерфейса, уточняющих вопросов и CSV

```bash cURL theme={"system"}
curl https://beta.helius-rpc.com/v1/lana/messages \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "model": "lana-thinking",
    "messages": [{ "role": "user", "content": "Export the top holders of So11111111111111111111111111111111111111112 as a CSV" }],
    "extensions": {
      "read_only": true,
      "include_ui_schema": true,
      "include_followups": true,
      "include_documents": true
    }
  }'
```

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

> [card] [API Reference](https://www.helius.dev/docs/ru/api-reference/lana/messages.md)
>
> Схема запроса и ответа с интерактивной средой.

> [card] [Rate Limits](https://www.helius.dev/docs/ru/billing/rate-limits.md#api-lana)
>
> Ограничения частоты запросов Lana для каждого тарифа.

> [card] [Credits](https://www.helius.dev/docs/ru/billing/credits.md#кредиты-lana-api)
>
> Как запросы Lana используют кредиты вашего тарифа.

> [card] [Contact Support](https://www.helius.dev/docs/ru/support/contact-support)
>
> Получите помощь через Discord, чат или электронную почту.


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