엔드포인트 레퍼런스

모든 엔드포인트는 https://api.cognivolabs.io/v1/api 아래에 있습니다. 인텔리전스 엔드포인트는 JSON 본문이 있는 POST입니다 (이렇게 하면 링크 미리보기, 크롤러, 프리페처가 실행을 트리거하는 일을 원천 차단합니다). GET은 health, me, discover에만 존재합니다.

기계가 읽을 수 있는 버전이 필요하신가요? 전체 OpenAPI 스펙이 이 페이지의 모든 내용을 담고 있습니다.

응답 엔벨로프

모든 엔드포인트는 동일한 엔벨로프로 응답합니다. 성공 시:

{
  "ok": true,
  "data": { "...": "the result" },
  "meta": {
    "chain": "base",
    "request_id": "capi_9f2c41d8a0b34e7c9d5a1f02",
    "credits_charged": 0,
    "generated_at": "2026-07-09T00:00:00.000Z"
  }
}

data - 인텔리전스 결과 자체이며, 형태는 엔드포인트마다 다릅니다
meta.request_id - 이 호출의 고유 ID. 보관해 두면 지원팀이 이 값으로 호출을 추적할 수 있습니다
meta.credits_charged - 이 호출이 쓴 크레딧: 무료 엔드포인트, 샌드박스 데모나 트라이얼 허용량, 실패했거나 빈 결과에서는 0. 유료 사용에서는 해당 엔드포인트의 크레딧 가격
meta.generated_at - 결과가 생성된 시각
meta.chain은 체인별 호출에 나타나고, meta.sources(소스 라벨 배열)는 결과가 소스를 인용할 때 나타납니다

실패 시:

{ "ok": false, "error": "invalid_chain", "message": "chain must be one of: eth, base, bsc", "request_id": "capi_..." }

error는 안정적인 기계 판독용 코드입니다 (속도 제한 및 오류 참고). message는 사람을 위한 선택적 힌트입니다.

공통 본문 필드

chain - eth, base, bsc 중 하나 (대소문자 구분 없음)
address / wallet / token - 0x… EVM 주소 (16진수 40자)

아래 모든 예제는 자리표시자 YOUR_API_KEY를 사용합니다. 실제 코드에서는 키를 환경 변수나 시크릿 매니저에서 불러오고 절대 하드코딩하지 마세요.

접근과 크레딧 비용

실행형 인텔리전스 엔드포인트에는 트라이얼, 파트너, 유료 또는 엔터프라이즈 접근이 필요합니다. 접근 권한이 없으면 무료로 실행되지 않고 access_required 같은 명확한 403 오류가 반환됩니다 (속도 제한 및 오류 참고). 유료 사용은 성공한 호출당 Cognivo 크레딧으로 과금되며, 실패한 호출에는 과금되지 않습니다. 엔드포인트별 비용 (유료 사용에 적용되며, 투명성을 위해 공개합니다):

엔드포인트	성공한 호출당 크레딧
`POST intel/liquidity`	2
`POST intel/risk`	2
`POST wallet/approvals`	2
`POST intel/why-down`	3
`POST intel/team-wallets`	5
`POST wallet/exact-movements`	5
`POST wallet/pnl`	10
`GET health`, `GET me`	무료
`GET discover`	무료 (엄격한 속도 상한 적용)

서비스

GET /v1/api/health

생존 확인 프로브. API 키가 필요 없습니다.

curl 'https://api.cognivolabs.io/v1/api/health'

const res = await fetch("https://api.cognivolabs.io/v1/api/health");
const json = await res.json();

응답 (의도적으로 표준 엔벨로프가 아님):

{ "ok": true, "service": "cognivo-public-api", "version": "v1", "generated_at": "2026-07-09T00:00:00.000Z" }

한계: 공개 API가 꺼져 있으면 여기서도 404 public_api_disabled가 반환되므로, 이 엔드포인트는 가용성 체크 역할도 겸합니다.

GET /v1/api/me

호출한 키를 조회합니다. 스코프: 아무 유효한 키. 무료. 셀프서브 라이브 키의 경우, 소유 계정의 credits_balance(일시적으로 사용할 수 없으면 null)와 top_up 안내, 그리고 키의 access_mode도 함께 보여 줍니다.

