WELTIQ / DOCS / QUICK STARTS

빠른 시작 — MCP · REST API · TradingView

첫 모의 주문까지의 세 가지 길: Claude·Codex(MCP), 자작 코드(REST API), TradingView 알림 훅 — 실제 엔드포인트와 필드 이름 그대로.

첫 모의 주문까지의 세 가지 길. 모두 무료 계정이면 되고, 거래 한도는 언제나 브라우저에서 사람이 승인합니다 — 키·에이전트·스크립트는 승인할 수 없습니다. 각 절 끝의 링크는 한국어 매뉴얼의 해당 절입니다.

Claude · Codex · MCP REST API · 자작 코드 TradingView · 알림 훅

Claude · Codex · MCP

MCP: API 키 → 스코프 → 한도 승인 → 첫 주문 → 체결 확인

API 키 발급 — weltiq.ai/login 에서 가입(이메일 또는 Google) 뒤 마이 → 연결 → API 키(/connections). 라벨과 스코프를 고르고 발급합니다. wq_… 비밀키는 한 번만 보이므로 WELTIQ_API_KEY 로 보관하세요.
스코프 고르기 — read-data 는 마켓·계좌·체결·저널 읽기, operate-sim 은 모의 주문과 상주 슬롯, run-backtest 는 백테스트. 거래 에이전트에는 read-data + operate-sim 을 줍니다. 분석 서버(https://weltiq.ai/mcp/analyst)는 read-data 단독 키만 받습니다.
브라우저에서 주문 한도 승인 — 마이 → 연결의 주문 한도 승인 절(/connections#envelope)에서 종목(예 BTCUSDT)·주문당 노셔널·일일 노셔널·유효 일수를 승인합니다. 키·MCP 는 한도를 만들거나 넓힐 수 없습니다(403). 승인이 없으면 첫 주문은 envelope_required 로 거절됩니다.
MCP 서버 연결 — Claude Code 는 한 줄. Claude Desktop 이나 streamable HTTP MCP 를 지원하는 클라이언트(Codex 포함)는 클라이언트 MCP 설정에 서버 URL 과 Authorization 헤더를 넣습니다. 거래 서버에는 order_oneoff·oneoff_orders·fills·account·slots 등이 있고, 분석 서버에는 주문 도구가 없습니다.
```
claude mcp add --transport http weltiq https://weltiq.ai/mcp --header "Authorization: Bearer $WELTIQ_API_KEY"

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

첫 주문 — "binance-spot 에서 BTCUSDT 0.001 시장가로 사 줘. 가설은 4시간 지지선 유지, 60000 아래면 틀린 것." 이라고 말하면 에이전트가 order_oneoff(venue="binance-spot", symbol="BTCUSDT", side="buy", qty="0.001", thesis_why=…, px_below="60000") 를 부릅니다. thesis_why 는 필수이고, 진입에는 px_below·px_above 중 하나 이상이 필요합니다(레벨에 닿으면 엔진이 청산). client_ts 는 MCP 가 자동으로 찍습니다. REST 로는 POST /v1/orders/oneoff.

curl -sS -X POST https://weltiq.ai/v1/orders/oneoff -H "Authorization: Bearer $WELTIQ_API_KEY" -H "Content-Type: application/json" \
  -d '{"venue":"binance-spot","symbol":"BTCUSDT","side":"buy","type":"market","qty":"0.001",
       "thesis":{"why":"4h support holds"},"invalidation":{"px_below":"60000"},
       "client_ts":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"}'
# {"queue_id":"dq_…","status":"queued","est_notional":"…","closing":false,"target":"paper"}
curl -sS https://weltiq.ai/v1/orders/oneoff -H "Authorization: Bearer $WELTIQ_API_KEY"   # queued → filled | rejected (result.code)

체결·거절 확인 — "체결됐어?" 라고 물으면 oneoff_orders 를 부릅니다: status queued → filled(result.fills: qty·px·fee) 또는 rejected(result.code). 흔한 코드: thesis_required, invalidation_required, envelope_required, order_notional_exceeded, daily_notional_exceeded, no_price, spot_short_not_allowed. 이어서 fills(mode="paper")·account 로 원장을 읽습니다. 보유 포지션에 대한 반대 주문은 청산(reduce-only, 레벨 불필요)입니다.

매뉴얼 해당 절 →

REST API · 자작 코드

REST API: 연결 승인 → curl·Python 주문 → 상태

브라우저에서 연결 승인 — 마이 → 연결(/connections) → New connection: Binance 현물 USDT 1종목(예 BTCUSDT), 모의 자본, max_order_notional·max_daily_notional(USDT), stop_loss_pct, 허용 rule_id(기본 buy: entry, sell: exit), 10자 이상 전략 설명, 유효 일수, 선택으로 fee_venue. Approve & create 뒤 connection_id(pc_…)를 복사합니다. 한도는 이 화면에서만 정해집니다 — POST /v1/paper/connections 는 키가 아니라 브라우저 세션이 필요합니다.

curl 로 주문 — 본문 필드: schema_version 1, event_id(연결 안에서 유일), sequence(양의 정수, 단조 증가), emitted_at(UTC ISO 8601, 60초 안 도착), action buy|sell, qty(lot 배수의 문자열 Decimal), rule_id(허용 목록). 그 밖의 필드(target·live·cred_id·user_id)는 422. 202 는 접수이지 체결이 아닙니다.

curl -sS -X POST "https://weltiq.ai/v1/paper/connections/$CID/orders" \
  -H "Authorization: Bearer $WELTIQ_API_KEY" -H "Content-Type: application/json" \
  -d '{"schema_version":1,"event_id":"bot-1","sequence":1,"emitted_at":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","action":"buy","qty":"0.001","rule_id":"entry"}'
# 202 {"status":"queued","event_id":"bot-1","order_id":"dq_…","exec_mode":"delayed","status_url":"/v1/paper/connections/pc_…/orders/bot-1"}

Python 으로 — Authorization 헤더에 API 키를 넣고 sequence 는 재시작 뒤에도 증가하게 유지합니다(밀리초 타임스탬프면 충분). 같은 본문 재전송은 200 duplicate: true, 같은 event_id 에 다른 본문은 409 idempotency_conflict.

import os, time, datetime, httpx
BASE, CID = "https://weltiq.ai", os.environ["WELTIQ_CID"]
H = {"Authorization": "Bearer " + os.environ["WELTIQ_API_KEY"]}
seq = int(time.time() * 1000)                      # strictly increasing sequence
body = {"schema_version": 1, "event_id": f"bot-{seq}", "sequence": seq,
        "emitted_at": datetime.datetime.now(datetime.timezone.utc).isoformat(),
        "action": "buy", "qty": "0.001", "rule_id": "entry"}
r = httpx.post(f"{BASE}/v1/paper/connections/{CID}/orders", json=body, headers=H, timeout=10)
print(r.status_code, r.json())                    # 202 queued — accepted, not filled
st = httpx.get(BASE + r.json()["status_url"], headers=H).json()
print(st["status"], st.get("filled_qty"), st.get("fill_vwap"), st.get("protection"))

상태 읽기 — GET /v1/paper/connections/{cid}/orders/{event_id}: status queued → submitted → filled(또는 partial·rejected·expired·canceled), filled_qty, fill_vwap, fills [{qty, px, fee}], 그리고 체결 VWAP 과 stop_loss_pct 로 계산한 protection. GET …/orders 는 최근 주문과 접수 단계 거절, GET …/fills 는 연결 전용 장부의 체결 목록.
```
curl -sS "https://weltiq.ai/v1/paper/connections/$CID/orders/bot-1" -H "Authorization: Bearer $WELTIQ_API_KEY"
# {"event_id":"bot-1","status":"filled","filled_qty":"0.001","fill_vwap":"…","fills":[{"qty":"0.001","px":"…","fee":"…"}],"protection":{…}}
curl -sS "https://weltiq.ai/v1/paper/connections/$CID/fills" -H "Authorization: Bearer $WELTIQ_API_KEY"
```
만나게 될 거절 — 422 invalid_payload(형식), event_expired(emitted_at 60초 초과), future_event, rule_not_allowed, insufficient_position(보유보다 큰 sell), connection_inactive; 409 position_exists(롱 보유·대기 중 buy)·out_of_order(sequence 비증가); 429 rate_limited(연결당 60/분·2,000/일); 404·410 없는·폐기된 연결. buy 는 연결당 롱 1개, sell 은 축소만.
취소·청산 — DELETE /v1/paper/connections/{cid}/orders/{event_id} 는 엔진이 아직 집지 않은 주문만 취소합니다(그 뒤는 409 not_cancelable). 체결된 보유분은 sell 주문 또는 브라우저의 연결 화면에서 줄입니다.

매뉴얼 해당 절 →

TradingView · 알림 훅

TradingView: 훅 URL → alert() JSON → 체결

연결 생성과 훅 URL 복사 — REST 와 같은 연결 화면(마이 → 연결 → New connection). Approve & create 직후 훅 URL https://weltiq.ai/hooks/tv-orders/<token> 이 한 번만 보입니다 — 복사하세요. 잃어버리면 연결을 폐기하고 새로 만듭니다. 연결 1개는 무료, Pro 는 3개.

Pine 의 alert() 로 주문 JSON 만들기 — TradingView placeholder 로는 증가하는 정수 sequence 와 유일한 event_id 를 만들 수 없으므로 스크립트가 본문을 만듭니다. bar_index 를 둘 다에 쓰고, emitted_at 은 str.format_time 으로 UTC, rule_id 는 연결에서 허용한 값을 씁니다.

//@version=5
strategy("weltiq hook", overlay=true)
fast = ta.sma(close, 20), slow = ta.sma(close, 50)
msg(action, rule) => '{"schema_version":1,"event_id":"tv-' + str.tostring(bar_index) + '-' + action +
     '","sequence":' + str.tostring(bar_index) + ',"emitted_at":"' + str.format_time(timenow, "yyyy-MM-dd'T'HH:mm:ss'Z'", "UTC") +
     '","action":"' + action + '","qty":"0.001","rule_id":"' + rule + '"}'
if ta.crossover(fast, slow)
    alert(msg("buy", "entry"), alert.freq_once_per_bar_close)
if ta.crossunder(fast, slow)
    alert(msg("sell", "exit"), alert.freq_once_per_bar_close)

알림 만들기 — 차트에 전략을 올리고 → 알림 생성 → 조건 "alert() 함수 호출만", Webhook URL 에 1단계 주소, 메시지 칸은 비움(alert() 본문이 그대로 전송), 만료 없음, 2FA 켜기. TradingView 웹훅은 TradingView 유료 플랜에서만 전송됩니다.
첫 체결 확인 — 마이 → 연결에서 연결을 열면 이벤트가 queued 로 보이다가 체결가·수수료·보호 stop 과 함께 filled 가 되거나 코드와 함께 rejected 가 됩니다. 같은 데이터는 GET /v1/paper/connections/{cid}/orders/{event_id} 와 MCP 도구 paper_order_status 에도 있습니다. 무료: emitted_at 이후 첫 확정 1분 봉에 체결, Pro: 실시간 호가.
아무것도 오지 않을 때 — 404·410: 토큰이 틀리거나 폐기됨. 422 event_expired: emitted_at 이 60초를 넘음 — 알림 빈도를 확인. 409 position_exists: 이 연결에 롱이 이미 보유·대기 중. 200 duplicate: 같은 알림이 두 번 와서 무시됨. TradingView 는 전달을 보장하지 않으므로 알림 로그와 연결의 주문 목록을 대조합니다.

매뉴얼 해당 절 →

무료 플랜: 주문 시각 이후 첫 확정 1분 봉에 체결되므로(exec_mode "delayed") 1~2분 기다립니다. Pro 는 실시간 호가 체결. 시장: 외부 연결은 코인 현물, 직접 주문은 코인 현물·무기한 선물.

첫 실험은, 주문 한 건부터.

지원 범위를 확인하고 원하는 방식으로 시작하세요.

외부 주문 연결 화면 열기 시작하기 →