A
licenseA
qualityD
maintenanceKorean crypto market data API for AI agents. Real-time Kimchi Premium (Upbit vs Binance), Korean exchange prices, USD/KRW FX rate. First verified Korean market data MCP server. Pay-per-use via x402 on Base.
17
2
MIT
bamsaikr
by eddyParkGG
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
밤사이
국내 시장이 닫힌 밤과 주말에도 거래되는 하이퍼리퀴드 한국 주식 perp 가격으로 ① 밤사이 해외 가격과, 과거에 국내 시장이 그 방향대로 열린 비율, ② 두 시장 사이 가격 차이 거래(시세차익) 기회가 있는지 알려주는 서비스. 장 시작 가격은 사용자가 직접 가늠함
API 문서: bamsai.kr/api/openapi.json · MCP:
https://bamsai.kr/api/mcp· 화면 안내: bamsai.kr/developers제출용 1~2장 요약 PRD: docs/prd-submission.md
과제 핵심 한눈에
항목 | 내용 | 자세히 |
해결하려는 문제 | 국내 시장이 닫힌 시간(넥스트레이드 포함해도 주 168시간 중 65%)에 생긴 일이 다음 날 장 시작 가격에 어떻게 반영될지 개인은 알 방법이 없음. 그동안 가격은 하이퍼리퀴드 한국 주식 perp에서 정해지지만 달러 표시라 원화로 바로 비교하기 어려움 | |
타겟 고객 | 초기: LLM으로 국내 주식 자동매매 봇을 운영하는 개인 투자자(하이퍼리퀴드 한국 주식 perp를 함께 거래하는 사람 포함). 봇이 API·MCP로 밤사이 가격·적중률·비용 뺀 가격 차이를 받아 개장 전(06~08시)과 가격 차이가 벌어진 순간에 판단 → 확장: 삼성전자·SK하이닉스 등 국내 주식 일반 투자자. 결정의 순간은 아침 8시 넥스트레이드가 열릴 때 바로 거래할지, 기다릴지 (1% 넘게 움직인 밤, 08~09시에 국내 가격이 하이퍼리퀴드 가격 쪽으로 간 경우 72~75%) | |
핵심 가설 | H1 국내 시장(정규장·넥스트레이드)이 모두 닫힌 20:00~08:00에 하이퍼리퀴드에서 충분히(100만 달러 이상) 거래됐다면, 그 방향대로 다음 날 08:00 국내 시장이 시작한다(80% 이상) → 삼성전자 88.2%·SK하이닉스 85.4% 통과, 현대차 판단 보류. 같은 기간 상승 개장은 52~53%라 오르는 장 덕분은 아님. 다만 EWY·코스피200 perp도 방향은 83~87%로 비슷해, 가치는 '종목만의 방향 예측력'보다 닫힌 시간의 가격을 종목별 원화로 보여주는 데 있음 / H5(초기 타겟) 봇 운영자에게 API·MCP를 열면 매주 반복해서 호출한다 / H2(확장 타겟) 밤사이 해외 가격과 '그 방향대로 열린 비율'을 보여주면 장 시작 전에 다시 온다 | |
검증 지표 | North Star: 밤사이 API·MCP를 호출한 주간 외부 호출자 수(초기 타겟). 11/6 공식 MCP Registry·Glama 등록, awesome MCP 목록 2곳에 추가 PR. 확장 타겟: 미국장이 닫힌 뒤 국내 시장 시작 전(06:00~08:00)에 밤사이 가격을 본 주간 사용자. 첫 실험은 디시 주식 갤러리 게시, 개장 전 재방문 15% 이상이면 통과. 제출일(11/8)까지 게시하며 GA로 보고, 방문 200명이 안 되면 인터뷰 등 다른 방법으로 보완 | |
프로토타입 | https://bamsai.kr · 핵심(증권 앱에 들어갈 범위): 홈 종목 카드(국내 가격 vs 글로벌 가격, 그 방향대로 열린 비율), 지난 개장 기록, 소개(계산 방법) / 확장 트랙: 종목 상세(차트 | 호가 | 주문 3단, 가격 차이 거래 기회), API·MCP. 토스증권·하이퍼리퀴드·업비트 실시간 데이터 | |
과제 해석 | 'AI를 활용한 투자 프로덕트'를 ① AI로 문제를 찾고 직접 만들고, ② 고객의 AI 에이전트가 같은 숫자를 쓰도록 API·MCP로 연 제품으로 해석함. 금융 수치는 LLM이 아니라 실제 시세와 통계로 계산 | |
AI 활용 | Claude Code로 리서치·데이터 검증·모델 백테스트·구현·브라우저 QA·운영 장애 분석. 제품 안의 숫자는 LLM이 아니라 통계 계산이 만듦. API·MCP는 과제 배경의 'AI 툴로 자기만의 투자 도구를 만드는 고객', 곧 초기 타겟인 LLM 자동매매 봇 운영자가 바로 붙여 쓰도록 열어 둠 |
PRD
Related MCP server: crypto-quant-signal-mcp
한 줄 요약
국내 시장이 닫혀 있는 65%의 시간(넥스트레이드 포함) 동안에도 삼성전자·SK하이닉스·현대차 가격은 해외 24시간 시장에서 움직임. 이 가격을 원화로 바꿔 보여주고, 과거에 국내 시장이 그 방향대로 열린 비율과 보통 시작하는 범위를 함께 보여줌. 같은 숫자를 API·MCP로 열어 **LLM으로 자동매매 봇을 운영하는 개인 투자자(초기 타겟)**의 봇이 바로 판단에 쓰게 함. 두 시장에 자금을 둔 사용자에게는 비용 뺀 가격 차이 거래 기회를 계산해 주문 화면(출시 예정)까지 연결.
1. 해결하려는 문제
# | 누가 | 문제 | 지금은 어떻게 하나 |
P1 | 삼성전자·하이닉스 보유 개인 | "내일 아침 오를까, 내릴까?"에 답할 근거가 없음. 미국장 끝난 뒤, 주말·연휴 동안 생긴 뉴스가 다음 날 장 시작 가격에 얼마나 반영될지 모름 | 미국 지수, ADR, 커뮤니티 분위기로 짐작 |
P2 | 주식·코인 같이 하는 트레이더 | 두 시장 차이를 보려면 창 3개(하이퍼리퀴드, HTS, 업비트 환율)를 띄우고 직접 계산. 수수료·세금·환전·펀딩비를 빼면 실제로 남는지 알 수 없음 | 엑셀, 감으로 판단 |
P3 | 자동매매·AI 에이전트 사용자 | 두 시장 시세·가격 차이·예측을 한 번에 조회하는 API가 없음 | 거래소별 API 따로 붙여서 직접 구현 |
문제를 보게 된 계기 — 투자자들이 이미 하고 있던 행동
토스증권 커뮤니티, 디시 국내·해외 주식 갤러리 같은 주식 커뮤니티에서 개장 전과 주말마다 하이퍼리퀴드 가격 이야기가 계속 올라왔음. 디시에서 '하이퍼리퀴드 삼전'으로만 찾아도 2026년 2~10월 국내 주식·미국 주식·나스닥·차트 갤러리 등에 15건 넘게 나옴(글마다 조회 50~400회)
실제 글 (디시, 2026) | 보이는 불편 |
"하이퍼리퀴드 현재가격 삼전27.9 하닉184" (5/17 일 19시), "하이퍼리퀴드 삼전 24.4 하닉 170 / 월요일 서킷 확정" (7/19 일 새벽) | 주말·새벽에 달러 가격을 직접 원화로 바꿔 공유함 |
"어제 새벽에 삼전 390000원이라길래 말이 되나 싶었는데 아니다 다를까 음전 ㅋㅋ 괜히 날 잠못자게 만들었어" (6/4) | 언제 본 가격이 맞는지 모름 → 이후 '언제 본 가격이냐' 분석의 출발점 |
"삼성 갭락이라고 생각하면 … 하이퍼리퀴드에 삼전선물 숏치세요" (8/22), "주식사고 하이퍼리퀴드에서 공매도쳐서 헷징" (9/15) | 두 시장을 함께 쓰는 사람이 이미 있음 → 가격 차이 거래·API 고객 |
오류 가격과 진짜 움직임을 구분하지 못함 → 오라클 위험 |
→ 사람들은 이미 이 가격을 보고 있지만 직접 환산하고, 언제 본 가격이 맞는지 모르고, 오류 가격과 구분하지 못함. 밤사이는 이 세 가지를 풀려고 시작함
문제의 크기 (2026-11-05 직접 조회)
국내 시장은 넥스트레이드(08:00–08:50, 15:30–20:00)를 포함해도 하루 11시간 50분, 주 약 59시간(168시간의 35%). 정규장만 보면 주 32.5시간(19%)
하이퍼리퀴드
xyz:SKHX(SK하이닉스) 24시간 거래대금 약 5.4억 달러,xyz:SMSN(삼성전자) 약 0.9억 달러하이퍼리퀴드 상장(2026-02-20 한국 시간 새벽) 이후 국내 시장 개장 174번 중 39번이 주말·연휴 뒤 개장
2. 타겟 고객
구분 | 고객 | 이 고객을 고른 이유 | 주로 쓰는 것 |
초기 타겟 | LLM으로 국내 주식 자동매매 봇을 운영하는 개인 투자자. 어떤 LLM·에이전트를 쓰든 API·MCP로 숫자를 받아 봇이 판단. 하이퍼리퀴드에서 한국 주식 perp를 함께 거래하는 사람 포함 | 이미 자동주문·전략·분석 도구를 직접 만들어 쓰고 있어 설명 비용이 낮음. 하이퍼리퀴드 달러 가격, 원/USDC 환율, 국내 시세(정규장·넥스트레이드)를 직접 모아 맞추고 적중률 검증·비용 계산까지 해야 하는 불편이 가장 큼. 쓰는지 안 쓰는지가 호출 수로 바로 보여 검증이 빠름 | API · MCP |
확장 타겟 | 삼성전자·SK하이닉스 등 국내 주식을 거래하는 일반 투자자 | 개인 보유자가 많은 대표 종목이고 perp 거래대금도 가장 큼. 아침 8시 국내 시장이 열리기 전에 판단할 일이 매일 있음. 초기 타겟이 숫자를 꾸준히 쓰면 그 근거로 증권 앱 화면으로 넓힘 | 홈 · 종목 상세 |
초기 타겟의 결정의 순간 — 봇이 무엇을 보고 언제 움직이나
국내 주식 봇: 미국장이 닫힌 뒤(06~08시) 개장 전 포지션과 장전 주문 가격을 정할 때 (
predict_open)두 시장을 함께 거래하는 봇: 가격 차이가 평소보다 벌어졌을 때 (
get_arbitrage, 비용 뺀 금액)하이퍼리퀴드 perp 봇: 국내 장중에 국내 가격·투자자 동향이 바뀔 때 (원화 환산 가격, 지난 개장 기록)
확장 타겟의 결정의 순간 — 아침 8시 넥스트레이드가 열릴 때 바로 사고팔지, 기다릴지
보유자는 갭이 생기기 전(밤)에 팔 수 없음. 할 수 있는 결정은 '08시에 바로 거래할지, 가격이 자리 잡을 때까지 기다릴지'와 '장전 주문을 얼마에 걸지'
하이퍼리퀴드가 밤새 1% 넘게 움직인 날, 08~09시에 국내 가격이 하이퍼리퀴드 가격 쪽으로 가서 만난 경우가 삼성전자 72%·SK하이닉스 75%, 반대(하이퍼리퀴드가 국내 쪽으로)는 11%·10% (2026-04~11, 105·108번). 개장 직후 국내 가격이 하이퍼리퀴드 원화 가격과 크게 벌어져 있으면 그쪽으로 좁혀질 가능성이 큼
예: 11/6 삼성전자는 하이퍼리퀴드 07시 −9.5%, 08:00~08:10 평균 −11.9%로 과하게 시작한 뒤 10:28 −7.4%로 되돌아옴
일반 투자자 화면과 perp의 경계: 홈 카드·지난 개장 기록·소개는 국내 주식 판단까지만. 해외 perp는 국내 투자자 보호 대상이 아니라서(금융위·금감원 2026-10-16 유의사항 발표) perp 계좌가 없는 사람에게 권하지 않음. 가격 차이 거래와 perp 주문은 이미 하이퍼리퀴드를 쓰는 사용자용 별도 트랙이고, 증권 앱 버전에서는 국내 주문만 연결
주문 화면과 출시 알림 신청: 해외 가격과의 차이를 보다가 그 자리에서 주문까지 하고 싶은 사용자가 있는지 확인하려고, 종목 상세에 주문 화면(차트 | 호가 | 주문)과 출시 알림 신청(이메일)까지 만듦. 대상이 넓어지는 방향이라 핵심 범위와 나눈 별도 트랙으로 두고, 실제 주문은 보내지 않음. 주문 버튼 클릭과 알림 신청 수로 수요를 잼(H4)
3. 가설
가장 위험한 가정부터 순서대로 검증. 번호는 처음 정한 그대로 둠(GA 이벤트·실험 기록과 맞추려고).
# | 가설 | 위험도 | 이 가설이 틀리면 |
H1 신호 | 국내 시장이 모두 닫힌 동안(20:00~08:00) 하이퍼리퀴드에서 충분히 거래됐다면, 그 가격이 움직인 방향대로 다음 날 08:00 국내 시장도 80% 이상 같은 방향으로 시작한다 | 가장 높음 | 서비스 존재 이유가 없음 |
H5 에이전트 (초기 타겟) | LLM 자동매매 봇 운영자에게 밤사이 숫자를 API·MCP로 열면 봇이 매주 반복해서 호출한다 | 높음 | 초기 타겟 가정이 틀림. 웹 화면 중심(확장 타겟)으로 순서를 바꿈 |
H2 가치 (확장 타겟) | 보유 종목의 밤사이 해외 가격과 "그 방향대로 열린 비율"을 보여주면 장 시작 전에 다시 찾아온다 | 높음 | 신기한 숫자로 끝나고 습관이 안 됨 |
H3 신뢰 | 지난 개장 기록을 같이 보여줘야 숫자를 믿고 행동한다 | 중간 | 숫자만 보고 떠나거나, 반대로 맹신 |
H4 전환 (확장 트랙) | 수수료·세금까지 뺀 가격 차이 거래(시세차익) 기회를 보여주면 조회가 주문 버튼 클릭으로 이어진다 (주문은 출시 전이라 클릭 시 출시 알림 신청) | 중간 | 종목 상세가 구경용에 그침 |
H1은 출시 전 과거 데이터로 먼저 검증
왜 이 기준인가
개인 투자자는 정규장(09:00–15:30)뿐 아니라 넥스트레이드(08:00–08:50, 15:30–20:00)에서도 거래함 → '국내 시장'은 둘을 합친 08:00–20:00
국내가 정말 닫힌 시간은 20:00 → 다음 거래일 08:00(평일 12시간, 주말·연휴는 더 김). 이때 움직이는 건 하이퍼리퀴드뿐
그래서 기준 = 20:00 국내 마지막 가격, 맞힐 대상 = 08:00 국내 시장이 다시 열렸을 때 개인이 거래할 수 있는 가격
08:00 첫 체결 한 건은 거래가 적어 들쭉날쭉함 → 08:00~08:10 거래량 가중 평균을 씀 (아래 비교표에서 5분·10분 평균이 가장 안정적)
채점 방법
하이퍼리퀴드 움직임 = 08:00 직전(07:00~07:59 1시간 봉 종가, 그 시각 환율로 원화 환산) 하이퍼리퀴드 가격 ÷ 전날 20:00 국내 가격 − 1. 08:00 넥스트레이드 첫 체결이 오라클로 들어가 perp가 튀는 경우(2026-07-28)를 피하려고 08:00 직전 가격을 씀
국내 움직임 = 08:00~08:10 평균 가격 ÷ 전날 20:00 국내 가격 − 1
둘의 방향(+/−)이 같으면 '따라감'. 둘 중 하나라도 ±0.05% 안쪽이면 '거의 그대로'로 따로 표시하고 비율에서 뺌
조건: 그날 밤(20:00~08:00) 하이퍼리퀴드 거래대금 100만 달러 이상. 거래가 적으면 몇 건의 주문으로도 가격이 흔들려 '시장의 판단'으로 보기 어려움 (아래 근거)
종목 | 방향대로 (거래 충분한 밤) | 전체 밤 | 80% 구간 실제 포함 | 예상 가격 오차 | 비교: 어제 20:00 가격 그대로 |
삼성전자 (2026-11-05 기준, 매일 다시 계산) | 88.2% (119번 중 105번) | 85.8% (134번 중 115번) | 83.2% | 1.22%p | 2.40%p |
SK하이닉스 | 85.4% (130번 중 111번) | 85.4% (137번 중 117번) | 89.1% | 1.10%p | 2.84%p |
현대차 | 판단 보류 (7번 중 5번) | 66.7% (135번 중 90번) | 88.2% | 1.26%p | 1.53%p |
거래대금 조건의 근거 (같은 기간, 세 종목 합산)
밤사이 하이퍼리퀴드 거래대금 | 해당 밤 | 방향대로 열림 |
100만 달러 미만 | 150 | 67.3% |
100만 달러 이상 | 256 | 86.3% |
(참고) 50만 / 200만 달러 이상 | 290 / 232 | 84.8% / 87.1% |
한 종목 안에서도 거래가 많은 밤이 더 잘 맞음: 삼성전자 78.8% → 92.6%, SK하이닉스 81.2% → 89.7% (각자 중간값 아래/위)
현대차는 밤사이 거래대금 중간값이 23만 달러(삼성전자 1,760만, SK하이닉스 9,700만)라 거의 모든 밤이 기준 미만
기준선은 백테스트에서 거래대금 구간별로 적중률을 비교해 정함 (100만 달러 미만 67.3% vs 이상 86.3%로 차이가 가장 뚜렷한 지점)
같은 데이터로 기준을 고르고 같은 데이터로 채점하면 성적이 실제보다 좋게 보일 수 있음 → 기준을 0~500만 달러로 바꿔도 결과가 거의 같은지 확인함 (아래 표). 숫자 하나에 기대는 결과가 아님. 앞으로 쌓이는 밤으로 계속 다시 확인
밤사이 거래대금 기준 | 0 (조건 없음) | 25만 달러 | 50만 달러 | 100만 달러 | 200만 달러 | 500만 달러 |
삼성전자 | 85.9% (135) | 85.6% (132) | 86.2% (130) | 88.3% (120) | 88.9% (108) | 89.3% (103) |
SK하이닉스 | 85.5% (138) | 85.5% (138) | 86.0% (136) | 85.5% (131) | 86.3% (124) | 86.3% (117) |
(2026-11-06 기준, 괄호는 채점한 밤 수. 하이퍼리퀴드 방향대로 열린 비율)
화면: 그날 밤 거래가 기준 미만으로 보이면(지금까지 밤 거래와 최근 20일 밤 거래의 중간값 중 큰 쪽) 예측 옆에 '거래 적어 덜 정확' 표시
어느 시점 가격으로 채점할지 비교 (조건 없이 전체 밤, 하이퍼리퀴드 방향대로 열린 비율)
종목 | 08:00 첫 체결 | 08:00~08:05 평균 | 08:00~08:10 평균 | 08:00~08:30 평균 | 정규장 09:00 |
삼성전자 | 80.5% | 85.3% | 85.8% | 84.6% | 83.5% |
SK하이닉스 | 85.9% | 85.4% | 85.4% | 84.2% | 84.1% |
현대차 | 70.1% | 66.9% | 66.7% | 69.9% | 73.3% |
기간: 2026-04-13 ~ 2026-11-05, 종목별 139번. 80% 구간·오차는 앞 20번을 학습에만 쓰고 나머지 119번으로 채점. 하이퍼리퀴드 상장은 2026-02-20(한국 시간 새벽 5시, SK하이닉스 기준)이지만, API가 1시간봉을 최근 5,000개(약 7개월)만 보관해서 08:00 가격이 있는 4월 13일부터 채점 가능. 시간이 지나면 표본이 계속 늘어남
이전 기준(정규장 15:30 종가 → 09:00 시가)에서는 91.2 / 90.8 / 85.5%였음. 15:30~20:00 넥스트레이드에서 이미 보이는 움직임까지 '예측'으로 쳤기 때문에 높게 나온 것 → 서비스 전제와 맞지 않아 기준을 바꿈
표본은 2026년 4~11월 한 시기라, 다른 장세(긴 횡보·강세장)에서도 같은지는 쌓이는 밤으로 계속 확인해야 함
다른 신호와 비교 (같은 기간·같은 채점, 조건 없이 전체 밤, 2026-11-06 계산)
신호 | 삼성전자 | SK하이닉스 |
국내가 오르며 열린 비율 (항상 '오른다'로 찍기) | 53.3% | 52.2% |
종목 perp (하이퍼리퀴드 삼성전자·SK하이닉스) | 85.9% | 85.5% |
EWY perp (하이퍼리퀴드 MSCI 한국 ETF) | 87.2% | 85.3% |
코스피200 perp (하이퍼리퀴드) | 84.3% | 83.1% |
오르는 장이라 적중률이 부풀려진 것은 아님 (상승 개장 52~53%)
방향만 보면 종목 perp가 한국 지수 perp보다 낫지 않음 → 이 서비스의 가치는 '종목 perp만의 방향 예측력'이 아니라 국내가 닫힌 시간에 정해지는 가격을 종목별 원화 가격으로 보여주는 것
아직 못 한 비교: 코스피200 야간선물(무료 분봉 데이터 없음), 시작 가격 '크기' 오차를 신호별로 비교
결론: 삼성전자·SK하이닉스 통과, 현대차 판단 보류. 현대차는 하이퍼리퀴드 거래가 너무 적어 기준을 넘는 밤이 거의 없음 → 예측에 '거래 적어 덜 정확' 표시
화면에서도 같은 숫자를 매일 다시 계산해 공개 (H3 검증 장치)
언제 본 가격이냐: 미국장 전·중·후
밤사이 하이퍼리퀴드는 미국장(겨울 23:30~06:00, 여름 22:30~05:00 한국 시간)이 열려 있는 동안 가장 크게 움직임. 저녁 9시에 본 가격과 새벽 6시에 본 가격은 믿을 수 있는 정도가 완전히 다름.
밤의 시각별로 '그때 하이퍼리퀴드 가격을 그대로 봤다면' 다음 날 국내 시장이 그 방향으로 열렸는지 (2026-04-13~11-06 평일 밤, 종목별 108번)
시각 | 삼성전자 | SK하이닉스 | 1% 넘게 움직인 날만 | 평균 오차 |
21시 | 49.1% | 48.6% | 46% | 2.5~3.0%p |
23시 | 66.0% | 62.6% | 63~68% | 2.3~2.6%p |
01시 | 71.7% | 72.9% | 76~79% | 1.9~2.1%p |
03시 | 83.0% | 79.4% | 86~89% | 1.7~1.8%p |
06시 (미국장 마감 뒤) | 85.8% | 86.9% | 91~95% | 1.3%p |
07시 | 88.7% | 89.7% | 94~95% | 1.3~1.4%p |
상장(2/20)부터 4시간봉으로 본 133번도 같은 모양: 21시 49~53%, 01시 70~74%, 05시 83~86%
화면은 지금이 미국장 전·중·후 중 어디인지에 따라, 같은 단계에서 봤던 지난 개장일의 적중률을 보여줌 (개장일마다 한 번씩 셈. 주말 60시간이 평일 12시간보다 많이 세어지지 않게)
평일 밤 | 미국장 열리기 전 | 열려 있는 동안 | 닫힌 뒤 |
삼성전자 | 54.7% | 75.0% | 87.4% |
SK하이닉스 | 52.5% | 73.9% | 88.0% |
(주말·연휴 닫힌 뒤) | 삼성전자 68.5%, SK하이닉스 75.6% |
그래서 화면은 '오를 확률'처럼 앞으로를 약속하는 숫자 대신 "미국장 마감 때 하이퍼리퀴드 가격 / 지금 가격 / 과거 이 시간대엔 n%가 이 방향대로 열렸어요" 를 보여줌. 틀릴 수 있는 숫자를 확률로 포장하지 않기 위해서
발견 경위: 커뮤니티 첫 글(11/5 21시)에 '내일 시초가 +0.3%'를 썼는데, 새벽 미국장에서 하이퍼리퀴드가 −9.5%까지 내려가 실제 시작은 −11.9%. 저녁 숫자를 내일 가격처럼 보여준 게 문제였음
예측 계산법
화면의 '보통 이 안에서 시작(80% 구간)'과 지난 개장 기록 채점은 아래 순서로 계산함. API에는 예상 가격·probUp도 남아 있지만 화면에서는 쓰지 않음 (확률이 약속처럼 읽혀서). 사용자용 설명은 소개 페이지('밤사이는 이렇게 계산해요')에 있음. 모델은 일부러 단순하게 둠 (표본이 종목별 140번 남짓이라 복잡하면 과적합되고, 초보도 이해할 수 있어야 해서)
밤사이 차이
g= 지금 하이퍼리퀴드 가격(원화) ÷ 어제 20:00 국내 가격 − 1예상 움직임
μ= α + β × gβ = 과거 개장에서 국내가 하이퍼리퀴드 움직임을 평균 몇 배 따라갔는지. 1(그대로 따라감) 쪽으로 당겨서 급락일 몇 번에 흔들리지 않게 함
α = 하이퍼리퀴드와 상관없이 생기는 평균 차이 (거의 0)
불확실성
σ= √(과거 예측이 빗나간 폭² + β² × 하이퍼리퀴드 시간당 변동성² × 장 열리기까지 남은 시간)빗나간 폭은 평일 밤 / 주말·연휴를 따로 계산 (주말이 더 큼)
남은 시간이 길수록 하이퍼리퀴드가 더 움직일 수 있으니 범위를 넓힘
결과
예상 가격 = 어제 20:00 가격 × (1 + μ)
probUp(API 전용, 화면에는 안 씀) = 정규분포에서 0보다 클 확률 Φ(μ / σ)예상 범위(80% 구간) = μ ± 1.28σ. 10번 중 8번은 이 안에서 시작하도록 잡은 범위
검증: 그날 이전 데이터로만 2~4를 계산해 그날 결과와 비교 (walk-forward). 미래 정보가 섞이지 않음
예시: SK하이닉스, 2026-11-04 아침 (실제 채점과 같은 방식: 11월 3일까지 137번 개장으로 맞춘 계수 α −0.22%, β 0.875, 평일 밤 σ 1.36%)
단계 | 값 |
어제(11/3) 20:00 국내 가격 | 1,414,000원 |
11/4 08:00 직전(07:59) 하이퍼리퀴드 가격 (원화) | 1,461,621원 → |
예상 움직임 | +2.73% → 예상 가격 약 1,452,600원 |
불확실성 | 1.36% |
| 약 98% (97.8%) |
예상 범위 2.73% ± 1.74% | +0.99% ~ +4.47% → 약 1,428,000원 ~ 1,477,200원 |
실제 08:00~08:10 평균 | 1,451,776원 (+2.67%) → 방향 맞음, 예상 범위 안 |
지금(11/5) 기준 계수는 α −0.24%, β 0.88, σ 1.37%로 매일 조금씩 바뀜. 예시는 그날 아침 실제로 썼을 계수로 계산함 (서버 채점 값 +2.7289%와 일치)
4. 검증 지표
North Star: 밤사이 API·MCP를 호출한 주간 외부 호출자 수 (초기 타겟) → 선정 이유: 초기 타겟의 봇이 밤사이 숫자를 실제 판단에 쓰고 있다는 가장 직접적인 신호. 한 번 붙여 보고 마는지, 매주 다시 부르는지가 핵심
정의: 서버가 GA로 보내는
api_call이벤트(화면 밖 호출만)의 주간 고유 호출자. IP를 보내지 않고 User-Agent로 구분하는 근사값이라, 같은 도구를 쓰는 여러 사람이 하나로 묶일 수 있음. 목록 사이트의 상태 점검 호출은 제외보조: 개장 전(06~08시)
predict_open호출 수, 2주 연속 호출한 호출자 비율유입: 2026-11-06 공식 MCP Registry(
io.github.eddyParkGG/bamsai)와 Glama(kr.bamsai/bamsai, A등급)에 등록, awesome-mcp-servers·awesome-remote-mcp-servers 목록에 추가 PR 제출
확장 타겟 지표: 미국장이 닫힌 뒤 국내 시장 시작 전(06:00~08:00)에 밤사이 가격을 실제로 본 주간 사용자 수 → 선정 이유: H2(습관)와 H1(하이퍼리퀴드 신호)이 둘 다 맞아야 오르는 숫자. 06시 이후가 하이퍼리퀴드 가격이 가장 정확한 시간대(위 표)이고, 08시에 넥스트레이드가 열리기 전 판단하는 순간이라 이 시간대만 셈
정의: GA
prediction_view이벤트 중kst_window = preopen(06:00~08:00 KST)인 고유 사용자. 홈·종목 페이지에 들어왔을 뿐인page_view는 세지 않음측정 상태: 2026-11-06에 GA 맞춤 측정기준(
kst_window등)을 등록해 그날부터 측정 가능. 그 전 데이터로는 계산할 수 없음다음 단계에서 이어 볼 것: 같은 사용자의 주간 재방문률, (주문 출시 후) 개장 직후 주문 전환
확장 타겟 첫 실험: 커뮤니티 4일 테스트
항목 | 내용 |
목적 | H2(개장 전에 다시 오나)를 가장 싸게, 가장 빨리 확인 |
채널 | 디시 주식 갤러리. 종목별 마이너 갤러리는 글이 거의 없어서(SK하이닉스 하루 몇 건, 하이퍼리퀴드·삼성전자 주주 갤러리는 몇 달째 0건) 제외. 네이버 종목토론방은 운영원칙상 광고·홍보 금지라 첫 글이 몇 분 만에 삭제됐고 본문 링크도 클릭되지 않아 제외 |
시점 | 저녁 8시 넥스트레이드 마감 후(21~22시) 게시. 목·금·일 저녁 → 금·월 개장 전 재방문 측정 (주말 갭 포함). 첫날(목)은 A형·B형 1개씩 시간 간격을 두고 게시(연속 게시는 도배로 보일 수 있음) |
기간 | 4일 (목 마감 ~ 월 09:00) |
메시지 A/B | A 예측형 / B 사실형 "지금 해외에선 삼성전자 -2.6%". 1차(11/5)는 A에 저녁 숫자와 '오를 확률'을 썼는데, 저녁 숫자가 거의 동전 던지기 수준이라(위 '언제 본 가격이냐') 이후 A는 미국장 마감 뒤 숫자 + '과거 이 시간대엔 n%가 이 방향대로 열렸어요' 로 바꿈 |
추적 | 글마다 |
측정 범위 | 첫 글 다음 날인 11/6 0시 이후 전체 방문(내부 트래픽 제외). 글 링크로 처음 온 사람도 나중엔 주소를 직접 쳐서 다시 올 수 있어, 출처(UTM)가 남은 방문만 세지 않음. UTM은 글·메시지별 유입 비교용 |
판단 최소 표본 | 방문자 200명. 미만이면 결론 보류, 게시 1회 추가 |
현재 상황과 보완 (11/6) | 11/6까지 게시 4번, 조회 수십 회 수준. 제출일(11/8)까지 계속 게시하며 GA로 방문·개장 전 재방문을 봄. 클릭률 3%를 가정하면 방문 200명에 조회 약 6,700회가 필요해서, 그때까지 200명이 안 되면 정량 결론은 미루고 보유자 인터뷰 등 다른 방법(언제 무엇을 보고 결정하는지 확인)으로 보완 |
단계 | 지표 | 성공 기준 | 근거 | GA4 |
유입 | 게시글 조회 대비 방문 | ≥ 3% | 커뮤니티 링크 클릭률 통상 1~3% 가정. 3%를 넘으면 문제 자체에 관심 있다고 판단 |
|
활성화 | 방문 → 예측 확인 | ≥ 70% | 첫 화면에 바로 보여서 이보다 낮으면 첫 화면 문제 |
|
활성화 | 예측 → 종목 상세 | ≥ 30% | 숫자 하나 보고 이탈하는지, 근거를 더 보는지 |
|
핵심 리텐션 | 첫 방문 다음 개장 전 재방문 (밤사이 가격을 실제로 본 경우만) | ≥ 15% | 커뮤니티발 일회성 유입의 D1 재방문은 보통 5~10% 수준으로 가정. 그 두 배면 '습관' 신호 |
|
리텐션 | 4일 중 2일 이상 방문 | ≥ 20% | 주말 갭이 있는 월요일까지 다시 오는지 | 코호트 탐색 |
신뢰 | 근거 확인 (개장 전 가격·지난 개장 기록 탭 열람) | ≥ 10% | 숫자만 보고 믿는지, 근거를 확인하는지 |
|
판단 규칙
개장 전 재방문 15% 이상 → 개장 전 알림(웹 푸시) 바로 개발. 알림이 리텐션을 더 올릴 여지가 큼
5~15% → 메시지(A/B 중 나은 쪽)와 게시 시각을 바꿔 1회 재실험
5% 미만 → '매일 보는 습관' 가설 기각. 주말·연휴 갭 리포트처럼 이벤트성 콘텐츠로 방향 전환
A/B는 채널 간 차이보다 메시지 차이를 먼저 봄 (채널은 2개뿐이라 비교 의미가 약함)
주의할 점
커뮤니티 홍보 금지 규정: 정보 공유 형식(주말 갭 수치 + 그래프 캡처)으로 쓰고 링크는 1개만
특정 종목 매수·매도 권유 문구 금지 (유사투자자문 오해 방지)
출시 후 지표 (실험 통과 시)
가설 | 지표 | 목표 (4주) | GA4 이벤트 |
H1 | 하이퍼리퀴드 방향대로 열린 비율 (보조: 80% 구간 포함률) | ≥ 80% / 75~85% | 서버 계산, 화면 공개. 4주 연속 75% 미만이면 노출 중단 |
H3 | 근거 확인한 사람의 재방문율 차이 | +10%p |
|
H4 | 시세차익 기회 조회 → 주문 버튼 클릭 | ≥ 5% |
|
H4 | 주문 버튼 → 출시 알림 신청 (주문 열리기 전 수요 측정) | ≥ 20% |
|
H5 | 주간 외부 API·MCP 호출 | 주 1,000회 | 서버가 GA로 보내는 |
가드레일 (나빠지면 바로 멈춤)
예측 오차 3%p 이상인 날의 비율 (오라클 이상, 상한가·하한가 날 포함)
주문 버튼 클릭 중 하이퍼리퀴드·레버리지 5배 이상 비중 (
order_submit의market,leverage)홈에서 들어와 종목 상세 주문까지 간 비율 (초보의 고위험 상품 유입 감시)
5. 해결 방법
홈 | 종목 상세 | |
질문 | "밤사이 해외에선 얼마나 움직였어요? 믿을 만해요?" / "지금 시세차익 기회 있어요?" | 두 시장이 어디서, 얼마나, 왜 벌어졌나 |
화면 | 종목 카드 3개 (누르면 종목 상세). 장중: 위 '국내 지금' / 아래 '미국장 닫힌 뒤 · 국내 개장 직전 글로벌 가격'. 장 마감 후: 위 '국내 종가' / 아래 '지금 글로벌 가격'(실시간) + 미국장 단계 + '과거 이 시간대 n%가 이 방향대로 열렸어요'. 아래에 해외 가격과 시세차익 기회(1천만원 기준) | 차트 | 호가 | 주문 3단(경계를 끌어 너비 조절, 기본 340px, 페이지 스크롤 없음), 차트 위 '하이퍼리퀴드 지금 · [자세히]'와 그 아래 미국장 단계·과거 적중률 한 줄·'시세차익 · 1천만원이면 약 N원 [시세차익 내기]', 차트 전체화면, 탭 줄 끝 오늘의 이슈, 개장 전 가격·지난 개장 기록·투자자 동향 탭 |
용어 | perp → "하이퍼리퀴드", KRX·넥스트레이드 → "국내 시장", 시가 → "장 시작 가격" | 같음 (원화 환산 기준) |
종목 상세 차트
두 시장 캔들/라인 겹침, 시장별 on/off, 시장별 거래량
배경색으로 국장 개장(정규장·넥스트레이드)·휴장(하이퍼리퀴드만 거래) 구분, 일봉 포함
하이퍼리퀴드 일봉은 국내 거래일과 같은 저녁 8시~저녁 8시 기준으로 다시 묶음 (거래소 일봉은 UTC 하루라 13시간 어긋남)
가격 차이 패널: 장중은 진하게, 휴장 중(직전 종가 대비)은 연하게. 하이퍼리퀴드 상장일 세로선
따라간 정도 패널: 하이퍼리퀴드가 1% 이상 움직인 날, 그 움직임을 국내 시장이 몇 % 따라 시작했는지 막대로 (100 점선 = 같은 만큼)
보조 패널(거래량·가격 차이·따라간 정도·펀딩비·RSI·MACD)마다 제목과 물음표 설명, 지표를 켜면 자동으로 붙음
휴장 중에는 보통 시작 범위(점선 2개), 시세차익이 생기면 그 가격에 '시세차익 내기' 버튼
뉴스 말풍선 (하루 1건, 출처 확인된 것만) → 누르면 요약과 원문 링크
이동평균, 그물망, 볼린저, 일목균형, VWAP, RSI, MACD, 펀딩비
따라간 정도 지표 ('지난 개장 기록' 표·차트·API 공통)
따라간 정도= 08:00~08:10 국내 움직임 ÷ 밤사이 하이퍼리퀴드 움직임. 100%면 그대로 따라 시작. 차트에는 하이퍼리퀴드가 1% 이상 움직인 날만 표시 (작은 움직임은 비율이 의미 없음)만난 지점= 08:00~09:00 동안 두 가격이 만난 위치. 0이면 하이퍼리퀴드가 국내 쪽으로, 1이면 국내가 하이퍼리퀴드 쪽으로 이동
가격 차이 거래 (화면 이름 '시세차익')
전제: 하이퍼리퀴드 지갑(USDC)과 국내 증권 계좌에 미리 자금을 둔 상태. 원화를 USDC로 바꿔 옮기는 시간은 거래 순간에 들지 않음
방법: 두 가격 차이가 평소보다 벌어졌을 때 비싼 쪽을 팔고 싼 쪽을 산 뒤, 차이가 평소 수준으로 돌아오면 둘 다 정리
성격: 무위험 차익이 아니라 평소 차이로 돌아온다는 데 거는 거래(통계적 차익). 같은 순간에 사고팔아 확정되는 이익이 아님
아직 반영 못 한 위험: 차이가 언제 좁혀질지 모름(펀딩비는 1시간 보유로 가정), 양쪽에 자금을 묶어 두는 부담
순차익 = |가격 차이 − 평소 차이| − 슬리피지 − 주문 간 시차 비용 − 주식 수수료·세금 − perp 수수료 − 환전 비용 − 보유 중 펀딩비
두 시장 가격 차이는 0으로 돌아가지 않고 '평소 수준'에서 움직임. 정규장 시간 월별 중간값이 2026년 9월 약 −0.7~+0.1%, 10월 +0.9~1.0%, 11월 +0.5% (세 종목 비슷)
그래서 평소 차이 = 최근 5거래일 정규장 1시간 가격 차이의 중간값으로 두고, 지금 차이가 평소보다 더 벌어진 만큼만 기회로 봄. 처음에는 0을 기준으로 계산해서, 평소 수준인 날에도 '1천만원 기준 약 17,000원 남아요'로 보였던 문제를 고침
화면 목록은 두 경우만: 비용을 빼고 남으면 '+N원', 아니면 '아직 시세차익 기회가 없어요'. 이유(평소 수준·비용이 더 큼·주식 매도 필요)는 차트 위 설명에서 봄
호가 기준 체결가: 1천만원(
notionalKrw)만큼 하이퍼리퀴드는 매수 호가를, 국내는 매도 호가를 쌓아 평균 체결가를 계산. 중간 가격과의 차이가 슬리피지. 보이는 호가로 다 못 채우면 '호가 잔량이 부족해 최대 N만원까지'로 표시하고 채울 수 있는 금액으로 계산주문 간 시차: 두 주문은 동시에 체결되지 않음. 최근 60분 1분 변동성 × √(시차/60초), 시차 기본 3초(
lagSec)오라클이 튀는 순간에도 숨기지 않고 실제 호가 그대로 계산 (그 가격에 실제로 체결되므로). 대신 추가 급변 시 청산 위험이 큼
항목 | 기본값 | 근거 |
주식 | 왕복 수수료 0.03% + 매도세 0.20% | 2026년 코스피 증권거래세·농특세 합계로 가정 |
perp | 왕복 0.018% | HL 기본 0.045% × HIP-3 배수 2 × growth mode 0.1 |
환전 | (0.05% + 호가 스프레드 절반) × 2 ÷ 레버리지 | 업비트 원화마켓 수수료, 증거금만 환전 |
펀딩 | 시간당 펀딩 × 1시간 | 숏이면 받고 롱이면 냄 |
슬리피지 | 1천만원어치 호가를 쌓은 평균 체결가 − 중간 가격 | 두 시장에서 받아 오는 호가 단계까지 |
주문 간 시차 | 1분 변동성 × √(3초/60초) | 최근 60분 원화 환산 1분봉 |
개인은 주식 공매도가 어려워서 perp가 쌀 때(주식 매도 필요)는 기회로 세지 않음
모든 비용은 API 파라미터로 바꿀 수 있음
6. 주요 결정과 이유
결정 | 이유 |
환율은 원/USDC (업비트 실시간) | perp는 USDC로 정산. 국내 투자자가 실제로 돈을 옮기는 경로가 원 → USDC라서, 은행 원/달러 환율보다 체결 가능한 값에 가까움 |
증권사 API는 토스증권 Open API | 카카오페이증권은 오픈 API가 없어서, 개인이 직접 발급받아 쓸 수 있는 토스증권 Open API를 사용. 실시간 체결·호가 웹소켓, 1분봉(넥스트레이드 포함 통합 시세), 투자자 동향, 장 운영 캘린더, 주문까지 한 곳에서. 브라우저가 직접 못 붙는 웹소켓(헤더 인증·허용 IP)은 서버가 하나만 열어 나눠줌 |
예측·시세차익은 국내 주식 3종만, 나머지는 하이퍼리퀴드 가격만 | 하이퍼리퀴드의 한국 상품 7개(삼성전자·SK하이닉스·현대차·SK하이닉스 ADR·코스피200·EWY·KORU)를 다 보여주되, 같은 기초자산의 국내 가격이 있는 국내 주식 3종만 예측·시세차익을 계산. ADR은 보통주로 바꿀 수 없고, 코스피200은 증권사 API에 실시간 지수가 없고, EWY·KORU는 미국 ETF라 비교 대상이 없음 |
화면은 Vercel, API 서버는 Fly.io (고정 IP 서버 1대) | 토스증권 Open API는 허용 IP에서만 호출되고, 토큰을 새로 받으면 이전 토큰이 바로 무효가 됨. 그래서 고정 출구 IP를 가진 서버가 항상 1대만 떠 있어야 함. Vercel·Firebase 같은 서버리스 함수는 요청마다 인스턴스가 여러 개 뜰 수 있어 토큰이 서로를 끊고, 고정 IP는 유료 옵션. Fly는 머신 1대 + 고정 출구 IP(월 $3.6)로 월 $8 안팎. 화면(정적 파일)은 Vercel이 내보내고 |
국내 실주문은 기본 꺼둠 | 토스증권은 모의투자가 없어서 실제 돈이 나감. 공개 서버(bamsai.kr)는 꺼두고 미리보기만 함. 남의 계좌로 대신 주문하지 않음. 실주문은 각자 이 저장소를 직접 띄우고 본인 토스증권 키·허용 IP· |
'국내 시장' = 정규장 + 넥스트레이드 (08:00–20:00) | 개인이 실제로 거래할 수 있는 시간 전체. 15:30~20:00 넥스트레이드 움직임은 이미 국내에서 보이는 정보라, 이걸 예측으로 치면 실력이 부풀려짐. 그래서 기준은 20:00 마지막 가격, 대상은 08:00 재개장 가격 |
08:00~08:10 평균 가격으로 채점 | 첫 체결 한 건은 거래가 적어 튐. 5·10·30분 평균과 정규장 09:00을 비교해 가장 안정적인 10분 평균 선택 |
예측 모델은 단순 선형 + 정규분포 | 표본이 종목별 140번 남짓이라 복잡한 모델은 과적합. 설명할 수 있어야 초보가 믿음(H3). 계수 β는 1(하이퍼리퀴드 그대로) 쪽으로 당겨서 급락일 몇 번에 휘둘리지 않게 함. 계산법은 3장 '예측 계산법' |
장 열리기까지 남은 시간만큼 범위를 넓힘 | 금요일 밤 예측과 월요일 07:59 예측의 확신이 같으면 안 됨. 닫힌 시간대 하이퍼리퀴드 변동성 × 남은 시간 반영 |
홈 → 종목 상세 한 갈래 | 요약/상세 모드를 따로 두면 같은 정보가 두 번 나오고 '뭐가 다르지?' 고민이 생김. 초보 질문 2개("밤사이 해외에선 얼마나 움직였어?", "지금 남는 돈 있어?")는 홈 카드에서 답하고, 종목 상세에서는 같은 답을 차트 위 해당 가격에 붙여 보여줌 |
예측시장은 v2로 미룸 | 국내 사행성 규제 소지, 금융당국이 해외 perp 이용에 경고한 상황. 먼저 예측 정확도와 신뢰를 쌓는 게 순서 |
화면 주문은 '출시 예정' + 알림 신청, API는 기본 미리보기(dryRun) | 프로토타입에서 실수 주문 0건이 우선. 대신 주문 버튼 클릭과 알림 신청으로 실제 수요(H4)를 잼. API 실주문은 서버 토큰 + 명시적 전환 필요, perp는 테스트넷 기본 |
API의 perp 주문은 에이전트 키로만 서명 | 메인 지갑 키가 서버에 들어오지 않음. 에이전트는 주문만 가능, 출금 불가 |
MCP는 조회 + 미리보기만 | 에이전트 오작동이 실제 돈으로 이어지지 않게 |
뉴스는 하루 1건, 출처 있는 것만 | 차트가 뉴스로 덮이면 안 됨. 틀린 뉴스 1건이 신뢰를 다 깎음 |
차트는 TradingView lightweight-charts | Skia(CanvasKit)는 wasm만 수 MB라 첫 화면이 느려짐. 캔버스 기반, 약 57KB(gzip), 거래소에서 검증된 라이브러리. 종목 상세에서만 내려받음 |
디자인 토큰은 토스증권 PC, 키컬러·CTA만 카카오페이 | 카카오페이증권은 PC 버전이 없어서, 간편한 UX로 잘 알려진 토스증권 PC를 참고. 증권 사용자가 이미 익숙한 정보 밀도와 컴포넌트(패널, 칩, 호가, 검색, 필터). 하이퍼리퀴드는 그쪽 키컬러에 가까운 민트로 구분. 브랜드 구분은 노랑(#FFEB00) 하나로 충분. 폰트는 토스 전용 서체 대신 가장 가까운 공개 서체 Pretendard |
React 19.3.1 / Vite 8.3.5 | 최신 패치 버전이면서 실사용 2위 버전. 2025~26년 React 보안 이슈는 서버 컴포넌트 한정이라 SPA는 해당 없음. Vite는 10월 보안 패치 포함 버전 |
7. GTM
단계 | 기간 | 대상 | 채널 | 넘어가는 조건 |
0-A. MCP 목록 등록 | 상시 | LLM 자동매매 봇 운영자 (초기 타겟) | 공식 MCP Registry·Glama 등록(11/6), awesome-mcp-servers·awesome-remote-mcp-servers 추가 PR, AI 검색 유입(GEO·llms.txt) | 주간 외부 호출자 증가 (H5) |
0-B. 커뮤니티 실험 | 4일 | 디시 주식·종목 갤러리 사용자 (확장 타겟) | 국내 시장 마감(20:00) 후 게시글 3회 (UTM 분리) | 개장 전 재방문 15% |
1. 홈 공개 | 4주 | 삼성전자·하이닉스 보유자 | 개장 전 07:00 알림(미국장 마감 뒤: "삼성전자 하이퍼리퀴드 −2.1%, 과거 이 시간대엔 87%가 이 방향대로 열렸어요"), 증권 앱 종목 페이지 진입점 | North Star 주 1만 명, H2 재방문 30% (가정. 첫 실험·인터뷰 결과로 다시 정함) |
2. 종목 상세 주문 | 4주 | 주식·코인 겸업 트레이더 | 업비트·하이퍼리퀴드 커뮤니티, 주말 갭 리포트 콘텐츠 | H4 전환 5% |
3. 봇 운영자 확대 | 상시 | 초기 타겟 | 하이퍼리퀴드·퀀트 커뮤니티, 예제 봇 저장소 | H5 주 1,000회 |
메시지: "장 열리기 전에 먼저 보세요" (가격 정보가 아니라 '시간'을 파는 서비스)
훅 콘텐츠: 연휴 끝 개장 전날 "연휴 동안 해외에서 삼성전자 -3.7%, 내일 장 시작 가격은?" (2026-10-18 주말 사례처럼 큰 갭이 생기는 날이 가장 강한 획득 시점)
증권사 입장에서의 가치: 해외 perp로 빠져나가는 수요를 '국내 주식 장 시작 가격 판단' 쪽으로 되돌림. 주문은 국내 주식으로 연결
검색·AI 검색 유입 (SEO · GEO · llms.txt)
장 시작 전 "삼성전자 야간 시세", "하이닉스 장전", "하이퍼리퀴드 삼성전자"를 검색하거나 AI에게 묻는 사람이 그대로 들어오게 함
항목 | 한 것 |
페이지별 정적 HTML | 빌드할 때 홈·소개·API·종목 7개 페이지마다 제목·설명·canonical·공유 미리보기·크롤러용 요약이 다른 HTML을 만듦( |
구조화 데이터 | 홈: WebApplication + FAQ(서비스 설명·적중률·환산 방식·API). 나머지: WebPage + 경로(Breadcrumb) |
sitemap · robots | sitemap은 빌드마다 갱신일을 새로 씀. robots는 주문·계좌 API만 막고 GPTBot·ClaudeBot·PerplexityBot·Google-Extended를 명시적으로 허용 |
llms.txt | 서비스 요약, 지원 종목, 계산 방법과 수치(기준일 표기), API·MCP 사용법, 페이지 안내를 AI가 읽기 쉬운 형식으로 공개 |
에이전트 접근 | OpenAPI 문서( |
검색엔진 등록 | 2026-11-06 구글 서치콘솔(도메인 속성, DNS 확인)과 네이버 서치어드바이저(HTML 태그 확인)에 등록. 구글은 sitemap 제출 성공, 페이지 10개 발견 |
8. 다음 액션 (개선 포인트)
예측시장: "월요일 장 시작 가격 +2% 이상?" 같은 질문에 사용자 예측을 받아 모델과 비교 (포인트 기반, 현금 없음)
개장 전 알림 (웹 푸시 / 카카오 알림톡)
개인 주문 이벤트 실시간 구독 (토스증권
personal:order웹소켓)예측 대상 확대: 지금은 가격만 보여주는 코스피200·EWY·KORU·ADR에도 국내 비교 기준을 만들어 예측 적용 (예: 코스피200 선물·ETF 시세)
오라클 가격 괴리 방어 (2026-07-28 사례는 한계 메모 참고)
밤사이 가격·적중률: 08:00 직후처럼 오라클 기준이 바뀌는 시각에는 순간 가격 대신 거래량 가중 평균을 씀. 호가 중간값·표시 가격·오라클 가격의 차이가 기준을 넘거나 체결 수가 극히 적은 급변 구간은 '가격 불안정'으로 표시하고, EWY·코스피200 perp 방향과 크게 다르면 경고. 급변 구간이 일정 시간 이상 이어질 때만 숫자에 반영
시세차익: 숨기지 않고 하이퍼리퀴드 실제 호가로 그대로 계산함(그 가격에 실제로 체결되므로). 대신 '오라클 이상 구간: 추가 급변 시 청산 위험' 경고와 낮은 레버리지 안내를 붙이고, 국내 쪽은 호가 잔량이 있는 가격만 씀
AI 에이전트 자동 시세차익 봇 (아이디어): 사용자가 자기 AI 에이전트(어떤 LLM이든)에 밤사이 MCP를 붙여, 두 시장 차이가 평소보다 벌어져 비용을 빼고도 남을 때 시세차익 페어 주문을 대신 준비하게 함
흐름:
get_arbitrage로 감시 → 순차익이 사용자가 정한 기준(예: 1천만원당 3만원)을 넘으면preview_pair_order로 주식 수량·하이퍼리퀴드 주문을 계산 → 사용자에게 승인 요청 → 승인하면 사용자 본인 서버·본인 키로 실행안전장치: 기본은 승인 후 실행, 1회·하루 금액 한도, 레버리지 상한(예: 2배), 국내 장 마감 전 청산 규칙, 공매도가 필요한 방향은 제외
먼저 확인할 것: 호가 잔량을 넣은 실제 체결 기준 수익, 두 주문 사이 체결 시차 위험, 투자일임·자문 규제에 걸리지 않는 범위(사용자가 직접 정한 규칙을 사용자 계좌에서 실행)
AI 활용 과정
Claude Code(Opus 5.5)와 대화하며 기획부터 배포까지 진행
AI로 만든 것과 제품 안의 계산은 다름
AI는 개발 도구로만 씀: 리서치, 데이터 검증, 백테스트 코드 작성·분석, 구현, QA
화면과 API의 숫자는 전부 실제 시세 데이터로 통계 계산이 만듦. 서비스 실행 중에 LLM API를 부르지 않고, LLM이 금융 수치를 만들거나 바꾸지 않음
단계 | AI가 한 일 | 사람이 한 일 |
리서치 | 하이퍼리퀴드 API를 직접 호출해 한국 종목 perp 목록·상장일·호가 확인. 토스증권 OpenAPI·AsyncAPI 스펙을 받아 엔드포인트·웹소켓 확인. HIP-3 수수료 구조 문서 확인 | 아이디어(perp ↔ 국장 차익, 개장 예측), 범위 결정 |
사실 확인 | 서브 에이전트가 2026년 주요 이슈 25건을 출처와 함께 조사 → 차트 뉴스로 사용 | 사용할 이슈 기준 결정 (하루 1건) |
검증 | 삼성전자 perp 환산가(204,919원)와 KRX 현재가(204,750원)를 비교해 환산 방식 검증. 토스 일봉이 넥스트레이드 포함 통합 시세라 KRX 종가와 다르다는 점(218,000원 vs 221,500원)을 찾아 분봉 기준으로 수정 | 원/USDC(업비트) 사용 결정 |
모델 | walk-forward 백테스트 작성, 사전분포 강도 5가지 비교 후 선택. 채점 기준을 넥스트레이드 포함 '국내 시장'으로 다시 정하면서 시작 가격 정의 5가지(08:00 첫 체결·5분·10분·30분 평균·09:00)를 같은 기간으로 다시 채점해 비교 | 지표 해석, 공개 방식 결정. "개인이 거래할 수 있는 가장 이른 시간부터 가장 늦은 시간까지가 국내 시장"이라는 기준 제시 |
디자인 | 토스증권 PC 화면에서 디자인 토큰(배경 | 토스 PC 기준·키컬러만 카카오페이로 방향 지정, 로고 콘셉트(구름·초승달·호버 시 노란 화살표) 제안 |
구현·QA | 서버·프론트 구현. 바꿀 때마다 AI가 Chrome을 직접 띄워 화면을 누르고 스크린샷·콘솔·네트워크 요청을 확인(예: 1분봉 3분 관찰로 새 봉이 밀리는지, iPhone Safari 조건으로 로딩되는지) → 차트 새 봉·깜빡임, 마커 과밀 등 수정. 이 확인 흐름을 E2E 테스트로 옮겨 PR마다 자동 실행 | 문구·UX 리뷰 |
보안 | React·Vite 버전별 보안 권고(GitHub Advisory) 조회 후 버전 선택 | 최종 승인 |
판단 교정 | 커뮤니티 글에 저녁 9시 '내일 시초가 +0.3%'를 썼다가 실제 −11.9%로 시작 → 밤 시각별 적중률을 상장 이후 전체로 다시 계산해 21시 49% vs 06시 86~87%를 찾음 | "미국장 끝난 뒤 가격으로 봐야 한다", "오를 확률 대신 담백하게 과거 비율로" 방향 결정 |
채택·거절 | 외부 AI 리뷰 피드백을 근거로 하나씩 검토: North Star 시간대 불일치(채택), 거래대금 기준 민감도 표(채택), 확률 보정 검증(향후 과제로 분리), AI 야간 브리핑(거절: LLM API 운영 비용과 수치 생성 위험) | 최종 선택 |
운영 버그 | 아이폰 사파리 조건으로 API를 반복 요청해 CDN이 zstd 응답을 잘못 내보내는 문제를 찾고, 서버가 직접 gzip 압축하도록 수정. 토스 한도 초과는 1분 단위 그룹별 호출 집계 로그를 만들어 원인(지수 미니차트가 며칠치 분봉을 10초마다 다시 받음)을 찾고 고침 (README '운영하며 고친 것') | 배포 승인, "접속자가 늘면?" 관점 제시 |
사용자 관점 점검 | API 14개·MCP 도구 5개를 실서버에서 직접 호출해 문서와 대조 → MCP 종목 검증 누락(ADR에 +48%), OpenAPI의 잘못된 출처 표기 등 수정 | "우리 계좌로 주문이 나가면 안 된다" 기준 제시, 실주문 경로 확인 지시 |
데이터 출처 검토 | KRX·공공데이터·한국은행·증권사 API를 조사해 비교, 토스 약관(시세는 본인 매매 목적만)을 찾아 한계로 문서화 | 공개 화면 축소는 보류, 문서 명시로 결정 |
실행 방법
npm install
cp .env.example .env.local # TOSS_CLIENT_ID / TOSS_CLIENT_SECRET 입력 (토스증권 WTS > 설정 > Open API)
npm run dev # 웹 http://localhost:5173 (API는 배포 서버 bamsai-api.fly.dev 사용)
npm run dev:local # 서버 코드 수정 시: 로컬 API http://localhost:8787/api 도 실행. 켜는 동안 배포 서버의 토스 토큰이 끊김 (토스 키는 하나뿐이고 새 토큰이 이전 토큰을 무효화)
npm run mcp:stdio # MCP를 표준 입출력으로 실행 (Claude Desktop 등 로컬 프로세스로 붙이는 클라이언트용). 조회 도구는 키 없이 동작
npx tsx --env-file=.env.local server/scripts/backtest.ts # 백테스트 결과 출력 (서버를 끄고 실행: 토스 토큰이 서로를 무효화함. 서버가 켜져 있으면 /api/v1/convergence로 확인)
npx tsx --env-file=.env.local server/scripts/build-sessions.ts # 지난 국내 시장 하루 가격(20:00 마지막 가격·08:00~08:10 평균·정규장 시작·종가) 저장 (배포 전, 서버를 끄고 실행)환경변수 | 용도 | 없으면 |
| 토스증권 Open API (국내 시세·호가·실시간·주문) | 국내 시세 없음 |
|
| API는 미리보기만 |
| 서버 API로 perp 주문 | API perp 주문은 미리보기만 |
|
| 테스트넷만 |
| 외부(에이전트)에서 실주문 API를 부를 때 인증. 화면에서 누르는 주문엔 필요 없음 | 외부 실주문 불가 |
| GA4 측정 | 이벤트 전송 안 함 |
| 주문 출시 알림 이메일을 쌓는 구글 시트(Apps Script 웹앱, docs/launch-notify) | 신청 수만 GA에 기록 |
| 서버가 외부 API·MCP 호출을 GA4 | 서버 로그에만 남음 |
GA4 설정
가설별 실험 계획·결과 기록과 GA 이벤트·파라미터 전체 목록(어느 화면에서 언제 보내는지)은
docs/experiments/에 정리함
Google Analytics → 관리 → 속성 만들기 → 웹 스트림 추가 → 측정 ID(
G-…) 복사Vercel 환경변수
VITE_GA_ID에 넣고 재배포관리 → 맞춤 정의에 등록
이벤트 범위:
kst_window,asset,from,market,tab,mode,side,api_path,caller,mcp_call사용자 범위:
first_source,first_content주요 이벤트(전환):
launch_notify_signup,order_submit,model_explain_open
탐색 → 코호트 탐색: 코호트 =
first_source, 재방문 조건 =page_view중kst_window = preopen커뮤니티 글 링크 예시:
https://bamsai.kr/?utm_source=dc_stock&utm_medium=community&utm_campaign=bamsai_test1&utm_content=smsn_thu_A
사용한 외부 API
출처 | 쓰는 곳 |
토스증권 Open API | 현재가, 호가, 1분봉·일봉, 지수(코스피·코스닥), 장 운영 캘린더, 투자자별 매매, 실시간 체결·호가(웹소켓), 주문·취소, 보유 주식, 매수 가능 금액, 계좌 |
하이퍼리퀴드 (trade.xyz HIP-3) | perp 시세·펀딩·미결제약정, 나스닥 100·S&P 500(국내 정규장 밖 상단 지표), 캔들, 호가, 펀딩 이력, 실시간 WS, 주문·취소·레버리지·에이전트 승인 |
업비트 | 원/USDC 호가·캔들, 실시간 WS |
구조
server/ Hono API (Fly.io, 고정 IP). sources=외부 API, services=차익·예측·주문
shared/ 서버·브라우저 공통 (종목, 장 시간, HL 주문 서명)
src/ React 웹앱. pages=홈·종목 상세·소개(계산 방법)·API, pro=차트·호가·주문
docs/ experiments=가설별 실험 계획·결과·GA 이벤트 연결테스트와 장애 대응
구분 | 내용 |
AI 브라우저 QA | 화면을 바꿀 때마다 AI(Claude Code)가 Chrome을 직접 띄워 누르고, 스크린샷·콘솔 에러·네트워크 요청으로 확인한 뒤 PR을 올림 |
단위 테스트 (vitest, 27개) | 시세차익(호가 체결가·부분 체결·주문 간 시차), 장 시간·휴장일, 미국장 단계(서머타임), IP당 호출 제한, 토스 그룹별 한도, 헬스체크 |
E2E (Playwright, 7개, 약 6초) | 녹화한 API 응답, 테스트가 직접 보내는 시세 웹소켓, 고정한 시계로 시장 상황과 무관하게 같은 결과. ① 홈 카드·시세차익 줄 ② 금 19:59 → 20:00 넘기면 장중 라벨이 '국내 종가'·'지금 글로벌 가격'으로 바뀜 ③ 차트 드래그·휠 확대·1시간봉·시장 끄기/켜기·RSI 패널 ④ 1분봉 다음 분 tick → 새 봉이 생기고 오른쪽 여백을 유지한 채 밀림, 늦게 온 서버 분봉이 새 봉을 지우지 않음 ⑤ 매수 버튼 → 출시 알림 신청, 실제 주문 요청 0건 ⑥ 소개·API 페이지(MCP 설정 복사). 매 테스트마다 콘솔 에러 0건 확인 |
CI (GitHub Actions) | PR·push마다 타입 검사 → 단위 테스트 → 빌드 → E2E |
커버리지 | 전체 소스 기준 문장 약 9%. 돈이 걸린 계산(시세차익)과 시간 처리(장 시간·미국장 단계) 위주로 단위 테스트를 두고, 화면 흐름은 E2E로 확인. 다음: 예측·채점( |
헬스체크 |
|
장애 대응 런북 |
|
운영하며 고친 것 (시스템)
배포 후 실제로 돌려 보며 찾은 문제와 고친 방법. 숫자는 Fly 서버 로그와 직접 측정 기준.
날짜 | 문제 | 원인 | 고친 방법 | 결과 |
11/6 | iPhone 등 일부 브라우저에서 화면이 계속 로딩 | Vercel CDN이 zstd로 압축된 API 응답을 캐시해서, zstd를 못 읽는 브라우저에도 그대로 줌 | API 서버가 직접 gzip으로 압축 | iPhone Safari 프로필 15회 요청 모두 정상 |
11/6 | 봇·과도한 호출에 비용 위험 | 호출 제한 없음 | IP당 1분 300회(REST·MCP 합산), 넘으면 429 | 화면 하나가 1분 약 55회라 여러 탭도 여유 |
11/6 | 국내 시세가 가끔 비거나 502 | 토스 API는 그룹별 초당 한도(캔들 20, 지수 캔들 5 등)가 있는데, 화면 하나가 여러 API를 동시에 부르고 접속자가 겹치면 넘침 | 토스 호출을 API 그룹별 대기열로 공개 한도보다 낮게 보냄(지수 캔들 4/초, 캔들 15/초 …). 한도 초과 시 1·2·3초 간격 재시도. 1분마다 그룹별 호출·초과 수를 로그로 남김 | 1~2초마다 나던 한도 초과 → 분당 0~2회. 재시작 직후 1분에 캔들 423회도 초과 0 |
11/6 | 접속자가 늘면 토스 호출도 늘까 | 분봉을 몇 초마다 며칠치 통째로 다시 받음(지수 미니차트만 1분 약 50회) | 서버 캐시는 모든 접속자가 공유. 과거 봉은 10분(일봉 1시간) 캐시하고 최신 200개만 10초마다 받아 합침. 같은 요청은 한 번만 | 토스 호출은 접속자 수가 아니라 종목 × 봉 간격 수에 비례 |
11/6 | '개장 직전 글로벌 가격'이 낮 동안 바뀜 | 8시 달러 가격에 '지금' 환율을 곱함 | 그 시각의 업비트 USDC 시간봉 환율로 환산 | 삼성 8시 가격 181,791 → 182,326원(8시 환율 1,364원)으로 고정, 백테스트 기록과 일치 |
11/6 | 차트 새 봉이 안 밀리고 가격표에 가려짐, 직전 봉 깜빡임 | 시작 위치가 마지막 봉을 오른쪽 끝에 붙임 / 실시간 봉이 미래 빈칸을 채움 / 늦게 오는 서버 분봉이 실시간 봉을 덮어씀 | 오른쪽 여백 화면 폭 12%(80~160px), 새 봉마다 같은 간격으로 밀기, 실시간 봉을 보관해 서버 데이터에 이어 붙이기 | 1분봉 3분 관찰: 여백 유지, 봉 사라짐 없음 |
11/6 | MCP에 SK하이닉스 ADR을 넣으면 '+48%' 같은 엉터리 값 | REST는 막았지만 MCP는 종목 검증이 없었음 | REST와 같은 규칙으로 국내 주식만 받음 | 이유와 함께 오류 응답 |
11/6 | 토스 토큰 발급 429 때 API 서버가 종료 | 캔들 두 요청 중 하나를 기다리는 동안 다른 쪽 실패가 처리되지 않은 오류가 됨 | 두 요청을 함께 기다리도록 수정 | 실패해도 오류 응답만 내고 서버는 유지 |
11/6 | 화면이 서버보다 먼저 배포되면 시세차익이 '+NaN원' | 새 응답 필드가 없을 때 대비가 없었음 (E2E가 발견) | 이전 필드로 대신 표시 | E2E 통과 |
11/6 | API·MCP를 누가 얼마나 쓰는지 모름 (H5) | 서버 로그에만 잠깐 남음 | 외부 호출을 GA4 | GA 실시간에서 확인 |
한계 메모
국내 시세 이용 조건: 토스증권 오픈 API 약관(제3조 ③)은 시세를 "개인투자자 본인의 매매 목적에 한하여" 쓰고 제3자 제공·배포·상업적 활용을 하지 않도록 정함. 공개 사이트로 국내 시세를 보여주는 이 프로토타입은 이 조건을 넘을 수 있음. 실제 서비스는 증권사가 이미 계약한 정식 시세(코스콤 등 시세 제공업체)를 쓰는 것을 전제로 함. 무료 공공 출처(KRX Open API, 공공데이터포털 금융위 주식시세)는 일별·T+1 데이터라 저녁 8시 넥스트레이드 종가와 아침 8:00~8:10 분봉을 대신할 수 없음
하이퍼리퀴드 한국 주식 perp와 오라클: 2026년 2월 상장 후 거래가 성장세(SK하이닉스 perp 월 거래대금 3월 1.2억 달러 → 10월 70억 달러, 시장 상황에 따라 월별 변동. 11/6 기준 trade.xyz 주식 perp 전체 24시간 거래대금 약 96억 달러). 다만 perp 가격은 오라클(기초 시장이 열려 있을 땐 외부 체결가, 닫혀 있을 땐 자체 계산 가격)에 묶여 있음. 2026-07-28 08:00 넥스트레이드 프리마켓에서 SK하이닉스 1주가 하한가(127만 2천 원, −29.99%)에 체결되자 이 가격이 오라클에 들어가 perp가 17.9% 급락했고, 약 5,700만 달러의 롱이 청산됨(보도 기준). 거래가 얇은 시점의 체결 하나로 청산을 일으키고 반대편에서 이익을 내는 것이 구조적으로 가능하다는 뜻(국내에서는 시세조종에 해당할 수 있음). 밤사이의 비교 시점(08:00)과 같은 시각이라 영향을 받음
토스증권 API는 그룹별 초당 한도(캔들 20, 현재가 15, 지수 캔들 5 등)가 있어 서버가 그룹마다 한도 아래로 줄 세움. 몰리면 국내 시세 갱신이 잠깐 늦어질 수 있음
시세차익의 호가 잔량은 받아 오는 호가 단계까지만 반영(보이지 않는 잔량은 모름). 주문 간 시차 비용은 변동성 기반 근사값
토스증권 API는 허용 IP에서만 호출 가능. 서버 IP가 고정이어야 함
토스증권 토큰은 새로 발급하면 이전 토큰이 바로 무효 → 서버는 한 대(한 프로세스)로 운영
토스증권은 동시호가 예상체결가를 주지 않아 개장 직전 예상가는 perp 기준만 표시
서버 메모리 캐시라 인스턴스가 바뀌면 백테스트를 다시 계산함 (첫 요청 수 초)
하이퍼리퀴드 API는 간격별로 최근 캔들 5,000개만 보관 → 08:00 가격이 필요한 1시간봉은 약 7개월치. 그래서 채점 기간이 2026-04-13부터이고, 서버가 매일 쌓으면 길어짐
넥스트레이드 08:00 직후는 거래가 적어 10분 평균도 가끔 튈 수 있음. 현대차처럼 거래가 적은 종목은 영향이 더 큼
투자 권유가 아닌 참고 정보. 해외 perp는 국내 투자자 보호 대상이 아님
Available Tools
5 toolsget_arbitrageCInspect
Premium between Hyperliquid perp (mid) and KRX price, its usual level (5-day regular-session median) and the net left after costs on the gap beyond that level. net.netPct subtracts fees, tax, FX, funding, order-book slippage for notionalKrw (net.costs.slippage, net.fills: volume-weighted fill prices per leg) and the price move during the gap between the two orders (net.costs.latency = 1-minute volatility × √(lagSec/60)). net.depthLimited / net.maxNotionalKrw: the visible book can fill less than notionalKrw. All assets if asset is omitted
| Name | Required | Description | Default |
|---|---|---|---|
| asset | No | SMSN=Samsung Electronics, SKHX=SK hynix, HYUNDAI=Hyundai Motor, SKHY=SK hynix ADR (vs 0.1 common share) | |
| lagSec | No | Seconds between the two orders (default 3) | |
| notionalKrw | No | Trade size per leg in KRW (default 10000000) |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full behavioral burden. It does disclose the cost model in detail (fees, tax, FX, funding, order-book slippage scaled to notionalKrw, and latency as 1-minute volatility times sqrt(lagSec/60)) plus the depth-limited/maxNotionalKrw condition, which is genuinely useful. But it never states that this is a read-only calculation with no side effects, and it gives no indication of data freshness, market-hours restrictions, or error behavior for an illiquid asset.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Density is high and nearly every clause carries technical content, but it is written as a run-on chain of noun fragments with dotted field paths (net.netPct, net.costs.latency) and no front-loaded statement of what the tool returns overall. The most important qualifier, 'All assets if asset is omitted', is buried in the final position.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description sensibly spends most of its budget defining the returned net.* fields, which is the right call for a three-parameter calculator. What is missing is scope framing: whether this is a snapshot or time series, how it relates to get_convergence_history and preview_pair_order, and whether illiquid assets return an error or a depth-limited flag.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents asset, lagSec, and notionalKrw, making 3 the baseline. The description does add real semantics by linking notionalKrw to net.costs.slippage and net.depthLimited, and lagSec to the latency cost term, which is meaning the schema does not convey; that lifts it just above baseline rather than far above it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the exact quantities produced: the premium between the Hyperliquid perp mid and the KRX price, its 5-day regular-session median baseline, and the post-cost net on the gap. That is specific enough to distinguish it as a spread/cost calculator, but it never names the closest sibling (preview_pair_order, get_convergence_history), so the agent must infer the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no exclusions, and no pointer to an alternative tool. The only routing-like statement, 'All assets if asset is omitted', is a parameter default behavior rather than a usage rule, leaving the agent to guess whether this is a screening call or an execution-preview call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_convergence_historyAInspect
Past re-open record per day since 2026-04-13: Hyperliquid move while closed (20:00→08:00), actual re-open move, follow (yes/no/flat), and where the prices met. Newest first, 20 days unless limit is given
| Name | Required | Description | Default |
|---|---|---|---|
| asset | Yes | SMSN=Samsung Electronics, SKHX=SK hynix, HYUNDAI=Hyundai Motor | |
| limit | No |
TDQS
A3.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the fixed start date (2026-04-13), the default window (20 days unless limit is given), the sort order (newest first), and the exact columns returned. It stops short of declaring read-only semantics or what happens when an asset has no records in range.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The content is front-loaded and dense with no filler, packing the time window, record fields, ordering, and default limit into one compact statement. The telegraphic '20:00→08:00' notation and the phrase 'where the prices met' are slightly cryptic but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must explain return values, and it does so by listing the recorded fields and their ordering. Combined with the disclosed time window and default limit, an agent has enough to call the tool, with only the limit unit and empty-result behavior left unresolved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The asset enum is fully documented in the schema, but limit has no schema description; the description supplies its default ('20 days unless limit is given') yet leaves the unit ambiguous — days of history versus number of rows. That partially compensates for the 50% coverage but doesn't fully resolve the parameter's meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource (past re-open records, per day) and enumerates the recorded fields: Hyperliquid move while closed, actual re-open move, follow flag, and meeting price. The historical framing ('Past ... record') implicitly separates it from the predictive sibling predict_open, though the contrast is never made explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: 'Past' signals this is the retrospective counterpart to predict_open, but the description never states when to pick this over get_arbitrage or predict_open. There are no stated prerequisites or exclusions, leaving the agent to infer the historical-vs-predictive split from the wording alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_newsCInspect
Top issue per day for an asset (1 per day)
| Name | Required | Description | Default |
|---|---|---|---|
| asset | Yes | SMSN=Samsung Electronics, SKHX=SK hynix, HYUNDAI=Hyundai Motor, SKHY=SK hynix ADR (0.1 share), KR200=KOSPI 200, EWY=MSCI Korea ETF, KORU=3x Korea ETF |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses cardinality (one issue per day) and scope (per asset), but omits whether it is read-only, what date range is returned, whether results are empty when no news exists, and what the response format looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with little wasted wording. The parenthetical '(1 per day)' slightly repeats 'per day', but it usefully clarifies cardinality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with a fully documented enum, the description gives the minimum viable context: scope and cardinality. However, with no output schema and no annotations, it should clarify the time horizon and return format more explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the asset enum includes a detailed ticker-to-company mapping. The description adds no meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource and scope: top issue per day for a given asset, with cardinality of one per day. It is clear enough to identify the tool's purpose, but it does not explicitly say 'news' or differentiate itself from the sibling analytics tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance, no when-not-to-use guidance, and no mention of alternatives among the sibling tools. The description only implies that the tool is for retrieving daily top issues for an asset.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
predict_openAInspect
Where the next domestic re-open (08:00–08:10 average on KRX/NXT, vs the 20:00 close) stands, for SMSN/SKHX/HYUNDAI. While the domestic market trades, status=in-session and preOpen is Hyperliquid at today's 08:00 open. Otherwise: the Hyperliquid price in KRW now and at the US close, how often past re-opens followed Hyperliquid at this stage of the night (night.follow.ratePct), the 80% band, and the overall follow rate (backtest.followRatePct). probUp and the expected price are model output, not a promise
| Name | Required | Description | Default |
|---|---|---|---|
| asset | Yes | SMSN=Samsung Electronics, SKHX=SK hynix, HYUNDAI=Hyundai Motor |
TDQS
A3.6/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does substantial work: it discloses the in-session branch semantics (preOpen = Hyperliquid at today's 08:00 open), the off-hours payload (current KRW price, US-close price, historical follow statistics, 80% band), and explicitly warns that probUp and the expected price are model output rather than a promise. It omits operational traits like latency, caching, or data freshness beyond the market-state split.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The two modes are reasonably front-loaded, but the prose is a dense run-on mixing field paths (night.follow.ratePct, backtest.followRatePct) with domain jargon. The information earns its place, yet restructuring into short bulleted branches would make it far easier to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must convey return content, and it does list the key outputs (preOpen, current KRW price, US-close price, follow rate, 80% band, probUp, expected price). Combined with the market-state branching, an agent has enough to call it and interpret results, though exact field names and shapes remain partly implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single enum parameter already documents SMSN=Samsung Electronics, SKHX=SK hynix, HYUNDAI=Hyundai Motor. The description restates the same tickers without adding new meaning about the parameter, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete subject (the next domestic re-open at 08:00–08:10 on KRX/NXT versus the 20:00 close) and the exact assets covered (SMSN/SKHX/HYUNDAI), so the agent knows precisely what is being predicted. It does not explicitly distinguish itself from siblings like get_arbitrage or get_convergence_history, which keeps it out of the top band.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies usage by explaining the two regimes (while the domestic market trades vs. otherwise), which effectively tells the agent what it will get in each situation. However, there is no explicit when-to-use guidance, no statement of when not to call it, and no routing to alternatives such as get_arbitrage or get_convergence_history.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
preview_pair_orderAInspect
Preview (dry-run) of an arbitrage pair order: stock quantity and the Hyperliquid order it would send. Nothing is ever sent from this server. Hyperliquid side is priced on testnet (the default network), so its price can differ from mainnet
| Name | Required | Description | Default |
|---|---|---|---|
| asset | Yes | SMSN=Samsung Electronics, SKHX=SK hynix, HYUNDAI=Hyundai Motor, SKHY=SK hynix ADR (0.1 share), KR200=KOSPI 200, EWY=MSCI Korea ETF, KORU=3x Korea ETF | |
| direction | Yes | ||
| notionalKrw | Yes | Trade size in KRW. get_arbitrage with the same notionalKrw shows the expected fill prices, slippage and net for this size |
TDQS
A3.6/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations supplied, the description carries the safety burden itself and does so: "Nothing is ever sent from this server" establishes the read-only, non-mutating nature. It also discloses a non-obvious behavioral trait — pricing is on Hyperliquid testnet by default, so prices can diverge from mainnet — which an agent would otherwise misreport as a live quote.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with what the tool is, then what it returns, then the two caveats. No filler or repetition; the density is appropriate for a preview operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotations, so the description must cover the return shape and safety alone — it handles safety well and sketches the return values in one clause, but leaves the response structure, the derivation of the stock quantity, and the direction semantics unaddressed. Adequate but with clear gaps for a three-required-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%: asset and notionalKrw are documented in-schema, while direction has only self-describing enum values. The description adds essentially nothing about parameters beyond echoing "stock quantity" and the order payload, and does not clarify which leg is perp versus stock per direction value. Baseline 3 fits given partial schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
"Preview (dry-run) of an arbitrage pair order" gives a specific verb and resource, and the follow-on clause states what the caller gets back: stock quantity plus the Hyperliquid order that would be sent. It does not name a sibling tool to contrast with in the main body (only the notionalKrw schema note references get_arbitrage), so it falls short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The dry-run framing implies "call before committing," which is useful implied context, but the description never states an explicit when-to-use rule or an exclusion. The only routing hint is buried in the schema: get_arbitrage with the same notionalKrw shows fill prices, slippage and net, so the split of responsibilities between the two tools is left for the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
v0.1.0- First observed
get_arbitrage - First observed
get_convergence_history - First observed
get_news - First observed
predict_open - First observed
preview_pair_order
TDQS
A3.5/5.0
Scored across 5 tools
Disambiguation5/5
Each tool has a clearly distinct role: prediction of re-open, current arbitrage premium/cost, historical convergence, news, and dry-run pair-order preview. Although predict_open and get_arbitrage both involve current Hyperliquid/KRX pricing, their outputs and purposes are described distinctly enough to avoid misselection.
Naming Consistency4/5
All names use snake_case verb_noun style and are readable. The verb set is mostly get_* plus predict_open and preview_pair_order, which is a minor but acceptable deviation.
Tool Count5/5
Five tools is well-scoped for this niche arbitrage/prediction server. Each tool covers a distinct part of the workflow without obvious filler.
Completeness4/5
The surface covers prediction, current arbitrage economics, historical follow-through, news context, and order preview. Actual order execution is intentionally absent, so the main limitation is advisory-only coverage rather than a missing core operation.
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues
Related MCP Connectors
Read-only Hyperliquid analytics: orderflow, liquidation levels, whale positioning, funding.
Live perp funding rates across 6 venues (Hyperliquid, Binance, Bybit, Lighter...) and arbitrage.
Hyperliquid perp funding, OI, preflight & news sentiment for agents. Pay per call in USDC (x402).
Read-only Hyperliquid smart-money positioning: top-trader bias, flows. Not financial advice.
Related MCP Servers
- AlicenseAqualityBmaintenanceAI-native quantitative trading signal engine for crypto and TradFi perpetuals. Multi-factor composite BUY/SELL/HOLD signals, cross-venue funding rate arbitrage scanning, and market regime detection powered by Hyperliquid data.10644 npm10MIT
- AlicenseNot gradedqualityCmaintenanceRead-only crypto perps microstructure for AI agents: normalized cross-exchange market state (funding + multi-year percentile, OI, volume, CVD, order-book imbalance, liquidations, basis), OHLCV, 15-min state history, and measured conditional outcomes (historical base rates, not predictions) — 6 assets across Binance, Bybit, OKX and Hyperliquid, every metric with self-declared coverage and freshnessMIT
- AlicenseAqualityCmaintenanceRead-only MCP server for the Hyperliquid / HyperEVM ecosystem - yields, protocol TVL, fees, markets, funding history, order-book depth.957 npmMIT