curl 'https://api.cognivolabs.io/v1/api/me' \
  -H 'X-API-Key: YOUR_API_KEY'

const res = await fetch("https://api.cognivolabs.io/v1/api/me", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const json = await res.json();

응답:

{
  "ok": true,
  "data": {
    "key": "cogv_live_****abcd",
    "project_id": "…",
    "environment": "live",
    "tier": "basic",
    "access_mode": "live",
    "scopes": ["intel:read", "liquidity:read"],
    "rate_limit_per_hour": 1000,
    "credits_balance": 1250,
    "top_up": "Top up Cognivo credits on your account billing page in the dApp."
  },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

한계: 마스킹된 키만 보여 주며, 전체 키 원문은 절대 보여 주지 않습니다. credits_balance는 소유 계정의 Cognivo 크레딧 잔액이며, 일시적으로 사용할 수 없을 때는 null일 수 있습니다.

토큰 인텔리전스

POST /v1/api/intel/why-down - 스코프 `intel:read`

이 토큰이 왜 하락하는가: 최근 온체인 활동을 근거에 기반해 읽어 지배적 요인(매도, LP 회수, 소유자 자금 이동)을 찾습니다.

접근과 비용: 라이브 접근(트라이얼, 파트너, 유료 또는 엔터프라이즈)이 필요합니다. 유료 사용 시 성공한 호출당 3 크레딧.

요청 본문:

{ "chain": "base", "address": "0xTOKEN_CONTRACT" }

curl -X POST 'https://api.cognivolabs.io/v1/api/intel/why-down' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"base","address":"0xTOKEN_CONTRACT"}'

const res = await fetch("https://api.cognivolabs.io/v1/api/intel/why-down", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "base", address: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();

응답: 표준 엔벨로프. data에 하락 분석(지배적 요인과 이를 뒷받침하는 온체인 관찰)이 담기고 meta.chain이 설정됩니다.

한계: 유용한 결론을 내려면 최근 활동이 필요합니다. 거래 이력이 아주 적은 토큰은 읽어낼 내용이 빈약할 수 있습니다. 신호일 뿐 투자 조언이 아닙니다.

POST /v1/api/intel/team-wallets - 스코프 `intel:read`

토큰의 팀 및 컨트롤러 지갑 스캔: 배포자, 소유자, 컨트롤러 지갑과 그들의 최근 행동.

접근과 비용: 라이브 접근(트라이얼, 파트너, 유료 또는 엔터프라이즈)이 필요합니다. 유료 사용 시 성공한 호출당 5 크레딧.

요청 본문:

{ "chain": "eth", "address": "0xTOKEN_CONTRACT" }

curl -X POST 'https://api.cognivolabs.io/v1/api/intel/team-wallets' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"eth","address":"0xTOKEN_CONTRACT"}'

const res = await fetch("https://api.cognivolabs.io/v1/api/intel/team-wallets", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "eth", address: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();

응답: 표준 엔벨로프. data에 식별된 팀/컨트롤러 지갑과 최근 행동이 나열되며, 종종 meta.sources가 함께 옵니다.

한계: 지갑 식별은 온체인 관계(배포, 소유, 통제)에 기반합니다. 오프체인 팀 구조는 볼 수 없습니다.

POST /v1/api/intel/liquidity - 스코프 `liquidity:read`

토큰의 풀/LP 상태: 풀 상황, LP 보관, 잠금/소각 현황.

접근과 비용: 라이브 접근(트라이얼, 파트너, 유료 또는 엔터프라이즈)이 필요합니다. 유료 사용 시 성공한 호출당 2 크레딧.

요청 본문 (선택적 불리언 metadata, locks, full은 각각 근거 있는 풀 메타데이터, 시한 잠금 증명, 사용 가능한 가장 풍부한 읽기를 추가합니다):

{ "chain": "base", "address": "0xTOKEN_CONTRACT", "locks": true }

curl -X POST 'https://api.cognivolabs.io/v1/api/intel/liquidity' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"base","address":"0xTOKEN_CONTRACT","locks":true}'

const res = await fetch("https://api.cognivolabs.io/v1/api/intel/liquidity", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "base", address: "0xTOKEN_CONTRACT", locks: true }),
});
const json = await res.json();

