REST API와 웹훅으로 CryptoGuide 데이터를 직접 연동합니다. Whale 플랜 전용입니다.
/api/v1 아래 읽기 전용 JSON 엔드포인트 3개, 요청마다 키 하나, 그리고 새 브리핑·리포트가 나올 때 서명된 웹훅. 아래 내용은 실제 동작하는 코드와 일치합니다.
기본 URL: https://cryptoguide.live
키는 Authorization: Bearer 헤더나 x-api-key 헤더로 보냅니다. 키는 cg_live_로 시작하고, 발급 시 한 번만 표시되며, 이 페이지에서 언제든 폐기할 수 있습니다. 계정당 활성 키는 최대 5개입니다. Whale 구독이 끝나는 순간 키도 멈추며, API의 지역별 제공 정책도 함께 적용됩니다.
curl -H "Authorization: Bearer cg_live_…" \
https://cryptoguide.live/api/v1/market/prices성공 응답은 항상 data 필드와 meta 필드를 가진 JSON 객체입니다. 시세 엔드포인트에는 stale과 updatedAt이 더 있습니다. stale: true는 모든 원천 소스가 실패해 마지막으로 성공한 값을 보고 있다는 뜻이고, updatedAt은 그 값을 가져온 시각입니다. data가 null인 경우는 그 엔드포인트에서 한 번도 값을 받은 적이 없을 때(브리핑은 아직 게시된 것이 없을 때)뿐입니다.
/api/v1/market/pricesBTC·ETH·SOL USD 시세와 24시간 등락률. 소스: CoinGecko → CoinPaprika → Binance, 서버 캐시 20초.
요청
curl -H "Authorization: Bearer cg_live_…" \
https://cryptoguide.live/api/v1/market/prices응답
{
"data": [
{ "id": "BTC", "name": "Bitcoin", "price": 64123.5, "changePct": -1.23 },
{ "id": "ETH", "name": "Ethereum", "price": 3105.2, "changePct": 0.41 },
{ "id": "SOL", "name": "Solana", "price": 142.8, "changePct": 2.05 }
],
"stale": false,
"updatedAt": "2026-08-24T01:23:45.000Z",
"meta": { … }
}필드
| data[].id | BTC | ETH | SOL |
| data[].name | 표시 이름 |
| data[].price | USD 가격(숫자) |
| data[].changePct | 24시간 등락률(%, 숫자. 소스가 제공하지 않으면 0일 수 있음) |
| stale | 모든 소스가 실패해 마지막 성공 값을 내려줄 때 true |
| updatedAt | 값을 가져온 ISO-8601 시각 또는 null |
/api/v1/market/sentimentAlternative.me의 크립토 공포·탐욕 지수, 서버 캐시 5분. 지수 자체는 하루 한 번 정도 갱신됩니다.
요청
curl -H "x-api-key: cg_live_…" \
https://cryptoguide.live/api/v1/market/sentiment응답
{
"data": { "value": 42, "classification": "Fear", "timestamp": 1756000000000 },
"stale": false,
"updatedAt": "2026-08-24T01:20:00.000Z",
"meta": { … }
}필드
| data.value | 0–100 |
| data.classification | 제공처 라벨. 예: "Extreme Fear", "Fear", "Neutral", "Greed", "Extreme Greed" |
| data.timestamp | 제공처 타임스탬프(epoch 밀리초) |
| stale / updatedAt | 위와 같음 |
/api/v1/briefs/latest가장 최근 게시된 AI 마켓 브리핑(상세 티어), 한국어·영어. 비개인화 AI 생성물이며 aiModel 필드에 모델명(템플릿 대체본이면 mock-v1)이 들어갑니다.
요청
curl -H "Authorization: Bearer cg_live_…" \
https://cryptoguide.live/api/v1/briefs/latest응답
{
"data": {
"briefDate": "2026-08-24",
"tier": "DETAILED",
"sections": {
"btc": { "ko": "…", "en": "…" },
"eth": { "ko": "…", "en": "…" },
"altcoin": { "ko": "…", "en": "…" },
"macro": { "ko": "…", "en": "…" },
"today": { "ko": "…", "en": "…" }
},
"aiModel": "claude-…",
"createdAt": "2026-08-23T22:31:02.000Z",
"aiGenerated": true
},
"meta": { … }
}필드
| data.briefDate | YYYY-MM-DD — 브리핑이 대상으로 한 날짜(작업이 날짜를 명시하지 않으면 생성 시점의 UTC 날짜) |
| data.tier | 이 엔드포인트에서는 항상 DETAILED |
| data.sections | btc, eth, altcoin, macro, today — 각각 ko·en 텍스트를 가진 객체 |
| data.aiModel | 사이트에 표시되는 모델 라벨 |
| data.createdAt | 게시 시각(ISO-8601) |
| data.aiGenerated | 항상 true |
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 37
{ "error": "rate limit exceeded" }| 상태 | error | 의미 | 대응 |
|---|---|---|---|
| 401 | missing api key | Authorization: Bearer 또는 x-api-key 헤더 없음 | 헤더 추가 |
| 401 | invalid api key | 알 수 없는 키 | 잘렸는지 확인하고 필요하면 새 키 발급 |
| 401 | api key revoked | 이 페이지에서 폐기된 키 | 새 키 발급 |
| 429 | too many failed authentication attempts | 같은 IP에서 1분 안에 인증 실패 20회 | Retry-After 초만큼 기다린 뒤 올바른 키로 재시도 |
| 403 | api access requires the Whale plan | 구독 만료 또는 Whale 미만 플랜 | 갱신·업그레이드하면 키가 자동으로 다시 동작 |
| 403 | api access is not available in your region | 지역별 제공 정책 | 키나 플랜으로는 우회 불가 |
| 429 | rate limit exceeded | 현재 1분 창에서 60회 초과 | Retry-After 초만큼 기다린 뒤 재시도 |
| 429 | monthly quota exceeded | 이번 달(UTC) 100,000회 소진 | 매월 1일(UTC) 초기화. 이 경우 Retry-After 헤더는 1분 창 기준이므로 참고만 |
오류 본문은 error 문자열 하나만 담은 JSON 객체이며, 메시지는 위 표 그대로입니다.
모든 응답 끝에는 meta 객체가 있습니다. provider("CryptoGuide API v1"), docs(이 페이지 링크), disclaimer(ko·en), terms(ko·en)입니다. 데이터는 정보 제공 목적이며 투자 권유가 아니고, 재배포·재판매·공개 게시는 금지됩니다. 데이터를 저장하거나 표시할 때는 면책 문구와 이용 조건을 함께 두세요.
"meta": {
"provider": "CryptoGuide API v1",
"docs": "https://cryptoguide.live/api-center",
"disclaimer": { "ko": "본 데이터는 정보 제공 목적으로만 제공되며 투자 권유가 아닙니다. …", "en": "This data is provided for informational purposes only and is not investment advice. …" },
"terms": { "ko": "데이터의 재배포·재판매·대중 공개 게시를 금지합니다. …", "en": "Redistribution, resale, or public re-publication of this data is prohibited. …" }
}https URL(포트 443 또는 8443)을 등록하면 브리핑이나 리포트가 게시될 때 그 주소로 POST를 보냅니다. 계정당 최대 5개. 발송 타임아웃은 5초이고 재시도는 하지 않으며, 마지막 HTTP 상태가 각 웹훅 옆에 표시됩니다. 사설·내부 주소로 해석되는 URL은 등록 단계에서 거부됩니다.
이벤트와 data 필드: brief.published(briefDate, tier); report.published(slug, locale, cadence, category, periodKey); test.ping(message — 테스트 발송 버튼). 본문은 항상 id, event, data, sentAt입니다.
헤더: content-type: application/json, x-cryptoguide-event: <이벤트>, x-cryptoguide-delivery: <발송 ID, 본문의 id와 같음>, x-cryptoguide-signature: sha256=<웹훅 시크릿을 키로 원문 본문을 HMAC-SHA256한 16진수>.
POST https://example.com/webhook
content-type: application/json
x-cryptoguide-event: brief.published
x-cryptoguide-delivery: 0b9d6c1e-6a52-4c0e-9a55-3f1f6f0f2a11
x-cryptoguide-signature: sha256=9f2c…
{ "id": "0b9d6c1e-6a52-4c0e-9a55-3f1f6f0f2a11", "event": "brief.published", "data": { "briefDate": "2026-08-24", "tier": "STANDARD" }, "sentAt": "2026-08-23T22:31:05.000Z" }요청 원문 본문으로 HMAC을 다시 계산해 상수 시간 비교로 검증하세요. 일치하지 않으면 거부하세요. 재전송 방어가 필요하면 오래된 sentAt을 거부하고, 이미 처리한 id가 다시 오면 무시하세요.
import crypto from 'node:crypto'
export function verify(rawBody: string, header: string, secret: string) {
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
return expected.length === header.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header))
}API 키와 웹훅은 계정에 묶여 있고 사용 내역이 기록됩니다. 아래는 우리가 자동으로 하는 일과 이용자가 지켜야 할 일입니다.
취약점이나 악용 사례를 발견하면 /.well-known/security.txt 에 적힌 연락처로 알려 주세요.
현재 v1입니다. 필드는 추가될 수 있지만, 기존 필드는 새 버전 접두사 없이 이름이 바뀌거나 삭제되지 않습니다.