FINCHAL season 1 server

Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.11-slim
+WORKDIR /app
+RUN pip install --no-cache-dir --upgrade pip
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY . .
+# 🔴 HF Space 컨테이너는 재시작하면 파일이 사라진다.
+#    원장이 사라지면 시즌이 통째로 없어진다. 영속 스토리지를 반드시 연결한다.
+ENV FINCHAL_DATA=/data/finchal
+ENV PYTHONUNBUFFERED=1
+EXPOSE 7860
+CMD ["python","-m","uvicorn","app.main:app","--host","0.0.0.0","--port","7860"]

README.md

@@ -1,10 +1,39 @@
 ---
-title: Finchal
-emoji: 🐨
-colorFrom: gray
+title: FINCHAL 파이낸셜 예측 챌린지
+emoji: 🏁
+colorFrom: blue
 colorTo: green
 sdk: docker
-pinned: false
+app_port: 7860
+pinned: true
+license: apache-2.0
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# FINCHAL — AI는 시장을 이길 수 있는가
+
+122일간의 공개 실험. 네 개의 시장, 총 상금 $2,000.
+
+포지션을 제출하면 실제 시세로 모의 매매되어 수익률이 순위에 반영됩니다.
+정답은 미래에 있으므로 과거를 맞추는 방식으로는 이길 수 없습니다.
+
+## 참가
+
+**사람** — 화면의 슬라이더로 포지션을 내면 됩니다.
+
+**에이전트** — MCP 서버를 붙이면 도구 네 개가 생깁니다.
+
+```
+claude mcp add --transport http finchal https://<space>/mcp \
+  --header "Authorization: Bearer <참가키>"
+```
+
+`get_rules` · `get_data` · `submit_position` · `check_score`
+
+## 규칙
+
+- 포지션 −1.0 ~ +1.0, 레버리지 1 고정
+- 매시간 갱신 가능. 다시 낼 때까지 직전 포지션이 유지됨
+- 포지션 변경분에 실거래 수수료 부과
+- 종목별 최종 수익률 1위에게 각 $500
+
+`/llms.txt` 에 에이전트용 요약이 있습니다.

announce_ceiling.json

@@ -0,0 +1,38 @@
+{
+ "season": 1,
+ "opens": "2026-08-24",
+ "closes": "2026-12-24",
+ "days": 122,
+ "method": "블록부트스트랩 5일 · 무작위 포지션 · 레버리지1 · 수수료 반영",
+ "note": "개막 공지용 추정치. 실제 채점은 시즌 실제 경로로 매일 재계산한다.",
+ "ceiling": {
+  "NVDA": {
+   "p50": -0.06322198717446942,
+   "p95": 0.5170854949790162,
+   "p99": 0.86208529355278,
+   "fee": 0.0002,
+   "days": 122
+  },
+  "BTC": {
+   "p50": -0.16992914478643856,
+   "p95": 0.8661647545448895,
+   "p99": 1.6673872469103215,
+   "fee": 0.0006,
+   "days": 122
+  },
+  "GOLD": {
+   "p50": -0.024204711467122608,
+   "p95": 0.09196673224668211,
+   "p99": 0.1406877930906722,
+   "fee": 0.0002,
+   "days": 122
+  },
+  "OIL": {
+   "p50": -0.045836532750657744,
+   "p95": 0.2685994543369719,
+   "p99": 0.4344880361598838,
+   "fee": 0.0003,
+   "days": 122
+  }
+ }
+}

app/anchors.py

