> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cryptoquant.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DEV REQUESTS

# 새 API Docs 관련 개발팀 요청사항

새 API 문서 사이트(Mintlify 기반, v1 docs + catalog + Data Guide + API v2 통합)가 준비됐습니다.
배포 전후로 아래 항목들의 확인/작업을 요청드립니다. 우선순위순입니다.

***

## 1. 배포 (인프라) — 다른 모든 항목의 전제

* [ ] docs 저장소를 GitHub 조직에 생성하고 푸시 (현재 로컬: `api-v2-docs/`)
* [ ] [mintlify.com/start](https://mintlify.com/start)에서 GitHub 연동 (push 시 자동 배포)
* [ ] `docs.cryptoquant.com` DNS CNAME 설정 (Mintlify 대시보드에서 안내되는 값으로)

배포되면 자동 활성화: `/llms.txt`, `/llms-full.txt`, 모든 페이지 `.md` 서빙,
docs MCP 서버, AI 크롤러 인덱싱, `catalog.json`·OpenAPI spec 정적 서빙.

## 2. 레거시 딥링크 처리 (웹 프론트)

기존 docs 링크 `cryptoquant.com/docs#operation/<id>`, `#tag/<Tag>` 형태가 외부 곳곳에
퍼져 있습니다 (Data Guide, 커뮤니티, 구글 인덱스). **fragment(#)는 서버에 전달되지 않아
서버 리다이렉트가 불가능**하므로, 기존 `/docs` 페이지에 JS 셰임이 필요합니다.

* [ ] `cryptoquant.com/docs` 페이지에 아래 셰임 추가 (전체 269개 anchor 매핑은
  새 docs 사이트의 `/legacy-redirect-map.json`에서 제공):

```html theme={null}
<script>
(async () => {
  const NEW_DOCS = 'https://docs.cryptoquant.com';
  const hash = location.hash;
  if (!hash) { location.replace(NEW_DOCS); return; }
  const map = await fetch(NEW_DOCS + '/legacy-redirect-map.json').then(r => r.json());
  location.replace(NEW_DOCS + (map[hash] ?? ''));
})();
</script>
```

* [ ] 셰임 안정화 후 `cryptoquant.com/docs` → `docs.cryptoquant.com` 자체를 정리할지 결정

## 3. GitBook userguide 중복 정리 (콘텐츠 운영)

`userguide.cryptoquant.com`의 `api/` 섹션(50페이지)과 `cryptoquant-metrics/`(Data Guide,
75페이지)가 새 사이트로 이전·통합됐습니다. 구버전이 남아 있으면 AI가 옛 문서를 학습/인용합니다.

* [ ] GitBook의 `api/`, `cryptoquant-metrics/` 섹션 처리 방침 결정
  (권장: 새 docs로 안내 배너 또는 GitBook page redirect 설정)
* [ ] 플랫폼(웹앱) 가이드 등 나머지 섹션은 GitBook 유지 무방

## 4. API 에러 응답 개선 (백엔드) — AI 에이전트 self-recovery용

* [ ] 4xx/5xx 에러 응답 body에 해당 문서 URL 포함
  (예: `"docs": "https://docs.cryptoquant.com/guides/authentication"`)
* [ ] `429` 응답에 `Retry-After` 및 `X-RateLimit-Limit` / `X-RateLimit-Remaining` /
  `X-RateLimit-Reset` 헤더 추가

## 5. Rate limit 정보 제공 (API팀 → docs)

플랜별 호출 한도가 현재 어떤 문서에도 없습니다.

* [ ] 플랜별 한도 표 (req/min, req/day, 동시 호출 등) 전달 주시면 docs에 페이지 추가하겠습니다

## 6. MCP 서버 (MCP팀)

* [ ] MCP tool 목록(이름/설명) 공유 요청 → docs의 `catalog.json`에 "메트릭 ↔ MCP tool" 매핑 추가 예정
* [ ] tool description에 v2 Metric Guide의 해석 요약(임계값 등) 포함 검토
  — 에이전트가 docs를 따로 읽지 않아도 분석 컨텍스트 확보
* [ ] MCP 에러 응답에도 docs 링크 포함 검토
* [ ] userguide의 MCP 문서가 새 docs로 이전됨 — 이후 업데이트는 새 docs 기준으로 요청

## 7. API v2 확인사항 (API팀)

v2 docs는 내부 시트(12개 지표) 기준으로 작성했습니다. 확인 부탁드립니다:

* [ ] **(중요) v2 엔드포인트 12개 전부 `api.cryptoquant.com/v2/...`에서 404** (2026-06-12 확인).
  v1은 미인증 요청에 401을 반환하는 반면 v2는 경로 자체가 404 → v2 라우터가 해당 호스트에
  미배포 상태이거나 다른 base URL 사용 중으로 보임. 실제 서빙 host/경로 확인 요청
  (확인되면 docs의 OpenAPI `servers` URL 업데이트하겠습니다)

* [ ] 시트 오타: "Realized net **pofit** and loss" → docs에서는 "Realized Net Profit and Loss"로 수정함. 시트도 수정 요망

* [ ] "P\&L Index" → 문서/슬러그 생성에서 `&`가 문제되어 docs에서는 "PnL Index"로 표기. 공식 명칭 확정 요망

* [ ] 각 v2 엔드포인트의 정확한 파라미터 스키마 확정 (지원 `window` 값, `from`/`to` 지원 여부,
  asset 파라미터 존재 여부 — 현재 docs에는 v1 관례 기준으로 가정 작성됨)

* [ ] v2에 메트릭 디스커버리 엔드포인트(`GET /v2/catalog`) 제공 검토
  — docs의 `catalog.json`과 동일 구조면 AI 에이전트가 프로그래매틱 디스커버리 가능

## 8. 기타

* [ ] `dataset.cryptoquant.com` 응답 없음 — 서비스 유지 여부 확인 (메인 앱 번들에서 아직 링크됨)
* [ ] Neue Haas Grotesk 웹폰트 라이선스에 docs 도메인 포함되는지 확인 (Monotype)