> ## 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 Lana - Agent IA Solana

> Appelez Lana, un agent IA Solana, via HTTP : posez des questions sur les portefeuilles, les tokens, les transactions et les prix, puis recevez la réponse en streaming. Démarrage rapide, référence de l’API et tarification.

L’API Lana est un agent IA Solana que vous appelez via HTTP. Vous lui envoyez une question en langage naturel, et elle recherche pour vous des portefeuilles, des tokens, des transactions et des prix, puis renvoie une réponse en streaming.

Lana exécute chaque recherche côté Helius. Vous n’avez donc aucun outil à définir ni à exécuter. Elle est disponible avec les offres Helius payantes (Developer et supérieures), à un prix fixe par requête : 10 000 crédits pour `lana-thinking` et 2 000 crédits pour `lana-fast`. Consultez la section [Tarification](#tarification).

L’API reprend la structure de l’API Messages d’Anthropic, mais les SDK Anthropic ne fonctionnent pas avec elle. Appelez-la directement via HTTP, comme dans les exemples ci-dessous. Consultez la section [Différences avec l’API Messages d’Anthropic](#différences-avec-lapi-messages-danthropic).

Lana utilise les modèles Claude d’Anthropic. Vos questions et la conversation sont envoyées à Anthropic pour générer les réponses.

> [!NOTE]
>
> L’API Lana est disponible en version bêta sur l’endpoint [Gatekeeper (Beta)](https://www.helius.dev/docs/fr/gatekeeper/overview.md), `beta.helius-rpc.com`. Elle n’est pas encore disponible sur `mainnet.helius-rpc.com`. De nouveaux événements et champs peuvent être ajoutés pendant la bêta.

## Ce que vous pouvez demander à Lana

Questions que vos utilisateurs peuvent poser sur leurs transactions et les portefeuilles avec lesquels ils interagissent :

* « Pourquoi ma dernière transaction a-t-elle échoué ? »
* « Quel slippage ai-je subi sur ce swap ? »
* « Quels frais ai-je payés pour cette transaction ? »
* « D’où ce portefeuille a-t-il reçu ses fonds, et où les a-t-il envoyés ? »
* « Ce portefeuille est-il lié à cet autre portefeuille ? »
* « Qui sont les principaux détenteurs de ce token ? »

Transmettez le portefeuille de l’utilisateur dans [`extensions.user_context.wallet`](#extensions) pour que les questions concernant « mon » portefeuille ou « ma dernière transaction » fonctionnent.

## Démarrage rapide

**1. Get an API key**

Copiez une clé API depuis le [tableau de bord Helius](https://dashboard.helius.dev).

**2. Ask a question**

Remplacez `YOUR_API_KEY` et exécutez :

```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` permet à curl d’afficher chaque événement dès son arrivée. Le premier événement peut prendre jusqu’à 10 secondes.

**3. Read the answer**

La réponse est un flux d’[événements](#événements-en-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 réponse correspond aux fragments `text_delta`, dans l’ordre. `lana-thinking` peut aussi envoyer des fragments `thinking_delta` : il s’agit du raisonnement de Lana. Affichez-le séparément de la réponse ou ignorez-le.

### Lire le flux dans le code

Les deux exemples vérifient le statut HTTP avant de lire le corps comme un flux, attendent `Retry-After` lors d’un `429` ou `503`, affichent la réponse à mesure qu’elle arrive et s’arrêtent si le tour échoue ou si le flux se termine prématurément.

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

## Différences avec l’API Messages d’Anthropic

* Les modèles sont `lana-thinking` et `lana-fast`.
* Lana exécute ses propres outils. `tools`, `tool_choice`, `temperature`, `top_p`, `top_k`, `stop_sequences` et `metadata` renvoient `400`.
* `system` est ajouté aux instructions de Lana.
* `max_tokens` est facultatif (valeur par défaut et maximale : 8 192), et les images doivent être des URL.
* Les événements sont différents. Il n’existe aucun `content_block_start`, `content_block_stop`, `message_delta` ou `message_stop`. Le flux se termine par `message_end` ou `error`.
* `usage` ajoute `tool_calls`, `prompt_tokens` et `context_window`. `stop_reason` peut être `error`.
* `extensions` est propre à Lana.

## Endpoint et authentification

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

Envoyez votre clé API Helius de l’une des manières suivantes :

| Méthode | Exemple |
| - | - |
| En-tête `X-Api-Key` (recommandé) | `X-Api-Key: YOUR_API_KEY` |
| Paramètre de requête `api-key` | `https://beta.helius-rpc.com/v1/lana/messages?api-key=YOUR_API_KEY` |

`Authorization: Bearer` ne fonctionne pas sur cet endpoint et renvoie `401`.

`mainnet.helius-rpc.com` ne dessert pas encore cette route et renvoie `503`.

Envoyez `Content-Type: application/json` avec chaque requête.

> [!WARNING]
>
> Votre clé API consomme les crédits de votre offre. Appelez Lana depuis votre serveur, et non depuis un navigateur ou une application distribuée aux utilisateurs.

## Corps de la requête

Le corps est un objet JSON. Les champs inconnus sont rejetés avec `400`, y compris ceux qui se trouvent dans `extensions` et dans les blocs de contenu.

**model** `string` *required*

`lana-thinking` ou `lana-fast`. Consultez la section [Modèles](#modèles).

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

La conversation, de la plus ancienne à la plus récente. Elle doit contenir au moins un message, et le dernier doit avoir `role: "user"`. Consultez la section [Messages](#messages).

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

Nombre maximal de tokens de sortie que Lana peut écrire en une étape de modèle, de `1` à `8192`. Un tour avec des recherches comporte plusieurs étapes. Le `output_tokens` total du tour peut donc être supérieur à `max_tokens`. En dessous de 2 048, `lana-thinking` ne raisonne pas.

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

`true` diffuse les [événements](#événements-en-streaming). `false` renvoie une seule [réponse JSON](#réponse-sans-streaming) à la fin du tour.

**system** `string`

Instructions supplémentaires de 1 à 10 000 caractères, par exemple « Répondez en trois points. » Elles sont ajoutées aux instructions propres à Lana et ne les remplacent pas.

**extensions** `object`

Options propres à Lana. Consultez la section [Extensions](#extensions).

### Modèles

| | `lana-thinking` | `lana-fast` |
| - | - | - |
| Idéal pour | Analyses en plusieurs étapes | Recherches rapides et faits isolés |
| Étapes de recherche par tour | Jusqu’à 20 | Jusqu’à 4 |
| Recherches web par tour | Jusqu’à 3 | Jusqu’à 2 |
| Récupérations de pages web par tour | Jusqu’à 2 | Jusqu’à 2 |
| Diffuse le raisonnement | Parfois, sous forme de `thinking_delta`. Lana décide quand raisonner. | Non |

`lana-thinking` ne raisonne que lorsque `max_tokens` est supérieur ou égal à 2048.

### Messages

Chaque message possède un `role` (`user` ou `assistant`) et un `content` :

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

L’API ne stocke pas les conversations. Pour poser une question complémentaire, renvoyez toute la conversation en ajoutant la nouvelle question à la fin. Le texte de la réponse de Lana suffit pour les tours `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 recherche uniquement les adresses qui apparaissent dans la conversation, dans ses propres résultats de recherche ou dans `extensions.user_context.wallet`.

`content` est une chaîne non vide ou un tableau non vide de blocs :

| Bloc | Autorisé dans | Structure |
| - | - | - |
| `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": "..." }` |

Les images doivent être des URL. Les images en Base64 ne sont pas prises en charge.

Vous n’avez pas besoin des blocs `tool_use` ou `tool_result`. Ils permettent de rejouer les recherches d’un tour précédent telles que Lana les a renvoyées, afin qu’elle puisse réutiliser ces résultats. `tool_result` accepte également un booléen facultatif `is_error`.

### Extensions

Toutes les extensions sont facultatives.

| Champ | Type | Valeur par défaut | Fonction |
| - | - | - | - |
| `read_only` | boolean | `true` | Supprime les outils de transfert, de swap et de lancement de token. Laissez-le sur `true` : cette API ne documente aucun flux pour afficher et signer des actions de portefeuille. |
| `output_format` | `"markdown"` \| `"plain"` | `"markdown"` | `plain` indique à Lana de ne pas utiliser Markdown et supprime les marqueurs `{{cite:N}}`. Les événements `source` continuent d’arriver. |
| `include_ui_schema` | boolean | `false` | Autorise les composants d’interface utilisateur, sous forme d’événements `ui_block` et `ui_schema`. |
| `include_followups` | boolean | `false` | Autorise jusqu’à 3 suggestions de questions complémentaires. |
| `include_documents` | boolean | `false` | Autorise les fichiers CSV, JSON ou texte téléchargeables, sous forme d’événements `document`. |
| `enable_deep_scan` | boolean | `false` | Permet à Lana de lire jusqu’à 10 000 transactions de l’historique d’une adresse (50 000 pour les décomptes et les totaux), avec jusqu’à 3 analyses par tour. Mainnet uniquement. Sans cette option, Lana lit jusqu’à 100 transactions par recherche. Les analyses approfondies sont plus lentes, mais coûtent le même prix fixe. Elles sont comptabilisées dans la limite de 5 minutes par tour. |
| `user_context` | object | aucun | Identité de l’auteur de la demande. Voir ci-dessous. |
| `attachments` | object\[] | aucun | Jusqu’à 8 images ajoutées au dernier message de l’utilisateur. Les blocs `image` dans `messages` ne sont pas comptabilisés dans cette limite. Chaque élément est `{ "url": "https://...", "kind": "image" }`. |

Les options `include_*` rendent la sortie possible. Lana décide de l’envoyer ou non.

`extensions` accepte également `progress_context` et `transaction_filter_context`. L’explorateur [Orb](https://www.helius.dev/docs/fr/orb.md) les utilise, mais vous n’en avez pas besoin.

Champs de `user_context` :

| Champ | Type | Fonction |
| - | - | - |
| `wallet` | chaîne, jusqu’à 128 caractères | Adresse de l’utilisateur, pour que « mon portefeuille » et « mon solde » fonctionnent. |
| `address_kind` | chaîne, jusqu’à 32 caractères | `"wallet"` ou `"token"` : ce que représente `wallet`. Nécessite `wallet`. |
| `time_zone` | chaîne, jusqu’à 64 caractères | Un fuseau horaire IANA, tel que `"America/New_York"`, pour que « aujourd’hui » fonctionne. |
| `network` | `"mainnet"` \| `"devnet"` | Réseau sur lequel effectuer la recherche. La valeur par défaut est mainnet. |

## Événements en streaming

Avec `"stream": true`, vous obtenez le statut `200` et `Content-Type: text/event-stream`. Chaque événement se présente ainsi :

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

```

`data` correspond à une ligne de JSON. Son `type` correspond au nom `event`.

Le `200` et les premiers événements arrivent lorsque Lana répond pour la première fois (raisonnement, texte de réponse, recherche ou fichier), ou après 10 secondes au maximum. Rien n’est envoyé avant cela. Une requête qui échoue pendant cette période reçoit donc une [réponse d’erreur](#avant-le-démarrage-du-flux) normale et n’est pas facturée. Ensuite, un `ping` arrive toutes les 10 secondes pendant que Lana travaille.

Définissez le délai d’expiration de lecture de votre client HTTP sur au moins 30 secondes. Une valeur par défaut de 5 secondes, comme dans `httpx`, est trop courte : le délai peut expirer avant le premier octet ou entre deux événements.

Les événements arrivent dans cet ordre :

1. `message_start`, toujours en premier.
2. Toute combinaison de `content_block_delta`, `tool_use`, `tool_result`, `source`, `ui_block`, `document`, `progress_update` et `ping`.
3. `ui_schema`, au plus une fois.
4. `follow_up`, au plus une fois.
5. `message_end` si le tour s’est terminé, ou `error` s’il a échoué. Il s’agit toujours du dernier événement.

De nouveaux types d’événements et champs peuvent être ajoutés. Ignorez ceux que vous ne reconnaissez pas.

| Événement | Signification | Exemple de `data` |
| - | - | - |
| `message_start` | Le tour a commencé. | `{"type":"message_start","message":{"id":"msg_3f9c...","model":"lana-thinking"}}` |
| `content_block_delta` (`text_delta`) | Un fragment de la réponse. | `{"type":"content_block_delta","delta":{"type":"text_delta","text":"SOL is trading at"}}` |
| `content_block_delta` (`thinking_delta`) | Un fragment de raisonnement. `lana-thinking` uniquement, lorsque Lana raisonne. | `{"type":"content_block_delta","delta":{"type":"thinking_delta","thinking":"I should check..."}}` |
| `tool_use` | Lana a lancé une recherche. | `{"type":"tool_use","tool_use_id":"toolu_01...","name":"...","input":{"address":"..."}}` |
| `tool_result` | Une recherche est terminée. `content` est un aperçu de 500 caractères maximum. `is_error: true` indique un échec ; consultez la section [Erreurs d’outil](#erreurs-doutil). | `{"type":"tool_result","tool_use_id":"toolu_01...","content":"{\"balance\":..."}` |
| `source` | Une page web utilisée par Lana. `index` correspond aux marqueurs `{{cite:N}}` dans la réponse. `snippet` est facultatif. | `{"type":"source","index":0,"url":"https://...","title":"...","snippet":"..."}` |
| `progress_update` | Une courte ligne d’état pendant un long tour. Affichez-la séparément de la réponse. `created_at` correspond à des millisecondes Unix. | `{"type":"progress_update","id":"progress_8a1b...","message":"I'll check this wallet's recent swaps.","created_at":1760436000000}` |
| `ui_block` | Un composant d’interface utilisateur. Nécessite `include_ui_schema`. `tool_use_id` est facultatif. | `{"type":"ui_block","tool_use_id":"toolu_01...","component":"...","schema":{...}}` |
| `document` | Un fichier téléchargeable. Nécessite `include_documents`. `format` vaut `csv`, `json` ou `txt`. `tool_use_id` et `description` sont facultatifs. | `{"type":"document","filename":"usdc-holders","format":"csv","content":"owner,amount\n...","description":"..."}` |
| `ui_schema` | Tous les composants d’interface utilisateur sous forme d’une seule arborescence. Nécessite `include_ui_schema`. | `{"type":"ui_schema","schema":{...}}` |
| `follow_up` | Suggestions de questions suivantes. Nécessite `include_followups`. | `{"type":"follow_up","suggestions":["Show the top 10 holders' recent transfers"]}` |
| `message_end` | Le tour est terminé. Consultez les sections [Motifs d’arrêt](#motifs-darrêt) et [Utilisation](#utilisation). | `{"type":"message_end","stop_reason":"end_turn","usage":{"input_tokens":91200,"output_tokens":212,"tool_calls":1,"prompt_tokens":46100,"context_window":200000}}` |
| `error` | Le tour a échoué. Consultez la section [Erreurs](#erreurs). | `{"type":"error","error":{"type":"overloaded_error","message":"Lana is temporarily overloaded. Retry the request shortly."}}` |
| `ping` | Un signal de maintien toutes les 10 secondes. Ignorez-le. | `{"type":"ping"}` |

Conseils pour afficher un flux :

* Utilisez `tool_use` uniquement pour les indicateurs de progression. Les noms et les entrées des outils peuvent changer.
* Avec la sortie `"markdown"`, transformez chaque `{{cite:N}}` en lien vers le `source` portant ce `index`, ou supprimez-le.
* `ui_block` et `ui_schema` transportent les mêmes composants. Lana peut n’envoyer que `ui_schema`. Affichez donc les événements `ui_block` s’ils arrivent ; sinon, affichez `ui_schema`.
* Les recherches web envoient un `tool_result` avec le texte `Web search completed.` ou `Web fetch completed.`. Les pages arrivent sous forme d’événements `source`.

### Erreurs d’outil

L’échec d’une recherche ne fait pas échouer le tour. Lana le contourne et vous n’avez pas besoin de réessayer. Le `tool_result` contient `is_error: true`, et `content` est un objet JSON comportant un court message et un `code` :

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

> [accordion] Tool error codes
>
> | `code` | Signification |
> | - | - |
> | `invalid_input` | Les arguments de la recherche n’étaient pas valides. |
> | `not_found` | Aucune donnée n’est disponible pour cette recherche. Certaines recherches signalent plutôt un élément manquant comme un résultat normal, par exemple `{"found": false}`. |
> | `rejected` | Le service de données a rejeté la recherche. |
> | `rate_limited` | Le service de données applique une limitation de débit. |
> | `upstream_timeout` | Le délai d’attente du service de données a expiré. |
> | `upstream_unavailable` | Le service de données a échoué. |
> | `upstream_error` | Un outil de données Helius a échoué. |
> | `timeout` | Le délai imparti à la recherche a expiré. |
> | `tool_failed` | La recherche n’a pas pu répondre. `error` en indique la raison. |
> | `internal` | Une erreur inattendue s’est produite. |
>
> De nouveaux codes peuvent être ajoutés. Traitez tout code inconnu comme `internal`.

### Motifs d’arrêt

`stop_reason` figure dans `message_end` et dans la réponse JSON :

| Valeur | Signification |
| - | - |
| `end_turn` | Lana a terminé sa réponse. |
| `max_tokens` | La réponse a atteint `max_tokens` et peut être tronquée. |
| `tool_use` | Le tour s’est terminé sur une étape de recherche, généralement à cause de la limite d’étapes. |
| `error` | Le tour a échoué. La réponse est incomplète. |

### Utilisation

| Champ | Signification |
| - | - |
| `input_tokens` | Tokens d’entrée pour l’ensemble du tour. |
| `output_tokens` | Tokens de sortie pour l’ensemble du tour. |
| `tool_calls` | Recherches exécutées pendant le tour, y compris certaines qui n’apparaissent jamais comme `tool_use`. |
| `prompt_tokens` | Tokens d’entrée de la dernière étape du modèle. Utilisez-le pour connaître le niveau de remplissage du contexte. |
| `context_window` | Fenêtre de contexte du modèle, actuellement `200000`. |

Les instructions et les outils de recherche propres à Lana occupent environ 45 000 tokens à chaque étape du modèle. `input_tokens` est donc élevé même pour une courte question. La tarification s’effectue par requête : le nombre de tokens ne modifie pas le prix payé.

## Réponse sans streaming

Avec `"stream": false`, vous recevez un objet JSON à la fin du tour :

```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 réponse correspond aux blocs `text`, concaténés dans l’ordre. Le raisonnement et `progress_update` sont disponibles uniquement en streaming.

Ces champs apparaissent uniquement lorsqu’ils ont une valeur :

| Champ | Condition |
| - | - |
| `ui_schema` | `include_ui_schema` est activé et il existe quelque chose à afficher. |
| `documents` | `include_documents` est activé et Lana a créé des fichiers. Mêmes champs qu’un événement `document`, sans `type`. |
| `follow_up` | `include_followups` est activé et Lana a suggéré des questions. Tableau de chaînes. |
| `sources` | Lana a utilisé des pages web. Mêmes champs qu’un événement `source`, sans `type`. |
| `error` | `stop_reason` vaut `"error"`. Objet contenant `type` et `message`. |

## Erreurs

### Avant le démarrage du flux

Une requête qui échoue avant le début de la réponse renvoie un statut différent de `200` avec un corps d’erreur normal, même avec `"stream": true`. Aucun événement n’est envoyé et la requête n’est pas facturée. Vérifiez le statut HTTP avant de lire le corps comme un flux.

Avec `"stream": true`, la réponse commence lorsque Lana répond pour la première fois, ou après 10 secondes au maximum. Un tour qui échoue avant cela, par exemple parce que le modèle est surchargé ou que la conversation est trop longue, relève également de ce cas.

| Statut | Cause | Action à effectuer |
| - | - | - |
| `400` | Le corps n’est pas valide, par exemple en raison d’un modèle inconnu ou d’un `max_tokens` supérieur à 8 192. `message` nomme chaque champ incorrect. | Corrigez la requête. |
| `401` | La clé API est absente ou non valide, ou a été envoyée comme `Authorization: Bearer`. | Envoyez la clé dans `X-Api-Key` ou `?api-key=`. |
| `403` | Votre offre n’inclut pas Lana (offre Free), ou les paramètres d’accès de votre clé la bloquent. | Passez à l’offre Developer ou supérieure, ou vérifiez les paramètres d’accès de la clé dans le [tableau de bord Helius](https://dashboard.helius.dev). |
| `400`, corps `Bad Request` | Le corps dépasse 10 Mo. Gatekeeper le rejette avant que Lana ne le voie. | Envoyez une requête plus petite, avec moins de messages ou des messages plus courts, par exemple. |
| `429`, corps `Too Many Requests` | Vous avez dépassé la [limite de débit](https://www.helius.dev/docs/fr/billing/rate-limits.md) de votre offre. | Attendez la durée indiquée par l’en-tête `Retry-After` (1 seconde), puis réessayez. |
| `429`, corps `max usage reached` | Votre projet n’a plus de crédits. | Ajoutez des crédits ou passez à une offre supérieure. Aucun `Retry-After` n’est fourni ; les nouvelles tentatives échoueront tant que vous ne l’aurez pas fait. |
| `429`, `error.type` `rate_limit_error` | Environ 3 requêtes Lana sont déjà en cours pour votre projet. | Attendez la durée indiquée par l’en-tête `Retry-After` (5 secondes), puis réessayez. |
| `503` | Lana a atteint sa capacité maximale ou redémarre. | Attendez la durée indiquée par l’en-tête `Retry-After` (5 secondes à capacité maximale, 30 secondes pendant un redémarrage), puis réessayez. |
| `400`, `error.type` `context_overflow` | La conversation ne tient pas dans la fenêtre de contexte. | Supprimez les messages les plus anciens ou posez une question plus ciblée. |
| `529`, `error.type` `overloaded_error` | Le modèle est surchargé. `529` est le statut utilisé par Anthropic dans ce cas. Certains clients HTTP ne le reconnaissent pas ; traitez-le donc comme `503`. | Réessayez avec un délai exponentiel. |
| `500`, `502`, `504` | Le tour a échoué avant sa première sortie avec `api_error`, `tool_error` ou `timeout_error`. | Gérez-le comme indiqué dans [Types d’erreurs](#types-derreurs). |

Les deux premiers `429` proviennent de votre offre, et le corps de la réponse indique lequel vous avez rencontré. Le troisième provient de Lana et possède un corps JSON.

Si un `429` ou `503` arrive sans en-tête `Retry-After`, attendez quelques secondes avant de réessayer.

Les erreurs propres à Lana (`400` pour un corps non valide ou `context_overflow`, `429` avec `rate_limit_error`, `500`, `502`, `503`, `504` et `529`) possèdent un corps JSON. Les erreurs de Gatekeeper (`401`, `403`, `400` pour un corps trop volumineux et les `429` de l’offre) sont en texte brut. Effectuez le branchement selon `error.type`, et non selon `message` :

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

### Après le démarrage du flux

Le statut est déjà `200`. Un échec termine donc le flux par un événement final `error`, ou par `message_end` avec `stop_reason: "error"`. Ce `message_end` ne contient aucun objet `error` ; traitez-le comme un `api_error`. Tout texte de réponse qui le précède est partiel. Affichez-le comme incomplet ou supprimez-le.

### Sans streaming

Avec `"stream": false`, un tour qui échoue renvoie l’un des résultats suivants :

* `200` avec `stop_reason: "error"` et un objet `error`, lorsque le tour a produit du contenu, y compris des recherches. Vérifiez toujours `stop_reason`.
* Un corps d’erreur JSON, lorsque le tour n’a rien produit. Le statut correspond à `error.type` : `400` pour `context_overflow`, `500` pour `api_error`, `502` pour `tool_error`, `504` pour `timeout_error` ou `529` pour `overloaded_error` (le statut utilisé par Anthropic pour un modèle surchargé ; certains clients HTTP ne le reconnaissent pas, traitez-le donc comme `503`). Ces requêtes ne sont pas facturées. Gérez-les comme indiqué dans [Types d’erreurs](#types-derreurs).

### Types d’erreurs

| `error.type` | Signification | Action à effectuer |
| - | - | - |
| `invalid_request_error` | La requête n’est pas valide. | Corrigez la requête. |
| `context_overflow` | La conversation et les résultats de recherche ne tiennent pas dans la fenêtre de contexte. | Supprimez les messages les plus anciens ou posez une question plus ciblée. |
| `overloaded_error` | Le modèle est surchargé. | Réessayez avec un délai exponentiel. |
| `timeout_error` | Le délai imparti au tour a expiré. | Posez une question plus ciblée ou utilisez `lana-fast`. |
| `tool_error` | Un service de recherche dont dépend Lana a échoué. | Réessayez avec un délai progressif. |
| `rate_limit_error` | Environ 3 requêtes sont en cours pour votre projet. | Réessayez après la durée indiquée par l’en-tête `Retry-After`. |
| `api_error` | Lana a échoué côté Helius ou a atteint sa capacité maximale. | Réessayez avec un délai progressif. |

Traitez tout autre type comme `api_error`.

## Limites

| Limite | Valeur |
| - | - |
| `max_tokens` | De 1 à 8 192 (8 192 par défaut) |
| `system` | Jusqu’à 10 000 caractères |
| `extensions.attachments` | Jusqu’à 8 images |
| Corps de la requête | 10 Mo |
| Fenêtre de contexte | 200 000 tokens, dont environ 80 % (après `max_tokens`) pour la conversation et les résultats de recherche |
| Durée du tour | 5 minutes |
| Limite de débit | Limite de débit DAS & Enhanced APIs de votre offre. Consultez la section [Limites de débit](https://www.helius.dev/docs/fr/billing/rate-limits.md#api-lana). |
| Requêtes simultanées | Environ 3 par projet. Les requêtes supplémentaires peuvent recevoir `429` jusqu’à ce que l’une d’elles se termine. |

Lorsqu’un tour approche des 5 minutes, Lana arrête les recherches et répond avec les informations dont elle dispose. Les longs tours se terminent généralement par une réponse partielle qui indique les éléments manquants, et non par une expiration du délai.

En streaming, définissez le délai d’expiration de lecture de votre client HTTP sur au moins 30 secondes. Le premier octet peut prendre jusqu’à 10 secondes, puis un `ping` arrive toutes les 10 secondes. Un intervalle beaucoup plus long indique donc que la connexion a été interrompue. Une valeur par défaut de 5 secondes, comme dans `httpx`, est trop courte. Sans streaming, rien n’arrive avant la fin du tour. Définissez donc le délai d’expiration de lecture sur plus de 5 minutes.

Si vous vous déconnectez, Lana arrête le tour. Une requête dont le flux a déjà commencé reste facturée.

Lorsque Lana a atteint sa capacité maximale, les nouvelles requêtes reçoivent `503` avant le début du flux. Elles ne sont pas facturées. Réessayez après la durée indiquée par l’en-tête `Retry-After`.

## Tarification

Chaque requête coûte un prix fixe qui dépend du modèle :

| Modèle | Crédits par requête |
| - | - |
| `lana-thinking` | **10 000** |
| `lana-fast` | **2 000** |

Le prix est identique pour les requêtes avec ou sans streaming et pour toutes les offres payantes (Developer et supérieures). Lana n’est pas disponible avec l’offre Free.

Les crédits proviennent de votre offre. Consultez la section [Crédits](https://www.helius.dev/docs/fr/billing/credits.md#crédits-de-lapi-lana).

### Ce qui est facturé

Chaque requête qui reçoit le statut HTTP `200` est facturée, avec ou sans streaming, quelle que soit l’issue du tour. Les requêtes qui échouent avant le début de la réponse reçoivent un autre statut et sont gratuites.

* Un tour en streaming qui échoue avec un événement `error`, ou dont vous vous déconnectez après son démarrage, est facturé : le statut était déjà `200`.
* Une requête rejetée avant le début du tour (`400`, `401`, `403`, `429`, `503`) est gratuite.
* Un tour qui échoue avant le début de la réponse (`400`, `5xx`), avec ou sans streaming, est gratuit.

## Autres exemples

### Définir le ton et le portefeuille de l’utilisateur

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

### Analyser tout l’historique d’un portefeuille

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

### Obtenir des composants d’interface, des questions complémentaires et un fichier 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
    }
  }'
```

## Étapes suivantes

> [card] [API Reference](https://www.helius.dev/docs/fr/api-reference/lana/messages.md)
>
> Schéma de la requête et de la réponse, avec un espace de test.

> [card] [Rate Limits](https://www.helius.dev/docs/fr/billing/rate-limits.md#api-lana)
>
> Limites de débit de Lana pour chaque offre.

> [card] [Credits](https://www.helius.dev/docs/fr/billing/credits.md#crédits-de-lapi-lana)
>
> Comment les requêtes Lana utilisent les crédits de votre offre.

> [card] [Contact Support](https://www.helius.dev/docs/fr/support/contact-support)
>
> Obtenez de l’aide via Discord, le chat ou l’e-mail.


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