@@ -0,0 +1,84 @@
+# -*- coding: utf-8 -*-
+"""기준선 봇 — 참가자와 같은 표에 놓일 척도.
+
+ODC가 승인약과 불활성 화합물을 같은 표에 넣어 척도를 보여주듯,
+리더보드에 기준 전략을 함께 올린다. 척도가 없는 순위표는 읽을 수 없다.
+
+🔴 주최측 모델은 넣지 않는다.
+   이 챌린지의 명분은 "누가 더 나은 예측 모델을 만드는가"이지
+   "주최자가 제일 잘한다"가 아니다. 주최자가 자기 모델을 참가자 표에 올리면
+   그 명분이 흐려진다. 기준선은 척도이지 경쟁자가 아니다.
+
+기준선 셋 — 전부 공개된 교과서 기법이다
+  BUYHOLD    항상 +1. 이걸 못 이기면 아무 의미 없다
+  VOLTARGET  지수가중 변동성으로 크기만 조절. 방향은 롱 고정
+  RANDOM     매일 -1/0/+1 무작위. 바닥
+
+🔑 VOLTARGET 은 방향을 예측하지 않는다.
+   방향 예측은 60개 변수로 다섯 단계에 걸쳐 시험했고 전부 예측력이 없었다.
+   기준선이 방향을 맞히는 척하면, 기각한 것을 공개면에 올리는 셈이 된다.
+   그래서 이 기준선은 '얼마나 크게 들 것인가'만 정한다.
+"""
+import os, sys
+import numpy as np, pandas as pd
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path[:0] = [HERE, os.path.dirname(HERE)]
+import ledger as L
+
+ANCHORS = {
+    "BUYHOLD": "단순 보유",
+    "VOLTARGET": "변동성 타겟팅",
+    "RANDOM": "무작위",
+}
+SPAN = 60
+
+
+def position(kind, px, seed=0):
+    """오늘 잡을 포지션. -1 ~ +1."""
+    if kind == "BUYHOLD":
+        return 1.0
+
+    if kind == "RANDOM":
+        # 날짜를 시드에 넣어 같은 날 같은 값 — 채점이 재현 가능해야 한다
+        g = np.random.default_rng(
+            int(pd.Timestamp.utcnow().strftime("%Y%m%d")) * 97 + seed)
+        return float(g.choice([-1.0, 0.0, 1.0]))
+
+    s = np.log(px).diff().ewm(span=SPAN).std().dropna()
+    if len(s) < SPAN * 2:
+        return 0.0
+    # 목표 변동성 = 그 종목 과거 중앙값. 변동성이 낮으면 크게, 높으면 작게 든다.
+    target = float(s.iloc[:len(s) // 2].median())
+    return float(max(0.0, min(1.0, target / float(s.iloc[-1]))))
+
+
+def run(assets, prices_fn, dry=False):
+    """기준선 셋의 오늘 포지션을 계산해 원장에 넣는다."""
+    if not dry:
+        for name in ANCHORS:
+            L.register(name, ANCHORS[name], "anchor", list(assets))
+    out = []
+    for i, a in enumerate(assets):
+        px = prices_fn(a)
+        if px is None or len(px) < SPAN * 2:
+            continue
+        for name in ANCHORS:
+            p = position(name, px, seed=i)
+            if not dry:
+                L.submit(name, a, p, "anchor")
+            out.append({"anchor": name, "asset": a, "position": round(p, 4)})
+    return out
+
+
+if __name__ == "__main__":
+    import main as M
+    dry = "--dry" in sys.argv
+    rows = run(list(M.ASSETS), lambda a: M.prices(a, "1d", 1500), dry=dry)
+    print("기준선 포지션 %s\n" % ("(모의)" if dry else "제출 완료"))
+    by = {}
+    for r in rows:
+        by.setdefault(r["asset"], {})[r["anchor"]] = r["position"]
+    print("  %-6s" % "종목" + "".join("%12s" % k for k in ANCHORS))
+    for a, v in by.items():
+        print("  %-6s" % a + "".join("%12.3f" % v.get(k, 0) for k in ANCHORS))

app/ledger.py

@@ -0,0 +1,129 @@
+# -*- coding: utf-8 -*-
+"""원장 — 참가자·포지션·점수를 담는다.
+
+파일 기반이다. HF Space 재시작 시 사라지므로 운영에서는 외부 저장소로 옮긴다.
+지금은 구조를 확정하는 게 목적이고, 저장 위치만 바꾸면 되도록 인터페이스를 좁게 둔다.
+
+🔴 포지션은 절대 덮어쓰지 않는다. 매 제출을 append 한다.
+   덮어쓰면 "언제 무엇을 냈는가"가 사라지고, 그게 사라지면 채점을 재현할 수 없다.
+"""
+import os, json, time, hashlib, threading
+from datetime import datetime, timezone
+
+ROOT = os.environ.get("FINCHAL_DATA", os.path.join(os.path.dirname(__file__), "_data"))
+LOCK = threading.Lock()
+
+
+def _p(*a):
+    p = os.path.join(ROOT, *a)
+    os.makedirs(os.path.dirname(p), exist_ok=True)
+    return p
+
+
+def now():
+    return datetime.now(timezone.utc).replace(microsecond=0)
+
+
+def _read(path, default):
+    try:
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+    except Exception:
+        return default
+
+
+def _write(path, obj):
+    tmp = path + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(obj, f, ensure_ascii=False)
+    os.replace(tmp, path)          # 원자적 교체 — 중간에 죽어도 반쪽 파일이 안 남는다
+
+
+# ─────────────────────── 참가자 ───────────────────────
+def make_key(user_id):
+    raw = "%s|%s|finchal" % (user_id, os.environ.get("FINCHAL_SALT", "s1"))
+    return "fc_" + hashlib.sha256(raw.encode()).hexdigest()[:24]
+
+
+def register(user_id, strategy, ptype, assets):
+    """참가 등록. 이미 있으면 전략명·유형만 갱신하고 키는 유지한다."""
+    with LOCK:
+        u = _read(_p("users.json"), {})
+        key = make_key(user_id)
+        prev = u.get(user_id, {})
+        u[user_id] = {
+            "user": user_id, "key": key, "strategy": strategy, "type": ptype,
+            "assets": sorted(set(assets)),
+            "joined": prev.get("joined", now().isoformat()),
+            "visits": prev.get("visits", []),
+        }
+        _write(_p("users.json"), u)
+        return u[user_id]
+
+
+def user_by_key(key):
+    for v in _read(_p("users.json"), {}).values():
+        if v.get("key") == key:
+            return v
+    return None
+
+
+def touch(user_id):
+    """접속 기록 — 사람 부문의 '주 1회 접속' 요건 판정에 쓴다."""
+    with LOCK:
+        u = _read(_p("users.json"), {})
+        if user_id in u:
+            v = u[user_id].setdefault("visits", [])
+            d = now().date().isoformat()
+            if not v or v[-1] != d:
+                v.append(d)
+                v[:] = v[-400:]
+                _write(_p("users.json"), u)
+
+
+def all_users():
+    return list(_read(_p("users.json"), {}).values())
+
+
+# ─────────────────────── 포지션 ───────────────────────
+def submit(user_id, asset, position, source="api"):
+    """포지션 제출. 덮어쓰지 않고 줄 단위로 쌓는다."""
+    pos = max(-1.0, min(1.0, float(position)))
+    rec = {"t": now().isoformat(), "u": user_id, "a": asset,
+           "p": pos, "src": source}
+    with LOCK:
+        with open(_p("positions", "%s.jsonl" % asset), "a", encoding="utf-8") as f:
+            f.write(json.dumps(rec, ensure_ascii=False) + "\n")
+    touch(user_id)
+    return rec
+
+
+def positions(asset, user_id=None):
+    out = []
+    p = _p("positions", "%s.jsonl" % asset)
+    if not os.path.exists(p):
+        return out
+    with open(p, encoding="utf-8") as f:
+        for line in f:
+            try:
+                r = json.loads(line)
+            except Exception:
+                continue
+            if user_id is None or r.get("u") == user_id:
+                out.append(r)
+    return out
+
+
+def latest(asset, user_id):
+    ps = positions(asset, user_id)
+    return ps[-1] if ps else None
+
+
+# ─────────────────────── 점수 스냅샷 ───────────────────────
+def save_scores(asset, rows):
+    _write(_p("scores", "%s.json" % asset),
+           {"at": now().isoformat(), "rows": rows})
+
+
+def load_scores(asset):
+    return _read(_p("scores", "%s.json" % asset), {"at": None, "rows": []})

app/main.py

@@ -0,0 +1,349 @@
+# -*- coding: utf-8 -*-
+"""FINCHAL 서버 — REST + MCP를 한 프로세스에서 서빙한다.
+
+REST 는 사람과 웹 화면이 쓰고, MCP 는 에이전트가 쓴다.
+둘이 같은 원장·같은 채점기를 본다. 경로가 갈리면 성적이 갈린다.
+"""
+import os, sys, json, time
+import numpy as np, pandas as pd
+from fastapi import FastAPI, Request, Header
+from fastapi.responses import JSONResponse, PlainTextResponse, FileResponse
+from fastapi.staticfiles import StaticFiles
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path[:0] = [HERE, os.path.dirname(HERE)]
+import seasons as S
+import scoring as SC
+import reference as RF
+import ledger as L
+import mcp as MCP
+
+CEIL = json.load(open(os.path.join(os.path.dirname(HERE), "announce_ceiling.json"),
+                     encoding="utf-8"))["ceiling"]
+
+app = FastAPI(title="FINCHAL")
+S1 = S.SEASONS[1]
+# 로컬에서 화면을 확인할 때만 쓴다. 시즌이 오늘 열리면 채점할 구간이 없어
+# 차트와 순위가 비어 보이는데, 그게 결함인지 정상인지 구분이 안 된다.
+if os.environ.get("FINCHAL_OPENS"):
+    S1 = dict(S1, opens=os.environ["FINCHAL_OPENS"])
+ASSETS = S1["assets"]
+
+_PX = {"at": 0.0, "d": {}}
+TTL = 900
+
+
+def prices(asset, interval="1d", bars=800):
+    """가격 캐시. 종목마다 소스가 다르지만 이 함수 밖에서는 신경 쓰지 않는다."""
+    k = "%s|%s" % (asset, interval)
+    if time.time() - _PX["at"] > TTL:
+        _PX["d"].clear(); _PX["at"] = time.time()
+    if k not in _PX["d"]:
+        src = ASSETS[asset]["src"]
+        import yfinance as yf
+        per = "5y" if interval == "1d" else "60d"
+        d = yf.download(src, period=per, interval=interval,
+                        progress=False, auto_adjust=True, threads=False)
+        if isinstance(d.columns, pd.MultiIndex):
+            d.columns = d.columns.droplevel(1)
+        s = d["Close"].dropna()
+        s.index = pd.to_datetime(s.index).tz_localize(None)
+        _PX["d"][k] = s
+    return _PX["d"][k].iloc[-bars:]
+
+
+def season_px(asset):
+    """시즌 개막 이후 구간만. 채점과 기준분포가 이걸 본다."""
+    s = prices(asset, "1d", 2000)
+    return s[s.index >= pd.Timestamp(S1["opens"])]
+
+
+def rules_doc():
+    return {
+        "season": S1["name"], "opens": S1["opens"], "closes": S1["closes"],
+        "days": (pd.Timestamp(S1["closes"]) - pd.Timestamp(S1["opens"])).days,
+        "prize": "종목별 최종 수익률 1위 %d달러 · 총 %d달러"
+                 % (S1["prize_usd_per_asset"], S1["prize_total_usd"]),
+        "leverage": "포지션 -1.0 ~ +1.0. 레버리지 1 고정. 벗어나면 잘림",
+        "update": "매시간 갱신 가능. 다시 낼 때까지 직전 포지션이 유지됨",
+        "fees": {k: SC.fee_of(k) for k in ASSETS},
+        "fee_note": "포지션 변경분에만 부과. 자주 뒤집으면 수수료로 잃는다",
+        "scoring": "최종 수익률로 종목별 순위. 옆에 '운으로 이럴 확률'을 함께 표시",
+        "participation": "해당 종목 개설~마감 기간의 70%% 이상 포지션이 유효해야 상금 대상",
+        "assets": {k: {"label": v["label"], "why": v["why"],
+                       "vol_annual": v["vol"], "hours": v["hours"]}
+                   for k, v in ASSETS.items()},
+        "types": {k: v["label"] for k, v in S.TYPES.items()},
+        "warning": ("엔비디아 실적이 2026-08-26이다. 실적일 변동은 평상일의 2.7배이고 "
+                    "87%가 시가 갭이라 장중 대응이 안 된다. 시즌 중 1회다."),
+        "manifesto": S.MANIFESTO["title"] + " — " + S.MANIFESTO["sub"],
+        # 운의 한계선. 실력 0 참가자를 20,000회 돌려 낸 상위 5% 지점이다.
+        # 이 값 아래의 수익은 운으로도 설명된다.
+        "luck_ceiling": {k: round(v["p95"], 4) for k, v in CEIL.items()},
+        "luck_note": ("실력 0인 참가자를 시즌 길이만큼 20,000회 돌려 낸 상위 5% 지점. "
+                      "수수료를 똑같이 물렸습니다. 이 선을 넘어야 실력의 증거가 됩니다."),
+    }
+
+
+def me_from(key):
+    u = L.user_by_key(key or "")
+    if not u:
+        raise PermissionError(
+            "참가 키가 필요합니다. 화면에서 Hugging Face로 로그인하면 fc_ 로 시작하는 "
+            "키가 나옵니다. MCP 설정의 Authorization 헤더에 넣어 주세요.")
+    return u
+
+
+def score_asset(asset):
+    """그 종목 참가자 전원을 채점한다. 기준분포는 시즌 실제 경로로 만든다."""
+    px = season_px(asset)
+    if len(px) < 2:
+        return []          # 시즌 첫날엔 계산할 구간이 없다
+    fee = SC.fee_of(asset)
+    recs = L.positions(asset)
+    rows = []
+    by_user = {}
+    for r in recs:
+        by_user.setdefault(r["u"], {})[pd.Timestamp(r["t"]).tz_localize(None)] = r["p"]
+    users = {u["user"]: u for u in L.all_users()}
+    for uid, pos in by_user.items():
+        ret = SC.total_return(pos, px, asset)
+        expo = float(np.abs(pd.Series(pos).reindex(
+            px.index, method="ffill").fillna(0.0)).mean())
+        refv = RF.live(px, fee, expo=max(expo, 0.05), n=3000)
+        u = users.get(uid, {})
+        rows.append({
+            "user": uid, "strategy": u.get("strategy", "-"),
+            "type": u.get("type", "agent"),
+            "joined": u.get("joined", ""),
+            "ret": ret, "score": SC.score(ret, refv),
+            "luck_p95": float(np.percentile(refv, 95)),
+            "turnover": SC.turnover(pos, px),
+            "fee_paid": SC.fee_paid(pos, px, asset),
+            "valid": SC.valid_ratio(pos, px),
+            "n_sub": len(L.positions(asset, uid)),
+        })
+    rows.sort(key=lambda x: -x["ret"])
+    for i, r in enumerate(rows, 1):
+        r["rank"] = i
+    return rows
+
+
+_SC = {}
+SC_TTL = 300
+
+
+def score_cached(asset):
+    """채점은 참가자마다 기준분포 3,000경로를 돌린다. 매 요청마다 하면 화면이 죽는다."""
+    e = _SC.get(asset)
+    if e and time.time() - e[0] < SC_TTL:
+        return e[1]
+    r = score_asset(asset)
+    _SC[asset] = (time.time(), r)
+    return r
+
+
+def curves(asset, top=12):
+    """참가자별 누적 수익률 곡선. 화면의 꺾은선 그래프가 이걸 그린다."""
+    px = season_px(asset)
+    if len(px) < 2:
+        return {"t": [], "series": []}
+    rows = score_cached(asset)
+    users = {u["user"]: u for u in L.all_users()}
+    keep = [r["user"] for r in rows[:top]]
+    ser = []
+    for uid in keep:
+        pos = {}
+        for r in L.positions(asset, uid):
+            pos[pd.Timestamp(r["t"]).tz_localize(None)] = r["p"]
+        if not pos:
+            continue
+        eq, _ = SC.equity(pos, px, asset)
+        u = users.get(uid, {})
+        ser.append({"user": uid, "strategy": u.get("strategy", "-"),
+                    "type": u.get("type", "agent"),
+                    "v": [round(float(x - 1) * 100, 4) for x in eq]})
+    # 시장 자체도 한 줄로 깔아 준다 — 참가자가 무엇을 이겨야 하는지 보이게
+    mk = (px / px.iloc[0] - 1) * 100
+    return {"t": [t.isoformat() for t in px.index],
+            "market": [round(float(x), 4) for x in mk],
+            "series": ser}
+
+
+# ─────────────────────── REST ───────────────────────
+@app.get("/api/rules")
+def api_rules():
+    return {"ok": True, **rules_doc()}
+
+
+@app.get("/api/data")
+def api_data(asset: str, bars: int = 500, interval: str = "1d"):
+    if asset not in ASSETS:
+        return JSONResponse({"ok": False, "error": "알 수 없는 종목"}, 400)
+    s = prices(asset, interval, min(max(bars, 10), 5000))
+    return {"ok": True, "asset": asset, "interval": interval,
+            "bars": [{"t": t.isoformat(), "c": float(v)} for t, v in s.items()]}
+
+
+@app.post("/api/register")
+async def api_register(req: Request):
+    b = await req.json()
+    u = L.register(b["user"], b.get("strategy", "-"),
+                   b.get("type", "agent"), b.get("assets", list(ASSETS)))
+    return {"ok": True, **u}
+
+
+@app.post("/api/submit")
+async def api_submit(req: Request, authorization: str = Header(None)):
+    b = await req.json()
+    key = (authorization or "").replace("Bearer ", "").strip() or b.get("key", "")
+    try:
+        u = me_from(key)
+    except PermissionError as e:
+        return JSONResponse({"ok": False, "error": str(e)}, 401)
+    if b["asset"] not in ASSETS:
+        return JSONResponse({"ok": False, "error": "알 수 없는 종목"}, 400)
+    r = L.submit(u["user"], b["asset"], b["position"], b.get("source", "rest"))
+    _SC.pop(b["asset"], None)      # 방금 낸 사람이 표에서 자기를 못 찾으면 안 된다
+    return {"ok": True, **r}
+
+
+@app.get("/api/leaderboard")
+def api_leaderboard(asset: str):
+    if asset not in ASSETS:
+        return JSONResponse({"ok": False, "error": "알 수 없는 종목"}, 400)
+    return {"ok": True, "asset": asset, "rows": score_cached(asset)}
+
+
+@app.get("/api/curves")
+def api_curves(asset: str, top: int = 12):
+    if asset not in ASSETS:
+        return JSONResponse({"ok": False, "error": "알 수 없는 종목"}, 400)
+    return {"ok": True, "asset": asset, **curves(asset, top)}
+
+
+@app.get("/api/manifesto")
+def api_manifesto():
+    return {"ok": True, **S.MANIFESTO, "anchors": S.ANCHORS,
+            "types": {k: v for k, v in S.TYPES.items()},
+            "season2": {k: v for k, v in S.SEASONS.get(2, {}).items()
+                        if k != "assets"}}
+
+
+# ─────────────────────── MCP ───────────────────────
+def _call(name, args, key=None):
+    if name == "get_rules":
+        return rules_doc()
+    if name == "get_data":
+        a = args["asset"]
+        if a not in ASSETS:
+            return {"error": "알 수 없는 종목. 가능: %s" % list(ASSETS)}
+        s = prices(a, args.get("interval", "1d"), min(args.get("bars", 500), 5000))
+        return {"asset": a, "interval": args.get("interval", "1d"),
+                "bars": [{"t": t.date().isoformat(), "c": round(float(v), 6)}
+                         for t, v in s.items()]}
+    if name == "submit_position":
+        u = me_from(key)
+        a = args["asset"]
+        if a not in ASSETS:
+            return {"error": "알 수 없는 종목. 가능: %s" % list(ASSETS)}
+        r = L.submit(u["user"], a, args["position"], "mcp")
+        _SC.pop(a, None)
+        return {"accepted": True, "asset": a, "position": r["p"], "at": r["t"],
+                "note": "다시 제출할 때까지 이 포지션이 유지됩니다"}
+    if name == "check_score":
+        u = me_from(key)
+        want = [args["asset"]] if args.get("asset") else u.get("assets", list(ASSETS))
+        out = []
+        for a in want:
+            if a not in ASSETS:
+                continue
+            rows = score_asset(a)
+            mine = next((r for r in rows if r["user"] == u["user"]), None)
+            if not mine:
+                last = L.latest(a, u["user"])
+                out.append({"asset": a, "status": "집계 전",
+                            "position": last["p"] if last else None,
+                            "hint": ("포지션은 접수됐습니다. 시즌이 하루 이상 진행되면 "
+                                     "수익률이 계산됩니다." if last else
+                                     "아직 포지션을 내지 않았습니다.")})
+            else:
+                out.append({"asset": a, "rank": mine["rank"], "of": len(rows),
+                            "return": round(mine["ret"], 4),
+                            "luck_ceiling": round(mine["luck_p95"], 4),
+                            "score": round(mine["score"], 2),
+                            "fee_paid": round(mine["fee_paid"], 4),
+                            "hint": ("운의 한계선을 넘었습니다" if mine["ret"] > mine["luck_p95"]
+                                     else "아직 운으로도 나올 수 있는 범위입니다")})
+        return {"user": u["user"], "strategy": u.get("strategy"), "results": out}
+    return {"error": "미구현"}
+
+
+@app.post("/mcp")
+async def mcp_endpoint(req: Request, authorization: str = Header(None)):
+    body = await req.json()
+    key = (authorization or "").replace("Bearer ", "").strip()
+    resp = MCP.handle(body, lambda n, a: _call(n, a, key))
+    if resp is None:
+        return JSONResponse({}, 202)
+    return JSONResponse(resp)
+
+
+@app.get("/llms.txt", response_class=PlainTextResponse)
+def llms():
+    r = rules_doc()
+    return (
+        "# %s\n\n" % r["manifesto"] +
+        "당신은 실제 포지션을 잡아 수익률로 겨룹니다. 방향 예측이 아니라 매매입니다.\n\n"
+        "종목: %s\n" % ", ".join("%s(%s)" % (k, v["label"]) for k, v in ASSETS.items()) +
+        "기간: %s ~ %s\n" % (r["opens"], r["closes"]) +
+        "상금: %s\n" % r["prize"] +
+        "포지션: %s\n" % r["leverage"] +
+        "갱신: %s\n" % r["update"] +
+        "수수료: 포지션 변경분에만. 자주 뒤집으면 손해입니다\n"
+        "채점: 종목별 최종 수익률 순위\n\n"
+        "시작: get_rules() → get_data() → 직접 모델링 → submit_position()\n")
+
+
+STATIC = os.path.join(HERE, "static")
+if os.path.isdir(STATIC):
+    app.mount("/static", StaticFiles(directory=STATIC), name="static")
+
+
+@app.get("/")
+def index():
+    f = os.path.join(STATIC, "index.html")
+    if not os.path.exists(f):
+        return JSONResponse({"ok": True, "note": "화면 준비 중", **rules_doc()})
+    return FileResponse(f, headers={"Cache-Control": "no-cache"})
+
+
+# ─────────────────────── 기준선 자동 제출 ───────────────────────
+def _anchor_loop():
+    """하루 한 번 기준선 셋의 포지션을 낸다.
+
+    🔑 실패해도 서버를 죽이면 안 된다. 기준선은 척도이지 서비스가 아니다.
+       yfinance가 잠깐 막혀도 화면과 참가자 제출은 계속 돌아가야 한다.
+    """
+    import traceback
+    import anchors as A
+    while True:
+        try:
+            A.run(list(ASSETS), lambda a: prices(a, "1d", 1500))
+            _SC.clear()
+        except Exception:
+            traceback.print_exc()
+        time.sleep(6 * 3600)
+
+
+@app.on_event("startup")
+def _startup():
+    if os.environ.get("FINCHAL_NO_ANCHOR"):
+        return
+    import threading
+    threading.Thread(target=_anchor_loop, daemon=True).start()
+
+
+@app.get("/health")
+def health():
+    return {"ok": True, "season": S1["name"], "assets": list(ASSETS)}

app/mcp.py

@@ -0,0 +1,133 @@
+# -*- coding: utf-8 -*-
+"""MCP 서버 — 에이전트가 도구로 직접 참가한다.
+
+이게 이 챌린지의 정체성이다. Numerai도 M6도 사람이 CSV를 올린다.
+참가자는 이 한 줄만 치면 된다:
+
+    claude mcp add finchal https://<space>/mcp --header "Authorization: Bearer fc_xxx"
+
+그러면 에이전트에게 도구 네 개가 생기고, 사람은 "챌린지 참가해줘" 한 마디만 하면 된다.
+
+프로토콜은 JSON-RPC 2.0 위의 Streamable HTTP. 세 메서드만 구현하면 붙는다:
+  initialize / tools/list / tools/call
+notifications/* 는 응답 없이 202 로 받는다.
+"""
+import json
+from typing import Any, Dict
+
+PROTOCOL = "2025-06-18"
+SERVER = {"name": "finchal", "version": "1.0.0"}
+
+TOOLS = [
+    {
+        "name": "get_rules",
+        "description": (
+            "챌린지 규칙과 현재 시즌 정보를 읽는다. 참가 전에 반드시 먼저 호출한다. "
+            "종목 목록·마감일·레버리지 상한·수수료·채점 방식이 들어 있다."),
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "get_data",
+        "description": (
+            "종목의 과거 시세를 받는다. 이 데이터로 직접 모델을 만들어 예측하라. "
+            "미래 데이터는 주지 않는다 — 정답은 아직 세상에 없다."),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "asset": {"type": "string",
+                          "description": "종목 코드. NVDA / BTC / GOLD / OIL"},
+                "bars": {"type": "integer", "default": 500,
+                         "description": "받을 봉 개수 (최대 5000)"},
+                "interval": {"type": "string", "enum": ["1d", "1h"], "default": "1d"},
+            },
+            "required": ["asset"],
+        },
+    },
+    {
+        "name": "submit_position",
+        "description": (
+            "포지션을 제출한다. -1.0(전량 숏) ~ +1.0(전량 롱). 레버리지는 1로 고정이며 "
+            "범위를 벗어나면 잘린다. 다시 제출할 때까지 이 포지션이 유지된다. "
+            "포지션을 바꿀 때마다 수수료가 나가므로 자주 뒤집으면 손해다."),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "asset": {"type": "string"},
+                "position": {"type": "number", "minimum": -1, "maximum": 1},
+                "note": {"type": "string", "description": "선택. 판단 근거 메모"},
+            },
+            "required": ["asset", "position"],
+        },
+    },
+    {
+        "name": "check_score",
+        "description": (
+            "내 성적과 순위를 확인한다. 수익률·순위·운의 한계선 대비 위치를 돌려준다."),
+        "inputSchema": {
+            "type": "object",
+            "properties": {"asset": {"type": "string",
+                                     "description": "생략하면 참가 중인 전 종목"}},
+        },
+    },
+]
+
+
+def _ok(rid, result):
+    return {"jsonrpc": "2.0", "id": rid, "result": result}
+
+
+def _err(rid, code, msg):
+    return {"jsonrpc": "2.0", "id": rid, "error": {"code": code, "message": msg}}
+
+
+def _text(obj):
+    """도구 결과는 텍스트 콘텐츠로 돌려준다. 에이전트가 JSON을 잘 읽으므로
+    구조를 그대로 직렬화하되, 사람이 로그를 볼 때도 읽히게 들여쓴다."""
+    return {"content": [{"type": "text",
+                         "text": json.dumps(obj, ensure_ascii=False, indent=1)}]}
+
+
+def handle(body: Dict[str, Any], call) -> Any:
+    """call(name, args) -> dict 를 받아 도구를 실제로 실행한다.
+
+    반환이 None 이면 응답 없음(notification)이라는 뜻이다.
+    """
+    method = body.get("method")
+    rid = body.get("id")
+
+    if method == "initialize":
+        return _ok(rid, {
+            "protocolVersion": PROTOCOL,
+            "capabilities": {"tools": {"listChanged": False}},
+            "serverInfo": SERVER,
+            "instructions": (
+                "금융 예측 챌린지다. 방향을 맞히는 것이 아니라 실제 포지션을 잡아 "
+                "수익률로 겨룬다. get_rules 로 시작하라."),
+        })
+
+    if method and method.startswith("notifications/"):
+        return None                      # 알림은 응답하지 않는다
+
+    if method == "tools/list":
+        return _ok(rid, {"tools": TOOLS})
+
+    if method == "tools/call":
+        p = body.get("params") or {}
+        name = p.get("name")
+        args = p.get("arguments") or {}
+        if not any(t["name"] == name for t in TOOLS):
+            return _err(rid, -32602, "알 수 없는 도구: %s" % name)
+        try:
+            return _ok(rid, _text(call(name, args)))
+        except PermissionError as e:
+            return _ok(rid, {"content": [{"type": "text", "text": str(e)}],
+                             "isError": True})
+        except Exception as e:
+            return _ok(rid, {"content": [
+                {"type": "text", "text": "%s: %s" % (type(e).__name__, e)}],
+                "isError": True})
+
+    if method == "ping":
+        return _ok(rid, {})
+
+    return _err(rid, -32601, "지원하지 않는 메서드: %s" % method)

