> ## 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 - Agente de IA da Solana

> Chame Lana, um agente de IA da Solana, por HTTP: pergunte sobre carteiras, tokens, transações e preços e receba a resposta por streaming. Início rápido, referência da API e preços.

A Lana API é um agente de IA da Solana que você chama por HTTP. Você envia uma pergunta em linguagem natural, e ela consulta carteiras, tokens, transações e preços para você e transmite uma resposta por streaming.

Lana executa todas as consultas do lado da Helius, então você não precisa definir nem executar ferramentas. Ela está disponível nos planos pagos da Helius (Developer e superiores), por um preço fixo por solicitação: 10.000 créditos para `lana-thinking` e 2.000 créditos para `lana-fast`. Consulte [Preços](#preços).

A API tem um formato semelhante ao da Anthropic Messages API, mas os SDKs da Anthropic não funcionam com ela. Chame-a diretamente por HTTP, como nos exemplos abaixo. Consulte [Diferenças em relação à Anthropic Messages API](#diferenças-em-relação-à-anthropic-messages-api).

Lana é executada nos modelos Claude da Anthropic. Suas perguntas e conversas são enviadas à Anthropic para gerar respostas.

> [!NOTE]
>
> A Lana API está em beta no endpoint [Gatekeeper (Beta)](https://www.helius.dev/docs/pt-BR/gatekeeper/overview.md), `beta.helius-rpc.com`. Ela ainda não está disponível em `mainnet.helius-rpc.com`. Novos eventos e campos podem ser adicionados durante o beta.

## O que você pode perguntar à Lana

Perguntas que seus usuários podem fazer sobre suas negociações e as carteiras com as quais interagem:

* "Por que minha última transação falhou?"
* "Quanto de slippage tive neste swap?"
* "Quais taxas paguei nesta transação?"
* "De onde esta carteira recebeu os fundos e para onde os enviou?"
* "Esta carteira está conectada a esta outra carteira?"
* "Quem são os maiores detentores deste token?"

Passe a carteira do usuário em [`extensions.user_context.wallet`](#extensões) para que perguntas sobre "minha" carteira ou "minha última transação" funcionem.

## Início rápido

**1. Get an API key**

Copie uma chave de API do [Painel da Helius](https://dashboard.helius.dev).

**2. Ask a question**

Substitua `YOUR_API_KEY` e execute:

```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` faz o curl imprimir cada evento assim que ele chega. O primeiro evento pode levar até 10 segundos.

**3. Read the answer**

A resposta é um fluxo de [eventos](#eventos-de-streaming):

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

A resposta está nos blocos `text_delta`, em ordem. `lana-thinking` também pode enviar blocos `thinking_delta`: esse é o raciocínio da Lana, portanto exiba-o separadamente da resposta ou ignore-o.

### Ler o fluxo no código

Os dois exemplos verificam o status HTTP antes de ler o corpo como um fluxo, aguardam `Retry-After` em um `429` ou `503`, imprimem a resposta conforme ela é transmitida e param se o turno falhar ou se o fluxo terminar antes do esperado.

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

## Diferenças em relação à Anthropic Messages API

* Os modelos são `lana-thinking` e `lana-fast`.
* Lana executa suas próprias ferramentas. `tools`, `tool_choice`, `temperature`, `top_p`, `top_k`, `stop_sequences` e `metadata` retornam `400`.
* `system` é adicionado às instruções da Lana.
* `max_tokens` é opcional (padrão e máximo de 8.192), e as imagens devem ser URLs.
* Os eventos são diferentes. Não há `content_block_start`, `content_block_stop`, `message_delta` nem `message_stop`. O fluxo termina com `message_end` ou `error`.
* `usage` adiciona `tool_calls`, `prompt_tokens` e `context_window`. `stop_reason` pode ser `error`.
* `extensions` é exclusivo da Lana.

## Endpoint e autenticação

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

Envie sua chave de API da Helius de uma destas formas:

| Método | Exemplo |
| - | - |
| Cabeçalho `X-Api-Key` (recomendado) | `X-Api-Key: YOUR_API_KEY` |
| Parâmetro de consulta `api-key` | `https://beta.helius-rpc.com/v1/lana/messages?api-key=YOUR_API_KEY` |

`Authorization: Bearer` não funciona neste endpoint e retorna `401`.

`mainnet.helius-rpc.com` ainda não disponibiliza esta rota e retorna `503`.

Envie `Content-Type: application/json` em todas as solicitações.

> [!WARNING]
>
> Sua chave de API consome os créditos do seu plano. Chame Lana a partir do seu servidor, não de um navegador nem de um aplicativo distribuído aos usuários.

## Corpo da solicitação

O corpo é um objeto JSON. Campos desconhecidos são rejeitados com `400`, incluindo campos desconhecidos dentro de `extensions` e blocos de conteúdo.

**model** `string` *required*

`lana-thinking` ou `lana-fast`. Consulte [Modelos](#modelos).

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

A conversa, da mais antiga para a mais recente. Ela precisa ter pelo menos uma mensagem, e a última deve ter `role: "user"`. Consulte [Mensagens](#mensagens).

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

O número máximo de tokens de saída que Lana pode escrever em uma etapa do modelo, de `1` a `8192`. Um turno com consultas exige várias etapas, portanto o `output_tokens` total do turno pode ser maior que `max_tokens`. Abaixo de 2.048, `lana-thinking` não raciocina.

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

`true` transmite [eventos](#eventos-de-streaming). `false` retorna uma [resposta JSON](#resposta-sem-streaming) quando o turno termina.

**system** `string`

Instruções adicionais, de 1 a 10.000 caracteres, como "Responda em três tópicos." Elas são adicionadas às instruções próprias da Lana, e não usadas no lugar delas.

**extensions** `object`

Opções exclusivas da Lana. Consulte [Extensões](#extensões).

### Modelos

| | `lana-thinking` | `lana-fast` |
| - | - | - |
| Mais indicado para | Análises em várias etapas | Consultas rápidas e fatos isolados |
| Etapas de consulta por turno | Até 20 | Até 4 |
| Pesquisas na web por turno | Até 3 | Até 2 |
| Buscas de páginas da web por turno | Até 2 | Até 2 |
| Transmite o raciocínio | Às vezes, como `thinking_delta`. Lana decide quando raciocinar. | Não |

`lana-thinking` só raciocina quando `max_tokens` é 2048 ou mais.

### Mensagens

Cada mensagem tem um `role` (`user` ou `assistant`) e `content`:

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

A API não armazena conversas. Para fazer uma pergunta complementar, envie novamente a conversa inteira com a nova pergunta no final. O texto da resposta da Lana é suficiente para os turnos `assistant`:

```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 só consulta endereços que aparecem na conversa, nos resultados de suas próprias consultas ou em `extensions.user_context.wallet`.

`content` é uma string não vazia ou um array não vazio de blocos:

| Bloco | Permitido em | Formato |
| - | - | - |
| `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": "..." }` |

As imagens devem ser URLs. Imagens em Base64 não são compatíveis.

Você não precisa de blocos `tool_use` nem `tool_result`. Eles permitem reproduzir as consultas de um turno anterior, conforme retornadas pela Lana, para que ela possa reutilizar esses resultados. `tool_result` também aceita um booleano `is_error` opcional.

### Extensões

Todas as extensões são opcionais.

| Campo | Tipo | Padrão | O que faz |
| - | - | - | - |
| `read_only` | boolean | `true` | Remove as ferramentas de transferência, swap e lançamento de tokens. Mantenha como `true`: esta API não documenta um fluxo para exibir e assinar ações de carteira. |
| `output_format` | `"markdown"` \| `"plain"` | `"markdown"` | `plain` instrui Lana a não usar Markdown e remove os marcadores `{{cite:N}}`. Os eventos `source` ainda chegam. |
| `include_ui_schema` | boolean | `false` | Permite componentes de interface, como eventos `ui_block` e `ui_schema`. |
| `include_followups` | boolean | `false` | Permite até 3 perguntas complementares sugeridas. |
| `include_documents` | boolean | `false` | Permite arquivos CSV, JSON ou de texto para download, como eventos `document`. |
| `enable_deep_scan` | boolean | `false` | Permite que Lana leia até 10.000 transações do histórico de um endereço (50.000 para contagens e totais), com até 3 varreduras por turno. Somente na mainnet. Sem isso, Lana lê até 100 transações por consulta. Varreduras profundas são mais lentas, mas custam o mesmo preço fixo. Elas contam para o limite de 5 minutos do turno. |
| `user_context` | object | nenhum | Quem está perguntando. Veja abaixo. |
| `attachments` | object\[] | nenhum | Até 8 imagens adicionadas à última mensagem do usuário. Blocos `image` em `messages` não contam para esse limite. Cada uma é `{ "url": "https://...", "kind": "image" }`. |

As opções `include_*` tornam a saída possível. Lana decide se a envia.

`extensions` também aceita `progress_context` e `transaction_filter_context`. O explorador [Orb](https://www.helius.dev/docs/pt-BR/orb.md) os utiliza, mas você não precisa deles.

Campos de `user_context`:

| Campo | Tipo | O que faz |
| - | - | - |
| `wallet` | string, até 128 caracteres | O endereço do usuário, para que "minha carteira" e "meu saldo" funcionem. |
| `address_kind` | string, até 32 caracteres | `"wallet"` ou `"token"`: o que é `wallet`. Exige `wallet`. |
| `time_zone` | string, até 64 caracteres | Um fuso horário IANA, como `"America/New_York"`, para que "hoje" funcione. |
| `network` | `"mainnet"` \| `"devnet"` | A rede a consultar. O padrão é mainnet. |

## Eventos de streaming

Com `"stream": true`, você recebe o status `200` e `Content-Type: text/event-stream`. Cada evento tem esta aparência:

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

```

`data` é uma linha de JSON. Seu `type` corresponde ao nome `event`.

O `200` e os primeiros eventos chegam quando Lana responde pela primeira vez (raciocínio, texto da resposta, uma consulta ou um arquivo), ou após no máximo 10 segundos. Até lá, nada é enviado, portanto uma solicitação que falhar nesse intervalo recebe uma [resposta de erro](#antes-do-início-do-fluxo) normal e não é cobrada. Depois disso, um `ping` chega a cada 10 segundos enquanto Lana trabalha.

Defina o tempo limite de leitura do seu cliente HTTP como 30 segundos ou mais. Um padrão de 5 segundos, como em `httpx`, é curto demais: ele pode expirar antes do primeiro byte ou entre dois eventos.

Os eventos chegam nesta ordem:

1. `message_start`, sempre primeiro.
2. Qualquer combinação de `content_block_delta`, `tool_use`, `tool_result`, `source`, `ui_block`, `document`, `progress_update` e `ping`.
3. `ui_schema`, no máximo uma vez.
4. `follow_up`, no máximo uma vez.
5. `message_end` se o turno terminou, ou `error` se falhou. Este é sempre o último evento.

Novos tipos de eventos e campos podem ser adicionados. Ignore os que você não reconhecer.

| Evento | Significado | Exemplo de `data` |
| - | - | - |
| `message_start` | O turno começou. | `{"type":"message_start","message":{"id":"msg_3f9c...","model":"lana-thinking"}}` |
| `content_block_delta` (`text_delta`) | Um trecho da resposta. | `{"type":"content_block_delta","delta":{"type":"text_delta","text":"SOL is trading at"}}` |
| `content_block_delta` (`thinking_delta`) | Um trecho do raciocínio. Somente `lana-thinking`, quando Lana raciocina. | `{"type":"content_block_delta","delta":{"type":"thinking_delta","thinking":"I should check..."}}` |
| `tool_use` | Lana iniciou uma consulta. | `{"type":"tool_use","tool_use_id":"toolu_01...","name":"...","input":{"address":"..."}}` |
| `tool_result` | Uma consulta terminou. `content` é uma prévia de até 500 caracteres. `is_error: true` indica que ela falhou; consulte [Erros de ferramentas](#erros-de-ferramentas). | `{"type":"tool_result","tool_use_id":"toolu_01...","content":"{\"balance\":..."}` |
| `source` | Uma página da web usada pela Lana. `index` corresponde aos marcadores `{{cite:N}}` na resposta. `snippet` é opcional. | `{"type":"source","index":0,"url":"https://...","title":"...","snippet":"..."}` |
| `progress_update` | Uma linha curta de status durante um turno longo. Exiba-a separadamente da resposta. `created_at` está em milissegundos Unix. | `{"type":"progress_update","id":"progress_8a1b...","message":"I'll check this wallet's recent swaps.","created_at":1760436000000}` |
| `ui_block` | Um componente de interface. Exige `include_ui_schema`. `tool_use_id` é opcional. | `{"type":"ui_block","tool_use_id":"toolu_01...","component":"...","schema":{...}}` |
| `document` | Um arquivo para download. Exige `include_documents`. `format` é `csv`, `json` ou `txt`. `tool_use_id` e `description` são opcionais. | `{"type":"document","filename":"usdc-holders","format":"csv","content":"owner,amount\n...","description":"..."}` |
| `ui_schema` | Todos os componentes de interface como uma única árvore. Exige `include_ui_schema`. | `{"type":"ui_schema","schema":{...}}` |
| `follow_up` | Próximas perguntas sugeridas. Exige `include_followups`. | `{"type":"follow_up","suggestions":["Show the top 10 holders' recent transfers"]}` |
| `message_end` | O turno terminou. Consulte [Motivos de parada](#motivos-de-parada) e [Uso](#uso). | `{"type":"message_end","stop_reason":"end_turn","usage":{"input_tokens":91200,"output_tokens":212,"tool_calls":1,"prompt_tokens":46100,"context_window":200000}}` |
| `error` | O turno falhou. Consulte [Erros](#erros). | `{"type":"error","error":{"type":"overloaded_error","message":"Lana is temporarily overloaded. Retry the request shortly."}}` |
| `ping` | Um sinal de atividade a cada 10 segundos. Ignore-o. | `{"type":"ping"}` |

Dicas para exibir um fluxo:

* Use `tool_use` somente para indicadores de progresso. Os nomes e as entradas das ferramentas podem mudar.
* Com a saída `"markdown"`, transforme cada `{{cite:N}}` em um link para o `source` que tenha esse `index`, ou remova-o.
* `ui_block` e `ui_schema` contêm os mesmos componentes. Lana pode enviar somente `ui_schema`, portanto exiba os eventos `ui_block` se eles chegarem; caso contrário, renderize `ui_schema`.
* Pesquisas na web enviam um `tool_result` com o texto `Web search completed.` ou `Web fetch completed.`. As páginas chegam como eventos `source`.

### Erros de ferramentas

Uma consulta com falha não faz o turno falhar. Lana contorna o problema, e você não precisa tentar novamente. O `tool_result` tem `is_error: true`, e `content` é um JSON com uma mensagem curta e um `code`:

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

> [accordion] Tool error codes
>
> | `code` | Significado |
> | - | - |
> | `invalid_input` | Os argumentos da consulta eram inválidos. |
> | `not_found` | Não há dados para esta consulta. Algumas consultas informam um item ausente como um resultado normal, como `{"found": false}`. |
> | `rejected` | O serviço de dados rejeitou a consulta. |
> | `rate_limited` | O serviço de dados está limitando a taxa. |
> | `upstream_timeout` | O tempo limite do serviço de dados expirou. |
> | `upstream_unavailable` | O serviço de dados falhou. |
> | `upstream_error` | Uma ferramenta de dados da Helius falhou. |
> | `timeout` | O tempo da consulta se esgotou. |
> | `tool_failed` | A consulta não conseguiu responder. `error` informa o motivo. |
> | `internal` | Ocorreu uma falha inesperada. |
>
> Novos códigos podem ser adicionados. Trate um código desconhecido como `internal`.

### Motivos de parada

`stop_reason` está em `message_end` e na resposta JSON:

| Valor | Significado |
| - | - |
| `end_turn` | Lana terminou sua resposta. |
| `max_tokens` | A resposta atingiu `max_tokens` e pode ter sido cortada. |
| `tool_use` | O turno terminou em uma etapa de consulta, geralmente no limite de etapas. |
| `error` | O turno falhou. A resposta está incompleta. |

### Uso

| Campo | Significado |
| - | - |
| `input_tokens` | Tokens de entrada do turno inteiro. |
| `output_tokens` | Tokens de saída do turno inteiro. |
| `tool_calls` | Consultas executadas no turno, incluindo algumas que nunca aparecem como `tool_use`. |
| `prompt_tokens` | Tokens de entrada na última etapa do modelo. Use-o para ver o quanto o contexto está cheio. |
| `context_window` | A janela de contexto do modelo, atualmente `200000`. |

As próprias instruções e ferramentas de consulta da Lana consomem cerca de 45.000 tokens em cada etapa do modelo, portanto `input_tokens` é alto mesmo para uma pergunta curta. O preço é por solicitação, então a contagem de tokens não altera o valor pago.

## Resposta sem streaming

Com `"stream": false`, você recebe um objeto JSON quando o turno termina:

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

A resposta está nos blocos `text`, unidos em ordem. O raciocínio e `progress_update` estão disponíveis somente por streaming.

Estes campos aparecem somente quando têm um valor:

| Campo | Quando |
| - | - |
| `ui_schema` | `include_ui_schema` está ativado e há algo para exibir. |
| `documents` | `include_documents` está ativado e Lana criou arquivos. Os mesmos campos de um evento `document`, sem `type`. |
| `follow_up` | `include_followups` está ativado e Lana sugeriu perguntas. Um array de strings. |
| `sources` | Lana usou páginas da web. Os mesmos campos de um evento `source`, sem `type`. |
| `error` | `stop_reason` é `"error"`. Um objeto com `type` e `message`. |

## Erros

### Antes do início do fluxo

Uma solicitação que falha antes do início da resposta retorna um status diferente de `200` com um corpo de erro normal, mesmo com `"stream": true`. Nenhum evento é enviado, e você não é cobrado. Verifique o status HTTP antes de ler o corpo como um fluxo.

Com `"stream": true`, a resposta começa quando Lana responde pela primeira vez, ou após no máximo 10 segundos. Um turno que falha antes disso, por exemplo porque o modelo está sobrecarregado ou a conversa é longa demais, também se enquadra aqui.

| Status | Causa | O que fazer |
| - | - | - |
| `400` | O corpo é inválido, por exemplo, um modelo desconhecido ou um `max_tokens` acima de 8.192. `message` identifica cada campo inválido. | Corrija a solicitação. |
| `401` | A chave de API está ausente ou é inválida, ou foi enviada como `Authorization: Bearer`. | Envie a chave em `X-Api-Key` ou `?api-key=`. |
| `403` | Seu plano não inclui Lana (o plano Free), ou as configurações de acesso da sua chave a bloqueiam. | Faça upgrade para Developer ou superior, ou verifique as configurações de acesso da chave no [Painel da Helius](https://dashboard.helius.dev). |
| `400`, corpo `Bad Request` | O corpo tem mais de 10 MB. Gatekeeper o rejeita antes que Lana o veja. | Envie uma solicitação menor, por exemplo, com menos mensagens ou mensagens mais curtas. |
| `429`, corpo `Too Many Requests` | Você ultrapassou o [limite de taxa](https://www.helius.dev/docs/pt-BR/billing/rate-limits.md) do seu plano. | Aguarde o cabeçalho `Retry-After` (1 segundo) e tente novamente. |
| `429`, corpo `max usage reached` | Seu projeto ficou sem créditos. | Adicione créditos ou faça upgrade do plano. Não há `Retry-After`; novas tentativas falharão até você fazer isso. |
| `429`, `error.type` `rate_limit_error` | Seu projeto já tem cerca de 3 solicitações da Lana em execução. | Aguarde o cabeçalho `Retry-After` (5 segundos) e tente novamente. |
| `503` | Lana atingiu a capacidade máxima ou está reiniciando. | Aguarde o cabeçalho `Retry-After` (5 segundos na capacidade máxima, 30 durante uma reinicialização) e tente novamente. |
| `400`, `error.type` `context_overflow` | A conversa não cabe na janela de contexto. | Remova mensagens antigas ou faça uma pergunta mais específica. |
| `529`, `error.type` `overloaded_error` | O modelo está sobrecarregado. `529` é o status que a Anthropic usa para isso; alguns clientes HTTP não o reconhecem, portanto trate-o como `503`. | Tente novamente com backoff exponencial. |
| `500`, `502`, `504` | O turno falhou antes da primeira saída com `api_error`, `tool_error` ou `timeout_error`. | Trate-o como descrito em [Tipos de erro](#tipos-de-erro). |

Os dois primeiros `429`s vêm do seu plano, e o corpo da resposta informa qual deles ocorreu. O terceiro vem da Lana e tem um corpo JSON.

Se um `429` ou `503` chegar sem um cabeçalho `Retry-After`, aguarde alguns segundos antes de tentar novamente.

Os erros da própria Lana (`400` para um corpo inválido ou `context_overflow`, `429` com `rate_limit_error`, `500`, `502`, `503`, `504` e `529`) têm um corpo JSON. Os erros do Gatekeeper (`401`, `403`, o `400` por corpo grande demais e os `429`s do plano) são texto simples. Faça a ramificação com base em `error.type`, não em `message`:

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

### Após o início do fluxo

O status já é `200`, portanto uma falha encerra o fluxo com um evento final `error` ou com `message_end` e `stop_reason: "error"`. Esse `message_end` não tem um objeto `error`; trate-o como um `api_error`. Qualquer texto de resposta anterior a ele é parcial. Exiba-o como incompleto ou descarte-o.

### Sem streaming

Com `"stream": false`, um turno com falha retorna uma destas opções:

* `200` com `stop_reason: "error"` e um objeto `error`, quando o turno produziu algum conteúdo, incluindo consultas. Sempre verifique `stop_reason`.
* Um corpo de erro JSON, quando o turno não produziu nada. O status corresponde a `error.type`: `400` para `context_overflow`, `500` para `api_error`, `502` para `tool_error`, `504` para `timeout_error` ou `529` para `overloaded_error` (o status que a Anthropic usa para um modelo sobrecarregado; alguns clientes HTTP não o reconhecem, portanto trate-o como `503`). Eles não são cobrados. Trate-os como descrito em [Tipos de erro](#tipos-de-erro).

### Tipos de erro

| `error.type` | Significado | O que fazer |
| - | - | - |
| `invalid_request_error` | A solicitação é inválida. | Corrija a solicitação. |
| `context_overflow` | A conversa e os resultados das consultas não cabem na janela de contexto. | Remova mensagens antigas ou faça uma pergunta mais específica. |
| `overloaded_error` | O modelo está sobrecarregado. | Tente novamente com backoff exponencial. |
| `timeout_error` | O tempo do turno se esgotou. | Faça uma pergunta mais específica ou use `lana-fast`. |
| `tool_error` | Um serviço de consulta do qual Lana depende falhou. | Tente novamente com backoff. |
| `rate_limit_error` | Seu projeto tem cerca de 3 solicitações em execução. | Tente novamente após o cabeçalho `Retry-After`. |
| `api_error` | Lana falhou do lado da Helius ou atingiu a capacidade máxima. | Tente novamente com backoff. |

Trate qualquer outro tipo como `api_error`.

## Limites

| Limite | Valor |
| - | - |
| `max_tokens` | De 1 a 8.192 (padrão: 8.192) |
| `system` | Até 10.000 caracteres |
| `extensions.attachments` | Até 8 imagens |
| Corpo da solicitação | 10 MB |
| Janela de contexto | 200.000 tokens, dos quais cerca de 80% (após `max_tokens`) são destinados à conversa e aos resultados das consultas |
| Duração do turno | 5 minutos |
| Limite de taxa | O limite de taxa de DAS e Enhanced APIs do seu plano. Consulte [Limites de taxa](https://www.helius.dev/docs/pt-BR/billing/rate-limits.md#api-lana). |
| Solicitações simultâneas | Cerca de 3 por projeto. Solicitações adicionais podem receber `429` até que uma termine. |

Quando um turno se aproxima de 5 minutos, Lana para de fazer consultas e responde com o que tem. Turnos longos geralmente terminam com uma resposta parcial que informa o que está faltando, e não com um tempo limite.

Ao usar streaming, defina o tempo limite de leitura do seu cliente HTTP como 30 segundos ou mais. O primeiro byte pode levar até 10 segundos, e um `ping` chega a cada 10 segundos depois disso, portanto um intervalo muito maior significa que a conexão caiu. Um padrão de 5 segundos, como em `httpx`, é curto demais. Sem streaming, nada chega até o turno terminar, portanto defina o tempo limite de leitura acima de 5 minutos.

Se você se desconectar, Lana encerrará o turno. Uma solicitação cujo fluxo já tenha começado ainda será cobrada.

Quando Lana atinge a capacidade máxima, novas solicitações recebem `503` antes que qualquer dado seja transmitido. Elas não são cobradas. Tente novamente após o cabeçalho `Retry-After`.

## Preços

Cada solicitação custa um preço fixo que depende do modelo:

| Modelo | Créditos por solicitação |
| - | - |
| `lana-thinking` | **10.000** |
| `lana-fast` | **2.000** |

O preço é o mesmo para solicitações com e sem streaming e em todos os planos pagos (Developer e superiores). Lana não está disponível no plano Free.

Os créditos vêm do seu plano. Consulte [Créditos](https://www.helius.dev/docs/pt-BR/billing/credits.md#créditos-da-api-lana).

### O que é cobrado

Você é cobrado por toda solicitação que recebe HTTP `200`, com ou sem streaming, independentemente de como o turno termina. Solicitações que falham antes do início da resposta recebem outro status e são gratuitas.

* Um turno com streaming que falha com um evento `error`, ou do qual você se desconecta após o início, é cobrado: o status já era `200`.
* Uma solicitação rejeitada antes do início do turno (`400`, `401`, `403`, `429`, `503`) é gratuita.
* Um turno que falha antes do início da resposta (`400`, `5xx`), com ou sem streaming, é gratuito.

## Mais exemplos

### Definir o tom e a carteira do usuário

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

### Verificar todo o histórico de uma carteira

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

### Obter componentes de interface, perguntas complementares e um 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
    }
  }'
```

## Próximas etapas

> [card] [API Reference](https://www.helius.dev/docs/pt-BR/api-reference/lana/messages.md)
>
> O esquema de solicitação e resposta, com um ambiente de testes.

> [card] [Rate Limits](https://www.helius.dev/docs/pt-BR/billing/rate-limits.md#api-lana)
>
> Os limites de taxa da Lana para cada plano.

> [card] [Credits](https://www.helius.dev/docs/pt-BR/billing/credits.md#créditos-da-api-lana)
>
> Como as solicitações da Lana usam os créditos do seu plano.

> [card] [Contact Support](https://www.helius.dev/docs/pt-BR/support/contact-support)
>
> Obtenha ajuda pelo Discord, chat ou e-mail.


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