첫 거래

이 가이드는 저장소를 새로 클론한 시점부터 Agent를 통해 첫 소액 거래를 실행하는 시점까지를 안내합니다. 실제 자금을 운용하기 전에 반드시 알아야 할 모든 안전 설정을 다루며, 각 설정이 존재하는 이유도 함께 설명합니다.

빠르게 훑어보고 싶다면, 설치 → 로그인 → 하드 제약 설정 → minara doctor → 채팅 및 거래 순서로 진행하세요. 이 페이지의 나머지 내용은 각 단계가 왜 중요한지를 설명합니다.

이 문서는 터미널 환경의 안내입니다. 모든 단계를 대화형 minara 채팅 세션(REPL)에서 직접 수행합니다. 대시보드를 선호한다면, 에이전트와 채팅 문서에서 동일한 첫 거래를 웹 UI로 진행하는 방법을 확인할 수 있습니다.

0. 사전 요구사항

Node.js ≥ 24.
Minara 계정 (디바이스 플로우 또는 API 키로 로그인).
LLM 공급자 하나 이상 설정 (Anthropic API, Claude OAuth, OpenAI, 또는 OpenRouter).
손실을 감수할 수 있는 소액 자금. Agent는 안전하게 설계되었지만, 연결된 모든 시스템은 예상치 못한 방식으로 오류가 발생할 수 있습니다. 첫 거래는 실제 운용이 아닌 훈련 과정으로 여기세요.

클론 및 설치 단계를 아직 완료하지 않았다면, 설치 문서를 먼저 확인하세요.

1. 설정 마법사 실행

minara setup

마법사는 사용 가능한 공급자를 자동으로 감지하고, 각 공급자의 로그인을 안내하며, 기존 ~/.minara/ 디렉터리에서 가져올 수 있는 상태를 탐색합니다. 이후 워크스페이스(SOUL.md, AGENTS.md, USER.md)를 생성하고, doctor 명령을 실행한 뒤 치트 시트를 출력합니다.

마법사가 실제로 수행하는 작업은 다음과 같습니다.

~/.minara/(또는 설정된 경우 $MINARA_DATA_DIR)에 sandbox/files/, workspace/, logs/ 디렉터리와 빈 minara.db를 생성합니다.
활성 모델을 ~/.minara/settings.json의 model 섹션에 기록하고, 메시징/공급자 자격 증명을 ~/.minara/credentials.json에 저장합니다.
암호화된 인증 프로필을 ~/.minara/auth/ 아래에 저장합니다.
마지막에 전체 doctor 검사를 실행하여, 첫 LLM 호출 시점이 아닌 부팅 시점에 회귀 오류가 바로 드러나도록 합니다.

환경 변수에 이미 자격 증명이 있는 경우, 마법사는 해당 정보를 자동으로 인식하고 해당 로그인 단계를 건너뜁니다.

2. 설정 확인

minara doctor

정상적인 출력은 모든 항목이 초록색으로 표시됩니다.

✓ data dir            /Users/you/.minara
✓ sqlite              minara.db  (WAL)
✓ llm provider        anthropic (api_key)
✓ minara auth         device flow
✓ tool registry       62 tools registered
✓ workspace           SOUL.md, AGENTS.md, USER.md
✓ env                 ANTHROPIC_API_KEY, MINARA_API_KEY set

노란색이나 빨간색 항목은 모두 실질적 경계입니다. doctor 결과가 모두 정상이 될 때까지 다음 단계로 진행하지 마세요. 자주 발생하는 문제는 다음과 같습니다.

minara auth (not configured): minara auth login minara를 실행하고 브라우저에서 디바이스 플로우를 완료하세요.
llm provider (no credentials): 마법사에서 공급자를 선택하거나 환경 변수를 직접 내보내세요.
tool registry (0 tools): 일반적으로 어떤 팩토리(함수)가 필요로 하는 자격 증명이 환경에 없는 경우 발생합니다. 로그의 누락된 환경 변수 경고를 확인하세요.

3. 첫 턴 이전에 하드 제약 설정

이 단계는 페이지에서 가장 중요한 단계입니다. Agent는 LLM의 동작과 무관하게 권한 등급 훅 체인이 강제하는 세 가지 하드 코딩된 상한선을 준수합니다.