응답: 표준 엔벨로프. data에 토큰 식별 정보, 시장 스냅샷, LP 보관 및 잠금/소각 현황이 담깁니다.

한계: 깊은 과거 소각 이력(provenance)은 v1에서 노출되지 않습니다. 잠금 현황은 알려진 락커 패턴을 다루며, 인식되지 않는 커스텀 락커는 잠기지 않은 보관으로 읽힐 수 있습니다.

POST /v1/api/intel/risk - 스코프 `intel:read`

토큰에 대한 체인 인식 Cognivo 리스크 신호 (폴백으로 레드 플래그 읽기).

접근과 비용: 라이브 접근(트라이얼, 파트너, 유료 또는 엔터프라이즈)이 필요합니다. 유료 사용 시 성공한 호출당 2 크레딧.

요청 본문:

{ "chain": "bsc", "address": "0xTOKEN_CONTRACT" }

curl -X POST 'https://api.cognivolabs.io/v1/api/intel/risk' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"bsc","address":"0xTOKEN_CONTRACT"}'

const res = await fetch("https://api.cognivolabs.io/v1/api/intel/risk", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "bsc", address: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();

응답: 표준 엔벨로프. data에 해당 토큰에서 발견된 리스크 신호와 플래그가 담깁니다.

한계: 깨끗한 결과가 결코 "안전"을 뜻하지 않습니다. 읽는 시점에 알려진 레드 플래그가 발견되지 않았다는 뜻일 뿐입니다.

지갑 인텔리전스

POST /v1/api/wallet/pnl - 스코프 `intel:read`

한 토큰에 대한 지갑의 실현 손익을 검증된 지갑 활동으로부터 계산합니다. wallet과 token 모두 필수입니다.

접근과 비용: 라이브 접근(트라이얼, 파트너, 유료 또는 엔터프라이즈)이 필요합니다. 유료 사용 시 성공한 호출당 10 크레딧.

요청 본문:

{ "chain": "base", "wallet": "0xWALLET", "token": "0xTOKEN_CONTRACT" }

curl -X POST 'https://api.cognivolabs.io/v1/api/wallet/pnl' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"base","wallet":"0xWALLET","token":"0xTOKEN_CONTRACT"}'

const res = await fetch("https://api.cognivolabs.io/v1/api/wallet/pnl", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "base", wallet: "0xWALLET", token: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();

응답: 표준 엔벨로프. data에 해당 지갑/토큰 쌍의 실현 손익 계산 결과가 담깁니다.

한계: 지갑에 그 토큰의 가격이 매겨진 거래가 없어 공정한 수치를 계산할 수 없으면 422(예: insufficient_data)를 반환합니다. Cognivo는 절대 수치를 지어내지 않으며, 422에는 절대 과금되지 않습니다. 실현 손익만 다루며, 미실현(보유 중) 포지션은 여기서 평가되지 않습니다.

POST /v1/api/wallet/approvals - 스코프 `security:read`

지갑에 걸려 있는 토큰 승인을 반환하고 무제한 허용량에 플래그를 답니다. 읽기 전용: Cognivo는 절대 자금을 옮기지 않으며 대신 철회해 줄 수도 없습니다.

접근과 비용: 라이브 접근(트라이얼, 파트너, 유료 또는 엔터프라이즈)이 필요합니다. 유료 사용 시 성공한 호출당 2 크레딧.

요청 본문 (limit과 offset으로 큰 승인 목록을 선택적으로 페이지네이션할 수 있음):

{ "chain": "eth", "address": "0xWALLET" }

curl -X POST 'https://api.cognivolabs.io/v1/api/wallet/approvals' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"eth","address":"0xWALLET"}'

const res = await fetch("https://api.cognivolabs.io/v1/api/wallet/approvals", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "eth", address: "0xWALLET" }),
});
const json = await res.json();

응답: 표준 엔벨로프. data에 스펜더, 토큰, 허용량 정보가 포함된 승인 목록이 담깁니다.

