weltiq API · MCP 사용 매뉴얼

버전 2026-09-06 · 기준 URL https://weltiq.ai · 코드가 진실: weltiq/api/server.py(REST), weltiq/api/mcp_server.py(MCP). 요약 레퍼런스는 /docs, OpenAPI 탐색기는 /api-docs.

weltiq는 하나의 주문 인터페이스입니다. 지금은 실시간 시세 위에서 거래소 실제 수수료·슬리피지로 체결하는 모의 엔진이 돌고, 내 거래소 키(커넥터)를 붙이면 같은 요청이 같은 정책 검사를 달고 거래소 데모/실주문으로 갑니다. 봇·스크립트는 REST, 내 Claude는 MCP로 씁니다.

목차

1. 5분 빠른 시작
2. API 키 발급
3. 인증 · 스코프 · 한도 · 크레딧
4. REST 튜토리얼
5. MCP 튜토리얼 — 내 Claude 연결
6. 예제 코드 (Python · JavaScript · curl)
7. 가능한 것 — 기능 목록
8. 한계점 · 설계상 없는 것
9. 오류 코드
10. FAQ

1. 5분 빠른 시작

1. 가입 — weltiq.ai/login에서 이메일+비밀번호(8자 이상) 또는 Google로 가입합니다. 무료이며 크레딧 100이 지급됩니다. 이메일 가입은 확인 메일의 링크를 24시간 안에 열어야 커넥터 등록 같은 소유권 전제 기능이 열립니다(Google 가입은 즉시 확인).
2. API 키 발급 — 로그인 후 설정 → API 키(/settings/keys). 라벨과 스코프를 고르고 발급하면 wq_… 비밀키가 한 번만 표시됩니다. 복사해 안전한 곳에 보관하세요.
3. 첫 호출

export WELTIQ_API_KEY=wq_...
curl -s https://weltiq.ai/v1/markets -H "Authorization: Bearer $WELTIQ_API_KEY" -H "User-Agent: my-bot/1.0"

{"markets": [{"venue": "binance-spot", "status": "live", "symbols": 5, "last_bar": "2026-09-05T18:18:00+00:00", "age_seconds": 39.1},
             {"venue": "binance-usdm", "status": "live", "symbols": 2, "last_bar": "2026-09-05T18:17:00+00:00", "age_seconds": 34.2}, "…"]}

4. 첫 백테스트 — 카탈로그 템플릿을 최근 봉으로 리플레이합니다. 모의 엔진과 같은 체결 규칙입니다.

curl -s -X POST https://weltiq.ai/v1/backtest -H "Authorization: Bearer $WELTIQ_API_KEY" -H "Content-Type: application/json" \
  -d '{"template_id":"TPL-002","venue":"binance-spot","symbol":"BTCUSDT","tf":"1m","hours":24}'

{"run_id": "bt_3aacbdfc14ed8243", "n_bars": 1439, "n_fills": 1, "pnl": "0", "fees": "0.79646004", "n_trades": 0,
 "deployment_id": "dep_ba_b4d525458e44d62e", "warning": null, "data_mode": "idealized", "lookahead": null}

5. Claude에 연결 — 터미널에서 한 줄:

claude mcp add --transport http weltiq https://weltiq.ai/mcp --header "Authorization: Bearer $WELTIQ_API_KEY"

이제 Claude에게 "BTCUSDT 최근 24시간 봉으로 TPL-002 백테스트해 줘"라고 말하면 됩니다.

2. API 키 발급

2.1 절차

• 키는 브라우저 세션에서만 만들 수 있습니다. 키로 키를 만들 수 없습니다 (GET/POST/DELETE /v1/keys는 세션 전용).
• 비밀키는 서버에 해시로만 저장됩니다. 잃어버리면 새로 발급하고 옛 키는 폐기하세요.
• 폐기는 즉시 효력이 있고 되돌릴 수 없습니다. 이후 호출은 401 invalid token.
• 발급·폐기는 위임 저널(GET /v1/journal, kind api_key_issued)에 남습니다.

2.2 키를 몇 개 만들까

세션(브라우저)은 항상 세 스코프를 다 가집니다. API 키는 발급 시 준 것만 가집니다.

2.3 키 API (세션 전용)

GET    /v1/keys                → {"keys":[{"key_id":"wqk_a8572d1484b2","label":"docs-sample","scopes":[…],"created_at":"…","revoked_at":null}]}
POST   /v1/keys {label, scopes[]} → {"key_id":"wqk_…","secret":"wq_…","scopes":[…],"label":"…"}   # secret은 이 응답에만
DELETE /v1/keys/{key_id}

3. 인증 · 스코프 · 한도 · 크레딧

3.1 인증

