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

# API de Lana - Agente de IA de Solana

> Llama a Lana, un agente de IA de Solana, mediante HTTP: pregunta sobre billeteras, tokens, transacciones y precios, y recibe la respuesta por streaming. Inicio rápido, referencia de la API y precios.

La API de Lana es un agente de IA de Solana al que llamas mediante HTTP. Le envías una pregunta en lenguaje natural y busca billeteras, tokens, transacciones y precios por ti; luego devuelve una respuesta por streaming.

Lana ejecuta todas las búsquedas del lado de Helius, por lo que no tienes que definir ni ejecutar herramientas. Está disponible en los planes de pago de Helius (Developer y superiores), con un precio fijo por solicitud: 10,000 créditos para `lana-thinking` y 2,000 créditos para `lana-fast`. Consulta [Precios](#precios).

La API tiene una estructura similar a la API Messages de Anthropic, pero los SDK de Anthropic no funcionan con ella. Llámala mediante HTTP estándar, como en los ejemplos siguientes. Consulta [Diferencias con la API Messages de Anthropic](#diferencias-con-la-api-messages-de-anthropic).

Lana funciona con los modelos Claude de Anthropic. Tus preguntas y conversaciones se envían a Anthropic para generar respuestas.

> [!NOTE]
>
> La API de Lana está en beta en el endpoint [Gatekeeper (Beta)](https://www.helius.dev/docs/es/gatekeeper/overview.md), `beta.helius-rpc.com`. Todavía no está disponible en `mainnet.helius-rpc.com`. Durante la beta, pueden agregarse eventos y campos nuevos.

## Qué puedes preguntarle a Lana

Preguntas que tus usuarios pueden hacer sobre sus operaciones y las billeteras con las que interactúan:

* "¿Por qué falló mi última transacción?"
* "¿Cuánto deslizamiento tuve en este intercambio?"
* "¿Qué comisiones pagué en esta transacción?"
* "¿De dónde obtuvo fondos esta billetera y adónde los envió?"
* "¿Esta billetera está conectada con esta otra billetera?"
* "¿Quiénes son los mayores titulares de este token?"

Pasa la billetera del usuario en [`extensions.user_context.wallet`](#extensiones) para que funcionen las preguntas sobre "mi" billetera o "mi última transacción".

## Inicio rápido

**1. Get an API key**

Copia una clave de API desde el [panel de Helius](https://dashboard.helius.dev).

**2. Ask a question**

Reemplaza `YOUR_API_KEY` y ejecuta:

```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` hace que curl imprima cada evento en cuanto llega. El primer evento puede tardar hasta 10 segundos.

**3. Read the answer**

La respuesta es un flujo 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}}
```

La respuesta está en los fragmentos `text_delta`, en orden. `lana-thinking` también puede enviar fragmentos `thinking_delta`: ese es el razonamiento de Lana, así que muéstralo separado de la respuesta u omítelo.

### Lee el flujo en código

Ambos ejemplos verifican el estado HTTP antes de leer el cuerpo como flujo, esperan `Retry-After` ante un `429` o `503`, imprimen la respuesta a medida que llega y se detienen si el turno falla o el flujo termina antes de tiempo.

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

## Diferencias con la API Messages de Anthropic

* Los modelos son `lana-thinking` y `lana-fast`.
* Lana ejecuta sus propias herramientas. `tools`, `tool_choice`, `temperature`, `top_p`, `top_k`, `stop_sequences` y `metadata` devuelven `400`.
* `system` se agrega a las instrucciones de Lana.
* `max_tokens` es opcional (valor predeterminado y máximo de 8,192), y las imágenes deben ser URL.
* Los eventos son diferentes. No hay `content_block_start`, `content_block_stop`, `message_delta` ni `message_stop`. El flujo termina con `message_end` o `error`.
* `usage` agrega `tool_calls`, `prompt_tokens` y `context_window`. `stop_reason` puede ser `error`.
* `extensions` es exclusivo de Lana.

## Endpoint y autenticación

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

Envía tu clave de API de Helius de una de estas formas:

| Método | Ejemplo |
| - | - |
| Encabezado `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` no funciona en este endpoint y devuelve `401`.

`mainnet.helius-rpc.com` todavía no ofrece esta ruta y devuelve `503`.

Envía `Content-Type: application/json` en cada solicitud.

> [!WARNING]
>
> Tu clave de API consume los créditos de tu plan. Llama a Lana desde tu servidor, no desde un navegador ni desde una aplicación que distribuyas a los usuarios.

## Cuerpo de la solicitud

El cuerpo es un objeto JSON. Los campos desconocidos se rechazan con `400`, incluidos los campos desconocidos dentro de `extensions` y los bloques de contenido.

**model** `string` *required*

`lana-thinking` o `lana-fast`. Consulta [Modelos](#modelos).

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

La conversación, comenzando por el mensaje más antiguo. Necesita al menos un mensaje y el último debe tener `role: "user"`. Consulta [Mensajes](#mensajes).

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

La cantidad máxima de tokens de salida que Lana puede escribir en un paso del modelo, desde `1` hasta `8192`. Un turno con búsquedas requiere varios pasos, por lo que el `output_tokens` total del turno puede ser mayor que `max_tokens`. Por debajo de 2,048, `lana-thinking` no razona.

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

`true` transmite [eventos](#eventos-de-streaming). `false` devuelve una [respuesta JSON](#respuesta-sin-streaming) cuando termina el turno.

**system** `string`

Instrucciones adicionales, de 1 a 10,000 caracteres, como "Responde en tres viñetas". Se agregan a las instrucciones propias de Lana, no las reemplazan.

**extensions** `object`

Opciones exclusivas de Lana. Consulta [Extensiones](#extensiones).

### Modelos

| | `lana-thinking` | `lana-fast` |
| - | - | - |
| Ideal para | Análisis de varios pasos | Búsquedas rápidas y datos individuales |
| Pasos de búsqueda por turno | Hasta 20 | Hasta 4 |
| Búsquedas web por turno | Hasta 3 | Hasta 2 |
| Obtenciones de páginas web por turno | Hasta 2 | Hasta 2 |
| Transmite el razonamiento | A veces, como `thinking_delta`. Lana decide cuándo razonar. | No |

`lana-thinking` solo razona cuando `max_tokens` es 2048 o más.

### Mensajes

Cada mensaje tiene un `role` (`user` o `assistant`) y `content`:

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

La API no almacena conversaciones. Para hacer una pregunta de seguimiento, vuelve a enviar toda la conversación con la nueva pregunta al final. El texto de la respuesta de Lana es suficiente para los 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 solo busca direcciones que aparecen en la conversación, en los resultados de sus propias búsquedas o en `extensions.user_context.wallet`.

`content` es una cadena no vacía o un arreglo no vacío de bloques:

| Bloque | Permitido en | Estructura |
| - | - | - |
| `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": "..." }` |

Las imágenes deben ser URL. No se admiten imágenes Base64.

No necesitas bloques `tool_use` ni `tool_result`. Te permiten reproducir las búsquedas de un turno anterior, tal como Lana las devolvió, para que pueda reutilizar esos resultados. `tool_result` también acepta un booleano `is_error` opcional.

### Extensiones

Todas las extensiones son opcionales.

| Campo | Tipo | Valor predeterminado | Función |
| - | - | - | - |
| `read_only` | boolean | `true` | Elimina las herramientas de transferencia, intercambio y lanzamiento de tokens. Déjalo como `true`: esta API no documenta un flujo para mostrar y firmar acciones de billetera. |
| `output_format` | `"markdown"` \| `"plain"` | `"markdown"` | `plain` indica a Lana que no use Markdown y elimina los marcadores `{{cite:N}}`. Los eventos `source` siguen llegando. |
| `include_ui_schema` | boolean | `false` | Permite componentes de UI, como eventos `ui_block` y `ui_schema`. |
| `include_followups` | boolean | `false` | Permite hasta 3 preguntas de seguimiento sugeridas. |
| `include_documents` | boolean | `false` | Permite archivos CSV, JSON o de texto descargables, como eventos `document`. |
| `enable_deep_scan` | boolean | `false` | Permite que Lana lea hasta 10,000 transacciones del historial de una dirección (50,000 para conteos y totales), con hasta 3 análisis por turno. Solo en mainnet. Sin esta opción, Lana lee hasta 100 transacciones por búsqueda. Los análisis profundos son más lentos, pero cuestan el mismo precio fijo. Cuentan para el límite de 5 minutos por turno. |
| `user_context` | object | ninguno | Quién hace la pregunta. Consulta a continuación. |
| `attachments` | object\[] | ninguno | Hasta 8 imágenes agregadas al último mensaje del usuario. Los bloques `image` en `messages` no cuentan para este límite. Cada una es `{ "url": "https://...", "kind": "image" }`. |

Las opciones `include_*` permiten generar esos resultados. Lana decide si los envía.

`extensions` también acepta `progress_context` y `transaction_filter_context`. El explorador [Orb](https://www.helius.dev/docs/es/orb.md) los usa, pero tú no los necesitas.

Campos de `user_context`:

| Campo | Tipo | Función |
| - | - | - |
| `wallet` | string, hasta 128 caracteres | La dirección del usuario, para que funcionen "mi billetera" y "mi saldo". |
| `address_kind` | string, hasta 32 caracteres | `"wallet"` o `"token"`: qué es `wallet`. Requiere `wallet`. |
| `time_zone` | string, hasta 64 caracteres | Una zona horaria de IANA, como `"America/New_York"`, para que funcione "hoy". |
| `network` | `"mainnet"` \| `"devnet"` | La red que se consultará. El valor predeterminado es mainnet. |

## Eventos de streaming

Con `"stream": true`, recibes el estado `200` e `Content-Type: text/event-stream`. Cada evento tiene este aspecto:

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

```

`data` es una línea de JSON. Su `type` coincide con el nombre `event`.

El `200` y los primeros eventos llegan cuando Lana responde por primera vez (razonamiento, texto de respuesta, una búsqueda o un archivo), o después de 10 segundos como máximo. Hasta entonces no se envía nada, por lo que una solicitud que falla en ese periodo recibe una [respuesta de error](#antes-de-que-comience-el-flujo) normal y no se cobra. Después, llega un `ping` cada 10 segundos mientras Lana trabaja.

Configura el tiempo de espera de lectura de tu cliente HTTP en 30 segundos o más. Un valor predeterminado de 5 segundos, como en `httpx`, es demasiado corto: puede vencer antes del primer byte o entre dos eventos.

Los eventos llegan en este orden:

1. `message_start`, siempre primero.
2. Cualquier combinación de `content_block_delta`, `tool_use`, `tool_result`, `source`, `ui_block`, `document`, `progress_update` e `ping`.
3. `ui_schema`, como máximo una vez.
4. `follow_up`, como máximo una vez.
5. `message_end` si el turno terminó, o `error` si falló. Este siempre es el último evento.

Pueden agregarse nuevos tipos de eventos y campos. Ignora los que no reconozcas.

| Evento | Significado | Ejemplo de `data` |
| - | - | - |
| `message_start` | El turno comenzó. | `{"type":"message_start","message":{"id":"msg_3f9c...","model":"lana-thinking"}}` |
| `content_block_delta` (`text_delta`) | Un fragmento de la respuesta. | `{"type":"content_block_delta","delta":{"type":"text_delta","text":"SOL is trading at"}}` |
| `content_block_delta` (`thinking_delta`) | Un fragmento del razonamiento. Solo `lana-thinking`, cuando Lana razona. | `{"type":"content_block_delta","delta":{"type":"thinking_delta","thinking":"I should check..."}}` |
| `tool_use` | Lana inició una búsqueda. | `{"type":"tool_use","tool_use_id":"toolu_01...","name":"...","input":{"address":"..."}}` |
| `tool_result` | Una búsqueda terminó. `content` es una vista previa de hasta 500 caracteres. `is_error: true` significa que falló; consulta [Errores de herramientas](#errores-de-herramientas). | `{"type":"tool_result","tool_use_id":"toolu_01...","content":"{\"balance\":..."}` |
| `source` | Una página web que usó Lana. `index` coincide con los marcadores `{{cite:N}}` de la respuesta. `snippet` es opcional. | `{"type":"source","index":0,"url":"https://...","title":"...","snippet":"..."}` |
| `progress_update` | Una línea breve de estado durante un turno largo. Muéstrala separada de la respuesta. `created_at` son milisegundos Unix. | `{"type":"progress_update","id":"progress_8a1b...","message":"I'll check this wallet's recent swaps.","created_at":1760436000000}` |
| `ui_block` | Un componente de UI. Requiere `include_ui_schema`. `tool_use_id` es opcional. | `{"type":"ui_block","tool_use_id":"toolu_01...","component":"...","schema":{...}}` |
| `document` | Un archivo descargable. Requiere `include_documents`. `format` es `csv`, `json` o `txt`. `tool_use_id` e `description` son opcionales. | `{"type":"document","filename":"usdc-holders","format":"csv","content":"owner,amount\n...","description":"..."}` |
| `ui_schema` | Todos los componentes de UI como un solo árbol. Requiere `include_ui_schema`. | `{"type":"ui_schema","schema":{...}}` |
| `follow_up` | Sugerencias de preguntas siguientes. Requiere `include_followups`. | `{"type":"follow_up","suggestions":["Show the top 10 holders' recent transfers"]}` |
| `message_end` | El turno terminó. Consulta [Motivos de detención](#motivos-de-detención) y [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` | El turno falló. Consulta [Errores](#errores). | `{"type":"error","error":{"type":"overloaded_error","message":"Lana is temporarily overloaded. Retry the request shortly."}}` |
| `ping` | Una señal de actividad cada 10 segundos. Ignórala. | `{"type":"ping"}` |

Consejos para mostrar un flujo:

* Usa `tool_use` solo para indicadores de progreso. Los nombres y las entradas de las herramientas pueden cambiar.
* Con la salida `"markdown"`, convierte cada `{{cite:N}}` en un enlace al `source` que tenga ese `index`, o elimínalo.
* `ui_block` e `ui_schema` contienen los mismos componentes. Es posible que Lana solo envíe `ui_schema`, así que muestra los eventos `ui_block` si llegan; de lo contrario, renderiza `ui_schema`.
* Las búsquedas web envían un `tool_result` con el texto `Web search completed.` o `Web fetch completed.`. Las páginas llegan como eventos `source`.

### Errores de herramientas

Una búsqueda fallida no hace que falle el turno. Lana intenta sortear el problema y no necesitas volver a intentarlo. `tool_result` tiene `is_error: true`, e `content` es JSON con un mensaje breve y un `code`:

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

> [accordion] Tool error codes
>
> | `code` | Significado |
> | - | - |
> | `invalid_input` | Los argumentos de la búsqueda no eran válidos. |
> | `not_found` | No hay datos para esta búsqueda. Algunas búsquedas informan un elemento ausente como resultado normal, como `{"found": false}`. |
> | `rejected` | El servicio de datos rechazó la búsqueda. |
> | `rate_limited` | El servicio de datos está limitando la tasa. |
> | `upstream_timeout` | Se agotó el tiempo de espera del servicio de datos. |
> | `upstream_unavailable` | El servicio de datos falló. |
> | `upstream_error` | Falló una herramienta de datos de Helius. |
> | `timeout` | Se agotó el tiempo de la búsqueda. |
> | `tool_failed` | La búsqueda no pudo responder. `error` indica el motivo. |
> | `internal` | Ocurrió un error inesperado. |
>
> Pueden agregarse códigos nuevos. Trata un código desconocido como `internal`.

### Motivos de detención

`stop_reason` está en `message_end` y en la respuesta JSON:

| Valor | Significado |
| - | - |
| `end_turn` | Lana terminó su respuesta. |
| `max_tokens` | La respuesta alcanzó `max_tokens` y puede estar cortada. |
| `tool_use` | El turno terminó en un paso de búsqueda, normalmente por alcanzar el límite de pasos. |
| `error` | El turno falló. La respuesta está incompleta. |

### Uso

| Campo | Significado |
| - | - |
| `input_tokens` | Tokens de entrada de todo el turno. |
| `output_tokens` | Tokens de salida de todo el turno. |
| `tool_calls` | Búsquedas ejecutadas en el turno, incluidas algunas que nunca aparecen como `tool_use`. |
| `prompt_tokens` | Tokens de entrada del último paso del modelo. Úsalo para ver qué tan lleno está el contexto. |
| `context_window` | La ventana de contexto del modelo, actualmente `200000`. |

Las instrucciones y herramientas de búsqueda propias de Lana consumen unos 45,000 tokens en cada paso del modelo, por lo que `input_tokens` es alto incluso para una pregunta corta. El precio es por solicitud, así que la cantidad de tokens no cambia lo que pagas.

## Respuesta sin streaming

Con `"stream": false`, recibes un objeto JSON cuando termina el turno:

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

La respuesta está en los bloques `text`, unidos en orden. El razonamiento e `progress_update` solo están disponibles con streaming.

Estos campos solo aparecen cuando tienen un valor:

| Campo | Cuándo |
| - | - |
| `ui_schema` | `include_ui_schema` está activado y hay algo que mostrar. |
| `documents` | `include_documents` está activado y Lana creó archivos. Tiene los mismos campos que un evento `document`, sin `type`. |
| `follow_up` | `include_followups` está activado y Lana sugirió preguntas. Es un arreglo de cadenas. |
| `sources` | Lana usó páginas web. Tiene los mismos campos que un evento `source`, sin `type`. |
| `error` | `stop_reason` es `"error"`. Es un objeto con `type` e `message`. |

## Errores

### Antes de que comience el flujo

Una solicitud que falla antes de que comience la respuesta devuelve un estado distinto de `200` con un cuerpo de error normal, incluso con `"stream": true`. No se envían eventos y no se te cobra. Verifica el estado HTTP antes de leer el cuerpo como flujo.

Con `"stream": true`, la respuesta comienza cuando Lana responde por primera vez, o después de 10 segundos como máximo. Un turno que falla antes, por ejemplo porque el modelo está sobrecargado o la conversación es demasiado larga, también se incluye aquí.

| Estado | Causa | Qué hacer |
| - | - | - |
| `400` | El cuerpo no es válido; por ejemplo, contiene un modelo desconocido o un `max_tokens` superior a 8,192. `message` identifica cada campo incorrecto. | Corrige la solicitud. |
| `401` | Falta la clave de API, no es válida o se envió como `Authorization: Bearer`. | Envía la clave en `X-Api-Key` o `?api-key=`. |
| `403` | Tu plan no incluye Lana (el plan Free) o la configuración de acceso de tu clave la bloquea. | Cambia al plan Developer o uno superior, o revisa la configuración de acceso de la clave en el [panel de Helius](https://dashboard.helius.dev). |
| `400`, cuerpo `Bad Request` | El cuerpo supera los 10 MB. Gatekeeper lo rechaza antes de que Lana lo reciba. | Envía una solicitud más pequeña, por ejemplo con menos mensajes o mensajes más cortos. |
| `429`, cuerpo `Too Many Requests` | Superaste el [límite de tasa](https://www.helius.dev/docs/es/billing/rate-limits.md) de tu plan. | Espera el encabezado `Retry-After` (1 segundo) y vuelve a intentarlo. |
| `429`, cuerpo `max usage reached` | Tu proyecto se quedó sin créditos. | Agrega créditos o mejora tu plan. No hay `Retry-After`; los reintentos fallarán hasta que lo hagas. |
| `429`, `error.type` `rate_limit_error` | Tu proyecto ya tiene unas 3 solicitudes de Lana en ejecución. | Espera el encabezado `Retry-After` (5 segundos) y vuelve a intentarlo. |
| `503` | Lana alcanzó su capacidad máxima o se está reiniciando. | Espera el encabezado `Retry-After` (5 segundos si está al máximo de capacidad y 30 durante el reinicio) y vuelve a intentarlo. |
| `400`, `error.type` `context_overflow` | La conversación no cabe en la ventana de contexto. | Elimina mensajes antiguos o haz una pregunta más específica. |
| `529`, `error.type` `overloaded_error` | El modelo está sobrecargado. `529` es el estado que Anthropic usa para esto; algunos clientes HTTP no lo reconocen, así que trátalo como `503`. | Vuelve a intentarlo con espera exponencial. |
| `500`, `502`, `504` | El turno falló antes de producir su primera salida con `api_error`, `tool_error` o `timeout_error`. | Manéjalo como se indica en [Tipos de error](#tipos-de-error). |

Los dos primeros `429` provienen de tu plan y el cuerpo de la respuesta indica cuál alcanzaste. El tercero proviene de Lana y tiene un cuerpo JSON.

Si llega un `429` o `503` sin un encabezado `Retry-After`, espera unos segundos antes de volver a intentarlo.

Los errores propios de Lana (`400` para un cuerpo no válido o `context_overflow`, `429` con `rate_limit_error`, `500`, `502`, `503`, `504` y `529`) tienen un cuerpo JSON. Los errores de Gatekeeper (`401`, `403`, `400` por un cuerpo demasiado grande y los `429` del plan) son texto sin formato. Bifurca según `error.type`, no según `message`:

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

### Después de que comience el flujo

El estado ya es `200`, por lo que un fallo termina el flujo con un evento `error` final, o con `message_end` e `stop_reason: "error"`. Ese `message_end` no tiene un objeto `error`; trátalo como un `api_error`. Cualquier texto de respuesta anterior es parcial. Muéstralo como incompleto o descártalo.

### Sin streaming

Con `"stream": false`, un turno fallido devuelve una de estas opciones:

* `200` con `stop_reason: "error"` y un objeto `error`, cuando el turno produjo algún contenido, incluidas búsquedas. Verifica siempre `stop_reason`.
* Un cuerpo de error JSON cuando el turno no produjo nada. El estado coincide con `error.type`: `400` para `context_overflow`, `500` para `api_error`, `502` para `tool_error`, `504` para `timeout_error` o `529` para `overloaded_error` (el estado que Anthropic usa para un modelo sobrecargado; algunos clientes HTTP no lo reconocen, así que trátalo como `503`). Estos casos no se cobran. Manéjalos como se indica en [Tipos de error](#tipos-de-error).

### Tipos de error

| `error.type` | Significado | Qué hacer |
| - | - | - |
| `invalid_request_error` | La solicitud no es válida. | Corrige la solicitud. |
| `context_overflow` | La conversación y los resultados de búsqueda no caben en la ventana de contexto. | Elimina mensajes antiguos o haz una pregunta más específica. |
| `overloaded_error` | El modelo está sobrecargado. | Vuelve a intentarlo con espera exponencial. |
| `timeout_error` | Se agotó el tiempo del turno. | Haz una pregunta más específica o usa `lana-fast`. |
| `tool_error` | Falló un servicio de búsqueda del que depende Lana. | Vuelve a intentarlo con espera progresiva. |
| `rate_limit_error` | Tu proyecto tiene unas 3 solicitudes en ejecución. | Vuelve a intentarlo después del encabezado `Retry-After`. |
| `api_error` | Lana falló del lado de Helius o alcanzó su capacidad máxima. | Vuelve a intentarlo con espera progresiva. |

Trata cualquier otro tipo como `api_error`.

## Límites

| Límite | Valor |
| - | - |
| `max_tokens` | De 1 a 8,192 (valor predeterminado: 8,192) |
| `system` | Hasta 10,000 caracteres |
| `extensions.attachments` | Hasta 8 imágenes |
| Cuerpo de la solicitud | 10 MB |
| Ventana de contexto | 200,000 tokens, de los cuales alrededor del 80 % (después de `max_tokens`) corresponde a la conversación y los resultados de búsqueda |
| Duración del turno | 5 minutos |
| Límite de tasa | El límite de tasa de DAS y Enhanced APIs de tu plan. Consulta [Límites de tasa](https://www.helius.dev/docs/es/billing/rate-limits.md#api-de-lana). |
| Solicitudes simultáneas | Alrededor de 3 por proyecto. Las solicitudes adicionales pueden recibir `429` hasta que termine una. |

Cuando un turno se acerca a los 5 minutos, Lana deja de buscar y responde con lo que tiene. Los turnos largos suelen terminar con una respuesta parcial que indica qué falta, no con un error de tiempo de espera.

Cuando uses streaming, configura el tiempo de espera de lectura de tu cliente HTTP en 30 segundos o más. El primer byte puede tardar hasta 10 segundos y después llega un `ping` cada 10 segundos, por lo que una pausa mucho más larga significa que se perdió la conexión. Un valor predeterminado de 5 segundos, como en `httpx`, es demasiado corto. Sin streaming, no llega nada hasta que termina el turno, así que configura el tiempo de espera de lectura en más de 5 minutos.

Si te desconectas, Lana detiene el turno. Una solicitud cuyo flujo ya comenzó se cobra de todos modos.

Cuando Lana alcanza su capacidad máxima, las solicitudes nuevas reciben `503` antes de que se transmita algo. No se cobran. Vuelve a intentarlo después del encabezado `Retry-After`.

## Precios

Cada solicitud tiene un precio fijo que depende del modelo:

| Modelo | Créditos por solicitud |
| - | - |
| `lana-thinking` | **10,000** |
| `lana-fast` | **2,000** |

El precio es el mismo para las solicitudes con y sin streaming, y en todos los planes de pago (Developer y superiores). Lana no está disponible en el plan Free.

Los créditos provienen de tu plan. Consulta [Créditos](https://www.helius.dev/docs/es/billing/credits.md#créditos-de-la-api-de-lana).

### Qué se cobra

Se te cobra por cada solicitud que recibe HTTP `200`, con streaming o sin él, independientemente de cómo termine el turno. Las solicitudes que fallan antes de que comience la respuesta reciben otro estado y son gratuitas.

* Se cobra un turno de streaming que falla con un evento `error` o del que te desconectas después de que comienza: el estado ya era `200`.
* Una solicitud rechazada antes de que comience el turno (`400`, `401`, `403`, `429`, `503`) es gratuita.
* Un turno que falla antes de que comience la respuesta (`400`, `5xx`), con streaming o sin él, es gratuito.

## Más ejemplos

### Configura el tono y la billetera del usuario

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

### Analiza el historial completo de una billetera

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

### Obtén componentes de UI, preguntas de seguimiento y un 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óximos pasos

> [card] [API Reference](https://www.helius.dev/docs/es/api-reference/lana/messages.md)
>
> El esquema de solicitud y respuesta, con un entorno de pruebas.

> [card] [Rate Limits](https://www.helius.dev/docs/es/billing/rate-limits.md#api-de-lana)
>
> Los límites de tasa de Lana para cada plan.

> [card] [Credits](https://www.helius.dev/docs/es/billing/credits.md#créditos-de-la-api-de-lana)
>
> Cómo usan las solicitudes de Lana los créditos de tu plan.

> [card] [Contact Support](https://www.helius.dev/docs/es/support/contact-support)
>
> Obtén ayuda por Discord, chat o correo electrónico.


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