app/static/index.html

@@ -0,0 +1,436 @@
+<!doctype html>
+<html lang="ko">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>FINCHAL · 파이낸셜 예측 챌린지</title>
+<script src="https://unpkg.com/lightweight-charts@4.1.3/dist/lightweight-charts.standalone.production.js"></script>
+<style>
+/* ORACLE 화면과 같은 밝은 팔레트. 어두운 배경에서 수익률 색이 안 읽혔다. */
+:root{
+ --bg:#f5f6f8; --panel:#ffffff; --panel2:#f4f6f9; --line:#e4e8ee;
+ --tx:#0f1729; --dim:#5f6b7f; --faint:#6b7684;
+ --up:#07804e; --up-bg:#e8f6ef; --dn:#c62828; --dn-bg:#fdecea;
+ --acc:#1f5fd6; --acc-bg:#eaf1fd; --gold:#9a6b00; --gold-bg:#fdf5e3;
+ --sh:0 1px 2px rgba(16,24,40,.05),0 1px 3px rgba(16,24,40,.06);
+ --sh2:0 4px 12px rgba(16,24,40,.07),0 1px 3px rgba(16,24,40,.05);
+}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--tx);
+ font:14px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI","Pretendard","Noto Sans KR",sans-serif;
+ -webkit-font-smoothing:antialiased}
+a{color:var(--acc);text-decoration:none}
+.wrap{max-width:1240px;margin:0 auto;padding:0 20px 72px}
+.card{background:var(--panel);border:1px solid var(--line);border-radius:14px;
+ padding:20px 22px;box-shadow:var(--sh)}
+h2{font-size:17px;margin:0 0 14px;letter-spacing:-.01em}
+h3{font-size:14px;margin:0 0 8px;color:var(--dim);font-weight:600}
+.mono{font-variant-numeric:tabular-nums;
+ font-family:"SF Mono",ui-monospace,"Cascadia Mono",Consolas,monospace}
+.up{color:var(--up)} .dn{color:var(--dn)} .dim{color:var(--dim)} .faint{color:var(--faint)}
+
+/* ───── 히어로 ───── */
+.hero{padding:52px 0 28px;text-align:center}
+.kicker{display:inline-block;background:var(--acc-bg);color:var(--acc);font-weight:700;
+ font-size:12px;letter-spacing:.06em;padding:6px 14px;border-radius:999px}
+.hero h1{font-size:clamp(30px,5vw,50px);margin:16px 0 6px;letter-spacing:-.03em;line-height:1.14}
+.hero .sub{color:var(--dim);font-size:16px}
+.prize{display:inline-flex;align-items:baseline;gap:10px;margin-top:22px;
+ background:var(--gold-bg);border:1px solid #f0dfae;border-radius:14px;padding:14px 26px}
+.prize b{font-size:34px;letter-spacing:-.02em;color:var(--gold)}
+.hero .meta{margin-top:14px;color:var(--faint);font-size:13px}
+.ctas{display:flex;gap:10px;justify-content:center;margin-top:24px;flex-wrap:wrap}
+.btn{border:1px solid var(--line);background:var(--panel);color:var(--tx);
+ padding:11px 20px;border-radius:10px;font-weight:600;font-size:14px;cursor:pointer;
+ box-shadow:var(--sh);transition:.12s}
+.btn:hover{box-shadow:var(--sh2);transform:translateY(-1px)}
+.btn.pri{background:var(--acc);border-color:var(--acc);color:#fff}
+.btn:disabled{opacity:.5;cursor:not-allowed;transform:none}
+
+/* ───── 종목 탭 ───── */
+.tabs{display:flex;gap:8px;margin:26px 0 16px;flex-wrap:wrap}
+.tab{border:1px solid var(--line);background:var(--panel);border-radius:11px;
+ padding:11px 18px;cursor:pointer;font-weight:600;box-shadow:var(--sh);transition:.12s;
+ display:flex;align-items:center;gap:9px}
+.tab:hover{box-shadow:var(--sh2)}
+.tab.on{border-color:var(--acc);background:var(--acc-bg);color:var(--acc)}
+.tab .p{font-size:12px;font-weight:500;color:var(--faint)}
+.tab.on .p{color:var(--acc)}
+
+.grid{display:grid;grid-template-columns:1fr 336px;gap:16px;align-items:start}
+.grid>*{min-width:0}
+@media(max-width:940px){.grid{grid-template-columns:1fr}}
+.row3{display:grid;grid-template-columns:repeat(3,1fr);gap:16px;margin-top:16px}
+@media(max-width:940px){.row3{grid-template-columns:1fr}}
+
+/* ───── 지표 ───── */
+.kpis{display:grid;grid-template-columns:repeat(4,1fr);gap:1px;background:var(--line);
+ border:1px solid var(--line);border-radius:12px;overflow:hidden;margin-bottom:14px}
+.kpi{background:var(--panel);padding:14px 16px}
+.kpi .l{font-size:11px;color:var(--faint);letter-spacing:.02em}
+.kpi .v{font-size:21px;font-weight:700;letter-spacing:-.02em;margin-top:3px}
+@media(max-width:700px){.kpis{grid-template-columns:repeat(2,1fr)}}
+
+#chart{height:clamp(380px,calc(100vh - 340px),620px)}
+.legend{display:flex;flex-wrap:wrap;gap:6px 14px;margin-top:12px;font-size:12px}
+.legend i{width:16px;height:3px;border-radius:2px;display:inline-block;
+ vertical-align:middle;margin-right:6px}
+
+/* ───── 표 ───── */
+.tw{overflow-x:auto;-webkit-overflow-scrolling:touch}
+table{width:100%;border-collapse:collapse;font-size:13px}
+/* 좁은 화면에서 8열이 짓눌리면 숫자를 못 읽는다. 줄이지 말고 밀어서 보게 한다. */
+.tw table{min-width:660px}
+th{text-align:left;font-size:11px;color:var(--faint);font-weight:600;
+ padding:0 10px 9px;letter-spacing:.03em;border-bottom:1px solid var(--line)}
+td{padding:11px 10px;border-bottom:1px solid var(--line)}
+tr:last-child td{border-bottom:0}
+tbody tr:hover{background:var(--panel2)}
+.num{text-align:right}
+.rk{width:34px;font-weight:700;color:var(--faint)}
+.rk.g{color:var(--gold)}
+.who b{font-weight:600}
+.who small{display:block;color:var(--faint);font-size:11px;margin-top:1px}
+.pill{display:inline-block;font-size:10px;padding:2px 7px;border-radius:6px;
+ background:var(--panel2);color:var(--dim);border:1px solid var(--line);font-weight:600}
+.pill.base{background:#f2f0fb;color:#5b4bb5;border-color:#e3ddf6}
+.star{color:var(--gold);font-weight:700}
+
+/* ───── 제출 패널 ───── */
+.sub label{display:block;font-size:12px;color:var(--dim);margin:14px 0 5px;font-weight:600}
+.sub input[type=text]{width:100%;padding:9px 11px;border:1px solid var(--line);
+ border-radius:9px;background:var(--panel2);color:var(--tx);font-size:13px}
+.sub input[type=range]{width:100%;accent-color:var(--acc)}
+.posv{font-size:30px;font-weight:700;text-align:center;letter-spacing:-.02em;margin:6px 0}
+.posl{text-align:center;font-size:12px;color:var(--faint);margin-bottom:6px}
+.marks{display:flex;justify-content:space-between;font-size:10px;color:var(--faint)}
+.note{background:var(--panel2);border-radius:9px;padding:10px 12px;font-size:12px;
+ color:var(--dim);margin-top:12px;line-height:1.55}
+.key{background:var(--up-bg);border:1px solid #bfe5d3;border-radius:9px;padding:10px 12px;
+ font-size:12px;margin-top:12px;word-break:break-all}
+
+/* ───── 규칙·프롬프트 ───── */
+pre{background:#0f1729;color:#e6edf7;border-radius:11px;padding:14px 16px;overflow:auto;
+ font-size:12px;line-height:1.65;margin:0;
+ font-family:"SF Mono",ui-monospace,Consolas,monospace}
+.copy{float:right;font-size:11px;padding:5px 11px;border-radius:7px;border:1px solid var(--line);
+ background:var(--panel);cursor:pointer;font-weight:600}
+.why{display:grid;gap:12px}
+.why div{background:var(--panel2);border-radius:10px;padding:12px 14px}
+.why b{display:block;margin-bottom:3px}
+.why span{font-size:12.5px;color:var(--dim)}
+.foot{margin-top:34px;padding-top:18px;border-top:1px solid var(--line);
+ color:var(--faint);font-size:12px;text-align:center}
+.load{padding:40px;text-align:center;color:var(--faint)}
+</style>
+</head>
+<body>
+<div class="wrap">
+
+  <!-- ① 취지 -->
+  <div class="hero">
+    <span class="kicker">FINANCIAL FORECAST CHALLENGE · SEASON 1</span>
+    <h1 id="m-title">AI는 시장을 이길 수 있는가</h1>
+    <div class="sub" id="m-sub">122일간의 공개 실험</div>
+    <div class="prize"><span class="dim">총 상금</span><b>$2,000</b>
+      <span class="dim" id="prize-rule">종목별 1위 $500 × 4종목</span></div>
+    <div class="meta" id="m-meta">—</div>
+    <div class="ctas">
+      <button class="btn pri" onclick="go('#submit')">직접 참가하기</button>
+      <button class="btn" onclick="go('#guide')">에이전트로 참가하기</button>
+    </div>
+  </div>
+
+  <!-- 종목 탭 -->
+  <div class="tabs" id="tabs"></div>
+
+  <!-- ② 차트 + ④ 제출 -->
+  <div class="grid">
+    <div class="card">
+      <div class="kpis" id="kpis"></div>
+      <div id="chart"></div>
+      <div class="legend" id="legend"></div>
+    </div>
+
+    <div>
+      <div class="card sub" id="submit">
+        <h2>포지션 제출</h2>
+        <div class="posv mono" id="pv">+1.00</div>
+        <div class="posl" id="pl">전량 롱</div>
+        <input type="range" id="pos" min="-100" max="100" value="100" step="5"
+               oninput="onPos()">
+        <div class="marks"><span>−1.0 숏</span><span>0 관망</span><span>+1.0 롱</span></div>
+
+        <label>참가 ID</label>
+        <input type="text" id="uid" placeholder="huggingface 아이디">
+        <label>전략명</label>
+        <input type="text" id="strat" placeholder="예: 20일 추세추종">
+        <button class="btn pri" style="width:100%;margin-top:14px" id="go"
+                onclick="submit()">제출</button>
+        <div id="msg"></div>
+        <div class="note">
+          제출하면 <b>다시 낼 때까지</b> 이 포지션이 유지됩니다.
+          바꿀 때마다 수수료가 나가므로 자주 뒤집으면 손해입니다.
+        </div>
+      </div>
+
+      <div class="card" style="margin-top:16px">
+        <h2>운의 한계선</h2>
+        <div id="luck"></div>
+        <div class="note" id="luck-note">—</div>
+      </div>
+    </div>
+  </div>
+
+  <!-- ③ 랭킹 -->
+  <div class="card" style="margin-top:16px">
+    <h2>순위 <span class="faint" style="font-weight:400;font-size:13px"
+      id="rk-sub"></span></h2>
+    <div class="tw"><table>
+      <thead><tr>
+        <th class="rk">#</th><th>참가자 / 전략</th><th>유형</th>
+        <th class="num">수익률</th><th class="num">운 대비</th>
+        <th class="num">회전</th><th class="num">수수료</th><th class="num">참가일</th>
+      </tr></thead>
+      <tbody id="rank"><tr><td colspan="8" class="load">불러오는 중…</td></tr></tbody>
+    </table></div>
+  </div>
+
+  <!-- 규칙 · 가이드 -->
+  <div class="row3" id="guide">
+    <div class="card">
+      <h2>왜 하는가</h2>
+      <div class="why" id="why"></div>
+    </div>
+    <div class="card">
+      <h2>어떻게 다른가</h2>
+      <div class="why" id="how"></div>
+    </div>
+    <div class="card">
+      <h2>규칙</h2>
+      <div class="why" id="rules"></div>
+    </div>
+  </div>
+
+  <div class="card" style="margin-top:16px">
+    <h2>에이전트로 참가하기
+      <button class="copy" onclick="copyP()">복사</button></h2>
+    <p class="dim" style="margin:0 0 12px;font-size:13px">
+      Claude Code·Codex 등에 MCP 서버를 붙이면 도구 네 개가 생깁니다.
+      아래를 그대로 붙여넣으십시오.</p>
+    <pre id="prompt">—</pre>
+  </div>
+
+  <div class="foot">
+    <span id="stake">—</span><br>
+    <span id="s2">—</span>
+  </div>
+</div>
+
+<script>
+/* 차트 설정에는 CSS 변수를 넣을 수 없다. 문자열 그대로 들어가 무색이 된다. */
+const C = {
+  up:'#07804e', dn:'#c62828', line:'#e4e8ee', tx:'#0f1729', dim:'#6b7684',
+  pal:['#1f5fd6','#07804e','#c62828','#9a6b00','#7b4bb5','#0d8a9e',
+       '#d1640a','#4a5568','#b5297a','#2f7d32','#5b6ab5','#8a6d3b']
+};
+let R=null, ASSET=null, chart=null, lines=[];
+
+const fmt = v => (v>=0?'+':'') + v.toFixed(2) + '%';
+const go = h => document.querySelector(h).scrollIntoView({behavior:'smooth',block:'center'});
+const cls = v => v>0?'up':(v<0?'dn':'dim');
+
+async function boot(){
+  R = await (await fetch('/api/rules')).json();
+  document.getElementById('m-meta').textContent =
+    `${R.opens} ~ ${R.closes} · ${R.days}일 · 레버리지 1 고정 · 매시간 갱신`;
+  document.getElementById('prize-rule').textContent =
+    `종목별 1위 $500 × ${Object.keys(R.assets).length}종목`;
+  document.getElementById('luck-note').textContent = R.luck_note;
+
+  document.getElementById('tabs').innerHTML = Object.entries(R.assets).map(([k,v]) =>
+    `<div class="tab" data-a="${k}" onclick="pick('${k}')">
+       <span>${v.label}</span><span class="p">${k}</span></div>`).join('');
+
+  document.getElementById('luck').innerHTML = Object.entries(R.luck_ceiling)
+    .sort((a,b)=>b[1]-a[1]).map(([k,v]) =>
+    `<div style="display:flex;justify-content:space-between;padding:7px 0;
+       border-bottom:1px solid var(--line)">
+       <span>${R.assets[k].label}</span>
+       <b class="mono up">+${(v*100).toFixed(1)}%</b></div>`).join('');
+
+  const man = await (await fetch('/api/manifesto')).json();
+  document.getElementById('m-title').textContent = man.title;
+  document.getElementById('m-sub').textContent = man.sub;
+  const box = (a) => a.map(([t,d]) => `<div><b>${t}</b><span>${d}</span></div>`).join('');
+  document.getElementById('why').innerHTML = box(man.why);
+  document.getElementById('how').innerHTML = box(man.how);
+  document.getElementById('stake').textContent = man.our_stake;
+  document.getElementById('s2').textContent =
+    `${man.season2.name} — ${man.season2.teaser}. 종목은 시즌 1 종료 후 확정합니다.`;
+
+  document.getElementById('rules').innerHTML = box([
+    ['포지션', R.leverage],
+    ['갱신', R.update],
+    ['수수료', Object.entries(R.fees).map(([k,v])=>`${k} ${(v*100).toFixed(2)}%`).join(' · ')
+              + ' — ' + R.fee_note],
+    ['순위', R.scoring],
+    ['참여 요건', R.participation],
+  ]);
+
+  pick(Object.keys(R.assets)[0]);
+}
+
+function prompt_(a){
+  document.getElementById('prompt').textContent =
+`claude mcp add --transport http finchal ${location.origin}/mcp \\
+  --header "Authorization: Bearer <내 참가키>"
+
+# 그 다음 에이전트에게 이렇게 말하면 됩니다
+"finchal 챌린지에 참가해줘. get_rules로 규칙을 읽고,
+ get_data로 ${a} 시세를 받아서 직접 모델을 만든 다음
+ submit_position으로 포지션을 내줘. 매일 check_score로 성적을 확인하고
+ 필요하면 포지션을 조정해."
+
+# 도구 넷
+get_rules()          규칙·종목·수수료·마감
+get_data(asset,bars) 과거 시세 (미래는 주지 않습니다)
+submit_position(asset, position)   -1.0 ~ +1.0
+check_score(asset)   내 순위와 운의 한계선 대비 위치`;
+}
+function copyP(){
+  navigator.clipboard.writeText(document.getElementById('prompt').textContent);
+}
+
+async function pick(a){
+  ASSET = a;
+  document.querySelectorAll('.tab').forEach(t =>
+    t.classList.toggle('on', t.dataset.a === a));
+  prompt_(a);
+  document.getElementById('rk-sub').textContent =
+    `${R.assets[a].label} · 1위 $500 · ${R.assets[a].why}`;
+  await Promise.all([drawChart(a), drawRank(a)]);
+}
+
+async function drawChart(a){
+  const d = await (await fetch(`/api/curves?asset=${a}&top=12`)).json();
+  const el = document.getElementById('chart');
+  if(chart){ chart.remove(); chart = null; }
+  chart = LightweightCharts.createChart(el, {
+    layout:{background:{color:'#ffffff'}, textColor:C.dim, fontSize:11},
+    grid:{vertLines:{color:C.line}, horzLines:{color:C.line}},
+    rightPriceScale:{borderColor:C.line},
+    timeScale:{borderColor:C.line, timeVisible:false},
+    crosshair:{mode:1}, height:el.clientHeight,
+  });
+  const t = d.t.map(x => x.slice(0,10));
+  const mk = (name, vals, color, w, dash) => {
+    const s = chart.addLineSeries({color, lineWidth:w, lineStyle:dash?2:0,
+      priceLineVisible:false, lastValueVisible:false});
+    s.setData(t.map((x,i)=>({time:x, value:vals[i]})));
+    return s;
+  };
+  const leg = [];
+  if(d.market && d.market.length){
+    mk('시장', d.market, C.dim, 2, true);
+    leg.push([C.dim, `${R.assets[a].label} 시장 (단순 보유)`,
+              d.market[d.market.length-1]]);
+  }
+  (d.series||[]).forEach((s,i) => {
+    const col = C.pal[i % C.pal.length];
+    mk(s.user, s.v, col, 2, false);
+    leg.push([col, `${s.user} · ${s.strategy}`, s.v[s.v.length-1]]);
+  });
+  chart.timeScale().fitContent();
+  document.getElementById('legend').innerHTML = leg.length
+    ? leg.map(([c,n,v]) => `<span><i style="background:${c}"></i>${n}
+        <b class="mono ${cls(v)}">${fmt(v)}</b></span>`).join('')
+    : '<span class="faint">아직 곡선이 없습니다. 시즌이 하루 이상 진행되면 그려집니다.</span>';
+
+  const rows = (d.series||[]);
+  const best = rows.length ? Math.max(...rows.map(s=>s.v[s.v.length-1])) : 0;
+  const mkt = d.market && d.market.length ? d.market[d.market.length-1] : 0;
+  const K = [
+    ['참가자', rows.length + '명', ''],
+    ['현재 1위', rows.length?fmt(best):'—', cls(best)],
+    [`${R.assets[a].label} 시장`, d.market&&d.market.length?fmt(mkt):'—', cls(mkt)],
+    ['운의 한계선', '+' + (R.luck_ceiling[a]*100).toFixed(1) + '%', 'dim'],
+  ];
+  document.getElementById('kpis').innerHTML = K.map(([l,v,c]) =>
+    `<div class="kpi"><div class="l">${l}</div>
+       <div class="v mono ${c}">${v}</div></div>`).join('');
+}
+
+async function drawRank(a){
+  const d = await (await fetch(`/api/leaderboard?asset=${a}`)).json();
+  const tb = document.getElementById('rank');
+  if(!d.rows || !d.rows.length){
+    tb.innerHTML = `<tr><td colspan="8" class="load">
+      아직 참가자가 없습니다. 첫 번째가 되십시오.</td></tr>`;
+    return;
+  }
+  const ceil = R.luck_ceiling[a];
+  const B = {human:'🧑 사람', expert:'📊 전문가', agent:'🤖 에이전트', anchor:'기준선'};
+  tb.innerHTML = d.rows.map(r => {
+    const over = r.ret > r.luck_p95;
+    return `<tr>
+      <td class="rk ${r.rank===1?'g':''}">${r.rank}</td>
+      <td class="who"><b>${r.user}</b><small>${r.strategy}</small></td>
+      <td><span class="pill ${r.type==='anchor'?'base':''}">${B[r.type]||r.type}</span></td>
+      <td class="num mono ${cls(r.ret*100)}"><b>${fmt(r.ret*100)}</b></td>
+      <td class="num mono">${over?'<span class="star">★ 넘음</span>'
+          :`<span class="faint">${(r.ret/Math.max(ceil,1e-9)*100).toFixed(0)}%</span>`}</td>
+      <td class="num mono faint">${r.turnover.toFixed(1)}</td>
+      <td class="num mono ${r.fee_paid>0.02?'dn':'faint'}">
+          −${(r.fee_paid*100).toFixed(2)}%</td>
+      <td class="num faint">${(r.joined||'').slice(5,10)}</td>
+    </tr>`;
+  }).join('');
+}
+
+function onPos(){
+  const v = +document.getElementById('pos').value / 100;
+  document.getElementById('pv').textContent = (v>=0?'+':'') + v.toFixed(2);
+  document.getElementById('pv').className = 'posv mono ' + cls(v);
+  document.getElementById('pl').textContent =
+    v === 0 ? '관망 — 시장에 노출되지 않습니다'
+    : v > 0 ? `롱 ${(v*100).toFixed(0)}% — 오르면 법니다`
+            : `숏 ${(-v*100).toFixed(0)}% — 내리면 법니다`;
+}
+
+async function submit(){
+  const uid = document.getElementById('uid').value.trim();
+  const st = document.getElementById('strat').value.trim() || '-';
+  const msg = document.getElementById('msg');
+  if(!uid){ msg.innerHTML = '<div class="note dn">참가 ID를 입력하십시오.</div>'; return; }
+  const b = document.getElementById('go');
+  b.disabled = true; b.textContent = '제출 중…';
+  try{
+    const reg = await (await fetch('/api/register', {method:'POST',
+      headers:{'Content-Type':'application/json'},
+      body:JSON.stringify({user:uid, strategy:st, type:'human',
+                           assets:Object.keys(R.assets)})})).json();
+    const pos = +document.getElementById('pos').value / 100;
+    const r = await (await fetch('/api/submit', {method:'POST',
+      headers:{'Content-Type':'application/json',
+               'Authorization':'Bearer ' + reg.key},
+      body:JSON.stringify({asset:ASSET, position:pos, source:'web'})})).json();
+    if(!r.ok) throw new Error(r.error || '실패');
+    msg.innerHTML = `<div class="key"><b>접수됐습니다.</b>
+      ${R.assets[ASSET].label} 포지션 ${(pos>=0?'+':'')+pos.toFixed(2)}<br>
+      <span class="dim">참가키 (에이전트 연결에 씁니다) —</span><br>
+      <b class="mono">${reg.key}</b></div>`;
+    drawRank(ASSET);
+  }catch(e){
+    msg.innerHTML = `<div class="note dn">${e.message}</div>`;
+  }
+  b.disabled = false; b.textContent = '제출';
+}
+
+addEventListener('resize', () => {
+  if(chart) chart.applyOptions({height:document.getElementById('chart').clientHeight});
+});
+onPos(); boot();
+</script>
+</body>
+</html>

luck_ceiling.json

@@ -0,0 +1,30 @@
+{
+ "season": 1,
+ "start": "2026-08-25",
+ "end": "2026-12-24",
+ "days": 121,
+ "n_sim": 20000,
+ "block": 5,
+ "seed": 20260825,
+ "method": "블록 부트스트랩 · 무작위 포지션 -1/0/+1 · 레버리지 1 · 95분위",
+ "ceiling": {
+  "SOL": 0.887,
+  "ETH": 0.6227,
+  "BTC": 0.5821,
+  "TSLA": 0.5264,
+  "NVDA": 0.4399,
+  "OIL": 0.3546,
+  "AAPL": 0.2271,
+  "GOLD": 0.1497
+ },
+ "vol": {
+  "SOL": 0.7955,
+  "ETH": 0.5821,
+  "BTC": 0.5575,
+  "TSLA": 0.4945,
+  "NVDA": 0.4295,
+  "OIL": 0.3407,
+  "AAPL": 0.2324,
+  "GOLD": 0.1558
+ }
+}

reference.py

@@ -0,0 +1,124 @@
+# -*- coding: utf-8 -*-
+"""기준분포 — '실력 0이었다면 어디까지 갔을까'를 계산한다.
+
+두 가지를 구분한다.
+
+  개막 전 추정치 (announce)
+    참가자에게 "이 종목은 운으로 이만큼까지 나온다"고 미리 알려주는 값.
+    과거 5년을 블록 부트스트랩해서 낸다. 화면의 '운의 한계선'에 쓴다.
+
+  채점용 기준 (live)
+    실제 순위를 정하는 값. 시즌이 진행된 만큼의 **실제 경로** 위에서
+    실력 0 참가자를 돌려 만든다. 매일 다시 계산한다.
+
+왜 나누는가
+  기준을 과거 부트스트랩으로 고정하면, 시즌 중 그 종목이 크게 오를 때
+  참가자 전원이 부풀려진다. 실측에서 GOLD 우승률 99.6%가 나왔다.
+  올바른 반사실은 '시장이 실제로 그렇게 움직였을 때 운으로 낼 수 있었던 성적'이다.
+
+🔑 개막 전에 고정·공개하는 것은 숫자가 아니라 **방법**이다.
+   숫자를 고정하면 시장이 예상과 다르게 움직였을 때 채점이 통째로 어긋난다.
+
+🔑 기준 참가자도 참가자와 똑같이 수수료를 낸다.
+   안 물리면 참가자만 손해를 보고 시작한다. BTC에서 그 차이가 77.2%p였다.
+"""
+import os, json, warnings
+import numpy as np, pandas as pd
+warnings.filterwarnings("ignore")
+
+ROOT = os.path.dirname(os.path.abspath(__file__))
+BLOCK = 5
+N_LIVE = 4000
+N_ANNOUNCE = 20000
+
+
+def _sim(returns, n, expo, fee, seed, block=None):
+    """실력 0 참가자 n명의 최종 수익률. expo 만큼의 시간을 포지션에 노출한다."""
+    g = np.random.default_rng(seed)
+    r = np.asarray(returns, dtype=float)
+    L = len(r)
+    out = np.empty(n)
+    for i in range(n):
+        if block:                                   # 부트스트랩 (개막 전 추정)
+            nb = int(np.ceil(L / block))
+            st = g.integers(0, max(len(r) - block, 1), size=nb)
+            path = np.concatenate([r[j:j+block] for j in st])[:L]
+        else:                                       # 실제 경로 (채점)
+            path = r
+        act = g.random(L) < expo
+        pos = np.where(act, g.choice([-1.0, 1.0], size=L), 0.0)
+        cost = np.abs(np.diff(np.r_[0.0, pos])) * fee
+        out[i] = np.prod(1 + np.r_[0.0, pos[:-1]] * path - cost) - 1
+    return np.sort(out)
+
+
+def live(prices, fee, expo=2/3, n=N_LIVE, seed=None):
+    """채점용 — 시즌 경과분의 실제 경로 위에서 만든다. 매일 다시 부른다.
+
+    seed 를 날짜로 주면 같은 날 같은 값이 나와 재현이 된다.
+    """
+    r = pd.Series(prices, dtype=float).sort_index().pct_change().fillna(0.0).values
+    s = seed if seed is not None else int(pd.Timestamp.utcnow().strftime("%Y%m%d"))
+    return _sim(r, n, expo, fee, s)
+
+
+def announce(returns, fee, days, expo=2/3, n=N_ANNOUNCE, seed=20260824):
+    """개막 전 추정 — 과거를 블록 부트스트랩해서 '이만큼까지 나온다'를 낸다."""
+    r = np.asarray(returns, dtype=float)
+    # 시즌 길이만큼만 쓰도록 잘라 붙인다
+    reps = int(np.ceil(days / len(r))) + 1
+    pool = np.tile(r, reps)[:max(len(r), days * 3)]
+    return _sim(pool[:days] if len(pool) >= days else pool, n, expo, fee, seed, block=BLOCK)
+
+
+def pct_of(ret, refv):
+    import bisect
+    return bisect.bisect_left(refv, ret) / len(refv)
+
+
+def score_of(ret, refv):
+    import math
+    p = min(pct_of(ret, refv), 1 - 1e-6)
+    return -math.log10(max(1.0 - p, 1e-6))
+
+
+# ─────────────────────── 개막 공지값 생성 ───────────────────────
+if __name__ == "__main__":
+    import seasons as S
+    import scoring as SC
+    import yfinance as yf
+
+    s1 = S.SEASONS[1]
+    days = (pd.Timestamp(s1["closes"]) - pd.Timestamp(s1["opens"])).days
+    print("시즌 1 개막 공지값 — %d일 · 수수료 반영\n" % days)
+    print("  %-6s %-8s %8s %11s %11s %11s"
+          % ("종목", "데이터", "수수료", "운 중앙", "운 상위5%", "운 상위1%"))
+    out = {}
+    for code, a in s1["assets"].items():
+        src = a["src"]
+        if code == "BTC":
+            p = os.path.join(os.path.dirname(ROOT), "btc-oracle", "data", "hourly.parquet")
+            H = pd.read_parquet(p).sort_index()
+            if "close" not in H.columns:
+                H = H.rename(columns={"c": "close"})
+            px = H.close.groupby(H.index.normalize()).last()
+        else:
+            d = yf.download(src, period="5y", interval="1d",
+                            progress=False, auto_adjust=True)["Close"]
+            px = (d.iloc[:, 0] if isinstance(d, pd.DataFrame) else d).dropna()
+        r = px.pct_change().dropna().values
+        fee = SC.fee_of(code)
+        c = announce(r, fee, days)
+        out[code] = {"p50": float(np.median(c)), "p95": float(np.percentile(c, 95)),
+                     "p99": float(np.percentile(c, 99)), "fee": fee, "days": days}
+        print("  %-6s %-8s %7.2f%% %10.1f%% %10.1f%% %10.1f%%"
+              % (code, src, fee * 100, np.median(c) * 100,
+                 np.percentile(c, 95) * 100, np.percentile(c, 99) * 100))
+    json.dump({"season": 1, "opens": s1["opens"], "closes": s1["closes"], "days": days,
+               "method": "블록부트스트랩 5일 · 무작위 포지션 · 레버리지1 · 수수료 반영",
+               "note": "개막 공지용 추정치. 실제 채점은 시즌 실제 경로로 매일 재계산한다.",
+               "ceiling": out},
+              open(os.path.join(ROOT, "announce_ceiling.json"), "w"),
+              ensure_ascii=False, indent=1)
+    print("\n  화면의 '운의 한계선'에는 상위5%를 쓴다.")
+    print("  저장: finchal/announce_ceiling.json")

requirements.txt

@@ -0,0 +1,5 @@
+fastapi==0.115.6
+uvicorn[standard]==0.34.0
+pandas==2.2.3
+numpy==2.2.1
+yfinance==0.2.51

scoring.py

@@ -0,0 +1,185 @@
+# -*- coding: utf-8 -*-
+"""채점 엔진 — 포지션 기록에서 수익률과 순위 점수를 낸다.
+
+규칙 (사전등록)
+  포지션은 -1.0 ~ +1.0. 범위를 벗어나면 잘라낸다 (레버리지 1 고정)
+  포지션 갱신은 매시간 가능. 미갱신 구간은 직전 포지션이 유지된다
+  수익률 = 각 구간 포지션 x 그 구간 수익률의 복리
+  거래비용 = 포지션 변경분에 왕복 0.02% (미국주식 무료 + 스프레드 추정)
+  순위 점수 = -log10(1 - 백분위)   백분위는 그 종목의 '실력0 분포' 기준
+
+🔴 채점기를 모델보다 먼저 검증한다. 이 파일을 바꾸면 selftest()를 반드시 다시 돌린다.
+   이번 프로젝트에서만 채점·시뮬 결함을 8건 겪었다. 대부분 '그럴듯하게 틀린' 값이었다.
+"""
+import os, json, math, bisect
+import numpy as np
+import pandas as pd
+
+ROOT = os.path.dirname(os.path.abspath(__file__))
+# 종목별 실거래 비용. 포지션 변경분(|Δw|)에 곱한다.
+# 🔑 이걸 물리지 않으면 포지션을 초당 뒤집는 무차별 제출이 이득을 본다.
+#    매시간 ±1을 뒤집으면 121일에 |Δw| 합계가 5,808이 되는데, 코인 0.06%면
+#    수수료만 자본의 348%다. 규칙이 아니라 비용이 그런 행동을 막는다.
+FEES = {
+    # 코인 — 바이낸스 테이커 0.05% + 슬리피지 0.01%
+    "BTC": 0.0006, "ETH": 0.0006, "SOL": 0.0008,
+    # 미국 주식 — 수수료 무료지만 스프레드·슬리피지가 남는다
+    "NVDA": 0.0002, "TSLA": 0.0002, "AAPL": 0.0002,
+    # 선물 — 계약당 수수료 + 호가폭
+    "GOLD": 0.0002, "OIL": 0.0003,
+}
+FEE_DEFAULT = 0.0006
+FEE = FEE_DEFAULT            # selftest에서 임시로 바꿔 쓰는 전역값
+
+
+def fee_of(asset=None):
+    if asset is None:
+        return FEE
+    return FEES.get(asset, FEE_DEFAULT)
+POS_MIN, POS_MAX = -1.0, 1.0
+
+def clip(p):
+    """레버리지 1 상한. 넘겨 제출해도 잘라낸다 — 거부하지 않는 이유는
+    에이전트가 반올림 오차로 1.0000001을 보내는 일이 흔하기 때문이다."""
+    return max(POS_MIN, min(POS_MAX, float(p)))
+
+
+def equity(positions, prices, asset=None):
+    """포지션 기록 + 가격에서 자산 곡선을 만든다.
+
+    positions: 시각→포지션 (제출된 시점만). 사이 구간은 직전 값이 유지된다
+    prices:    시각→가격 (채점 격자. 보통 1시간 간격)
+    """
+    pos = pd.Series(positions, dtype=float).sort_index().map(clip)
+    px = pd.Series(prices, dtype=float).sort_index()
+    w = pos.reindex(px.index, method="ffill").fillna(0.0)
+    r = px.pct_change().fillna(0.0)
+    cost = w.diff().abs().fillna(w.abs()) * fee_of(asset)
+    g = w.shift(1).fillna(0.0) * r - cost      # 🔑 포지션은 다음 구간에 적용된다
+    return (1 + g).cumprod(), g
+
+
+def total_return(positions, prices, asset=None):
+    eq, _ = equity(positions, prices, asset)
+    return float(eq.iloc[-1] - 1.0)
+
+
+def turnover(positions, prices):
+    """포지션 변경 총량. 무차별 제출 탐지와 화면 표시에 쓴다."""
+    pos = pd.Series(positions, dtype=float).sort_index().map(clip)
+    px = pd.Series(prices, dtype=float).sort_index()
+    w = pos.reindex(px.index, method="ffill").fillna(0.0)
+    return float(w.diff().abs().fillna(w.abs()).sum())
+
+
+def fee_paid(positions, prices, asset=None):
+    return turnover(positions, prices) * fee_of(asset)
+
+
+def percentile(ret, refv):
+    """그 종목의 '실력0 분포'에서 내 수익률의 백분위.
+
+    refv 는 reference.live(가격, 수수료, 노출) 이 만든 정렬된 배열이다.
+    시즌 실제 경로로 매일 다시 만든다 — 과거 부트스트랩으로 고정하면
+    시즌 중 그 종목이 오를 때 참가자 전원이 부풀려진다.
+    """
+    return bisect.bisect_left(refv, ret) / len(refv)
+
+
+def score(ret, refv):
+    """운으로 이 성적이 나올 확률의 역수 지수. 2.0이면 1/100, 3.0이면 1/1,000.
+
+    🔑 순위는 **종목 안에서만** 매긴다. 상금이 종목별이라 종목 간 비교를 하지 않는다.
+       종목 간 비교는 여섯 번 시도해도 편중이 잡히지 않았다
+       (4.7 -> 99.6 -> 3.7 -> 6.0 -> 4.5배). 분포 꼬리 모양이 종목마다 다르고,
+       우승자는 최댓값이라 꼬리가 결정한다. 종목별 시상이 그 비교를 없앤다.
+
+       종목 안에서는 잘 교정된다 — 실력0 참가자의 백분위 중앙이 0.47~0.54였다.
+    """
+    p = min(percentile(ret, refv), 1 - 1e-6)
+    return -math.log10(max(1.0 - p, 1e-6))
+
+
+def valid_ratio(positions, prices):
+    """포지션이 유효했던 구간 비율. 참여 요건 판정에 쓴다."""
+    pos = pd.Series(positions, dtype=float).sort_index()
+    if not len(pos):
+        return 0.0
+    px = pd.Series(prices, dtype=float).sort_index()
+    w = pos.reindex(px.index, method="ffill")
+    return float(w.notna().mean())
+
+
+# ─────────────────────── 채점기 자체 검증 ───────────────────────
+def selftest(verbose=True):
+    """닫힌 형태로 답을 아는 경우들. 하나라도 틀리면 채점을 신뢰할 수 없다."""
+    out = []
+    idx = pd.date_range("2026-01-01", periods=101, freq="h")
+
+    def chk(name, got, want, tol=1e-9):
+        ok = abs(got - want) <= tol
+        out.append((name, got, want, ok))
+        return ok
+
+    # ① 포지션 0이면 수익도 0 — 가격이 어떻게 움직이든
+    px = pd.Series(100 * np.cumprod(1 + np.random.default_rng(0).normal(0, .01, 101)), index=idx)
+    chk("포지션 0 → 수익 0", total_return({idx[0]: 0.0}, px), 0.0)
+
+    # ② 포지션 +1 · 무비용이면 단순보유와 정확히 같아야
+    global FEE
+    keep = FEE
+    FEE = 0.0
+    chk("포지션 +1 = 단순보유", total_return({idx[0]: 1.0}, px),
+        float(px.iloc[-1] / px.iloc[0] - 1), 1e-9)
+    # ③ 포지션 -1 은 부호가 뒤집힌 복리 (단순 -x 가 아니다)
+    w = -1.0
+    want = float(np.prod(1 + w * px.pct_change().fillna(0).values[1:]) - 1)
+    chk("포지션 -1 = 역방향 복리", total_return({idx[0]: -1.0}, px), want, 1e-9)
+    FEE = keep
+
+    # ④ 레버리지 상한 — 2.0을 내도 1.0으로 잘려야
+    FEE = 0.0
+    chk("포지션 2.0 → 1.0으로 절단",
+        total_return({idx[0]: 2.0}, px), total_return({idx[0]: 1.0}, px), 1e-12)
+    FEE = keep
+
+    # ⑤ 미래를 보지 않는가 — 가격이 오르기 직전에 포지션을 넣어도
+    #    그 구간 수익은 못 먹는다 (포지션은 다음 구간부터 적용)
+    p2 = pd.Series([100.0] * 50 + [200.0] * 51, index=idx)
+    FEE = 0.0
+    late = total_return({idx[50]: 1.0}, p2)      # 점프가 일어난 봉에 진입
+    early = total_return({idx[49]: 1.0}, p2)     # 한 봉 먼저 진입
+    ok = abs(late) < 1e-9 and early > 0.9
+    out.append(("미래 차단 (늦게 들어가면 못 먹음)", late, 0.0, ok))
+    FEE = keep
+
+    # ⑥ 비용이 실제로 빠지는가
+    a = total_return({idx[0]: 1.0}, px)
+    FEE = 0.01
+    b = total_return({idx[0]: 1.0}, px)
+    FEE = keep
+    out.append(("비용이 수익을 낮춤", b, a, b < a))
+
+    # ⑦ 백분위·점수가 단조인가 — 인공 기준분포로 확인
+    fake = np.sort(np.random.default_rng(1).normal(0, .3, 4000))
+    out.append(("점수 단조 증가", score(0.6, fake), score(0.1, fake),
+                score(0.6, fake) > score(0.1, fake)))
+    med = float(np.median(fake))
+    out.append(("중앙값 근처 점수 ~0.3", score(med, fake), 0.3,
+                abs(score(med, fake) - 0.30) < 0.05))
+
+    if verbose:
+        print("=" * 72)
+        print("채점기 자체 검증")
+        print("=" * 72)
+        for n, g, w, ok in out:
+            print("  %-32s %14.8f  %s" % (n, g, "✅" if ok else "🔴 실패 (기대 %.8f)" % w))
+        bad = [x for x in out if not x[3]]
+        print("\n  %d/%d 통과%s" % (len(out) - len(bad), len(out),
+                                   "" if not bad else "  🔴 실패 %d건 — 채점 중단" % len(bad)))
+    return all(x[3] for x in out)
+
+
+if __name__ == "__main__":
+    ok = selftest()
+    raise SystemExit(0 if ok else 1)

seasons.py

@@ -0,0 +1,213 @@
+# -*- coding: utf-8 -*-
+"""시즌 등록부. 시즌마다 달라지는 것은 전부 여기 있고 다른 곳에는 없다.
+
+ODC와 같은 원칙을 따른다. 시즌별 규칙은 공유하지 않고 시즌마다 되풀이해 적는다.
+시즌 2에는 시즌 1에서 발견한 결함의 교정이 들어가는데, 그 교정이 시즌 1에
+닿아서는 안 되기 때문이다. 시즌 1 참가자는 이미 공개된 규칙 아래 채점됐다.
+
+시즌 1과 2는 겹쳐 돌아간다. 그래서 '지금 시즌'은 상수가 아니라 조회다.
+
+정규화 계수(운의 한계선)의 근거 수치는 calibrate.py가 산출해 luck_ceiling.json에
+넣는다. 개막 전 데이터로만 계산하고 시즌 중에는 재계산하지 않는다.
+"""
+
+SEASONS = {
+    1: {
+        "name": "시즌 1 · 네 개의 시장",
+        "opens": "2026-08-24",
+        "closes": "2026-12-24",
+        # 성격이 갈리는 네 시장. 서로 거의 무상관이라(-0.04 ~ 0.19) 참가자가 흩어진다.
+        # 도지코인은 비트코인과 상관 0.763, 반도체ETF는 엔비디아와 0.797이라 뺐다.
+        # 두 종목이 사실상 하나가 되면 4종목이 3종목이 된다.
+        #
+        #   AI가 만든 것    엔비디아  ↕  인간이 오래 믿은 것   금
+        #   AI가 흔든 것    비트코인  ↕  세상을 굴려온 것     유가
+        #
+        # 🔴 엔비디아 실적이 개막 이틀 뒤(8/26)다. 실적일 변동은 평상일의 2.7배이고
+        #    87%가 시가 갭이라 장중 대응이 안 된다. 모두에게 같은 조건이지만
+        #    초반 순위에 운이 크게 섞인다는 점은 참가 안내에 명시한다.
+        "assets": {
+            "NVDA": {"label": "엔비디아", "cat": "stock", "vol": 0.514,
+                     "why": "AI 그 자체. 이 시장을 예측하는 것이 이 대회의 상징",
+                     "src": "NVDA", "hours": "rth",
+                     "anchor": {1: 0.781, 5: 0.772, 21: 0.780}},
+            "BTC": {"label": "비트코인", "cat": "coin", "vol": 0.392,
+                    "why": "AI가 흔든 새 화폐. 24시간 거래·휴장 없음",
+                    "src": "BTC-USD", "hours": "24h",
+                    "anchor": {1: 0.807, 7: 0.801, 30: 0.757}},
+            "GOLD": {"label": "금", "cat": "commodity", "vol": 0.212,
+                     "why": "인류가 5,000년 믿어온 가치. 방향이 없어 운으로 벌기 가장 어렵다",
+                     # 🔴 선물(GC=F)이 아니라 ETF를 쓴다. GC=F는 월말 이상점프가
+                     #    정상의 2.4배로, 롤 시점 가격차가 수익률에 섞여 든다.
+                     "src": "GLD", "hours": "rth",
+                     "anchor": {1: 0.748, 5: 0.762, 21: 0.744}},
+            "OIL": {"label": "유가", "cat": "commodity", "vol": 0.369,
+                    "why": "세상을 굴려온 산업의 심장. AI는 옛 시장도 예측하는가",
+                    # 🔴 CL=F는 3년 수익이 +10%인데 USO는 +89%다. 79%p 괴리는
+                    #    근월물을 이어붙일 때 생기는 롤 왜곡이다. 참가자가 실제로
+                    #    낼 수 없는 손익이라 ETF를 쓴다.
+                    "src": "USO", "hours": "rth",
+                    "anchor": {1: 0.782, 5: 0.780, 21: 0.804}},
+        },
+        "prize_usd_per_asset": 500,
+        "prize_total_usd": 2000,
+        "prize_rule": "종목별 최종 수익률 1위에게 각 500달러. 총 2,000달러",
+        # 종목 간 수익률을 직접 비교하는 방식은 폐기했다. 네 번 고쳐도 편중이
+        # 잡히지 않았다(4.7배 -> 99.6배 -> 3.7배 -> 6.0배). 분포 모양이 종목마다
+        # 근본적으로 달라, 어느 한 통계량을 맞추면 다른 지점이 어긋난다.
+        # 종목별 시상은 그 비교 자체를 없앤다. 통합 순위는 참고 표시로만 둔다.
+        "leverage": 1.0,
+        "min_participation": 0.70,
+        "update": "hourly",
+        "ledger": "s1/",
+    },
+    2: {
+        # 예고만 한다. 종목은 시즌 1이 끝난 뒤 확정한다.
+        # 시즌 1에서 어떤 성격의 시장에 참가자가 모이는지 보고 정하는 편이 낫다.
+        "name": "시즌 2 · 예고",
+        "opens": None,
+        "closes": None,
+        "assets": {},
+        "status": "announced",
+        "teaser": "선물과 원자재, 그리고 외환",
+        # 실측해둔 후보들. 확정 아님.
+        "candidates": {
+            "COPPER": {"label": "구리", "vol": 0.291,
+                       "note": "AI 데이터센터 서사는 있으나 데이터로는 약하다. "
+                               "반도체 상관 0.28~0.36 < 금 상관 0.40. "
+                               "서사로 내세우면 참가자가 상관표로 반박할 수 있다"},
+            "OIL": {"label": "유가", "vol": 0.405, "note": "롤오버 처리 필요"},
+            "USDKRW": {"label": "달러/원", "vol": 0.097, "note": "저변동"},
+            "USDJPY": {"label": "달러/엔", "vol": 0.093, "note": "저변동"},
+            "DXY": {"label": "달러지수", "vol": 0.064,
+                    "note": "변동성이 금의 1/3. 순위가 소수점에서 갈릴 위험"},
+        },
+        "prize_usd_per_asset": 500,
+        "leverage": 1.0,
+        "min_participation": 0.70,
+        "update": "hourly",
+        "ledger": "s2/",
+        # 🔴 선물·외환은 롤오버가 있다. 근월물 만기 시 차월물로 갈아타며 가격이
+        #    점프하는데, 이걸 수익률에 그대로 넣으면 없는 손익이 생긴다.
+        #    연결선물 구성 방식을 확정하기 전에는 시즌 2를 열지 않는다.
+        "rollover": None,
+    },
+}
+
+# 참고용 — 화면에 '운의 한계선'을 그을 때 쓴다. 순위 계산에는 쓰지 않는다.
+LUCK_CEILING = {
+    "SOL": 0.8870, "ETH": 0.6227, "BTC": 0.5821, "TSLA": 0.5264,
+    "NVDA": 0.4399, "OIL": 0.3546, "AAPL": 0.2271, "GOLD": 0.1497,
+}
+
+# 리더보드에 참가자와 함께 놓는 기준선. ODC가 승인약을 같은 표에 넣는 것과 같다.
+# 척도가 없는 리더보드는 순위를 읽을 수 없다.
+#
+# 🔴 주최측 모델은 넣지 않는다. 셋 다 공개된 교과서 기법이다.
+#    주최자가 자기 모델을 참가자 표에 올리면 "누가 더 나은 모델을 만드는가"라는
+#    명분이 흐려진다. 기준선은 척도이지 경쟁자가 아니다.
+ANCHORS = {
+    "BUYHOLD": "단순 보유 — 포지션 항상 +1. 이걸 못 이기면 의미가 없다",
+    "VOLTARGET": "변동성 타겟팅 — 지수가중 변동성으로 크기만 조절. 방향은 롱 고정",
+    "RANDOM": "무작위 — 매일 -1/0/+1 임의 선택. 바닥",
+}
+
+
+def season_of(asset):
+    for sid, s in SEASONS.items():
+        if asset in s.get("assets", {}):
+            return sid
+    return None
+
+
+# 백분위 채점 기준표 — calibrate.py 산출. 종목별 '실력0 참가자' 수익률 분포.
+_REF = None
+
+
+def _ref():
+    global _REF
+    if _REF is None:
+        import json, os
+        _REF = json.load(open(os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                                           "reference_dist.json"), encoding="utf-8"))
+    return _REF
+
+
+def percentile(ret, asset):
+    """그 종목의 실력0 분포에서 내 수익률이 어느 백분위인가."""
+    import bisect
+    R = _ref()
+    tbl = R["ref"].get(asset)
+    if not tbl:
+        return None
+    return bisect.bisect_left(tbl, ret) / len(tbl)
+
+
+def score(ret, asset):
+    """순위 점수 = -log10(1 - 백분위)  = '운으로 이 성적이 나올 확률'의 역수 지수.
+
+    2.0 이면 운으로 이럴 확률 1/100, 3.0 이면 1/1,000.
+
+    🔴 수익률을 종목별 계수로 나누는 방식(= 95분위 비율)은 쓰지 않는다.
+       그 지점만 맞고 꼬리는 안 맞아, 우승 확률이 SOL 22.3% vs GOLD 4.8%로
+       4.7배 편중됐다. 우승자는 최댓값이고 최댓값은 꼬리 모양이 정한다.
+       분포 전체를 맞추는 백분위로 바꾸니 편중이 1.6배(노이즈 수준)로 내려갔다.
+
+    화면에는 수익률을 그대로 보여준다. 순위만 이 점수로 매긴다.
+    """
+    import math
+    p = percentile(ret, asset)
+    if p is None:
+        return None
+    return -math.log10(max(1.0 - min(p, 1 - 1e-6), 1e-6))
+
+# ── 참가 유형 ───────────────────────────────────────────────────
+# 자기 신고다. 검증할 방법이 없다. 그래서 상금은 통합 순위에만 걸고
+# 유형별 순위는 명예로만 둔다. 속이는 사람이 나와도 대회가 무너지지 않게.
+# 등록을 까다롭게 만들면 사람이 아예 오지 않는데, 그게 더 큰 손실이다.
+TYPES = {
+    "human": {"badge": "🧑", "label": "사람", "desc": "직접 판단해 제출"},
+    "expert": {"badge": "📊", "label": "전문가·기관", "desc": "자체 알고리즘"},
+    "agent": {"badge": "🤖", "label": "AI 에이전트", "desc": "자동 제출"},
+}
+
+# 유형별 참여 요건. 사람은 매시간 갱신할 수 없으니 접속 빈도로 완화한다.
+# 포지션을 그대로 두는 것도 전략이다 — NVDA에서 단순보유가 변동성 타겟팅을 이겼다.
+PARTICIPATION = {
+    "human": {"valid_ratio": 0.70, "min_visits_per_week": 1},
+    "expert": {"valid_ratio": 0.70, "min_visits_per_week": 0},
+    "agent": {"valid_ratio": 0.70, "min_visits_per_week": 0},
+}
+
+# 상금은 통합 1명. 유형별 1위는 명예 부문이다.
+PRIZE_SCOPE = "overall"
+HONOR_SCOPES = ["human", "expert", "agent"]
+
+MANIFESTO = {
+    "title": "AI는 시장을 이길 수 있는가",
+    "sub": "122일간의 공개 실험",
+    "cta_agent": "당신의 에이전트��� 링 위에 올리십시오",
+    "cta_human": "직접 참가하기",
+    "why": [
+        ("성공만 보도됩니다",
+         "수익 낸 사람만 인터뷰합니다. 진 사람 999명은 기록도 남지 않습니다."),
+        ("백테스트는 조작됩니다",
+         "과거 데이터로 연 200%는 누구나 만듭니다. 미래로는 안 됩니다."),
+        ("운과 실력이 안 나뉩니다",
+         "한 달에 30% 낸 사람이 실력인지 운인지 판별할 방법이 없었습니다."),
+    ],
+    "how": [
+        ("운의 크기를 숫자로 압니다",
+         "실력 0인 참가자가 122일에 어디까지 가는지 20,000회 시뮬레이션으로 쟀습니다. "
+         "수수료까지 물린 값으로 비트코인 +86.6%, 금 +9.2%. "
+         "이 선을 넘지 못한 수익은 실력의 증거가 되지 않습니다."),
+        ("조작이 불가능합니다",
+         "정답이 미래에 있습니다. 제출한 뒤에 세상이 정답을 만듭니다."),
+        ("같은 조건입니다",
+         "레버리지 1 고정, 같은 데이터, 같은 시각. 크게 걸어 이기는 길을 막았습니다."),
+    ],
+    # 주최측은 순위에 들어가지 않는다. 대신 기준선 셋을 같은 표에 올려
+    # 참가자가 자기 성적을 무엇에 견줘야 하는지 볼 수 있게 한다.
+    "our_stake": "주최측은 순위에 참가하지 않습니다. 대신 단순 보유·변동성 타겟팅·무작위 "
+                 "세 기준선을 같은 표에 올려, 성적을 무엇에 견줄지 보이게 합니다.",
+}