Saltar al contenido principal
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. 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. Lana funciona con los modelos Claude de Anthropic. Tus preguntas y conversaciones se envían a Anthropic para generar respuestas.
La API de Lana está en beta en el endpoint Gatekeeper (Beta), 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 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.
2

Ask a question

Reemplaza YOUR_API_KEY y ejecuta:
cURL
-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:
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.

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

Envía tu clave de API de Helius de una de estas formas: 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.
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.
string
requerido
lana-thinking o lana-fast. Consulta Modelos.
object[]
requerido
La conversación, comenzando por el mensaje más antiguo. Necesita al menos un mensaje y el último debe tener role: "user". Consulta Mensajes.
integer
predeterminado:"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.
boolean
predeterminado:"false"
true transmite eventos. false devuelve una respuesta JSON cuando termina el turno.
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.
object
Opciones exclusivas de Lana. Consulta Extensiones.

Modelos

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

Mensajes

Cada mensaje tiene un role (user o assistant) y content:
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:
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: 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. 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 los usa, pero tú no los necesitas. Campos de user_context:

Eventos de streaming

Con "stream": true, recibes el estado 200 e Content-Type: text/event-stream. Cada evento tiene este aspecto:
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 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. 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:
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:

Uso

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:
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:

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í. 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:

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

Trata cualquier otro tipo como api_error.

Límites

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

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

cURL

Analiza el historial completo de una billetera

cURL

Obtén componentes de UI, preguntas de seguimiento y un CSV

cURL

Próximos pasos

API Reference

El esquema de solicitud y respuesta, con un entorno de pruebas.

Rate Limits

Los límites de tasa de Lana para cada plan.

Credits

Cómo usan las solicitudes de Lana los créditos de tu plan.

Contact Support

Obtén ayuda por Discord, chat o correo electrónico.