> ## 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 - Agen AI Solana

> Panggil Lana, agen AI Solana, melalui HTTP: tanyakan tentang dompet, token, transaksi, dan harga, lalu terima jawabannya sebagai aliran. Panduan memulai cepat, referensi API, dan harga.

Lana API adalah agen AI Solana yang Anda panggil melalui HTTP. Anda mengirimkan pertanyaan dalam bahasa Inggris biasa, lalu Lana mencari dompet, token, transaksi, dan harga untuk Anda, kemudian mengalirkan kembali jawabannya.

Lana menjalankan setiap pencarian di sisi Helius, sehingga Anda tidak perlu menentukan atau menjalankan alat apa pun. Lana tersedia dalam paket Helius berbayar (Developer dan yang lebih tinggi), dengan harga tetap per permintaan: 10.000 kredit untuk `lana-thinking` dan 2.000 kredit untuk `lana-fast`. Lihat [Harga](#harga).

Struktur API ini menyerupai Anthropic Messages API, tetapi SDK Anthropic tidak dapat digunakan dengannya. Panggil API melalui HTTP biasa, seperti dalam contoh di bawah. Lihat [Perbedaan dari Anthropic Messages API](#perbedaan-dari-anthropic-messages-api).

Lana berjalan pada model Claude milik Anthropic. Pertanyaan dan percakapan Anda dikirimkan ke Anthropic untuk menghasilkan jawaban.

> [!NOTE]
>
> Lana API tersedia dalam versi beta pada endpoint [Gatekeeper (Beta)](https://www.helius.dev/docs/id/gatekeeper/overview.md), `beta.helius-rpc.com`. API ini belum tersedia di `mainnet.helius-rpc.com`. Peristiwa dan bidang baru dapat ditambahkan selama versi beta.

## Hal yang dapat Anda tanyakan kepada Lana

Pertanyaan yang dapat diajukan pengguna Anda tentang perdagangan mereka dan dompet yang berinteraksi dengan mereka:

* "Mengapa transaksi terakhir saya gagal?"
* "Berapa slippage yang saya alami pada swap ini?"
* "Biaya apa saja yang saya bayar untuk transaksi ini?"
* "Dari mana dompet ini mendapatkan dananya, dan ke mana dana tersebut dikirim?"
* "Apakah dompet ini terhubung dengan dompet lain ini?"
* "Siapa pemegang terbesar token ini?"

Teruskan dompet pengguna di [`extensions.user_context.wallet`](#ekstensi) agar pertanyaan tentang dompet "saya" atau "transaksi terakhir saya" dapat berfungsi.

## Panduan memulai cepat

**1. Dapatkan kunci API**

Salin kunci API dari [Dasbor Helius](https://dashboard.helius.dev).

**2. Ajukan pertanyaan**

Ganti `YOUR_API_KEY` dan jalankan:

```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` membuat curl mencetak setiap peristiwa segera setelah peristiwa tersebut tiba. Peristiwa pertama dapat memerlukan waktu hingga 10 detik.

**3. Baca jawaban**

Responsnya berupa aliran [peristiwa](#peristiwa-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}}
```

Jawabannya adalah potongan `text_delta`, secara berurutan. `lana-thinking` juga dapat mengirimkan potongan `thinking_delta`: itu adalah penalaran Lana, jadi tampilkan secara terpisah dari jawaban atau lewati.

### Baca aliran dalam kode

Kedua contoh memeriksa status HTTP sebelum membaca isi sebagai aliran, menunggu `Retry-After` pada `429` atau `503`, mencetak jawaban saat dialirkan, dan berhenti jika giliran gagal atau aliran berakhir lebih awal.

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

## Perbedaan dari Anthropic Messages API

* Modelnya adalah `lana-thinking` dan `lana-fast`.
* Lana menjalankan alatnya sendiri. `tools`, `tool_choice`, `temperature`, `top_p`, `top_k`, `stop_sequences`, dan `metadata` mengembalikan `400`.
* `system` ditambahkan ke instruksi Lana.
* `max_tokens` bersifat opsional (nilai default dan maksimum 8.192), dan gambar harus berupa URL.
* Peristiwanya berbeda. Tidak ada `content_block_start`, `content_block_stop`, `message_delta`, atau `message_stop`. Aliran berakhir dengan `message_end` atau `error`.
* `usage` menambahkan `tool_calls`, `prompt_tokens`, dan `context_window`. `stop_reason` dapat berupa `error`.
* `extensions` hanya tersedia untuk Lana.

## Endpoint dan autentikasi

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

Kirimkan kunci API Helius Anda melalui salah satu cara berikut:

| Metode | Contoh |
| - | - |
| Header `X-Api-Key` (disarankan) | `X-Api-Key: YOUR_API_KEY` |
| Parameter kueri `api-key` | `https://beta.helius-rpc.com/v1/lana/messages?api-key=YOUR_API_KEY` |

`Authorization: Bearer` tidak berfungsi pada endpoint ini dan mengembalikan `401`.

`mainnet.helius-rpc.com` belum melayani rute ini dan mengembalikan `503`.

Kirimkan `Content-Type: application/json` pada setiap permintaan.

> [!WARNING]
>
> Kunci API Anda menggunakan kredit paket Anda. Panggil Lana dari server Anda, bukan dari browser atau aplikasi yang Anda distribusikan kepada pengguna.

## Isi permintaan

Isinya adalah objek JSON. Bidang yang tidak dikenal ditolak dengan `400`, termasuk bidang yang tidak dikenal di dalam `extensions` dan blok konten.

**model** `string` *required*

`lana-thinking` atau `lana-fast`. Lihat [Model](#model).

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

Percakapan, dimulai dari yang paling lama. Percakapan memerlukan setidaknya satu pesan, dan pesan terakhir harus memiliki `role: "user"`. Lihat [Pesan](#pesan).

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

Jumlah maksimum token keluaran yang dapat ditulis Lana dalam satu langkah model, dari `1` hingga `8192`. Giliran dengan pencarian memerlukan beberapa langkah, sehingga total `output_tokens` giliran tersebut dapat lebih tinggi daripada `max_tokens`. Di bawah 2.048, `lana-thinking` tidak melakukan penalaran.

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

`true` mengalirkan [peristiwa](#peristiwa-streaming). `false` mengembalikan satu [respons JSON](#respons-non-streaming) saat giliran berakhir.

**system** `string`

Instruksi tambahan, dari 1 hingga 10.000 karakter, seperti "Jawab dalam tiga poin berpoin." Instruksi tersebut ditambahkan ke instruksi Lana sendiri, bukan digunakan untuk menggantikannya.

**extensions** `object`

Opsi khusus Lana. Lihat [Ekstensi](#ekstensi).

### Model

| | `lana-thinking` | `lana-fast` |
| - | - | - |
| Paling cocok untuk | Analisis multilangkah | Pencarian cepat dan fakta tunggal |
| Langkah pencarian per giliran | Hingga 20 | Hingga 4 |
| Pencarian web per giliran | Hingga 3 | Hingga 2 |
| Pengambilan halaman web per giliran | Hingga 2 | Hingga 2 |
| Mengalirkan penalaran | Terkadang, sebagai `thinking_delta`. Lana menentukan kapan harus bernalar. | Tidak |

`lana-thinking` hanya melakukan penalaran jika `max_tokens` bernilai 2048 atau lebih tinggi.

### Pesan

Setiap pesan memiliki `role` (`user` atau `assistant`) dan `content`:

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

API tidak menyimpan percakapan. Untuk mengajukan pertanyaan lanjutan, kirimkan kembali seluruh percakapan dengan pertanyaan baru di bagian akhir. Teks jawaban Lana sudah cukup untuk giliran `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 hanya mencari alamat yang muncul dalam percakapan, dalam hasil pencariannya sendiri, atau di `extensions.user_context.wallet`.

`content` adalah string yang tidak kosong atau array blok yang tidak kosong:

| Blok | Diizinkan dalam | Bentuk |
| - | - | - |
| `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": "..." }` |

Gambar harus berupa URL. Gambar Base64 tidak didukung.

Anda tidak memerlukan blok `tool_use` atau `tool_result`. Blok tersebut memungkinkan Anda memutar ulang pencarian dari giliran sebelumnya, sebagaimana dikembalikan Lana, agar Lana dapat menggunakan kembali hasil tersebut. `tool_result` juga menerima boolean `is_error` opsional.

### Ekstensi

Semua ekstensi bersifat opsional.

| Bidang | Jenis | Default | Fungsinya |
| - | - | - | - |
| `read_only` | boolean | `true` | Menghapus alat transfer, swap, dan peluncuran token. Biarkan tetap `true`: API ini tidak mendokumentasikan alur untuk menampilkan dan menandatangani tindakan dompet. |
| `output_format` | `"markdown"` \| `"plain"` | `"markdown"` | `plain` memberi tahu Lana agar tidak menggunakan Markdown dan menghapus penanda `{{cite:N}}`. Peristiwa `source` tetap tiba. |
| `include_ui_schema` | boolean | `false` | Mengizinkan komponen UI, sebagai peristiwa `ui_block` dan `ui_schema`. |
| `include_followups` | boolean | `false` | Mengizinkan hingga 3 pertanyaan lanjutan yang disarankan. |
| `include_documents` | boolean | `false` | Mengizinkan file CSV, JSON, atau teks yang dapat diunduh, sebagai peristiwa `document`. |
| `enable_deep_scan` | boolean | `false` | Memungkinkan Lana membaca hingga 10.000 transaksi dari riwayat suatu alamat (50.000 untuk hitungan dan total), hingga 3 pemindaian per giliran. Hanya mainnet. Tanpa opsi ini, Lana membaca hingga 100 transaksi per pencarian. Pemindaian mendalam lebih lambat, tetapi dikenai harga tetap yang sama. Pemindaian tersebut diperhitungkan dalam batas giliran 5 menit. |
| `user_context` | object | tidak ada | Pihak yang bertanya. Lihat di bawah. |
| `attachments` | object\[] | tidak ada | Hingga 8 gambar yang ditambahkan ke pesan pengguna terakhir. Blok `image` dalam `messages` tidak diperhitungkan dalam batas ini. Masing-masing berupa `{ "url": "https://...", "kind": "image" }`. |

Opsi `include_*` memungkinkan keluaran tersebut. Lana menentukan apakah akan mengirimkannya.

`extensions` juga menerima `progress_context` dan `transaction_filter_context`. Penjelajah [Orb](https://www.helius.dev/docs/id/orb.md) menggunakannya, dan Anda tidak memerlukannya.

Bidang `user_context`:

| Bidang | Jenis | Fungsinya |
| - | - | - |
| `wallet` | string, hingga 128 karakter | Alamat pengguna, agar "dompet saya" dan "saldo saya" berfungsi. |
| `address_kind` | string, hingga 32 karakter | `"wallet"` atau `"token"`: jenis `wallet`. Memerlukan `wallet`. |
| `time_zone` | string, hingga 64 karakter | Zona waktu IANA, seperti `"America/New_York"`, agar "hari ini" berfungsi. |
| `network` | `"mainnet"` \| `"devnet"` | Jaringan yang akan dicari. Default-nya adalah mainnet. |

## Peristiwa streaming

Dengan `"stream": true`, Anda mendapatkan status `200` dan `Content-Type: text/event-stream`. Setiap peristiwa terlihat seperti ini:

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

```

`data` adalah satu baris JSON. `type` miliknya cocok dengan nama `event`.

`200` dan peristiwa pertama tiba saat Lana pertama kali merespons (penalaran, teks jawaban, pencarian, atau file), atau paling lambat setelah 10 detik. Hingga saat itu, tidak ada yang dikirim, sehingga permintaan yang gagal dalam jangka waktu tersebut mendapatkan [respons kesalahan](#sebelum-aliran-dimulai) normal dan tidak dikenai biaya. Setelah itu, `ping` tiba setiap 10 detik selama Lana bekerja.

Atur batas waktu baca klien HTTP Anda menjadi 30 detik atau lebih. Nilai default 5 detik, seperti pada `httpx`, terlalu singkat: batas waktu dapat berakhir sebelum byte pertama atau di antara dua peristiwa.

Peristiwa tiba dalam urutan berikut:

1. `message_start`, selalu pertama.
2. Campuran apa pun dari `content_block_delta`, `tool_use`, `tool_result`, `source`, `ui_block`, `document`, `progress_update`, dan `ping`.
3. `ui_schema`, paling banyak satu kali.
4. `follow_up`, paling banyak satu kali.
5. `message_end` jika giliran selesai, atau `error` jika gagal. Ini selalu menjadi peristiwa terakhir.

Jenis peristiwa dan bidang baru dapat ditambahkan. Abaikan yang tidak Anda kenali.

| Peristiwa | Arti | Contoh `data` |
| - | - | - |
| `message_start` | Giliran dimulai. | `{"type":"message_start","message":{"id":"msg_3f9c...","model":"lana-thinking"}}` |
| `content_block_delta` (`text_delta`) | Potongan jawaban. | `{"type":"content_block_delta","delta":{"type":"text_delta","text":"SOL is trading at"}}` |
| `content_block_delta` (`thinking_delta`) | Potongan penalaran. Hanya `lana-thinking`, saat Lana bernalar. | `{"type":"content_block_delta","delta":{"type":"thinking_delta","thinking":"I should check..."}}` |
| `tool_use` | Lana memulai pencarian. | `{"type":"tool_use","tool_use_id":"toolu_01...","name":"...","input":{"address":"..."}}` |
| `tool_result` | Pencarian selesai. `content` adalah pratinjau hingga 500 karakter. `is_error: true` berarti pencarian gagal; lihat [Kesalahan alat](#kesalahan-alat). | `{"type":"tool_result","tool_use_id":"toolu_01...","content":"{\"balance\":..."}` |
| `source` | Halaman web yang digunakan Lana. `index` cocok dengan penanda `{{cite:N}}` dalam jawaban. `snippet` bersifat opsional. | `{"type":"source","index":0,"url":"https://...","title":"...","snippet":"..."}` |
| `progress_update` | Baris status singkat selama giliran yang panjang. Tampilkan secara terpisah dari jawaban. `created_at` adalah milidetik Unix. | `{"type":"progress_update","id":"progress_8a1b...","message":"I'll check this wallet's recent swaps.","created_at":1760436000000}` |
| `ui_block` | Satu komponen UI. Memerlukan `include_ui_schema`. `tool_use_id` bersifat opsional. | `{"type":"ui_block","tool_use_id":"toolu_01...","component":"...","schema":{...}}` |
| `document` | File yang dapat diunduh. Memerlukan `include_documents`. `format` adalah `csv`, `json`, atau `txt`. `tool_use_id` dan `description` bersifat opsional. | `{"type":"document","filename":"usdc-holders","format":"csv","content":"owner,amount\n...","description":"..."}` |
| `ui_schema` | Semua komponen UI sebagai satu pohon. Memerlukan `include_ui_schema`. | `{"type":"ui_schema","schema":{...}}` |
| `follow_up` | Pertanyaan berikutnya yang disarankan. Memerlukan `include_followups`. | `{"type":"follow_up","suggestions":["Show the top 10 holders' recent transfers"]}` |
| `message_end` | Giliran selesai. Lihat [Alasan berhenti](#alasan-berhenti) dan [Penggunaan](#penggunaan). | `{"type":"message_end","stop_reason":"end_turn","usage":{"input_tokens":91200,"output_tokens":212,"tool_calls":1,"prompt_tokens":46100,"context_window":200000}}` |
| `error` | Giliran gagal. Lihat [Kesalahan](#kesalahan). | `{"type":"error","error":{"type":"overloaded_error","message":"Lana is temporarily overloaded. Retry the request shortly."}}` |
| `ping` | Denyut setiap 10 detik. Abaikan. | `{"type":"ping"}` |

Kiat untuk menampilkan aliran:

* Gunakan `tool_use` hanya untuk indikator progres. Nama dan masukan alat dapat berubah.
* Dengan keluaran `"markdown"`, ubah setiap `{{cite:N}}` menjadi tautan ke `source` dengan `index` tersebut, atau hapus.
* `ui_block` dan `ui_schema` membawa komponen yang sama. Lana mungkin hanya mengirimkan `ui_schema`, jadi tampilkan peristiwa `ui_block` jika tiba dan jika tidak, render `ui_schema`.
* Pencarian web mengirimkan `tool_result` dengan teks `Web search completed.` atau `Web fetch completed.` Halaman tiba sebagai peristiwa `source`.

### Kesalahan alat

Pencarian yang gagal tidak menggagalkan giliran. Lana mengatasinya, dan Anda tidak perlu mencoba lagi. `tool_result` memiliki `is_error: true`, dan `content` adalah JSON dengan pesan singkat dan `code`:

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

> [accordion] Kode kesalahan alat
>
> | `code` | Arti |
> | - | - |
> | `invalid_input` | Argumen pencarian tidak valid. |
> | `not_found` | Tidak ada data untuk pencarian ini. Beberapa pencarian melaporkan item yang tidak ditemukan sebagai hasil normal, seperti `{"found": false}`. |
> | `rejected` | Layanan data menolak pencarian. |
> | `rate_limited` | Layanan data menerapkan pembatasan laju. |
> | `upstream_timeout` | Waktu layanan data habis. |
> | `upstream_unavailable` | Layanan data gagal. |
> | `upstream_error` | Alat data Helius gagal. |
> | `timeout` | Waktu pencarian habis. |
> | `tool_failed` | Pencarian tidak dapat memberikan jawaban. `error` menjelaskan alasannya. |
> | `internal` | Terjadi kegagalan yang tidak terduga. |
>
> Kode baru dapat ditambahkan. Perlakukan kode yang tidak dikenal sebagai `internal`.

### Alasan berhenti

`stop_reason` terdapat pada `message_end` dan dalam respons JSON:

| Nilai | Arti |
| - | - |
| `end_turn` | Lana menyelesaikan jawabannya. |
| `max_tokens` | Jawaban mencapai `max_tokens` dan mungkin terpotong. |
| `tool_use` | Giliran berakhir pada langkah pencarian, biasanya pada batas langkah. |
| `error` | Giliran gagal. Jawaban tidak lengkap. |

### Penggunaan

| Bidang | Arti |
| - | - |
| `input_tokens` | Token masukan untuk seluruh giliran. |
| `output_tokens` | Token keluaran untuk seluruh giliran. |
| `tool_calls` | Pencarian yang dijalankan dalam giliran, termasuk beberapa yang tidak pernah muncul sebagai `tool_use`. |
| `prompt_tokens` | Token masukan dalam langkah model terakhir. Gunakan untuk melihat seberapa penuh konteksnya. |
| `context_window` | Jendela konteks model, saat ini `200000`. |

Instruksi dan alat pencarian milik Lana menggunakan sekitar 45.000 token pada setiap langkah model, sehingga `input_tokens` tetap tinggi bahkan untuk pertanyaan singkat. Harga ditetapkan per permintaan, sehingga jumlah token tidak mengubah biaya yang Anda bayar.

## Respons non-streaming

Dengan `"stream": false`, Anda mendapatkan satu objek JSON saat giliran berakhir:

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

Jawabannya adalah blok `text`, yang digabungkan secara berurutan. Penalaran dan `progress_update` hanya tersedia dalam streaming.

Bidang berikut hanya muncul jika memiliki nilai:

| Bidang | Kapan |
| - | - |
| `ui_schema` | `include_ui_schema` aktif dan ada sesuatu untuk ditampilkan. |
| `documents` | `include_documents` aktif dan Lana membuat file. Bidangnya sama seperti peristiwa `document`, tanpa `type`. |
| `follow_up` | `include_followups` aktif dan Lana menyarankan pertanyaan. Berupa array string. |
| `sources` | Lana menggunakan halaman web. Bidangnya sama seperti peristiwa `source`, tanpa `type`. |
| `error` | `stop_reason` adalah `"error"`. Objek dengan `type` dan `message`. |

## Kesalahan

### Sebelum aliran dimulai

Permintaan yang gagal sebelum respons dimulai mengembalikan status selain `200` dengan isi kesalahan normal, bahkan dengan `"stream": true`. Tidak ada peristiwa yang dikirim dan Anda tidak dikenai biaya. Periksa status HTTP sebelum membaca isi sebagai aliran.

Dengan `"stream": true`, respons dimulai saat Lana pertama kali merespons, atau paling lambat setelah 10 detik. Giliran yang gagal sebelum itu, misalnya karena model kelebihan beban atau percakapan terlalu panjang, juga masuk ke kategori ini.

| Status | Penyebab | Tindakan |
| - | - | - |
| `400` | Isinya tidak valid, misalnya model yang tidak dikenal atau `max_tokens` di atas 8.192. `message` menyebutkan setiap bidang yang bermasalah. | Perbaiki permintaan. |
| `401` | Kunci API tidak ada atau tidak valid, atau dikirim sebagai `Authorization: Bearer`. | Kirimkan kunci dalam `X-Api-Key` atau `?api-key=`. |
| `403` | Paket Anda tidak menyertakan Lana (paket Free), atau pengaturan akses kunci Anda memblokirnya. | Tingkatkan ke Developer atau yang lebih tinggi, atau periksa pengaturan akses kunci di [Dasbor Helius](https://dashboard.helius.dev). |
| `400`, isi `Bad Request` | Isi melebihi 10 MB. Gatekeeper menolaknya sebelum Lana menerimanya. | Kirimkan permintaan yang lebih kecil, misalnya dengan pesan yang lebih sedikit atau lebih pendek. |
| `429`, isi `Too Many Requests` | Anda melampaui [batas laju](https://www.helius.dev/docs/id/billing/rate-limits.md) paket. | Tunggu sesuai header `Retry-After` (1 detik), lalu coba lagi. |
| `429`, isi `max usage reached` | Kredit proyek Anda habis. | Tambahkan kredit atau tingkatkan paket Anda. Tidak ada `Retry-After`; percobaan ulang akan terus gagal hingga Anda melakukannya. |
| `429`, `error.type` `rate_limit_error` | Proyek Anda sudah menjalankan sekitar 3 permintaan Lana. | Tunggu sesuai header `Retry-After` (5 detik), lalu coba lagi. |
| `503` | Lana mencapai kapasitas atau sedang dimulai ulang. | Tunggu sesuai header `Retry-After` (5 detik saat mencapai kapasitas, 30 detik saat dimulai ulang), lalu coba lagi. |
| `400`, `error.type` `context_overflow` | Percakapan tidak muat dalam jendela konteks. | Hapus pesan lama atau ajukan pertanyaan yang lebih sempit. |
| `529`, `error.type` `overloaded_error` | Model kelebihan beban. `529` adalah status yang digunakan Anthropic untuk kondisi ini; beberapa klien HTTP tidak mengenalinya, jadi tangani seperti `503`. | Coba lagi dengan backoff eksponensial. |
| `500`, `502`, `504` | Giliran gagal sebelum keluaran pertamanya dengan `api_error`, `tool_error`, atau `timeout_error`. | Tangani seperti dalam [Jenis kesalahan](#jenis-kesalahan). |

Dua `429` pertama berasal dari paket Anda, dan isi respons menunjukkan mana yang terjadi. Yang ketiga berasal dari Lana dan memiliki isi JSON.

Jika `429` atau `503` tiba tanpa header `Retry-After`, tunggu beberapa detik sebelum mencoba lagi.

Kesalahan milik Lana (`400` untuk isi yang tidak valid atau `context_overflow`, `429` dengan `rate_limit_error`, `500`, `502`, `503`, `504`, dan `529`) memiliki isi JSON. Kesalahan dari Gatekeeper (`401`, `403`, `400` untuk isi berukuran terlalu besar, dan `429` paket) berupa teks biasa. Buat percabangan berdasarkan `error.type`, bukan `message`:

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

### Setelah aliran dimulai

Status sudah berupa `200`, sehingga kegagalan mengakhiri aliran dengan peristiwa `error` terakhir, atau dengan `message_end` dan `stop_reason: "error"`. `message_end` tersebut tidak memiliki objek `error`; perlakukan seperti `api_error`. Semua teks jawaban sebelumnya bersifat parsial. Tampilkan sebagai tidak lengkap atau buang.

### Tanpa streaming

Dengan `"stream": false`, giliran yang gagal mengembalikan salah satu dari:

* `200` dengan `stop_reason: "error"` dan objek `error`, jika giliran menghasilkan konten apa pun, termasuk pencarian. Selalu periksa `stop_reason`.
* Isi kesalahan JSON, jika giliran tidak menghasilkan apa pun. Statusnya cocok dengan `error.type`: `400` untuk `context_overflow`, `500` untuk `api_error`, `502` untuk `tool_error`, `504` untuk `timeout_error`, atau `529` untuk `overloaded_error` (status yang digunakan Anthropic untuk model yang kelebihan beban; beberapa klien HTTP tidak mengenalinya, jadi tangani seperti `503`). Permintaan ini tidak dikenai biaya. Tangani seperti dalam [Jenis kesalahan](#jenis-kesalahan).

### Jenis kesalahan

| `error.type` | Arti | Tindakan |
| - | - | - |
| `invalid_request_error` | Permintaan tidak valid. | Perbaiki permintaan. |
| `context_overflow` | Percakapan dan hasil pencarian tidak muat dalam jendela konteks. | Hapus pesan lama atau ajukan pertanyaan yang lebih sempit. |
| `overloaded_error` | Model kelebihan beban. | Coba lagi dengan backoff eksponensial. |
| `timeout_error` | Waktu giliran habis. | Ajukan pertanyaan yang lebih sempit, atau gunakan `lana-fast`. |
| `tool_error` | Layanan pencarian yang diandalkan Lana gagal. | Coba lagi dengan backoff. |
| `rate_limit_error` | Proyek Anda menjalankan sekitar 3 permintaan. | Coba lagi setelah waktu dalam header `Retry-After`. |
| `api_error` | Lana gagal di sisi Helius atau mencapai kapasitas. | Coba lagi dengan backoff. |

Perlakukan jenis lainnya seperti `api_error`.

## Batas

| Batas | Nilai |
| - | - |
| `max_tokens` | 1 hingga 8.192 (default 8.192) |
| `system` | Hingga 10.000 karakter |
| `extensions.attachments` | Hingga 8 gambar |
| Isi permintaan | 10 MB |
| Jendela konteks | 200.000 token, sekitar 80%-nya (setelah `max_tokens`) digunakan untuk percakapan dan hasil pencarian |
| Durasi giliran | 5 menit |
| Batas laju | Batas laju DAS & Enhanced APIs paket Anda. Lihat [Batas Laju](https://www.helius.dev/docs/id/billing/rate-limits.md#api-lana). |
| Permintaan serentak | Sekitar 3 per proyek. Permintaan tambahan dapat menerima `429` hingga salah satunya selesai. |

Saat giliran mendekati 5 menit, Lana berhenti melakukan pencarian dan menjawab dengan informasi yang dimilikinya. Giliran panjang biasanya berakhir dengan jawaban parsial yang menjelaskan informasi yang belum tersedia, bukan dengan batas waktu habis.

Saat melakukan streaming, atur batas waktu baca klien HTTP Anda menjadi 30 detik atau lebih. Byte pertama dapat memerlukan waktu hingga 10 detik dan `ping` tiba setiap 10 detik setelah itu, sehingga jeda yang jauh lebih lama berarti koneksi terputus. Nilai default 5 detik, seperti pada `httpx`, terlalu singkat. Tanpa streaming, tidak ada yang tiba hingga giliran berakhir, jadi atur batas waktu baca di atas 5 menit.

Jika Anda memutuskan koneksi, Lana menghentikan giliran. Permintaan yang alirannya sudah dimulai tetap dikenai biaya.

Saat Lana mencapai kapasitas, permintaan baru menerima `503` sebelum apa pun dialirkan. Permintaan tersebut tidak dikenai biaya. Coba lagi setelah waktu dalam header `Retry-After`.

## Harga

Setiap permintaan dikenai harga tetap yang bergantung pada model:

| Model | Kredit per permintaan |
| - | - |
| `lana-thinking` | **10.000** |
| `lana-fast` | **2.000** |

Harganya sama untuk permintaan streaming dan non-streaming serta pada setiap paket berbayar (Developer dan yang lebih tinggi). Lana tidak tersedia dalam paket Free.

Kredit berasal dari paket Anda. Lihat [Kredit](https://www.helius.dev/docs/id/billing/credits.md#kredit-lana-api).

### Hal yang dikenai biaya

Anda dikenai biaya untuk setiap permintaan yang mendapatkan HTTP `200`, baik streaming maupun tidak, terlepas dari bagaimana giliran berakhir. Permintaan yang gagal sebelum respons dimulai mendapatkan status lain dan tidak dikenai biaya.

* Giliran streaming yang gagal dengan peristiwa `error`, atau yang koneksinya Anda putus setelah dimulai, dikenai biaya: statusnya sudah berupa `200`.
* Permintaan yang ditolak sebelum giliran dimulai (`400`, `401`, `403`, `429`, `503`) tidak dikenai biaya.
* Giliran yang gagal sebelum respons dimulai (`400`, `5xx`), baik streaming maupun tidak, tidak dikenai biaya.

## Contoh lainnya

### Atur nada dan dompet pengguna

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

### Pindai seluruh riwayat dompet

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

### Dapatkan komponen UI, tindak lanjut, dan 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
    }
  }'
```

## Langkah berikutnya

> [card] [Referensi API](https://www.helius.dev/docs/id/api-reference/lana/messages.md)
>
> Skema permintaan dan respons, dengan playground.

> [card] [Batas Laju](https://www.helius.dev/docs/id/billing/rate-limits.md#api-lana)
>
> Batas laju Lana untuk setiap paket.

> [card] [Kredit](https://www.helius.dev/docs/id/billing/credits.md#kredit-lana-api)
>
> Cara permintaan Lana menggunakan kredit paket Anda.

> [card] [Hubungi Dukungan](https://www.helius.dev/docs/id/support/contact-support)
>
> Dapatkan bantuan melalui Discord, obrolan, atau email.


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