• 모든 /v1/* 호출: Authorization: Bearer wq_…
• 실제 User-Agent를 보내세요. 기본 Python/urllib 에이전트는 엣지에서 차단됩니다 (User-Agent: my-bot/1.0처럼 아무 이름이면 됩니다).
• JSON 입출력. 수량·가격·금액은 문자열로 보내고 받습니다 (부동소수 오차 방지).

3.2 스코프

3.3 요율 한도 (분당, 사용자당)

초과 시 429 rate_limited. 다음 분에 재시도하세요.

3.4 크레딧

• 가입 시 100. 잠정 요율: LLM 토큰 1,000 = 1 · 백테스트 봉 10,000 = 1 · API 주문 100 = 1 (실측 후 확정, 소급 없음).
• 잔액이 음수가 되면 유료 연산은 402 insufficient_credits. 잔액·원장은 GET /v1/billing, 사용량 집계는 GET /v1/usage.
• 백테스트 시도는 전략 계보(lineage)별로 예산이 잡혀 있어 파라미터 스윕으로 승격을 살 수 없습니다.

GET /v1/billing → {"balance":"99.836100","plan":"free",
  "plan_features":{"paper_slots":1,"custom_strategy":false,"custom_backtest":false,"pro_templates":false,"pro_signals":false,"live_connector":false},
  "ledger":[{"delta":"-0.010000","reason":"usage_api","meta":{"kind":"api_order","quantity":"1"}}, {"delta":"-0.143900","reason":"usage_backtest","meta":{"kind":"backtest","quantity":"1439"}}, {"delta":"100","reason":"signup_bonus"}]}

4. REST 튜토리얼

아래 응답은 2026-09-06 실서비스에서 받은 것을 줄인 것입니다.

4.1 시장 데이터

거래소와 신선도

GET /v1/markets

status: live(마지막 1분봉이 3분 이내) · stale(주말·휴장·수집 지연) · off(미지원). 현재 venue: binance-spot, binance-usdm, bybit-spot, bybit-linear, us-equity, krx (cme는 off).

확정 봉

GET /v1/bars?venue=binance-spot&symbol=BTCUSDT&tf=1m&hours=1
→ {"venue":"binance-spot","symbol":"BTCUSDT","tf":"1m","bars":[{"t":"2026-09-05T17:19:00+00:00","o":"80017.84","h":"80054","l":"80017.83","c":"80054","v":"6.09837"}, …]}

tf = 1m|1h|1d, hours ≤ 720, 호출당 최대 5,000봉. 마감된 봉만 옵니다 (진행 중인 봉 없음 — 엔진도 마감 봉만 봅니다).

워치리스트·시그널

GET  /v1/watchlist                        # 기법·무효화·48h 만료가 붙은 시그널 목록
POST /v1/signal-package {"venue":"binance-spot","symbol":"BTCUSDT"}   # 방향 편향·기법·후보 템플릿 (워치리스트에 없는 심볼은 404)
GET  /v1/briefing                         # 일일 브리핑

워치리스트 새로고침(POST /v1/watchlist/refresh)은 브라우저 세션에서만 됩니다 (6시간마다 자동 수집).

4.2 템플릿 · 인스턴스 · 백테스트

GET /v1/templates?q=breakout
→ {"templates":[{"template_id":"TPL-001","name":"52주 신고가 돌파","category_name":"주식 추세추종·돌파","targets":"한국·미국·홍콩 주식",
   "signal_summary":"RS·거래량 상위의 52주 고점 돌파","exit_summary":"추세 이탈·ATR 손절·수일~수주",
   "tags":{"technique":"Breakout","span":"Swing","risk":"Standard"},"tier":"pro","dsl_status":"ready","forecast_load":"low","has_doc":true}, …]}

GET /v1/templates/TPL-002
→ {"template_id":"TPL-002","name":"20일 고가 돌파","tier":"free","dsl_status":"ready",
   "fit":"유동성 높은 주식·BTC의 단기 모멘텀 국면. 일봉·1h 슬롯.","rules":"entry: 20-bar high breakout → exit: stop 0.02 · target 0.04"}

공개 카드에는 규칙 한 줄 요약만 있습니다. 규칙 문서·파라미터·DSL 자체는 서버 밖으로 나가지 않습니다.

내 인스턴스 만들기 → doc_hash

POST /v1/templates/TPL-002/instantiate
→ {"template_id":"TPL-002","doc_hash":"22c512f3…b8e3","lineage_id":"ln_0f9866e198425121","strategy":{"name":"20일 고가 돌파","line":"entry: 20-bar high breakout → exit: stop 0.02 · target 0.04"}}

doc_hash가 이후 백테스트·슬롯의 식별자입니다. Pro 템플릿은 Pro 플랜에서만 인스턴스화됩니다.

백테스트

POST /v1/backtest {"doc_hash":"22c512f3…","venue":"binance-spot","symbol":"BTCUSDT","tf":"1m","hours":24}
→ {"run_id":"bt_3aacbdfc14ed8243","n_bars":1439,"n_fills":1,"pnl":"0","fees":"0.79646004","n_trades":0,"data_mode":"idealized","warning":null}

• template_id 또는 doc_hash 중 하나. hours 상한은 tf별: 1m 720 · 1h 8,760 · 1d 43,800.
• 체결 규칙은 모의 엔진과 동일(보수적 봉 판정). compare_lookahead: true로 미래 참조 대조를 받을 수 있습니다.
• GET /v1/backtests?symbol=(기록) · GET /v1/instances(내 인스턴스).

엔지니어 AI(run-backtest)

POST /v1/ai/engineer {"template_id":"TPL-002","symbol":"BTCUSDT","messages":[{"role":"user","content":"손절을 1.5%로 줄이면?"}]}
→ {"reply":"…","changes":[{"path":"exit.stop","from":"0.02","to":"0.015"}],"doc_hash":"…"}
POST /v1/ai/engineer/variants   # 근접 변형 2~3안 동시 백테스트 (Pro)
POST /v1/ai/formalize {"idea":"BTC가 20일 고점을 돌파하면 사고 5% 손절","symbols":["BTCUSDT"]}   # 자연어 → 인스턴스 (Pro)

4.3 상주 슬롯 (24시간 전략 실행)

POST /v1/slots {"doc_hash":"22c512f3…","symbol":"BTCUSDT","tf":"1m","stop_max_loss":"50","stop_after_hours":2}
→ {"deployment_id":"dep_pa_8ffe4bf32eb06173","sleeve_id":"sl_pa_…","portfolio_id":"pf_u_…","mode":"paper","stop":{"max_loss":"50","until":"2026-09-05T20:18:42+00:00"}}

GET /v1/slots
→ {"slots":[{"deployment_id":"dep_pa_8ffe4bf32eb06173","status":"running","symbol":"BTCUSDT","tf":"1m",
   "stop":{"until":"…","max_loss":"50"},"stopped_reason":null,
   "live":{"at":"2026-09-05T18:18:47+00:00","attached":true,"last_bar":null,"position":null,"daily_pnl":"0"}}]}

DELETE /v1/slots/dep_pa_8ffe4bf32eb06173 → {"deployment_id":"…","status":"stopped"}   # 포지션 청산

• 중지 조건은 필수: 손실 한도(quote 통화)와 1~720시간. 한도에 닿거나 시간이 지나면 엔진이 청산하고 stopped_reason에 남깁니다.
• 무료 1개 · Pro 3개 (slot_limit).
• 슬롯은 해당 venue를 담당하는 집행 셀(코인은 도쿄)에 10~15초 안에 부착됩니다 (live.attached).
• 게이트형 템플릿은 signal_kind로 외부 시그널을 연결합니다.

4.4 봉투 → 1회성 주문 → 청산 (재량 주문)

봉투(브라우저에서 생성). 재량 주문이 할 수 있는 범위를 사람이 미리 승인합니다. Paper › Order 화면 또는 세션으로:

POST /v1/envelopes {"symbols":["BTCUSDT"],"max_order_notional":"500","max_daily_notional":"2000","days":7}
→ {"envelope_id":"ev_27cab40edb97253a","valid_until":"2026-09-12T18:18:58+00:00"}
GET /v1/envelopes → {"envelopes":[{"envelope_id":"ev_…","symbols":["BTCUSDT"],"max_order_notional":"500","max_daily_notional":"2000","status":"active", …}],"daily_notional_used":"0"}

API 키·MCP로는 봉투를 만들 수 없습니다 (403). 대리인이 자기 한도를 넓힐 수 없다는 규칙입니다.

진입 주문. 가설(thesis.why)과 처분 조건(px_below·px_above)이 필수입니다.

POST /v1/orders/oneoff
{"venue":"binance-spot","symbol":"BTCUSDT","side":"buy","type":"market","qty":"0.001",
 "thesis":{"why":"4시간 지지선 유지 — 소량 진입"},"invalidation":{"px_below":"60000","px_above":"120000"}}
→ {"queue_id":"dq_0aec82394e071eb0","status":"queued","est_notional":"79.97","closing":false,"target":"paper"}

가설이 없으면:

422 {"detail":{"code":"thesis_required","detail":"thesis 없이 포지션은 태어나지 않는다 (불변 12)"}}

결과 확인 (보통 1~2초, binance-usdm은 최대 30초).

GET /v1/orders/oneoff
→ {"orders":[{"queue_id":"dq_0aec82394e071eb0","venue":"binance-spot","symbol":"BTCUSDT","side":"buy","order_type":"market","qty":"0.001",
   "status":"filled","result":{"fills":[{"px":"80019.836182500","fee":"0.08001984","qty":"0.001"}],"state":"filled","closed":false,"intent_id":"dq_0aec82394e071eb0_i"},
   "created_at":"…","processed_at":"…","target":"paper","auto":false}]}

status: queued → filled | rejected | expired. 거절이면 result.code에 이유가 있습니다.

처분 규칙. px_below/px_above 중 하나에 닿으면 엔진이 자동 청산합니다(큐에 auto: true로 남음). 롱은 px_below가 손절, px_above가 목표가입니다. 조건 없이 들어갈 수는 없고, 들어간 뒤에는 직접 청산할 때까지 보유합니다.

청산. 보유 포지션의 반대 방향 주문은 청산으로 처리됩니다: reduce-only, 보유 수량까지, 조건 불필요, 봉투 명목에 계상하지 않음.

POST /v1/orders/oneoff {"venue":"binance-spot","symbol":"BTCUSDT","side":"sell","type":"market","qty":"0.001","thesis":{"why":"청산"}}
→ {"queue_id":"dq_9ec99a661531472d","status":"queued","est_notional":"0","closing":true,"target":"paper"}

지정가. "type":"limit","price":"79000". 대기 지정가는 미체결 목록(GET /v1/orders)에 상태 머신과 함께 보이며, DELETE /v1/orders/{intent_id}로 취소합니다. 확정 전까지 잔량은 위험으로 계상됩니다.

정책 게이트. 엔진이 검사하는 것: 봉투(심볼·주문당·일 명목), 방향권(한 심볼에 반대 방향 중첩 금지), 자기체결(STP), 데이터 신선도, 포트폴리오 예산. 거절 코드는 9장.

4.5 체결 · 원장 · 수수료 비교

GET /v1/fills?mode=paper
→ {"fills":[{"intent_id":"dq_9ec99a661531472d_i","qty":0.001,"px":80003.8138175,"fee":0.08000381,"fee_ccy":"USDT","liquidity":"taker","at":"…","symbol":"BTCUSDT","side":"sell","mode":"paper"}]}

GET /v1/account
→ {"accounts":[{"account_id":"acc_u_…","venue":"binance-spot","mode":"paper","base_ccy":"USDT"}],
   "balances":[{"book":"cash","ccy":"USDT","amt":-0.17604601},{"book":"fees","ccy":"USDT","amt":0.16002365},{"book":"position_value","ccy":"USDT","amt":0.01602236}]}

복식 원장: 체결마다 cash·position_value·fees의 합이 0입니다. 위 예는 0.001 BTC 왕복 후 수수료 0.16 USDT와 가격 변동 0.016 USDT가 남은 상태입니다.

GET /v1/fees/compare?mode=paper&days=1
→ {"n_fills":2,"actual_venues":["binance-spot"],"actual_fee":"0.16002365","turnover":"160.02","fee_rate":"0.00100000","maker_share":"0",
   "venues":[{"venue":"binance-spot","class":"crypto-spot","is_actual":true,"maker_rate":"0.001","taker_rate":"0.001","fee":"0.16002365","delta":"0","if_all_maker":"0.16002365"},
             {"venue":"bybit-spot","class":"crypto-spot","same_class":true,"fee":"0.16002365","delta":"0", …}, …]}

내 체결을 다른 거래소 수수료 규칙으로 다시 계산합니다. 기본은 같은 상품군(현물끼리·무기한끼리), venues=a,b로 지정하면 다른 군도 참고치로 계산합니다. if_all_maker는 전부 메이커였을 때의 수수료입니다.

4.6 저널

GET /v1/journal?limit=2
→ {"events":[{"id":4281,"at":"…","kind":"oneoff_queued","principal":"external_client","input_origin":"user","payload":{"queue_id":"dq_…","envelope_id":"ev_…"}}, …],
   "kinds":["api_key_issued","envelope_created","oneoff_queued","slot_created","slot_stopped","template_instantiated"]}

모든 행위가 누가(사람/외부 클라이언트/에이전트)·무엇을·누구를 대신해 했는지로 남습니다. 운영자 행위는 해시체인으로 봉인됩니다.

4.7 커넥터 — 내 거래소 키로 주문

내 거래소 API 키를 등록하면 같은 주문이 거래소 데모(테스트넷) 또는 실계정으로 갑니다.

등록은 브라우저에서만 — 설정 → Connectors(/settings/connectors). 등록 시 잔고 조회로 키를 검증합니다. 거래소에서 키를 만들 때 출금·이체 권한은 끄고 거래 권한만 주세요 (권한 자동 검사는 준비 중). 키는 사용자별 봉투 암호화로 저장되며 집행 셀만 주문 시점에 복호화합니다. 거래소 쪽 키에는 IP 제한을 거는 것을 권합니다 (집행 셀 IP는 등록 화면에 표시).

GET /v1/connectors → {"connectors":[{"cred_id":"bk_ae4cab810fc9e645","broker":"bybit","mode":"paper","label":"weltiq-demo","key_hint":"R0VT","status":"active","verify_note":"Bybit linear demo ok · USDT balance 50000 …"}]}

주문에서 실행 대상 고르기 — target에 cred_id:

POST /v1/orders/oneoff {"venue":"bybit-linear","symbol":"BTCUSDT","side":"buy","type":"market","qty":"0.002",
  "thesis":{"why":"데모에서 체결 비교"},"invalidation":{"px_below":"60000"},"target":"bk_ae4cab810fc9e645"}

• venue는 커넥터 브로커와 맞아야 합니다 (binance → binance-usdm, bybit → bybit-linear). 아니면 connector_venue_mismatch.
• 페이퍼(target: "paper")와 커넥터 주문을 나란히 내면 체결 차이를 비교할 수 있습니다. 실측: 바이낸스 테스트넷 중앙값 0.6bp, 바이비트 데모 0.04bp 차이 (reports/dualrun).
• 실거래 키는 추가로 thesis.live_ack: "I confirm real funds"가 필요하며, 승격 사다리 뒤에 있어 현재는 열려 있지 않습니다.

4.8 이메일 알림

주요 이벤트는 계정 이메일로 갑니다: 재량 주문 체결·거절, 무효 조건 자동 청산, 슬롯 자동 정지, 크레딧 부족, 공지, 보안(키·커넥터 변경). 받을 종류는 설정 → 알림(/settings/notifications)에서 고릅니다. 보안 알림은 끌 수 없습니다.

GET /v1/notifications → {"prefs":{"order_filled":true,"weekly_review":false,"security":true, …},"kinds":[{"kind":"order_filled","group":"trading","label":"재량 주문 체결","selectable":true}, …]}
PUT /v1/notifications {"prefs":{"order_filled":false,"weekly_review":true}}      # 세션 전용

4.9 AI 애널리스트

POST /v1/ai/analyze {"symbol":"BTCUSDT","venue":"binance-spot"}
→ {"report_id":"rp_…","stats":{"n_bars":1439,"return_pct":"0.5483","vol_of_returns_pct":"…"},"view":{"summary":"BTCUSDT는 24시간 동안 79,442~80,200 달러 범위에서 +0.55% 상승…","observations":[…],"risks":[…]}}
POST /v1/ai/chat     # 같은 근거 위 대화
POST /v1/ai/review?days=30&lang=ko   # 내 거래·계좌 정형 복기: 지표·규칙 소견·규율 상태 good/watch/alert

관찰과 리스크만 말하고 권유는 하지 않습니다. 크레딧이 차감됩니다.

5. MCP 튜토리얼 — 내 Claude 연결

원격 MCP 서버 두 개(streamable HTTP). 같은 REST 위의 얇은 어댑터라 스코프·요율·저널이 그대로 적용됩니다.

5.1 설정

Claude Code

claude mcp add --transport http weltiq https://weltiq.ai/mcp --header "Authorization: Bearer $WELTIQ_API_KEY"
claude mcp add --transport http weltiq-analyst https://weltiq.ai/mcp/analyst --header "Authorization: Bearer $WELTIQ_READONLY_KEY"

/dl/claude-code-mcp.sh로 같은 스크립트를 받을 수 있습니다.

Claude Desktop / 다른 MCP 클라이언트 — claude_desktop_config.json(또는 클라이언트의 mcpServers 설정)에:

{"mcpServers": {
  "weltiq":         {"url": "https://weltiq.ai/mcp",         "headers": {"Authorization": "Bearer wq_..."}},
  "weltiq-analyst": {"url": "https://weltiq.ai/mcp/analyst", "headers": {"Authorization": "Bearer wq_..."}}}}

/dl/claude-mcp.json에 같은 템플릿이 있습니다.

로컬 stdio(자체 호스팅·개발)

WELTIQ_API_KEY=wq_... python -m weltiq.api.mcp_server            # 실행 계통
WELTIQ_API_KEY=wq_... python -m weltiq.api.mcp_server analyst    # 정보 계통

5.2 도구 목록

weltiq (실행) — 21개

weltiq-analyst (정보) — 5개

5.3 대화 예시

아래는 실제로 어떤 도구가 불리는지 보여 줍니다. 결과 숫자는 시점에 따라 다릅니다.

예시 1 — 후보 고르기부터 백테스트까지

나: 돌파(breakout) 계열 무료 템플릿을 찾아서 BTCUSDT 1분봉 최근 48시간으로 백테스트하고 결과를 표로 정리해 줘.

Claude가 하는 일: templates(q="breakout") → 무료(tier: free, dsl_status: ready)만 고름 → 각 템플릿에 backtest(venue="binance-spot", symbol="BTCUSDT", template_id=…, tf="1m", hours=48) → pnl·fees·n_trades 표.

예시 2 — 상주 슬롯 띄우고 지켜보기

나: TPL-002를 BTCUSDT 1분봉으로 슬롯에 올려. 손실 한도 30 USDT, 6시간 뒤 자동 정지.

Claude: instantiate("TPL-002") → slot_run(symbol="BTCUSDT", doc_hash=…, tf="1m", stop_max_loss="30", stop_after_hours=6) → 잠시 후 slots로 live.attached·포지션 확인. 무료 플랜에서 두 번째 슬롯은 slot_limit으로 거절됩니다.

예시 3 — 재량 주문 (봉투는 미리 브라우저에서)

나: BTCUSDT 0.001 시장가로 사. 근거는 "4시간 지지선 유지". 손절 60,000, 목표 120,000.

Claude: envelopes로 활성 봉투 확인 → order_oneoff(venue="binance-spot", symbol="BTCUSDT", side="buy", qty="0.001", thesis_why="4시간 지지선 유지", px_below="60000", px_above="120000") → oneoff_orders로 체결 확인. 봉투가 없으면 envelope_required가 돌아오고, Claude는 봉투를 만들 수 없으니 사용자에게 화면에서 만들라고 안내해야 합니다.

예시 4 — 커넥터로 데모 주문 비교

나: 같은 주문을 내부 페이퍼와 내 바이비트 데모에 나란히 내고 체결가를 비교해 줘.

Claude: connectors → bybit paper의 cred_id → order_oneoff(venue="bybit-linear", …, target="paper")와 order_oneoff(…, target="bk_…") → oneoff_orders에서 두 체결가 차이(bp) 계산.

예시 5 — 분석 전용 Claude

나 (weltiq-analyst만 연결된 세션): 내 지난 30일 거래를 복기해 줘.

Claude: review_account(days=30, lang="ko") → 지표·규칙 소견·규율 상태. 이 세션에는 주문 도구가 아예 없습니다.

5.4 MCP에서 알아둘 것

• 도구 응답은 REST 응답 JSON 그대로입니다. 오류도 {"error": <code|status>, "detail": …} 형태로 돌아오므로 Claude가 이유를 읽고 다음 행동을 정합니다.
• weltiq-analyst에 실행 스코프가 섞인 키를 넣으면 모든 도구가 scope_mix를 돌려줍니다. read-data만 가진 키를 따로 발급하세요.
• 봉투 생성·커넥터 등록·키 발급·플랜 변경 도구는 없습니다. 사람이 화면에서 합니다.
• 주문은 5초 폴링 큐로 집행됩니다. order_oneoff 직후 oneoff_orders를 한두 번 확인하도록 Claude에게 말해 두면 좋습니다.

6. 예제 코드

6.1 Python — 템플릿 스윕 백테스트

import os, httpx

API = "https://weltiq.ai"
H = {"Authorization": f"Bearer {os.environ['WELTIQ_API_KEY']}", "User-Agent": "weltiq-example/1.0"}
c = httpx.Client(base_url=API, headers=H, timeout=120)

free = [t for t in c.get("/v1/templates").json()["templates"]
        if t["tier"] == "free" and t["dsl_status"] == "ready"]
rows = []
for t in free[:5]:                                   # 무료 플랜: 백테스트 분당 10회
    r = c.post("/v1/backtest", json={"template_id": t["template_id"], "venue": "binance-spot",
                                     "symbol": "BTCUSDT", "tf": "1h", "hours": 24 * 30})
    if r.status_code == 429:
        raise SystemExit("rate limited — wait a minute")
    b = r.json()
    rows.append((t["template_id"], t["name"], b["n_trades"], b["pnl"], b["fees"], b["data_mode"]))
for row in sorted(rows, key=lambda x: float(x[3]), reverse=True):
    print(*row, sep="\t")

6.2 Python — 재량 주문 봇 골격 (봉투는 화면에서 미리)

import os, time, httpx
from decimal import Decimal

API = "https://weltiq.ai"
c = httpx.Client(base_url=API, headers={"Authorization": f"Bearer {os.environ['WELTIQ_API_KEY']}",
                                        "User-Agent": "weltiq-bot/1.0"}, timeout=60)

def last_close(venue, symbol):
    bars = c.get("/v1/bars", params={"venue": venue, "symbol": symbol, "tf": "1m", "hours": 1}).json()["bars"]
    return Decimal(bars[-1]["c"])

def place(venue, symbol, side, qty, why, stop=None, target=None, conn_target="paper"):
    inv = {k: str(v) for k, v in (("px_below", stop), ("px_above", target)) if v is not None}
    r = c.post("/v1/orders/oneoff", json={"venue": venue, "symbol": symbol, "side": side, "type": "market",
                                          "qty": str(qty), "thesis": {"why": why}, "invalidation": inv,
                                          "target": conn_target})
    if r.status_code != 200:
        raise RuntimeError(r.json()["detail"])       # {"code": "envelope_required", …} 등
    return r.json()["queue_id"]

def wait(queue_id, timeout=45):
    for _ in range(timeout):
        o = next((o for o in c.get("/v1/orders/oneoff").json()["orders"] if o["queue_id"] == queue_id), None)
        if o and o["status"] != "queued":
            return o
        time.sleep(1)
    raise TimeoutError(queue_id)

px = last_close("binance-spot", "BTCUSDT")
q = place("binance-spot", "BTCUSDT", "buy", "0.001", "예제: 1분봉 종가 기준 소량 진입",
          stop=px * Decimal("0.97"), target=px * Decimal("1.05"))
o = wait(q)
print(o["status"], o["result"])
if o["status"] == "filled":
    print(wait(place("binance-spot", "BTCUSDT", "sell", "0.001", "예제: 청산"))["result"])

6.3 JavaScript (Node 18+) — 계좌·체결 대시보드용 읽기

const API = "https://weltiq.ai";
const H = { Authorization: `Bearer ${process.env.WELTIQ_API_KEY}`, "User-Agent": "weltiq-dash/1.0" };
const get = (p) => fetch(API + p, { headers: H }).then(r => r.json());

const [account, fills, fees, slots] = await Promise.all([
  get("/v1/account"), get("/v1/fills?mode=paper"), get("/v1/fees/compare?mode=paper&days=7"), get("/v1/slots")]);
for (const b of account.balances) console.log(b.book, b.ccy, b.amt);
console.log("fills", fills.fills.length, "fee 7d", fees.actual_fee, "best venue",
  fees.venues.sort((a, b) => Number(a.fee) - Number(b.fee))[0]?.venue);
for (const s of slots.slots) console.log(s.deployment_id, s.symbol, s.status, s.live?.daily_pnl);

6.4 curl 치트시트

K="Authorization: Bearer $WELTIQ_API_KEY"; U="User-Agent: curl-weltiq/1.0"; J="Content-Type: application/json"
curl -s https://weltiq.ai/v1/markets -H "$K" -H "$U"
curl -s "https://weltiq.ai/v1/bars?venue=bybit-linear&symbol=BTCUSDT&tf=1h&hours=48" -H "$K" -H "$U"
curl -s -X POST https://weltiq.ai/v1/templates/TPL-002/instantiate -H "$K" -H "$U"
curl -s -X POST https://weltiq.ai/v1/slots -H "$K" -H "$U" -H "$J" -d '{"doc_hash":"<hash>","symbol":"BTCUSDT","tf":"1m","stop_max_loss":"50","stop_after_hours":12}'
curl -s -X POST https://weltiq.ai/v1/orders/oneoff -H "$K" -H "$U" -H "$J" -d '{"venue":"binance-spot","symbol":"BTCUSDT","side":"buy","type":"limit","qty":"0.001","price":"79000","thesis":{"why":"되돌림 매수"},"invalidation":{"px_below":"76000"}}'
curl -s https://weltiq.ai/v1/orders -H "$K" -H "$U"                       # 대기 지정가·상태 머신
curl -s -X DELETE https://weltiq.ai/v1/orders/<intent_id> -H "$K" -H "$U"
curl -s "https://weltiq.ai/v1/journal?limit=20" -H "$K" -H "$U"

7. 가능한 것 — 기능 목록

8. 한계점 · 설계상 없는 것

8.1 일부러 없는 것 (계약)

• 정책 작성·한도 상향·실전 승격·킬스위치 해제 엔드포인트/도구는 없습니다. 사람이 앱에서 하는 스텝업입니다.
• 키로 키를 만들 수 없고, 키·MCP로 봉투를 만들거나 커넥터를 등록할 수 없습니다. 대리인은 자기 경계를 넓힐 수 없습니다.
• 전략 규칙 문서·파라미터·DSL은 나가지 않습니다. 템플릿은 공개 카드(한 줄 요약)까지만, 내 인스턴스는 doc_hash로만 가리킵니다.
• 가설 없는 진입, 처분 조건 없는 진입은 거절됩니다 (thesis_required, invalidation_required). AI 산출을 통째로 붙여넣은 가설은 thesis_verbatim으로 되돌려 보내 문답으로 바꿉니다.
• 수익률 리더보드·권유는 없습니다. AI는 관찰과 리스크만 말합니다.
• 애널리스트 MCP는 read-data 단독 키만 받습니다 (정보 계통과 실행 계통의 방화벽).

8.2 현재 상태의 제약 (2026-09-06)

9. 오류 코드

응답은 {"detail": {"code": "...", "detail": "..."}} (또는 {"detail": "invalid token"}). MCP는 {"error": …, "detail": …}.

10. FAQ

Q. 계좌를 안 만들어도 되나요? 네. 무료 가입만 하면 실시간 시세 위 모의거래·백테스트·AI 분석을 쓸 수 있고, 증권사·거래소 계좌는 필요 없습니다. 내 거래소 키를 붙이는 커넥터는 선택입니다.

Q. API 키는 어디서 발급하고, 잃어버리면요? 설정 → API 키(/settings/keys). 비밀키는 발급 순간 한 번만 보입니다. 잃어버리면 새로 발급하고 옛 키를 폐기하세요. 서버에는 해시만 있어 복구가 불가능합니다.

Q. 키 하나로 Claude Code와 봇을 같이 써도 되나요? 됩니다. 다만 애널리스트 MCP(/mcp/analyst)는 read-data 단독 키만 받으니, 분석 전용 세션을 원하면 키를 따로 발급하세요. 용도별로 키를 나누면 저널에서 누가 무엇을 했는지 구분하기도 쉽습니다.

Q. session_required가 나옵니다. 그 행위는 브라우저에서만 됩니다: 키 발급·폐기, 봉투 생성·폐기, 커넥터 등록·폐기, 워치리스트 새로고침, 플랜 변경. 대리인이 자기 권한을 넓히지 못하게 하는 규칙입니다.

Q. 주문이 envelope_required로 거절됩니다. 그 심볼을 허용하는 활성 봉투가 없습니다. Paper › Order 화면에서 종목·주문당 명목·일 명목·유효 일수를 정해 봉투를 만든 뒤 다시 보내세요. 청산 주문은 봉투 명목에 계상되지 않습니다.

Q. 진입 주문에 왜 가설과 처분 조건이 필수인가요? 가설 없는 포지션은 만들지 않는다는 것이 weltiq의 불변 규칙입니다. 처분 조건(px_below/px_above)은 엔진이 기계적으로 판정해 자동 청산하므로, "나중에 보고 정하겠다"는 진입은 받지 않습니다.

Q. 매도를 냈는데 숏이 아니라 청산이 됐어요. 보유 포지션의 반대 방향 주문은 청산으로 처리합니다(reduce-only, 보유 수량까지). 반대 방향 신규 포지션은 방향권 규칙상 같은 심볼에 중첩할 수 없습니다. 먼저 청산한 뒤 새로 진입하세요.

Q. 체결이 실제와 얼마나 비슷한가요? 실시간 호가로 거래소 실제 수수료·슬리피지 모델을 적용합니다. 같은 주문을 거래소 데모와 나란히 낸 실측에서 바이낸스 테스트넷 중앙값 0.64bp, 바이비트 데모 0.04bp 차이였습니다(페이퍼가 1bp 보수적). 데모/테스트넷은 자체 오더북이라 실시장과 다를 수 있습니다.

Q. 주문을 넣었는데 queued에서 안 움직입니다. 집행 셀이 큐를 5초 주기로 가져갑니다(알림으로 즉시 깨움). binance-usdm은 봉 신선도 판정 때문에 최대 30초 걸릴 수 있습니다. 시세가 stale이면(주말 주식 등) 신선해질 때까지 queued로 대기하고, 그 사이 봉투가 만료되면 expired가 됩니다. 기다리기 싫으면 화면에서 큐 항목을 취소하세요.

Q. 백테스트 결과의 data_mode: idealized는 무슨 뜻인가요? 저장된 확정 봉으로 리플레이했고 보수적 봉 판정(봉 내 손절 우선)을 적용했다는 표시입니다. compare_lookahead: true로 미래 참조 대조를 함께 받을 수 있습니다. 백테스트 결과는 참고이지 예측이 아닙니다.

Q. 전략 규칙 원문을 API로 받을 수 있나요? 없습니다. 공개 카드(한 줄 요약·적합 시장·예측 의존도)까지만이고, 엔지니어 AI가 앱 안에서 설명·조정해 줍니다. 규칙 자체는 플랜·로그인과 무관하게 서버 밖으로 나가지 않습니다.

Q. 내 전략 문서를 올려서 돌릴 수 있나요? Pro의 formalize(자연어 → 인스턴스)와 엔지니어 AI의 명시적 변경으로 내 인스턴스(doc_hash)를 만듭니다. 임의 코드 업로드는 없습니다.

Q. 실거래 주문은 언제 열리나요? 커넥터 실거래 키는 지금도 등록·검증되지만 주문은 live_ack 확인 문구와 승격 사다리(모의 실적 심사) 뒤에 있습니다. 데모/테스트넷 주문은 열려 있습니다.

Q. 거래소 API 키는 어떻게 보관되나요? 사용자별 봉투 암호화로 저장하고, 주문 시점에 집행 셀만 복호화합니다. 등록 시 잔고 조회로 검증합니다. 거래소에서 키를 만들 때 출금·이체 권한은 끄고, 거래소 쪽에서 집행 셀 IP만 허용하도록 IP 제한을 걸어 두세요.

Q. 요율 한도를 넘으면 어떻게 되나요? 429 rate_limited. 분당 창이 지나면 풀립니다. 백테스트(무료 10/분)는 순차로 돌리고, 429를 받으면 60초 쉬는 코드를 넣으세요.

Q. 크레딧은 어디에 쓰이나요? AI 호출(토큰), 백테스트(봉 수), API 주문 수. 잔액이 음수면 유료 연산이 402로 막힙니다. GET /v1/billing에서 원장을, GET /v1/usage에서 종류별 집계를 볼 수 있습니다.

Q. 웹훅이나 실시간 스트림이 있나요? 없습니다. oneoff_orders·slots·journal을 폴링하세요. 봉은 확정 봉만 제공합니다. 사람에게는 이메일 알림(체결·거절·자동 청산·슬롯 정지)이 갑니다 — 설정 → 알림에서 고릅니다.

Q. Python requests로 호출하면 403이 납니다. User-Agent가 기본값(python-requests/urllib)이면 엣지에서 차단됩니다. User-Agent: my-bot/1.0처럼 이름을 붙이세요.

Q. 시간대는요? 모든 시각은 UTC ISO-8601(+00:00)입니다. 봉의 t는 봉 시작 시각입니다.

Q. 저널에는 무엇이 남나요? 키 발급, 봉투 생성, 주문 큐잉, 슬롯 시작·정지, 템플릿 인스턴스화 등 모든 행위가 누가(사람/외부 클라이언트/에이전트)·무엇을·누구를 대신해 했는지로 남습니다. 운영자 행위는 해시체인으로 봉인돼 사후 변조가 드러납니다.

Q. OpenAPI 스펙이 있나요? /api-docs에서 Swagger UI로 모든 엔드포인트와 스키마를 볼 수 있습니다.

이 문서는 2026-09-06 실서비스 응답으로 검증했습니다. 동작이 문서와 다르면 문서가 아니라 코드가 맞습니다 — weltiq/api/server.py, weltiq/api/mcp_server.py.