> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Lana API – Solana-KI-Agent

> Rufe Lana, einen Solana-KI-Agenten, über HTTP auf: Stelle Fragen zu Wallets, Token, Transaktionen und Preisen und erhalte die Antwort als stream. Mit Schnellstart, API-Referenz und Preisen.

Die Lana API ist ein Solana-KI-Agent, den du über HTTP aufrufst. Du stellst eine Frage in natürlicher Sprache. Lana sucht dann Wallets, Token, Transaktionen und Preise für dich nach und gibt die Antwort als stream zurück.

Lana führt jede Abfrage auf der Helius-Seite aus. Du musst daher keine Tools definieren oder ausführen. Lana ist in kostenpflichtigen Helius-Tarifen (Developer und höher) zu einem Festpreis pro request verfügbar: 10.000 Credits für `lana-thinking` und 2.000 Credits für `lana-fast`. Siehe [Preise](#preise).

Die API ist wie die Anthropic Messages API aufgebaut. Die Anthropic SDKs funktionieren damit jedoch nicht. Rufe sie wie in den folgenden Beispielen direkt über HTTP auf. Siehe [Unterschiede zur Anthropic Messages API](#unterschiede-zur-anthropic-messages-api).

Lana nutzt die Claude-Modelle von Anthropic. Deine Fragen und die Konversation werden an Anthropic gesendet, um Antworten zu generieren.

> [!NOTE]
>
> Die Lana API befindet sich auf dem [Gatekeeper (Beta)](https://www.helius.dev/docs/de/gatekeeper/overview.md)-endpoint `beta.helius-rpc.com` in der Betaphase. Auf `mainnet.helius-rpc.com` ist sie noch nicht verfügbar. Während der Betaphase können neue Ereignisse und Felder hinzukommen.

## Was du Lana fragen kannst

Fragen, die deine Benutzer zu ihren Trades und den Wallets stellen können, mit denen sie interagieren:

* „Warum ist meine letzte Transaktion fehlgeschlagen?“
* „Wie hoch war der Slippage bei diesem Swap?“
* „Welche Gebühren habe ich für diese Transaktion bezahlt?“
* „Woher hat dieses Wallet sein Guthaben und wohin hat es dieses gesendet?“
* „Ist dieses Wallet mit diesem anderen Wallet verbunden?“
* „Wer sind die größten Inhaber dieses Tokens?“

Übergib das Wallet des Benutzers in [`extensions.user_context.wallet`](#erweiterungen), damit Fragen zu „meinem“ Wallet oder „meiner letzten Transaktion“ funktionieren.

## Schnellstart

**1. Get an API key**

Kopiere einen API key aus dem [Helius Dashboard](https://dashboard.helius.dev).

**2. Ask a question**

Ersetze `YOUR_API_KEY` und führe Folgendes aus:

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

Mit `-N` gibt curl jedes Ereignis sofort nach dem Eintreffen aus. Bis zum ersten Ereignis können bis zu 10 Sekunden vergehen.

**3. Read the answer**

Die response ist ein stream aus [Ereignissen](#streaming-ereignisse):

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

Die Antwort besteht aus den `text_delta`-Abschnitten in der richtigen Reihenfolge. `lana-thinking` kann auch `thinking_delta`-Abschnitte senden. Das sind Lanas Überlegungen. Zeige sie daher getrennt von der Antwort an oder überspringe sie.

### Den stream im Code lesen

Beide Beispiele prüfen den HTTP-Status, bevor sie den Body als stream lesen. Sie warten bei `429` oder `503` auf `Retry-After`, geben die Antwort während des Streamings aus und stoppen, wenn die Runde fehlschlägt oder der stream vorzeitig endet.

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

## Unterschiede zur Anthropic Messages API

* Die Modelle sind `lana-thinking` und `lana-fast`.
* Lana führt eigene Tools aus. `tools`, `tool_choice`, `temperature`, `top_p`, `top_k`, `stop_sequences` und `metadata` geben `400` zurück.
* `system` wird zu Lanas Anweisungen hinzugefügt.
* `max_tokens` ist optional (Standard und Maximum: 8.192) und Bilder müssen URLs sein.
* Die Ereignisse unterscheiden sich. Es gibt kein `content_block_start`, `content_block_stop`, `message_delta` oder `message_stop`. Der stream endet mit `message_end` oder `error`.
* `usage` fügt `tool_calls`, `prompt_tokens` und `context_window` hinzu. `stop_reason` kann `error` sein.
* `extensions` ist nur für Lana verfügbar.

## Endpoint und Authentifizierung

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

Sende deinen Helius API key auf eine der folgenden Arten:

| Methode | Beispiel |
| - | - |
| `X-Api-Key`-Header (empfohlen) | `X-Api-Key: YOUR_API_KEY` |
| `api-key`-Abfrageparameter | `https://beta.helius-rpc.com/v1/lana/messages?api-key=YOUR_API_KEY` |

`Authorization: Bearer` funktioniert auf diesem endpoint nicht und gibt `401` zurück.

`mainnet.helius-rpc.com` stellt diese Route noch nicht bereit und gibt `503` zurück.

Sende `Content-Type: application/json` bei jedem request.

> [!WARNING]
>
> Dein API key verbraucht die Credits deines Tarifs. Rufe Lana von deinem Server aus auf, nicht über einen Browser oder eine App, die du an Benutzer auslieferst.

## Request-Body

Der Body ist ein JSON-Objekt. Unbekannte Felder werden mit `400` abgelehnt. Das gilt auch für unbekannte Felder innerhalb von `extensions` und Inhaltsblöcken.

**model** `string` *required*

`lana-thinking` oder `lana-fast`. Siehe [Modelle](#modelle).

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

Die Konversation, beginnend mit der ältesten Nachricht. Sie muss mindestens eine Nachricht enthalten. Die letzte Nachricht muss `role: "user"` enthalten. Siehe [Nachrichten](#nachrichten).

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

Die maximale Anzahl an Ausgabe-Token, die Lana in einem Modellschritt schreiben kann: von `1` bis `8192`. Eine Runde mit Abfragen umfasst mehrere Schritte. Daher kann der gesamte `output_tokens`-Wert der Runde über `max_tokens` liegen. Unter 2.048 führt `lana-thinking` keine Überlegungen aus.

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

`true` streamt [Ereignisse](#streaming-ereignisse). `false` gibt nach dem Ende der Runde eine einzelne [JSON-response](#response-ohne-streaming) zurück.

**system** `string`

Zusätzliche Anweisungen mit 1 bis 10.000 Zeichen, etwa „Antworte in drei Stichpunkten.“ Sie werden zu Lanas eigenen Anweisungen hinzugefügt und ersetzen diese nicht.

**extensions** `object`

Optionen nur für Lana. Siehe [Erweiterungen](#erweiterungen).

### Modelle

| | `lana-thinking` | `lana-fast` |
| - | - | - |
| Am besten geeignet für | Mehrstufige Analysen | Schnelle Abfragen und einzelne Fakten |
| Abfrageschritte pro Runde | Bis zu 20 | Bis zu 4 |
| Websuchen pro Runde | Bis zu 3 | Bis zu 2 |
| Abrufe von Webseiten pro Runde | Bis zu 2 | Bis zu 2 |
| Streamt Überlegungen | Manchmal als `thinking_delta`. Lana entscheidet, wann Überlegungen nötig sind. | Nein |

`lana-thinking` führt nur Überlegungen aus, wenn `max_tokens` mindestens 2048 beträgt.

### Nachrichten

Jede Nachricht hat ein Feld `role` (`user` oder `assistant`) und ein Feld `content`:

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

Die API speichert keine Konversationen. Sende für eine Folgefrage die gesamte Konversation erneut und füge die neue Frage am Ende hinzu. Für Runden mit `assistant` reicht der Text von Lanas Antwort aus:

```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 sucht nur Adressen nach, die in der Konversation, in den eigenen Abfrageergebnissen oder in `extensions.user_context.wallet` vorkommen.

`content` ist entweder ein nicht leerer String oder ein nicht leeres Array aus Blöcken:

| Block | Zulässig in | Struktur |
| - | - | - |
| `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": "..." }` |

Bilder müssen URLs sein. Base64-Bilder werden nicht unterstützt.

Du benötigst keine `tool_use`- oder `tool_result`-Blöcke. Mit ihnen kannst du Abfragen aus einer früheren Runde so wiedergeben, wie Lana sie zurückgegeben hat. Lana kann diese Ergebnisse dann wiederverwenden. `tool_result` akzeptiert außerdem optional den booleschen Wert `is_error`.

### Erweiterungen

Alle Erweiterungen sind optional.

| Feld | Typ | Standard | Funktion |
| - | - | - | - |
| `read_only` | boolean | `true` | Entfernt die Tools für Transfers, Swaps und Token-Starts. Belasse den Wert auf `true`. Diese API dokumentiert keinen Ablauf zum Anzeigen und Signieren von Wallet-Aktionen. |
| `output_format` | `"markdown"` \| `"plain"` | `"markdown"` | `plain` weist Lana an, kein Markdown zu verwenden, und entfernt `{{cite:N}}`-Markierungen. `source`-Ereignisse treffen weiterhin ein. |
| `include_ui_schema` | boolean | `false` | Erlaubt UI-Komponenten als `ui_block`- und `ui_schema`-Ereignisse. |
| `include_followups` | boolean | `false` | Erlaubt bis zu 3 vorgeschlagene Folgefragen. |
| `include_documents` | boolean | `false` | Erlaubt herunterladbare CSV-, JSON- oder Textdateien als `document`-Ereignisse. |
| `enable_deep_scan` | boolean | `false` | Ermöglicht Lana, bis zu 10.000 Transaktionen aus dem Verlauf einer Adresse zu lesen (50.000 für Anzahlen und Summen), mit bis zu 3 Scans pro Runde. Nur Mainnet. Ohne diese Option liest Lana bis zu 100 Transaktionen pro Abfrage. Tiefenscans sind langsamer, kosten aber denselben Festpreis. Sie zählen zum Rundenlimit von 5 Minuten. |
| `user_context` | object | keiner | Wer die Frage stellt. Siehe unten. |
| `attachments` | object\[] | keiner | Bis zu 8 Bilder, die der letzten Benutzernachricht hinzugefügt werden. `image`-Blöcke in `messages` zählen nicht zu diesem Limit. Jedes Element ist `{ "url": "https://...", "kind": "image" }`. |

Die `include_*`-Optionen ermöglichen diese Ausgabe. Lana entscheidet, ob sie gesendet wird.

`extensions` akzeptiert außerdem `progress_context` und `transaction_filter_context`. Der [Orb](https://www.helius.dev/docs/de/orb.md)-Explorer verwendet sie. Du benötigst sie nicht.

Felder von `user_context`:

| Feld | Typ | Funktion |
| - | - | - |
| `wallet` | String, bis zu 128 Zeichen | Die Adresse des Benutzers, damit „mein Wallet“ und „mein Guthaben“ funktionieren. |
| `address_kind` | String, bis zu 32 Zeichen | `"wallet"` oder `"token"`: gibt an, was `wallet` ist. Erfordert `wallet`. |
| `time_zone` | String, bis zu 64 Zeichen | Eine IANA-Zeitzone wie `"America/New_York"`, damit „heute“ funktioniert. |
| `network` | `"mainnet"` \| `"devnet"` | Das abzufragende Netzwerk. Standardmäßig Mainnet. |

## Streaming-Ereignisse

Mit `"stream": true` erhältst du den Status `200` und `Content-Type: text/event-stream`. Jedes Ereignis sieht wie folgt aus:

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

```

`data` ist eine einzelne JSON-Zeile. Der Wert von `type` entspricht dem Namen `event`.

`200` und die ersten Ereignisse treffen ein, sobald Lana erstmals antwortet – mit Überlegungen, Antworttext, einer Abfrage oder einer Datei – oder spätestens nach 10 Sekunden. Bis dahin wird nichts gesendet. Ein request, der in diesem Zeitfenster fehlschlägt, erhält daher eine normale [Fehler-response](#vor-dem-start-des-streams) und wird nicht berechnet. Danach trifft alle 10 Sekunden ein `ping` ein, solange Lana arbeitet.

Setze den Lese-timeout deines HTTP-Clients auf mindestens 30 Sekunden. Ein Standardwert von 5 Sekunden, wie bei `httpx`, ist zu kurz. Der timeout kann vor dem ersten Byte oder zwischen zwei Ereignissen ablaufen.

Die Ereignisse treffen in dieser Reihenfolge ein:

1. `message_start`, immer zuerst.
2. Eine beliebige Kombination aus `content_block_delta`, `tool_use`, `tool_result`, `source`, `ui_block`, `document`, `progress_update` und `ping`.
3. `ui_schema`, höchstens einmal.
4. `follow_up`, höchstens einmal.
5. `message_end`, wenn die Runde abgeschlossen wurde, oder `error`, wenn sie fehlgeschlagen ist. Dies ist immer das letzte Ereignis.

Neue Ereignistypen und Felder können hinzukommen. Ignoriere alle, die du nicht kennst.

| Ereignis | Bedeutung | Beispiel für `data` |
| - | - | - |
| `message_start` | Die Runde wurde gestartet. | `{"type":"message_start","message":{"id":"msg_3f9c...","model":"lana-thinking"}}` |
| `content_block_delta` (`text_delta`) | Ein Abschnitt der Antwort. | `{"type":"content_block_delta","delta":{"type":"text_delta","text":"SOL is trading at"}}` |
| `content_block_delta` (`thinking_delta`) | Ein Abschnitt der Überlegungen. Nur `lana-thinking`, wenn Lana Überlegungen ausführt. | `{"type":"content_block_delta","delta":{"type":"thinking_delta","thinking":"I should check..."}}` |
| `tool_use` | Lana hat eine Abfrage gestartet. | `{"type":"tool_use","tool_use_id":"toolu_01...","name":"...","input":{"address":"..."}}` |
| `tool_result` | Eine Abfrage wurde abgeschlossen. `content` ist eine Vorschau mit bis zu 500 Zeichen. `is_error: true` bedeutet, dass sie fehlgeschlagen ist. Siehe [Toolfehler](#toolfehler). | `{"type":"tool_result","tool_use_id":"toolu_01...","content":"{\"balance\":..."}` |
| `source` | Eine von Lana verwendete Webseite. `index` entspricht den `{{cite:N}}`-Markierungen in der Antwort. `snippet` ist optional. | `{"type":"source","index":0,"url":"https://...","title":"...","snippet":"..."}` |
| `progress_update` | Eine kurze Statuszeile während einer langen Runde. Zeige sie getrennt von der Antwort an. `created_at` ist die Unix-Zeit in Millisekunden. | `{"type":"progress_update","id":"progress_8a1b...","message":"I'll check this wallet's recent swaps.","created_at":1760436000000}` |
| `ui_block` | Eine UI-Komponente. Erfordert `include_ui_schema`. `tool_use_id` ist optional. | `{"type":"ui_block","tool_use_id":"toolu_01...","component":"...","schema":{...}}` |
| `document` | Eine herunterladbare Datei. Erfordert `include_documents`. `format` ist `csv`, `json` oder `txt`. `tool_use_id` und `description` sind optional. | `{"type":"document","filename":"usdc-holders","format":"csv","content":"owner,amount\n...","description":"..."}` |
| `ui_schema` | Alle UI-Komponenten als ein Baum. Erfordert `include_ui_schema`. | `{"type":"ui_schema","schema":{...}}` |
| `follow_up` | Vorgeschlagene nächste Fragen. Erfordert `include_followups`. | `{"type":"follow_up","suggestions":["Show the top 10 holders' recent transfers"]}` |
| `message_end` | Die Runde wurde abgeschlossen. Siehe [Stoppgründe](#stoppgründe) und [Nutzung](#nutzung). | `{"type":"message_end","stop_reason":"end_turn","usage":{"input_tokens":91200,"output_tokens":212,"tool_calls":1,"prompt_tokens":46100,"context_window":200000}}` |
| `error` | Die Runde ist fehlgeschlagen. Siehe [Fehler](#fehler). | `{"type":"error","error":{"type":"overloaded_error","message":"Lana is temporarily overloaded. Retry the request shortly."}}` |
| `ping` | Ein Heartbeat alle 10 Sekunden. Ignoriere ihn. | `{"type":"ping"}` |

Tipps zum Anzeigen eines streams:

* Verwende `tool_use` nur für Fortschrittsanzeigen. Toolnamen und Eingaben können sich ändern.
* Wandle bei einer `"markdown"`-Ausgabe jede `{{cite:N}}`-Markierung in einen Link zum `source` mit dem entsprechenden `index` um oder entferne sie.
* `ui_block` und `ui_schema` enthalten dieselben Komponenten. Lana sendet möglicherweise nur `ui_schema`. Zeige daher `ui_block`-Ereignisse an, wenn sie eintreffen. Rendere andernfalls `ui_schema`.
* Websuchen senden ein `tool_result` mit dem Text `Web search completed.` oder `Web fetch completed.`. Die Seiten treffen als `source`-Ereignisse ein.

### Toolfehler

Eine fehlgeschlagene Abfrage lässt die Runde nicht fehlschlagen. Lana umgeht den Fehler und du musst den request nicht wiederholen. `tool_result` enthält `is_error: true`. `content` ist JSON mit einer kurzen Nachricht und einem `code`:

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

> [accordion] Tool error codes
>
> | `code` | Bedeutung |
> | - | - |
> | `invalid_input` | Die Argumente der Abfrage waren ungültig. |
> | `not_found` | Für diese Abfrage sind keine Daten vorhanden. Einige Abfragen melden ein fehlendes Element stattdessen als normales Ergebnis, etwa `{"found": false}`. |
> | `rejected` | Der Datendienst hat die Abfrage abgelehnt. |
> | `rate_limited` | Der Datendienst wendet eine rate limit an. |
> | `upstream_timeout` | Beim Datendienst ist ein timeout aufgetreten. |
> | `upstream_unavailable` | Der Datendienst ist fehlgeschlagen. |
> | `upstream_error` | Ein Helius-Datentool ist fehlgeschlagen. |
> | `timeout` | Die Zeit für die Abfrage ist abgelaufen. |
> | `tool_failed` | Die Abfrage konnte keine Antwort liefern. `error` nennt den Grund. |
> | `internal` | Ein unerwarteter Fehler ist aufgetreten. |
>
> Neue Codes können hinzukommen. Behandle einen unbekannten Code wie `internal`.

### Stoppgründe

`stop_reason` befindet sich in `message_end` und in der JSON-response:

| Wert | Bedeutung |
| - | - |
| `end_turn` | Lana hat die Antwort abgeschlossen. |
| `max_tokens` | Die Antwort hat `max_tokens` erreicht und wurde möglicherweise abgeschnitten. |
| `tool_use` | Die Runde endete bei einem Abfrageschritt, normalerweise am Schrittl2021imit. |
| `error` | Die Runde ist fehlgeschlagen. Die Antwort ist unvollständig. |

### Nutzung

| Feld | Bedeutung |
| - | - |
| `input_tokens` | Eingabe-Token für die gesamte Runde. |
| `output_tokens` | Ausgabe-Token für die gesamte Runde. |
| `tool_calls` | In der Runde ausgeführte Abfragen, einschließlich einiger, die nie als `tool_use` erscheinen. |
| `prompt_tokens` | Eingabe-Token im letzten Modellschritt. Damit kannst du prüfen, wie voll der Kontext ist. |
| `context_window` | Das Kontextfenster des Modells, derzeit `200000`. |

Lanas eigene Anweisungen und Abfragetools belegen in jedem Modellschritt etwa 45.000 Token. Daher ist `input_tokens` selbst bei einer kurzen Frage hoch. Die Abrechnung erfolgt pro request. Die Tokenanzahl ändert daher nicht deinen Preis.

## Response ohne Streaming

Mit `"stream": false` erhältst du nach dem Ende der Runde ein einzelnes JSON-Objekt:

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

Die Antwort besteht aus den `text`-Blöcken, die in der richtigen Reihenfolge zusammengefügt werden. Überlegungen und `progress_update` sind nur beim Streaming verfügbar.

Diese Felder erscheinen nur, wenn sie einen Wert haben:

| Feld | Bedingung |
| - | - |
| `ui_schema` | `include_ui_schema` ist aktiviert und es gibt etwas anzuzeigen. |
| `documents` | `include_documents` ist aktiviert und Lana hat Dateien erstellt. Dieselben Felder wie bei einem `document`-Ereignis, jedoch ohne `type`. |
| `follow_up` | `include_followups` ist aktiviert und Lana hat Fragen vorgeschlagen. Ein Array aus Strings. |
| `sources` | Lana hat Webseiten verwendet. Dieselben Felder wie bei einem `source`-Ereignis, jedoch ohne `type`. |
| `error` | `stop_reason` ist `"error"`. Ein Objekt mit `type` und `message`. |

## Fehler

### Vor dem Start des streams

Ein request, der vor Beginn der response fehlschlägt, gibt einen anderen Status als `200` mit einem normalen Fehler-Body zurück. Das gilt auch bei `"stream": true`. Es werden keine Ereignisse gesendet und dir entstehen keine Kosten. Prüfe den HTTP-Status, bevor du den Body als stream liest.

Bei `"stream": true` beginnt die response, sobald Lana erstmals antwortet, oder spätestens nach 10 Sekunden. Eine Runde, die vorher fehlschlägt, etwa weil das Modell überlastet oder die Konversation zu lang ist, fällt ebenfalls in diese Kategorie.

| Status | Ursache | Maßnahme |
| - | - | - |
| `400` | Der Body ist ungültig, etwa wegen eines unbekannten Modells oder eines `max_tokens`-Werts über 8.192. `message` nennt jedes ungültige Feld. | Korrigiere den request. |
| `401` | Der API key fehlt, ist ungültig oder wurde als `Authorization: Bearer` gesendet. | Sende den API key in `X-Api-Key` oder `?api-key=`. |
| `403` | Dein Tarif umfasst Lana nicht (Free-Tarif) oder die Zugriffseinstellungen deines API keys blockieren Lana. | Wechsle zu Developer oder höher oder prüfe die Zugriffseinstellungen des API keys im [Helius Dashboard](https://dashboard.helius.dev). |
| `400`, Body `Bad Request` | Der Body ist größer als 10 MB. Gatekeeper lehnt ihn ab, bevor Lana ihn erhält. | Sende einen kleineren request, etwa mit weniger oder kürzeren Nachrichten. |
| `429`, Body `Too Many Requests` | Du überschreitest die [rate limit](https://www.helius.dev/docs/de/billing/rate-limits.md) deines Tarifs. | Warte entsprechend dem `Retry-After`-Header (1 Sekunde) und versuche es erneut. |
| `429`, Body `max usage reached` | Dein Projekt hat keine Credits mehr. | Füge Credits hinzu oder wechsle zu einem höheren Tarif. Es gibt kein `Retry-After`. Bis dahin schlagen erneute Versuche fehl. |
| `429`, `error.type` `rate_limit_error` | In deinem Projekt werden bereits etwa 3 Lana-requests ausgeführt. | Warte entsprechend dem `Retry-After`-Header (5 Sekunden) und versuche es erneut. |
| `503` | Lana ist ausgelastet oder wird neu gestartet. | Warte entsprechend dem `Retry-After`-Header (5 Sekunden bei Auslastung, 30 Sekunden während eines Neustarts) und versuche es erneut. |
| `400`, `error.type` `context_overflow` | Die Konversation passt nicht in das Kontextfenster. | Entferne ältere Nachrichten oder stelle eine enger gefasste Frage. |
| `529`, `error.type` `overloaded_error` | Das Modell ist überlastet. `529` ist der Status, den Anthropic dafür verwendet. Einige HTTP-Clients erkennen ihn nicht. Behandle ihn daher wie `503`. | Versuche es mit exponentiellem Backoff erneut. |
| `500`, `502`, `504` | Die Runde ist vor der ersten Ausgabe mit `api_error`, `tool_error` oder `timeout_error` fehlgeschlagen. | Behandle den Fehler wie unter [Fehlertypen](#fehlertypen) beschrieben. |

Die ersten beiden `429`-Fehler stammen von deinem Tarif. Der response-Body gibt an, welcher davon aufgetreten ist. Der dritte stammt von Lana und hat einen JSON-Body.

Wenn `429` oder `503` ohne `Retry-After`-Header eintrifft, warte vor dem nächsten Versuch einige Sekunden.

Lanas eigene Fehler (`400` bei einem ungültigen Body oder `context_overflow`, `429` mit `rate_limit_error`, `500`, `502`, `503`, `504` und `529`) haben einen JSON-Body. Fehler von Gatekeeper (`401`, `403`, `400` bei einem zu großen Body und die tarifbedingten `429`-Fehler) sind Klartext. Verzweige anhand von `error.type`, nicht anhand von `message`:

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

### Nach dem Start des streams

Der Status ist bereits `200`. Bei einem Fehler endet der stream daher mit einem abschließenden `error`-Ereignis oder mit `message_end` und `stop_reason: "error"`. Dieses `message_end` enthält kein `error`-Objekt. Behandle es wie `api_error`. Jeder zuvor gesendete Antworttext ist unvollständig. Kennzeichne ihn als unvollständig oder verwirf ihn.

### Ohne Streaming

Mit `"stream": false` gibt eine fehlgeschlagene Runde eine der folgenden responses zurück:

* `200` mit `stop_reason: "error"` und einem `error`-Objekt, wenn die Runde Inhalte erzeugt hat, einschließlich Abfragen. Prüfe immer `stop_reason`.
* Einen JSON-Fehler-Body, wenn die Runde nichts erzeugt hat. Der Status entspricht `error.type`: `400` für `context_overflow`, `500` für `api_error`, `502` für `tool_error`, `504` für `timeout_error` oder `529` für `overloaded_error`. Letzteres ist der Status, den Anthropic bei einem überlasteten Modell verwendet. Einige HTTP-Clients erkennen ihn nicht. Behandle ihn daher wie `503`. Diese requests werden nicht berechnet. Behandle sie wie unter [Fehlertypen](#fehlertypen) beschrieben.

### Fehlertypen

| `error.type` | Bedeutung | Maßnahme |
| - | - | - |
| `invalid_request_error` | Der request ist ungültig. | Korrigiere den request. |
| `context_overflow` | Die Konversation und die Abfrageergebnisse passen nicht in das Kontextfenster. | Entferne ältere Nachrichten oder stelle eine enger gefasste Frage. |
| `overloaded_error` | Das Modell ist überlastet. | Versuche es mit exponentiellem Backoff erneut. |
| `timeout_error` | Die Zeit für die Runde ist abgelaufen. | Stelle eine enger gefasste Frage oder verwende `lana-fast`. |
| `tool_error` | Ein Abfragedienst, von dem Lana abhängt, ist fehlgeschlagen. | Versuche es mit Backoff erneut. |
| `rate_limit_error` | In deinem Projekt werden etwa 3 requests ausgeführt. | Versuche es nach der im `Retry-After`-Header angegebenen Zeit erneut. |
| `api_error` | Lana ist auf der Helius-Seite fehlgeschlagen oder ausgelastet. | Versuche es mit Backoff erneut. |

Behandle jeden anderen Typ wie `api_error`.

## Limits

| Limit | Wert |
| - | - |
| `max_tokens` | 1 bis 8.192 (Standard: 8.192) |
| `system` | Bis zu 10.000 Zeichen |
| `extensions.attachments` | Bis zu 8 Bilder |
| Request-Body | 10 MB |
| Kontextfenster | 200.000 Token, davon etwa 80 % (nach `max_tokens`) für die Konversation und Abfrageergebnisse |
| Rundendauer | 5 Minuten |
| Rate limit | Die rate limit deines Tarifs für DAS & Enhanced APIs. Siehe [Rate Limits](https://www.helius.dev/docs/de/billing/rate-limits.md#lana-api). |
| Gleichzeitige requests | Etwa 3 pro Projekt. Zusätzliche requests können `429` erhalten, bis einer abgeschlossen ist. |

Wenn sich eine Runde 5 Minuten nähert, beendet Lana die Abfragen und antwortet mit den vorhandenen Informationen. Lange Runden enden normalerweise mit einer Teilantwort, die angibt, was fehlt, und nicht mit einem timeout.

Setze beim Streaming den Lese-timeout deines HTTP-Clients auf mindestens 30 Sekunden. Bis zum ersten Byte können bis zu 10 Sekunden vergehen. Danach trifft alle 10 Sekunden ein `ping` ein. Eine deutlich längere Pause bedeutet daher, dass die Verbindung abgebrochen ist. Ein Standardwert von 5 Sekunden, wie bei `httpx`, ist zu kurz. Ohne Streaming trifft bis zum Ende der Runde nichts ein. Setze den Lese-timeout daher auf mehr als 5 Minuten.

Wenn du die Verbindung trennst, beendet Lana die Runde. Ein request, dessen stream bereits begonnen hat, wird trotzdem berechnet.

Wenn Lana ausgelastet ist, erhalten neue requests `503`, bevor etwas gestreamt wird. Sie werden nicht berechnet. Versuche es nach der im `Retry-After`-Header angegebenen Zeit erneut.

## Preise

Jeder request kostet einen vom Modell abhängigen Festpreis:

| Modell | Credits pro request |
| - | - |
| `lana-thinking` | **10.000** |
| `lana-fast` | **2.000** |

Der Preis ist für requests mit und ohne Streaming sowie in jedem kostenpflichtigen Tarif (Developer und höher) gleich. Lana ist im Free-Tarif nicht verfügbar.

Die Credits stammen aus deinem Tarif. Siehe [Credits](https://www.helius.dev/docs/de/billing/credits.md#lana-api-credits).

### Was berechnet wird

Jeder request mit dem HTTP-Status `200` wird berechnet, unabhängig vom Streaming und davon, wie die Runde endet. requests, die vor Beginn der response fehlschlagen, erhalten einen anderen Status und sind kostenlos.

* Eine Streaming-Runde, die mit einem `error`-Ereignis fehlschlägt oder deren Verbindung du nach dem Start trennst, wird berechnet. Der Status war bereits `200`.
* Ein request, der vor Beginn der Runde abgelehnt wird (`400`, `401`, `403`, `429`, `503`), ist kostenlos.
* Eine Runde, die vor Beginn der response fehlschlägt (`400`, `5xx`), ist mit und ohne Streaming kostenlos.

## Weitere Beispiele

### Tonalität und Wallet des Benutzers festlegen

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

### Den vollständigen Verlauf eines Wallets scannen

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

### UI-Komponenten, Folgefragen und eine CSV abrufen

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

## Nächste Schritte

> [card] [API Reference](https://www.helius.dev/docs/de/api-reference/lana/messages.md)
>
> Das request- und response-Schema mit einem Playground.

> [card] [Rate Limits](https://www.helius.dev/docs/de/billing/rate-limits.md#lana-api)
>
> Lanas tarifspezifische rate limits.

> [card] [Credits](https://www.helius.dev/docs/de/billing/credits.md#lana-api-credits)
>
> So verwenden Lana-requests die Credits deines Tarifs.

> [card] [Contact Support](https://www.helius.dev/docs/de/support/contact-support)
>
> Erhalte Hilfe über Discord, Chat oder E-Mail.


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