# 건당 달러 상한. Agent는 이 금액보다 큰 단일 거래를 실행할 수 없습니다.
minara config set safety.maxTransactionAmount 25

# 일일 총계 달러 상한. 원자적 확인 및 차감 방식이므로
# 동시에 진행 중인 거래가 경쟁적으로 이 한도를 초과할 수 없습니다.
minara config set safety.dailySpendCap 100

# 차단 목록. Agent가 절대 접근하지 않기를 원하는 항목을 추가하세요.
# 정규 주소 레이어가 알려진 스캠을 이미 감지하지만,
# 이 목록은 사용자가 직접 제어하는 레이어입니다.
minara config set safety.blockedTokens '["SAFEMARS","SQUID"]'

첫 거래에서는 실수가 발생하더라도 회복 가능한 수준으로 상한을 설정하세요. 건당 $25, 일일 $100으로 설정하면 최악의 경우에도 손실이 $100을 넘지 않으며, 이는 수업료 수준으로 처리할 수 있습니다.

설정값이 적용되었는지 확인합니다.

minara config list

안전 레이어가 제공하는 모든 설정 항목은 자금 안전 스택 문서에서 확인할 수 있습니다.

4. 비상 정지 워크플로 활성화

세션 전반에 걸쳐 /kill 명령을 항상 한 번의 입력으로 사용할 수 있도록 준비하세요. 이 명령은 BeforeToolCallHook 체인이 모든 도구 호출 시 확인하는 플래그를 설정하므로, 활성화하는 즉시 2등급 이상의 모든 작업이 중단됩니다.

이 단계에서 별도로 해야 할 작업은 없습니다. 명령이 존재한다는 사실을 기억해 두세요. 첫 턴에서 연습해 보세요.

> /kill
✓ emergency stop ACTIVE — all tier 2+ tools blocked
> /unkill
✓ emergency stop cleared

5. REPL 진입

minara

ID 배너, 치트 시트, 그리고 깜박이는 프롬프트가 표시됩니다. Agent가 정상적으로 동작하는지 확인하기 위해 읽기 전용 질문으로 시작하세요.

> what's BTC trading at?

Agent는 market.spot 스킬을 활성화하고, get_price를 호출하여 가격을 반환해야 합니다. 전체 체인을 보고 싶다면 /logs 20으로 로그의 도구 호출을 확인하세요.

자신감을 쌓기 위해 읽기 전용 쿼리를 몇 가지 더 시도해 보세요.

> show my portfolio
> trending tokens on solana
> what's my daily spend so far

이 쿼리들은 모두 1등급에 머무르며 자금을 이동시키지 않습니다.

6. 소액 스왑 준비

이제 설정한 상한에 맞는 가장 소액의 거래를 요청하세요. 건당 $25 상한의 경우 다음과 같이 입력합니다.

> swap $10 of USDC into ETH on base

예상되는 흐름은 다음과 같습니다.

Agent가 activate_skills를 통해 market.spot 스킬을 활성화합니다.
token_safety_check를 호출하여 Base 네트워크의 USDC와 ETH를 정규 주소로 확인합니다.
position_sizer를 호출하여 $10 크기를 계산하고, clipped: false(상한 미초과)를 반환합니다.
현재 포트폴리오를 기준으로 exposure_limit_check를 호출합니다.
스왑의 예상 결과와 가격 영향을 구하기 위해 시뮬레이션을 호출합니다.
시뮬레이션 결과를 가격 영향과 함께 제시하고 확인을 요청합니다.
yes를 입력한 후에만 실제 swap 도구를 호출합니다.

확인 단계는 실제로 동작합니다. requires_user_confirmation이 설정된 모든 3등급 도구는 사용자가 확인하기 전까지 L3 위험 게이트에서 차단됩니다. 다음 턴의 시스템 프롬프트에서 대기 중인 확인 블록을 확인할 수 있습니다.

<pending_confirmation>
  skill: market.spot
  action: swap
  summary: "$10 USDC → ETH on base, est output 0.0028 ETH, price impact 0.3%"
</pending_confirmation>

소액 거래의 슬리피지 임계값(기본값 2%)을 가격 영향이 초과하면, 확인 단계 이전에 스왑이 거부됩니다. 이것은 슬리피지 보호 기능이 정상적으로 작동하는 것입니다.

