Skip to main content

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

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

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

  • docs 저장소를 GitHub 조직에 생성하고 푸시 (현재 로컬: api-v2-docs/)
  • 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에서 제공):
<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개 지표) 기준으로 작성했습니다. 확인 부탁드립니다:
  • 시트 오타: “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)