한계: 빈 결과(발견된 승인 없음)도 유효한 성공 응답이며, 과금되지 않습니다.

POST /v1/api/wallet/exact-movements - 스코프 `intel:read`

지갑의 정확한 최근 자금 이동 (소유자/배포자 스타일 읽기). token은 선택 사항이며 지정하면 하나의 토큰으로 범위를 좁힙니다.

접근과 비용: 라이브 접근(트라이얼, 파트너, 유료 또는 엔터프라이즈)이 필요합니다. 유료 사용 시 성공한 호출당 5 크레딧.

요청 본문:

{ "chain": "base", "wallet": "0xWALLET", "token": "0xTOKEN_CONTRACT" }

curl -X POST 'https://api.cognivolabs.io/v1/api/wallet/exact-movements' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"base","wallet":"0xWALLET"}'

const res = await fetch("https://api.cognivolabs.io/v1/api/wallet/exact-movements", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "base", wallet: "0xWALLET" }),
});
const json = await res.json();

응답: 표준 엔벨로프. data에 건수와 함께 자금 이동 목록이 담깁니다.

한계: 가장 최근의 이동(호출당 최대 25건)을 반환합니다. 일치하는 이동이 없는 지갑에는 지어낸 이력이 아니라 422가 반환됩니다.

Discover

GET /v1/api/discover

공개 Discover 피드: 최신 고품질 공개 인텔리전스 카드(토큰 식별 정보, 훅, 요점 목록). 스코프: 아무 유효한 키. 무료 (엄격한 속도 상한 적용).

쿼리 파라미터: limit (1-50, 기본값 20)과 선택적 chain (eth, base, bsc).

curl 'https://api.cognivolabs.io/v1/api/discover?limit=10&chain=base' \
  -H 'X-API-Key: YOUR_API_KEY'

const res = await fetch("https://api.cognivolabs.io/v1/api/discover?limit=10&chain=base", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const json = await res.json();

응답:

{
  "ok": true,
  "data": { "cards": [ { "...": "public intelligence card" } ], "total": 10 },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

한계: 1-50 범위를 벗어나는 limit 값은 범위 안으로 강제 조정됩니다. 피드에는 사용자가 공개를 선택한 인텔리전스만 담기므로, 전체가 아니라 샘플입니다.

계획 중 (아직 사용 불가)

다음은 로드맵 투명성을 위해 문서화한 것으로, 현재는 아무것도 반환하지 않습니다:

API를 통한 딥 지갑 트레이스 (wallet/trace) - 비동기 작업 플로우는 당분간 Chat/dApp 전용입니다
ID로 리포트 조회 (reports/:id)
웹훅
Solana 엔드포인트

응답 엔벨로프​

공통 본문 필드​

접근과 크레딧 비용​

서비스​

GET /v1/api/health​

GET /v1/api/me​

토큰 인텔리전스​

POST /v1/api/intel/why-down - 스코프 intel:read​

POST /v1/api/intel/team-wallets - 스코프 intel:read​

POST /v1/api/intel/liquidity - 스코프 liquidity:read​

POST /v1/api/intel/risk - 스코프 intel:read​

지갑 인텔리전스​

POST /v1/api/wallet/pnl - 스코프 intel:read​

POST /v1/api/wallet/approvals - 스코프 security:read​

POST /v1/api/wallet/exact-movements - 스코프 intel:read​

Discover​

GET /v1/api/discover​

계획 중 (아직 사용 불가)​

응답 엔벨로프

공통 본문 필드

접근과 크레딧 비용

서비스

GET /v1/api/health

GET /v1/api/me

토큰 인텔리전스

POST /v1/api/intel/why-down - 스코프 `intel:read`

POST /v1/api/intel/team-wallets - 스코프 `intel:read`

POST /v1/api/intel/liquidity - 스코프 `liquidity:read`

POST /v1/api/intel/risk - 스코프 `intel:read`

지갑 인텔리전스

POST /v1/api/wallet/pnl - 스코프 `intel:read`

POST /v1/api/wallet/approvals - 스코프 `security:read`

POST /v1/api/wallet/exact-movements - 스코프 `intel:read`

Discover

GET /v1/api/discover

계획 중 (아직 사용 불가)