Pular para o conteúdo principal
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. 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. Lana é executada nos modelos Claude da Anthropic. Suas perguntas e conversas são enviadas à Anthropic para gerar respostas.
A Lana API está em beta no endpoint Gatekeeper (Beta), 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 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.
2

Ask a question

Substitua YOUR_API_KEY e execute:
cURL
-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:
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.

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

Envie sua chave de API da Helius de uma destas formas: 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.
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.
string
obrigatório
lana-thinking ou lana-fast. Consulte Modelos.
object[]
obrigatório
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.
integer
padrão:"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.
boolean
padrão:"false"
true transmite eventos. false retorna uma resposta JSON quando o turno termina.
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.
object
Opções exclusivas da Lana. Consulte Extensões.

Modelos

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

Mensagens

Cada mensagem tem um role (user ou assistant) e content:
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:
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: 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. 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 os utiliza, mas você não precisa deles. Campos de user_context:

Eventos de streaming

Com "stream": true, você recebe o status 200 e Content-Type: text/event-stream. Cada evento tem esta aparência:
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 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. 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:
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:

Uso

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

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. Os dois primeiros 429s 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 429s do plano) são texto simples. Faça a ramificação com base em error.type, não em message:

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

Trate qualquer outro tipo como api_error.

Limites

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

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

cURL

Verificar todo o histórico de uma carteira

cURL

Obter componentes de interface, perguntas complementares e um CSV

cURL

Próximas etapas

API Reference

O esquema de solicitação e resposta, com um ambiente de testes.

Rate Limits

Os limites de taxa da Lana para cada plano.

Credits

Como as solicitações da Lana usam os créditos do seu plano.

Contact Support

Obtenha ajuda pelo Discord, chat ou e-mail.