7. 확인 후 감사 로그 확인

yes를 입력하세요. Agent가 스왑을 실행하고 Minara 거래 ID와 함께 결과를 보고합니다. 이 턴의 감사 행을 즉시 확인하세요.

sqlite3 ~/.minara/minara.db \
  "SELECT tool_name, blocked, substr(result_json, 1, 80)
     FROM audit
    WHERE session_id = (SELECT session_id FROM sessions ORDER BY created_at DESC LIMIT 1)
    ORDER BY created_at DESC LIMIT 20;"

swap 행으로 끝나는 깔끔한 도구 호출 체인이 표시되어야 하며, blocked = 0이어야 합니다. 그 앞의 각 호출은 스왑 이전에 실행된 검사, 즉 토큰 안전 검사, 규모 산정, 노출 한도 검사, 슬리피지 시뮬레이션입니다.

이것이 향후 예상치 못한 동작을 조사할 때마다 사용하게 될 감사 추적 기록입니다. 미래 턴에서 문제가 발생하면, 이 쿼리를 가장 먼저 실행하세요.

8. 검토 및 반복

첫 스왑이 완료된 후 시도해 볼 후속 작업입니다.

/status: 비상 정지 상태, 오늘의 지출, 등록된 도구 수, 활성 스킬 세션을 표시합니다. 빠른 현황 확인 대시보드로 활용하세요.
/budget: 오늘의 LLM 지출을 작업별로 분류하여 표시합니다. 단일 세션의 실제 비용을 파악하는 데 유용합니다.
/prompt: 현재 시스템 프롬프트 블록을 출력합니다. 캐시 가능 영역과 동적 영역의 경계, 활성 스킬 프롬프트 조각을 확인하세요. LLM이 무엇을 보는지 이해하는 데 유용합니다.
/history 20: 역할 및 내용 미리보기와 함께 최근 20개의 히스토리 항목을 표시합니다.
/compress: 세션이 길어질 경우 실행하세요. Haiku를 통해 오래된 턴을 요약하여 프롬프트 비용을 절감합니다.

첫날 하지 말아야 할 것

Autopilot을 시작하지 마세요. Autopilot은 LLM이 사람의 개입 없이 의사 결정을 내리는 단계를 추가합니다. 설정을 신뢰할 수 있게 된 후에는 유용한 도구이지만, "Agent가 제대로 작동하는지 검증하는" 단계에는 적합하지 않습니다.
워크플로에서 비상 정지를 비활성화하지 마세요. 비상 정지를 비활성화하는 것이 올바른 선택인 경우는 없습니다.
일일 상한을 감내할 수 있는 수준 이상으로 높이지 마세요. 상한의 목적은 실수의 피해 범위를 제한하는 것입니다. "오늘 거래 총액이 얼마일 것 같다"가 아니라, "버그로 인해 얼마까지 잃을 수 있는가"를 기준으로 설정하세요.
감사 로그를 공개적으로 공유하지 마세요. 리댁터가 알려진 민감한 키를 마스킹 처리하지만, 거래 내역과 타임스탬프만으로도 일부 패턴의 익명성이 해제될 수 있습니다. 비공개 운영 데이터로 취급하세요.
업그레이드 후 doctor 실행을 건너뛰지 마세요. 스키마 마이그레이션은 멱등하게 처리되지만, 새로운 툴 세트나 환경 변수가 포함된 버전은 기존 설정과 충돌할 수 있습니다. minara doctor는 이를 몇 초 만에 감지합니다.

다음 단계

자금 안전 스택 문서를 읽고 모든 거래가 거치는 6단계 안전 경로를 이해하세요.
샌드박스 및 권한 문서를 읽고 훅 체인 동작을 이해하세요.
관찰 가능성 문서를 읽고 중요한 감사 쿼리를 익히세요.
자동화할 준비가 되면, 워크플로와 Autopilot 문서를 읽으세요.
터미널보다 대시보드를 선호한다면, 에이전트와 채팅 문서에서 웹 UI로 동일한 과정을 진행하는 방법을 확인하세요.

첫 거래는 지루하게 느껴져야 합니다. 그것이 바로 이 설계의 목적입니다. 만약 흥미진진하게 느껴졌다면, 안전 레이어에 버그가 있는 것이므로 알려주시기 바랍니다.

목차