> ## 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 AI 에이전트

> HTTP를 통해 Solana AI 에이전트인 Lana를 호출하세요. 지갑, 토큰, 트랜잭션, 가격에 관해 질문하고 답변을 스트리밍으로 받을 수 있습니다. 빠른 시작, API 레퍼런스, 요금 정보를 확인하세요.

Lana API는 HTTP를 통해 호출하는 Solana AI 에이전트입니다. 일반 영어로 질문을 보내면 지갑, 토큰, 트랜잭션, 가격을 조회한 후 답변을 스트리밍으로 반환합니다.

Lana는 모든 조회를 Helius 측에서 실행하므로 도구를 정의하거나 실행할 필요가 없습니다. 유료 Helius 요금제(Developer 이상)에서 사용할 수 있으며 요청당 고정 요금은 `lana-thinking`의 경우 10,000크레딧, `lana-fast`의 경우 2,000크레딧입니다. [요금](#요금)을 참조하세요.

이 API는 Anthropic Messages API와 유사한 형태이지만 Anthropic SDK는 사용할 수 없습니다. 아래 예시처럼 일반 HTTP를 통해 호출하세요. [Anthropic Messages API와의 차이점](#anthropic-messages-api와의-차이점)을 참조하세요.

Lana는 Anthropic의 Claude 모델에서 실행됩니다. 답변을 생성하기 위해 질문과 대화가 Anthropic으로 전송됩니다.

> [!NOTE]
>
> Lana API는 [Gatekeeper(베타)](https://www.helius.dev/docs/ko/gatekeeper/overview.md) 엔드포인트인 `beta.helius-rpc.com`에서 베타로 제공됩니다. 아직 `mainnet.helius-rpc.com`에서는 사용할 수 없습니다. 베타 기간에는 새로운 이벤트와 필드가 추가될 수 있습니다.

## Lana에 질문할 수 있는 내용

사용자가 자신의 거래와 거래 상대 지갑에 관해 다음과 같은 질문을 할 수 있습니다.

* "마지막 트랜잭션이 실패한 이유는 무엇인가요?"
* "이 스왑에서 슬리피지가 얼마나 발생했나요?"
* "이 트랜잭션에서 어떤 수수료를 지불했나요?"
* "이 지갑은 어디서 자금을 받았고 어디로 보냈나요?"
* "이 지갑은 다른 이 지갑과 연결되어 있나요?"
* "이 토큰의 최대 보유자는 누구인가요?"

"내" 지갑이나 "내 마지막 트랜잭션"에 관한 질문이 작동하도록 사용자의 지갑을 [`extensions.user_context.wallet`](#확장-기능)에 전달하세요.

## 빠른 시작

**1. Get an API key**

[Helius 대시보드](https://dashboard.helius.dev)에서 API 키를 복사하세요.

**2. Ask a question**

`YOUR_API_KEY`을 바꾸고 다음을 실행하세요.

```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`을 사용하면 각 이벤트가 도착하는 즉시 curl이 출력합니다. 첫 번째 이벤트가 도착하기까지 최대 10초가 걸릴 수 있습니다.

**3. Read the answer**

응답은 [이벤트](#스트리밍-이벤트) 스트림입니다.

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

답변은 순서대로 나열된 `text_delta` 청크입니다. `lana-thinking`은 `thinking_delta` 청크도 전송할 수 있습니다. 이는 Lana의 추론이므로 답변과 별도로 표시하거나 건너뛰세요.

### 코드에서 스트림 읽기

두 예시는 모두 본문을 스트림으로 읽기 전에 HTTP 상태를 확인하고, `429` 또는 `503`에서 `Retry-After`을 기다리고, 스트리밍되는 답변을 출력하며, 턴이 실패하거나 스트림이 조기에 종료되면 중지합니다.

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

## Anthropic Messages API와의 차이점

* 모델은 `lana-thinking` 및 `lana-fast`입니다.
* Lana는 자체 도구를 실행합니다. `tools`, `tool_choice`, `temperature`, `top_p`, `top_k`, `stop_sequences` 및 `metadata`은 `400`을 반환합니다.
* `system`은 Lana의 지침에 추가됩니다.
* `max_tokens`은 선택 사항이며 기본값과 최댓값은 8,192입니다. 이미지는 URL이어야 합니다.
* 이벤트가 다릅니다. `content_block_start`, `content_block_stop`, `message_delta` 또는 `message_stop`이 없습니다. 스트림은 `message_end` 또는 `error`으로 종료됩니다.
* `usage`에는 `tool_calls`, `prompt_tokens` 및 `context_window`이 추가됩니다. `stop_reason`은 `error`일 수 있습니다.
* `extensions`은 Lana 전용입니다.

## 엔드포인트 및 인증

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

다음 방법 중 하나로 Helius API 키를 보내세요.

| 방법 | 예시 |
| - | - |
| `X-Api-Key` 헤더(권장) | `X-Api-Key: YOUR_API_KEY` |
| `api-key` 쿼리 매개변수 | `https://beta.helius-rpc.com/v1/lana/messages?api-key=YOUR_API_KEY` |

`Authorization: Bearer`은 이 엔드포인트에서 작동하지 않으며 `401`을 반환합니다.

`mainnet.helius-rpc.com`은 아직 이 경로를 제공하지 않으며 `503`을 반환합니다.

모든 요청에 `Content-Type: application/json`을 보내세요.

> [!WARNING]
>
> API 키는 요금제의 크레딧을 사용합니다. 브라우저나 사용자에게 배포하는 앱이 아니라 서버에서 Lana를 호출하세요.

## 요청 본문

본문은 JSON 객체입니다. `extensions` 내부와 콘텐츠 블록의 알 수 없는 필드를 포함해 알 수 없는 필드는 `400`과 함께 거부됩니다.

**model** `string` *required*

`lana-thinking` 또는 `lana-fast`입니다. [모델](#모델)을 참조하세요.

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

가장 오래된 항목부터 나열한 대화입니다. 메시지가 하나 이상 있어야 하며 마지막 메시지에는 `role: "user"`이 있어야 합니다. [메시지](#메시지)를 참조하세요.

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

Lana가 한 모델 단계에서 작성할 수 있는 최대 출력 토큰 수로, `1`부터 `8192`까지입니다. 조회가 포함된 턴은 여러 단계를 거치므로 턴의 총 `output_tokens`은 `max_tokens`보다 클 수 있습니다. 2,048 미만에서는 `lana-thinking`이 추론하지 않습니다.

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

`true`은 [이벤트](#스트리밍-이벤트)를 스트리밍합니다. `false`은 턴이 끝날 때 하나의 [JSON 응답](#비스트리밍-응답)을 반환합니다.

**system** `string`

"세 개의 글머리 기호로 답변하세요."와 같은 1\~10,000자의 추가 지침입니다. Lana의 자체 지침을 대체하지 않고 해당 지침에 추가됩니다.

**extensions** `object`

Lana 전용 옵션입니다. [확장 기능](#확장-기능)을 참조하세요.

### 모델

| | `lana-thinking` | `lana-fast` |
| - | - | - |
| 적합한 용도 | 다단계 분석 | 빠른 조회 및 단일 사실 확인 |
| 턴당 조회 단계 | 최대 20회 | 최대 4회 |
| 턴당 웹 검색 | 최대 3회 | 최대 2회 |
| 턴당 웹 페이지 가져오기 | 최대 2회 | 최대 2회 |
| 추론 스트리밍 | 때때로 `thinking_delta`으로 전송됩니다. 추론 여부는 Lana가 결정합니다. | 아니요 |

`lana-thinking`은 `max_tokens`이 2048 이상일 때만 추론합니다.

### 메시지

각 메시지에는 `role`(`user` 또는 `assistant`)과 `content`이 있습니다.

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

API는 대화를 저장하지 않습니다. 후속 질문을 하려면 끝에 새 질문을 추가해 전체 대화를 다시 보내세요. `assistant` 턴에는 Lana의 답변 텍스트만으로 충분합니다.

```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는 대화, 자체 조회 결과 또는 `extensions.user_context.wallet`에 나타나는 주소만 조회합니다.

`content`은 비어 있지 않은 문자열 또는 비어 있지 않은 블록 배열입니다.

| 블록 | 허용되는 위치 | 구조 |
| - | - | - |
| `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": "..." }` |

이미지는 URL이어야 합니다. Base64 이미지는 지원되지 않습니다.

`tool_use` 또는 `tool_result` 블록은 필요하지 않습니다. 이 블록을 사용하면 Lana가 이전 턴에서 반환한 조회를 재생해 해당 결과를 재사용할 수 있습니다. `tool_result`은 선택적 `is_error` 불리언도 받습니다.

### 확장 기능

모든 확장 기능은 선택 사항입니다.

| 필드 | 유형 | 기본값 | 기능 |
| - | - | - | - |
| `read_only` | boolean | `true` | 전송, 스왑 및 토큰 출시 도구를 제거합니다. `true`으로 두세요. 이 API는 지갑 작업을 표시하고 서명하는 흐름을 문서화하지 않습니다. |
| `output_format` | `"markdown"` \| `"plain"` | `"markdown"` | `plain`은 Lana가 Markdown을 사용하지 않도록 하고 `{{cite:N}}` 마커를 제거합니다. `source` 이벤트는 계속 도착합니다. |
| `include_ui_schema` | boolean | `false` | `ui_block` 및 `ui_schema` 이벤트 형태의 UI 컴포넌트를 허용합니다. |
| `include_followups` | boolean | `false` | 최대 3개의 추천 후속 질문을 허용합니다. |
| `include_documents` | boolean | `false` | `document` 이벤트 형태로 다운로드 가능한 CSV, JSON 또는 텍스트 파일을 허용합니다. |
| `enable_deep_scan` | boolean | `false` | Lana가 주소 기록에서 최대 10,000개의 트랜잭션을 읽도록 허용합니다. 개수와 합계에는 최대 50,000개를 읽으며 턴당 최대 3회 스캔합니다. 메인넷에서만 사용할 수 있습니다. 이 옵션이 없으면 Lana는 조회당 최대 100개의 트랜잭션을 읽습니다. 심층 스캔은 더 느리지만 동일한 고정 요금이 적용됩니다. 5분의 턴 제한에 포함됩니다. |
| `user_context` | object | 없음 | 질문하는 사용자입니다. 아래를 참조하세요. |
| `attachments` | object\[] | 없음 | 마지막 사용자 메시지에 추가되는 최대 8개의 이미지입니다. `messages`의 `image` 블록은 이 제한에 포함되지 않습니다. 각 항목은 `{ "url": "https://...", "kind": "image" }`입니다. |

`include_*` 옵션은 출력 생성을 가능하게 합니다. 전송 여부는 Lana가 결정합니다.

`extensions`은 `progress_context` 및 `transaction_filter_context`도 받습니다. [Orb](https://www.helius.dev/docs/ko/orb.md) 탐색기에서 사용되며 직접 사용할 필요는 없습니다.

`user_context` 필드:

| 필드 | 유형 | 기능 |
| - | - | - |
| `wallet` | 문자열, 최대 128자 | 사용자의 주소로, "내 지갑"과 "내 잔액"이 작동하도록 합니다. |
| `address_kind` | 문자열, 최대 32자 | `"wallet"` 또는 `"token"`으로, `wallet`의 종류를 나타냅니다. `wallet`이 필요합니다. |
| `time_zone` | 문자열, 최대 64자 | "오늘"이 작동하도록 하는 `"America/New_York"` 같은 IANA 시간대입니다. |
| `network` | `"mainnet"` \| `"devnet"` | 조회할 네트워크입니다. 기본값은 메인넷입니다. |

## 스트리밍 이벤트

`"stream": true`을 사용하면 상태 `200`과 `Content-Type: text/event-stream`을 받습니다. 각 이벤트는 다음과 같습니다.

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

```

`data`은 JSON 한 줄입니다. 해당 `type`은 `event` 이름과 일치합니다.

`200`과 첫 이벤트는 Lana가 처음 응답할 때(추론, 답변 텍스트, 조회 또는 파일), 또는 늦어도 10초 후에 도착합니다. 그전에는 아무것도 전송되지 않으므로 이 시간 내에 실패한 요청은 일반 [오류 응답](#스트림-시작-전)을 받으며 요금이 부과되지 않습니다. 이후 Lana가 작업하는 동안 10초마다 `ping`이 도착합니다.

HTTP 클라이언트의 읽기 타임아웃을 30초 이상으로 설정하세요. `httpx`과 같은 5초 기본값은 너무 짧습니다. 첫 바이트가 도착하기 전이나 두 이벤트 사이에 만료될 수 있습니다.

이벤트는 다음 순서로 도착합니다.

1. `message_start`이 항상 먼저 도착합니다.
2. `content_block_delta`, `tool_use`, `tool_result`, `source`, `ui_block`, `document`, `progress_update` 및 `ping`이 임의로 섞여 도착합니다.
3. `ui_schema`이 최대 한 번 도착합니다.
4. `follow_up`이 최대 한 번 도착합니다.
5. 턴이 완료되면 `message_end`이, 실패하면 `error`이 도착합니다. 항상 마지막 이벤트입니다.

새 이벤트 유형과 필드가 추가될 수 있습니다. 인식하지 못하는 항목은 무시하세요.

| 이벤트 | 의미 | `data` 예시 |
| - | - | - |
| `message_start` | 턴이 시작되었습니다. | `{"type":"message_start","message":{"id":"msg_3f9c...","model":"lana-thinking"}}` |
| `content_block_delta` (`text_delta`) | 답변 청크입니다. | `{"type":"content_block_delta","delta":{"type":"text_delta","text":"SOL is trading at"}}` |
| `content_block_delta` (`thinking_delta`) | 추론 청크입니다. Lana가 추론할 때 `lana-thinking`에서만 제공됩니다. | `{"type":"content_block_delta","delta":{"type":"thinking_delta","thinking":"I should check..."}}` |
| `tool_use` | Lana가 조회를 시작했습니다. | `{"type":"tool_use","tool_use_id":"toolu_01...","name":"...","input":{"address":"..."}}` |
| `tool_result` | 조회가 완료되었습니다. `content`은 최대 500자의 미리 보기입니다. `is_error: true`은 실패를 의미합니다. [도구 오류](#도구-오류)를 참조하세요. | `{"type":"tool_result","tool_use_id":"toolu_01...","content":"{\"balance\":..."}` |
| `source` | Lana가 사용한 웹 페이지입니다. `index`은 답변의 `{{cite:N}}` 마커와 일치합니다. `snippet`은 선택 사항입니다. | `{"type":"source","index":0,"url":"https://...","title":"...","snippet":"..."}` |
| `progress_update` | 긴 턴 중에 표시되는 짧은 상태 줄입니다. 답변과 별도로 표시하세요. `created_at`은 Unix 밀리초입니다. | `{"type":"progress_update","id":"progress_8a1b...","message":"I'll check this wallet's recent swaps.","created_at":1760436000000}` |
| `ui_block` | 하나의 UI 컴포넌트입니다. `include_ui_schema`이 필요합니다. `tool_use_id`은 선택 사항입니다. | `{"type":"ui_block","tool_use_id":"toolu_01...","component":"...","schema":{...}}` |
| `document` | 다운로드 가능한 파일입니다. `include_documents`이 필요합니다. `format`은 `csv`, `json` 또는 `txt`입니다. `tool_use_id` 및 `description`은 선택 사항입니다. | `{"type":"document","filename":"usdc-holders","format":"csv","content":"owner,amount\n...","description":"..."}` |
| `ui_schema` | 모든 UI 컴포넌트를 하나의 트리로 제공합니다. `include_ui_schema`이 필요합니다. | `{"type":"ui_schema","schema":{...}}` |
| `follow_up` | 추천 후속 질문입니다. `include_followups`이 필요합니다. | `{"type":"follow_up","suggestions":["Show the top 10 holders' recent transfers"]}` |
| `message_end` | 턴이 완료되었습니다. [중지 이유](#중지-이유) 및 [사용량](#사용량)을 참조하세요. | `{"type":"message_end","stop_reason":"end_turn","usage":{"input_tokens":91200,"output_tokens":212,"tool_calls":1,"prompt_tokens":46100,"context_window":200000}}` |
| `error` | 턴이 실패했습니다. [오류](#오류)를 참조하세요. | `{"type":"error","error":{"type":"overloaded_error","message":"Lana is temporarily overloaded. Retry the request shortly."}}` |
| `ping` | 10초마다 전송되는 하트비트입니다. 무시하세요. | `{"type":"ping"}` |

스트림 표시 팁:

* `tool_use`은 진행률 표시기에만 사용하세요. 도구 이름과 입력은 변경될 수 있습니다.
* `"markdown"` 출력에서는 각 `{{cite:N}}`을 해당 `index`이 있는 `source` 링크로 바꾸거나 제거하세요.
* `ui_block`과 `ui_schema`에는 동일한 컴포넌트가 포함됩니다. Lana가 `ui_schema`만 보낼 수도 있으므로 `ui_block` 이벤트가 도착하면 표시하고, 그렇지 않으면 `ui_schema`을 렌더링하세요.
* 웹 검색은 `Web search completed.` 또는 `Web fetch completed.` 텍스트가 있는 `tool_result`을 전송합니다. 페이지는 `source` 이벤트로 도착합니다.

### 도구 오류

조회가 실패해도 턴은 실패하지 않습니다. Lana가 이를 우회하므로 재시도할 필요가 없습니다. `tool_result`에는 `is_error: true`이 있으며, `content`은 짧은 메시지와 `code`이 포함된 JSON입니다.

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

> [accordion] Tool error codes
>
> | `code` | 의미 |
> | - | - |
> | `invalid_input` | 조회 인수가 잘못되었습니다. |
> | `not_found` | 이 조회에 대한 데이터가 없습니다. `{"found": false}`처럼 일부 조회는 누락된 항목을 일반 결과로 보고합니다. |
> | `rejected` | 데이터 서비스가 조회를 거부했습니다. |
> | `rate_limited` | 데이터 서비스에서 요청 속도를 제한하고 있습니다. |
> | `upstream_timeout` | 데이터 서비스가 시간 초과되었습니다. |
> | `upstream_unavailable` | 데이터 서비스가 실패했습니다. |
> | `upstream_error` | Helius 데이터 도구가 실패했습니다. |
> | `timeout` | 조회 시간이 초과되었습니다. |
> | `tool_failed` | 조회에서 답변할 수 없었습니다. `error`에 이유가 표시됩니다. |
> | `internal` | 예상치 못한 오류가 발생했습니다. |
>
> 새 코드가 추가될 수 있습니다. 알 수 없는 코드는 `internal`으로 처리하세요.

### 중지 이유

`stop_reason`은 `message_end`과 JSON 응답에 있습니다.

| 값 | 의미 |
| - | - |
| `end_turn` | Lana가 답변을 완료했습니다. |
| `max_tokens` | 답변이 `max_tokens`에 도달해 잘렸을 수 있습니다. |
| `tool_use` | 턴이 조회 단계에서 종료되었습니다. 일반적으로 단계 제한에 도달한 경우입니다. |
| `error` | 턴이 실패했습니다. 답변이 불완전합니다. |

### 사용량

| 필드 | 의미 |
| - | - |
| `input_tokens` | 전체 턴의 입력 토큰입니다. |
| `output_tokens` | 전체 턴의 출력 토큰입니다. |
| `tool_calls` | 턴에서 실행된 조회입니다. `tool_use`으로 나타나지 않는 일부 조회도 포함됩니다. |
| `prompt_tokens` | 마지막 모델 단계의 입력 토큰입니다. 컨텍스트가 얼마나 찼는지 확인할 때 사용하세요. |
| `context_window` | 모델의 컨텍스트 창으로, 현재 `200000`입니다. |

Lana의 자체 지침과 조회 도구는 모델 단계마다 약 45,000개의 토큰을 사용하므로 짧은 질문에서도 `input_tokens`이 높습니다. 요금은 요청당 부과되므로 토큰 수는 지불 금액에 영향을 주지 않습니다.

## 비스트리밍 응답

`"stream": false`을 사용하면 턴이 끝날 때 하나의 JSON 객체를 받습니다.

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

답변은 `text` 블록을 순서대로 결합한 것입니다. 추론 및 `progress_update`은 스트리밍에서만 제공됩니다.

다음 필드는 값이 있을 때만 나타납니다.

| 필드 | 조건 |
| - | - |
| `ui_schema` | `include_ui_schema`이 켜져 있고 표시할 내용이 있을 때입니다. |
| `documents` | `include_documents`이 켜져 있고 Lana가 파일을 생성했을 때입니다. `type`이 없다는 점을 제외하면 `document` 이벤트와 필드가 같습니다. |
| `follow_up` | `include_followups`이 켜져 있고 Lana가 질문을 추천했을 때입니다. 문자열 배열입니다. |
| `sources` | Lana가 웹 페이지를 사용했을 때입니다. `type`이 없다는 점을 제외하면 `source` 이벤트와 필드가 같습니다. |
| `error` | `stop_reason`이 `"error"`일 때입니다. `type`과 `message`이 포함된 객체입니다. |

## 오류

### 스트림 시작 전

응답이 시작되기 전에 실패한 요청은 `"stream": true`을 사용하더라도 일반 오류 본문과 함께 `200`이 아닌 상태를 반환합니다. 이벤트는 전송되지 않으며 요금도 부과되지 않습니다. 본문을 스트림으로 읽기 전에 HTTP 상태를 확인하세요.

`"stream": true`을 사용하면 Lana가 처음 응답할 때 또는 늦어도 10초 후에 응답이 시작됩니다. 모델 과부하나 너무 긴 대화 등으로 그전에 실패한 턴도 여기에 해당합니다.

| 상태 | 원인 | 조치 |
| - | - | - |
| `400` | 알 수 없는 모델이나 8,192를 초과하는 `max_tokens` 등 본문이 잘못되었습니다. `message`에 잘못된 각 필드가 표시됩니다. | 요청을 수정하세요. |
| `401` | API 키가 없거나 유효하지 않거나 `Authorization: Bearer`으로 전송되었습니다. | `X-Api-Key` 또는 `?api-key=`에 키를 보내세요. |
| `403` | 요금제에 Lana가 포함되지 않았거나(Free 요금제), 키의 액세스 설정에서 차단되었습니다. | Developer 이상으로 업그레이드하거나 [Helius 대시보드](https://dashboard.helius.dev)에서 키의 액세스 설정을 확인하세요. |
| `400`, 본문 `Bad Request` | 본문이 10MB를 초과합니다. Lana가 보기 전에 Gatekeeper에서 거부됩니다. | 메시지 수나 길이를 줄이는 등 더 작은 요청을 보내세요. |
| `429`, 본문 `Too Many Requests` | 요금제의 [속도 제한](https://www.helius.dev/docs/ko/billing/rate-limits.md)을 초과했습니다. | `Retry-After` 헤더에 지정된 시간(1초) 동안 기다린 후 재시도하세요. |
| `429`, 본문 `max usage reached` | 프로젝트의 크레딧이 소진되었습니다. | 크레딧을 추가하거나 요금제를 업그레이드하세요. `Retry-After`이 없으며 조치하기 전에는 재시도해도 실패합니다. |
| `429`, `error.type` `rate_limit_error` | 프로젝트에서 이미 약 3개의 Lana 요청이 실행 중입니다. | `Retry-After` 헤더에 지정된 시간(5초) 동안 기다린 후 재시도하세요. |
| `503` | Lana가 처리 용량에 도달했거나 다시 시작 중입니다. | `Retry-After` 헤더에 지정된 시간(처리 용량 도달 시 5초, 다시 시작 중에는 30초) 동안 기다린 후 재시도하세요. |
| `400`, `error.type` `context_overflow` | 대화가 컨텍스트 창에 들어가지 않습니다. | 오래된 메시지를 제거하거나 질문의 범위를 좁히세요. |
| `529`, `error.type` `overloaded_error` | 모델이 과부하 상태입니다. `529`은 Anthropic이 이 상황에 사용하는 상태입니다. 일부 HTTP 클라이언트는 이를 인식하지 못하므로 `503`처럼 처리하세요. | 지수 백오프로 재시도하세요. |
| `500`, `502`, `504` | 첫 출력 전에 `api_error`, `tool_error` 또는 `timeout_error`으로 턴이 실패했습니다. | [오류 유형](#오류-유형)에 따라 처리하세요. |

처음 두 `429`은 요금제에서 발생하며 응답 본문에 어느 제한에 도달했는지 표시됩니다. 세 번째는 Lana에서 발생하며 JSON 본문이 있습니다.

`429` 또는 `503`이 `Retry-After` 헤더 없이 도착하면 몇 초 기다린 후 재시도하세요.

Lana 자체 오류(잘못된 본문 또는 `context_overflow`에 대한 `400`, `rate_limit_error`이 포함된 `429`, `500`, `502`, `503`, `504` 및 `529`)에는 JSON 본문이 있습니다. Gatekeeper 오류(`401`, `403`, 본문이 너무 큰 경우의 `400` 및 요금제의 `429`)는 일반 텍스트입니다. `message`이 아니라 `error.type`을 기준으로 분기하세요.

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

### 스트림 시작 후

상태가 이미 `200`이므로 실패하면 최종 `error` 이벤트로 스트림이 종료되거나 `stop_reason: "error"`이 포함된 `message_end`으로 종료됩니다. 이 `message_end`에는 `error` 객체가 없습니다. `api_error`처럼 처리하세요. 그전에 수신된 답변 텍스트는 일부에 불과합니다. 불완전한 것으로 표시하거나 폐기하세요.

### 스트리밍을 사용하지 않는 경우

`"stream": false`을 사용하면 실패한 턴은 다음 중 하나를 반환합니다.

* 조회를 포함해 턴에서 콘텐츠가 생성된 경우 `stop_reason: "error"`과 `error` 객체가 포함된 `200`을 반환합니다. 항상 `stop_reason`을 확인하세요.
* 턴에서 아무것도 생성되지 않은 경우 JSON 오류 본문을 반환합니다. 상태는 `error.type`과 일치합니다. `context_overflow`에는 `400`, `api_error`에는 `500`, `tool_error`에는 `502`, `timeout_error`에는 `504`, `overloaded_error`에는 `529`입니다. 마지막 상태는 Anthropic이 모델 과부하에 사용하는 상태이며 일부 HTTP 클라이언트는 이를 인식하지 못하므로 `503`처럼 처리하세요. 이러한 요청에는 요금이 부과되지 않습니다. [오류 유형](#오류-유형)에 따라 처리하세요.

### 오류 유형

| `error.type` | 의미 | 조치 |
| - | - | - |
| `invalid_request_error` | 요청이 잘못되었습니다. | 요청을 수정하세요. |
| `context_overflow` | 대화와 조회 결과가 컨텍스트 창에 들어가지 않습니다. | 오래된 메시지를 제거하거나 질문의 범위를 좁히세요. |
| `overloaded_error` | 모델이 과부하 상태입니다. | 지수 백오프로 재시도하세요. |
| `timeout_error` | 턴 시간이 초과되었습니다. | 질문의 범위를 좁히거나 `lana-fast`을 사용하세요. |
| `tool_error` | Lana가 의존하는 조회 서비스가 실패했습니다. | 백오프를 적용해 재시도하세요. |
| `rate_limit_error` | 프로젝트에서 약 3개의 요청이 실행 중입니다. | `Retry-After` 헤더에 지정된 시간이 지난 후 재시도하세요. |
| `api_error` | Helius 측에서 Lana가 실패했거나 처리 용량에 도달했습니다. | 백오프를 적용해 재시도하세요. |

다른 모든 유형은 `api_error`처럼 처리하세요.

## 제한

| 제한 | 값 |
| - | - |
| `max_tokens` | 1\~8,192(기본값 8,192) |
| `system` | 최대 10,000자 |
| `extensions.attachments` | 최대 8개 이미지 |
| 요청 본문 | 10MB |
| 컨텍스트 창 | 200,000개 토큰. 이 중 약 80%(`max_tokens` 제외)가 대화 및 조회 결과에 사용됩니다. |
| 턴 길이 | 5분 |
| 속도 제한 | 요금제의 DAS 및 Enhanced API 속도 제한입니다. [속도 제한](https://www.helius.dev/docs/ko/billing/rate-limits.md#lana-api)을 참조하세요. |
| 동시 요청 | 프로젝트당 약 3개입니다. 추가 요청은 하나가 완료될 때까지 `429`을 받을 수 있습니다. |

턴이 5분에 가까워지면 Lana는 조회를 중단하고 확보한 정보로 답변합니다. 긴 턴은 일반적으로 시간 초과가 아니라 누락된 내용을 설명하는 부분 답변으로 종료됩니다.

스트리밍할 때는 HTTP 클라이언트의 읽기 타임아웃을 30초 이상으로 설정하세요. 첫 바이트가 도착하기까지 최대 10초가 걸릴 수 있으며 이후 10초마다 `ping`이 도착하므로 훨씬 긴 간격이 발생하면 연결이 끊긴 것입니다. `httpx`과 같은 5초 기본값은 너무 짧습니다. 스트리밍하지 않으면 턴이 끝날 때까지 아무것도 도착하지 않으므로 읽기 타임아웃을 5분 이상으로 설정하세요.

연결을 끊으면 Lana가 턴을 중지합니다. 스트림이 이미 시작된 요청에는 여전히 요금이 부과됩니다.

Lana가 처리 용량에 도달하면 새 요청은 스트리밍이 시작되기 전에 `503`을 받습니다. 요금은 부과되지 않습니다. `Retry-After` 헤더에 지정된 시간이 지난 후 재시도하세요.

## 요금

각 요청에는 모델에 따라 고정 요금이 부과됩니다.

| 모델 | 요청당 크레딧 |
| - | - |
| `lana-thinking` | **10,000** |
| `lana-fast` | **2,000** |

스트리밍 및 비스트리밍 요청의 요금은 같으며 모든 유료 요금제(Developer 이상)에 동일하게 적용됩니다. Free 요금제에서는 Lana를 사용할 수 없습니다.

요금제의 크레딧이 사용됩니다. [크레딧](https://www.helius.dev/docs/ko/billing/credits.md#lana-api-크레딧)을 참조하세요.

### 요금이 부과되는 항목

턴의 종료 방식이나 스트리밍 여부와 관계없이 HTTP `200`을 받는 모든 요청에 요금이 부과됩니다. 응답 시작 전에 실패한 요청은 다른 상태를 받으며 무료입니다.

* `error` 이벤트로 실패한 스트리밍 턴이나 시작 후 연결을 끊은 턴에는 요금이 부과됩니다. 상태가 이미 `200`이기 때문입니다.
* 턴 시작 전에 거부된 요청(`400`, `401`, `403`, `429`, `503`)은 무료입니다.
* 스트리밍 여부와 관계없이 응답 시작 전에 실패한 턴(`400`, `5xx`)은 무료입니다.

## 추가 예시

### 어조 및 사용자 지갑 설정

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

### 지갑의 전체 기록 스캔

```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 컴포넌트, 후속 질문 및 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
    }
  }'
```

## 다음 단계

> [card] [API Reference](https://www.helius.dev/docs/ko/api-reference/lana/messages.md)
>
> 플레이그라운드가 포함된 요청 및 응답 스키마입니다.

> [card] [Rate Limits](https://www.helius.dev/docs/ko/billing/rate-limits.md#lana-api)
>
> Lana의 요금제별 속도 제한입니다.

> [card] [Credits](https://www.helius.dev/docs/ko/billing/credits.md#lana-api-크레딧)
>
> Lana 요청에서 요금제의 크레딧을 사용하는 방식입니다.

> [card] [Contact Support](https://www.helius.dev/docs/ko/support/contact-support)
>
> Discord, 채팅 또는 이메일을 통해 도움을 받으세요.


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