엔드포인트 레퍼런스

이 페이지는 무엇인가요

Cognivo Developer API를 사용하면 앱이 답하는 것과 동일한 질문을 여러분의 코드에서 Cognivo에게 물어볼 수 있습니다. 모든 엔드포인트는 https://api.cognivolabs.io/v1/api 아래에 있습니다.

앱이 아닌 다른 곳, 즉 여러분의 봇, 대시보드, 스프레드시트 작업, 또는 토큰 목록을 감시하는 야간 스크립트 안에서 Cognivo 체크를 실행하고 싶을 때 사용하세요.

인텔리전스 엔드포인트는 JSON 본문을 사용하는 POST입니다. 이는 의도된 설계입니다. 링크 미리보기, 크롤러, 브라우저 프리페치가 URL을 불러오는 것만으로 실행을 트리거할 수 없게 하기 위해서입니다. GET은 health, me, discover에만 존재합니다.

앱에서 어디에서 찾나요

Cognivo 앱에 로그인한 뒤 왼쪽 사이드바의 Account 아래에서 Developers를 열고 Endpoints 탭을 선택하세요.

Endpoints 탭이 열린 Developers 페이지로, Intelligence, Security, Liquidity 그룹이 있는 권한 설명 카드와 그 아래 모두 Free로 표시된 엔드포인트 항목 두 개가 보입니다. — Developers 페이지의 Endpoints 탭으로, 각 Cognivo 엔드포인트마다 필요한 권한과 비용이 나열됩니다.이미지 확대

이 탭은 실행 도구가 아니라 레퍼런스입니다. 모든 라이브 엔드포인트를 복사 가능한 예제, 키에 필요한 권한, 크레딧 기준 가격과 함께 나열합니다. Permissions explained 카드는 그 권한들을 세 가지로 묶습니다. Intelligence(왜 하락 중인지, 팀 지갑, 리스크, 지갑 손익, 정확한 이동 내역), Security(토큰 승인), Liquidity(유동성, 잠금과 소각)입니다. 각 키에는 꼭 필요한 권한만 부여하세요.

기계가 읽을 수 있는 버전을 원하시나요? 전체 OpenAPI 스펙이 이 페이지의 모든 내용을 다룹니다.

응답 봉투(envelope)

모든 엔드포인트는 동일한 봉투 형태로 응답합니다. 아래 예제의 id와 타임스탬프는 자리표시자 값입니다. 성공 시:

{
  "ok": true,
  "data": { "...": "the result" },
  "meta": {
    "chain": "base",
    "request_id": "capi_9f2c41d8a0b34e7c9d5a1f02",
    "credits_charged": 2,
    "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(Ethereum), base(Base), bsc(BNB Chain) 중 하나이며 대소문자를 구분하지 않습니다.
address, wallet, token은 16진수 40자로 이루어진 0x EVM 주소입니다.

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

각 엔드포인트의 비용

라이브 키는 셀프 서비스이며 종량제입니다. 새 라이브 키는 이 엔드포인트들을 곧바로 실행하며, 성공한 호출마다 계정 잔액에서 Cognivo 크레딧이 차감됩니다. 실패한 호출에는 절대 과금되지 않고, 성공한 호출은 정확히 한 번만 과금되므로 같은 작업을 반복 제출해도 이중 과금될 수 없습니다.

모든 계정은 매일 5 무료 크레딧을 받으며, UTC 자정에 초기화됩니다. 잔액으로 호출 비용을 감당할 수 없으면 402 payment_required가 반환되고 아무것도 과금되지 않습니다. 계정 결제 페이지에서 충전한 뒤 다시 시도하세요. 샌드박스(cogv_test_) 키는 라이브 인텔리전스를 실행할 수 없습니다. 결제와 크레딧을 참고하세요.

엔드포인트	성공한 호출당 크레딧
`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
`POST contract/analysis`	무료
`GET health`, `GET me`	무료
`GET discover`	무료, 단 엄격한 요청 상한 적용

서비스

GET /v1/api/health

Cognivo API가 정상 동작 중인지 확인합니다. 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와 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": "Manage credits from your Cognivo account billing page."
  },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

제한: 마스킹된 키만 보여주며, 전체 키 값은 절대 보여주지 않습니다. credits_balance는 null로 돌아올 수 있는데, 이는 그 시점에 Cognivo가 잔액을 읽지 못했다는 뜻이지 잔액이 0이라는 뜻이 아닙니다.

나머지 엔드포인트는 모두 아래 예제와 동일한 호출 형태를 따릅니다. 경로와 본문 필드만 바꾸면 됩니다.

토큰 인텔리전스

POST /v1/api/intel/why-down, 권한 Intelligence (`intel:read`)

토큰 가격이 왜 하락했는지를 최근 온체인 활동에서 구성해 평이한 언어로 읽어줍니다. 대량 매도, 유동성 회수, 소유자나 팀 지갑의 이동 같은 것들입니다.

표시 가격: 성공한 호출당 3 크레딧. 실패한 호출에는 절대 과금되지 않습니다. 현재 Developer API 호출에 대한 과금은 꺼져 있어, 호출이 성공해도 아무것도 차감되지 않고 잔액도 변하지 않습니다.

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, 권한 Intelligence (`intel:read`)

토큰의 팀이나 트레저리와 연결된 지갑을 드러냅니다. 배포자, 소유자, 컨트롤러 지갑과 그들이 최근에 한 행동입니다.

표시 가격: 성공한 호출당 5 크레딧. 실패한 호출에는 절대 과금되지 않습니다. 현재 Developer API 호출에 대한 과금은 꺼져 있어, 호출이 성공해도 아무것도 차감되지 않고 잔액도 변하지 않습니다.

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"}'

응답: 표준 봉투. data에는 식별된 지갑들과 그들의 최근 행동이 나열되며, 대체로 meta.sources가 함께 옵니다.

제한: 지갑은 배포, 소유권, 통제 같은 온체인 관계에서 식별됩니다. Cognivo는 오프체인 팀 구조를 볼 수 없으므로, 목록이 비어 있다는 것은 온체인에서 연결할 수 있는 것이 없었다는 뜻이지 그 토큰에 팀이 없다는 뜻이 아닙니다.

POST /v1/api/intel/liquidity, 권한 Liquidity (`liquidity:read`)

토큰의 유동성, 잠금, 소각을 온체인 증거와 함께 확인합니다. 풀 맥락, LP 토큰을 누가 보유하고 있는지, 그리고 잠금 또는 소각 맥락입니다.

표시 가격: 성공한 호출당 2 크레딧. 실패한 호출에는 절대 과금되지 않습니다. 현재 Developer API 호출에 대한 과금은 꺼져 있어, 호출이 성공해도 아무것도 차감되지 않고 잔액도 변하지 않습니다.

선택적 불리언 값 metadata, locks, full은 각각 풀 메타데이터, 시간이 명시된 잠금 증거, 이용 가능한 가장 상세한 읽기를 추가합니다.

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}'

응답: 표준 봉투. data에는 토큰 신원, 시장 스냅샷, 그리고 잠금 또는 소각 맥락이 포함된 LP 보관 정보가 담깁니다.

제한: 깊은 소각 이력의 출처 추적은 v1에서 제공되지 않습니다. 잠금 맥락은 알려진 락커 패턴을 다루므로, 특이한 커스텀 락커는 잠금이 아니라 일반 보관으로 읽힐 수 있습니다. 그것은 "잠기지 않음"이 아니라 "검증되지 않음"으로 읽으세요.

POST /v1/api/intel/risk, 권한 Intelligence (`intel:read`)

토큰 컨트랙트에 대한 Cognivo 리스크 신호로, 체인을 인식하며 위험 신호(red flags) 읽기를 대체 수단으로 제공합니다.

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"}'

응답: 표준 봉투. data에는 그 토큰에서 발견된 신호와 플래그가 담깁니다.

제한: 깨끗한 결과가 토큰이 안전하다는 뜻은 아닙니다. 읽은 시점에 알려진 위험 신호가 발견되지 않았다는 뜻입니다.

POST /v1/api/contract/analysis, 권한 Contract (`contract:read`)

컨트랙트 주소에 대한 컨트랙트 및 통제 증거입니다. 존재하는지, 누가 소유하는지, 소유권이 포기되었는지, 프록시인지와 누가 관리하는지, 누가 배포했는지, 어떤 지갑이 컨트롤러나 팀으로 귀속되는지, 소스가 검증되었는지입니다.

비용: 0 크레딧. 이 엔드포인트는 모든 플랜에서 결정에 따라 무료입니다. 아무것도 차감되지 않습니다.

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

응답: 표준 봉투. data에는 contract, ownership, proxy, deployer, controllers, source_verification, limitations, unavailable이 담깁니다.

모든 필드는 그 값이 어디에서 왔는지 알려줍니다. meta.provenance가 각 필드를 다음 중 정확히 하나에 대응시킵니다:

라벨	의미
`verified_onchain`	요청 시점에 해당 네트워크의 노드에서 읽었습니다. 사실입니다.
`augmented`	Cognivo Augmented Intelligence: 외부 소스가 제공했고 교차 확인했지만 Cognivo가 증명한 것은 아닙니다.
`interpretation`	사실에 대한 Cognivo의 해석입니다. 사실이 아니라 판단입니다.
`unavailable`	Cognivo가 이 값을 가져오지 못했습니다. 이유는 `data.unavailable`에 있습니다.

빈칸을 채우려고 추측하거나 기본값을 넣거나 0으로 반환하는 일은 없습니다.

meta.chain_data_source.cognivo_grounded는 그 읽기의 출처가 되는 인프라를 Cognivo가 직접 운영하는지 알려줍니다. Cognivo는 자체 Ethereum 노드를 운영하므로 Ethereum 읽기는 true입니다. Base와 BNB Chain 읽기는 외부 RPC 인프라에서 오므로 false입니다. 그 읽기들도 정확하지만 Cognivo가 통제하는 하드웨어에서 제공되는 것은 아니며, Cognivo는 여러분이 다르게 짐작하도록 두지 않고 그 사실을 밝힙니다.

Base에서의 제한이며, data.limitations에도 반환됩니다:

깊은 컨트롤러 그래프는 Ethereum 전용입니다. Base에서는 컨트롤러와 팀 귀속이 더 좁은 지갑 역할 읽기에서 나옵니다.
Base의 배포자 증거는 Cognivo 아카이브 읽기가 아니라 외부 소스에서 옵니다. 증명된 사실이 아니라 강력한 단서로 받아들이세요.
Base에서는 유동성 잠금 일정이 디코딩되지 않습니다. LP 보관과 소각 증거는 POST /v1/api/intel/liquidity를 사용하고, 잠금 정보가 없다고 해서 잠금이 없는 것으로 읽지 마세요.

이 엔드포인트는 컨트랙트 통제 증거만 보고합니다. 유동성에 대해서는 아무것도 말하지 않으며, 깨끗한 결과가 결코 컨트랙트가 안전하다는 뜻은 아닙니다.

읽기 전용입니다. 아무것도 서명하지 않고, 트랜잭션을 만들지 않으며, 브로드캐스트하지 않고, 어떤 지갑도 위임하지 않습니다.

지갑 인텔리전스

POST /v1/api/wallet/pnl, 권한 Intelligence (`intel:read`)

근거가 확보된 온체인 스왑으로 계산한, 한 지갑의 한 토큰에 대한 손익입니다. wallet과 token 모두 필수입니다.

표시 가격: 성공한 호출당 10 크레딧. 실패한 호출과 데이터 없음을 뜻하는 422 결과에는 절대 과금되지 않습니다. 현재 Developer API 호출에 대한 과금은 꺼져 있어, 호출이 성공해도 아무것도 차감되지 않고 잔액도 변하지 않습니다.

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"}'

응답: 표준 봉투. data에는 실현 수치가, 그리고 방어 가능한 취득 원가를 산출할 수 있는 경우 아직 보유 중인 포지션의 미실현 수치가 담깁니다.

제한: 방어 가능한 취득 원가를 확립할 수 없을 때 미실현 수치는 지어낸 숫자 대신 null로 돌아옵니다. 그 지갑에 해당 토큰의 가격이 매겨진 거래가 전혀 없으면 호출은 422(예: insufficient_data)를 반환하며, 이는 Cognivo가 공정한 수치를 계산할 수 없었다는 뜻이지 수익이 0이었다는 뜻이 아닙니다. 422에는 절대 과금되지 않습니다. Cognivo가 가격을 매길 수 없었던 스왑은 버려지지 않고 가격 미산정으로 표시됩니다.

POST /v1/api/wallet/approvals, 권한 Security (`security:read`)

지갑이 부여한 토큰 사용 승인을 나열하고 무제한 허용량을 표시합니다.

선택적 limit과 offset으로 큰 승인 목록을 페이지 단위로 조회할 수 있습니다.

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"}'

응답: 표준 봉투. data에는 사용자(spender), 토큰, 허용량 맥락이 포함된 승인 목록이 담깁니다.

제한: 이것은 읽기 전용입니다. Cognivo는 자금을 옮기지 않으며 여러분을 대신해 승인을 취소할 수 없습니다. 취소는 언제나 여러분의 지갑에서 직접 해야 합니다. 빈 목록도 유효한 성공 응답이며 과금되지 않습니다.

POST /v1/api/wallet/exact-movements, 권한 Intelligence (`intel:read`)

지갑의 정확한 토큰 이동 내역을 나열합니다. 매수, 매도, 전송입니다. token은 선택 사항이며 읽기를 한 토큰으로 좁힙니다.

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"}'

응답: 표준 봉투. 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'

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

제한: 1에서 50 범위를 벗어난 limit 값은 범위 안으로 조정됩니다. 이 피드에는 사용자가 공개하기로 선택한 인텔리전스만 담기므로, 전체를 포괄하는 것이 아니라 표본입니다.

아직 제공되지 않는 것

투명성을 위해 나열하며, 현재는 아무것도 반환하지 않습니다:

API를 통한 딥 지갑 추적(wallet/trace). 비동기 작업 흐름은 현재 채팅과 앱 전용입니다.
id로 리포트 가져오기(reports/:id).
웹훅.
Solana 엔드포인트.

다음 단계

퀵스타트에서 첫 호출을 해보고, 인증과 API 키에서 키를 만들고 권한 범위를 정하세요. 그리고 무언가를 정기 실행에 올리기 전에 속도 제한과 오류를 읽어보세요.

이 페이지는 무엇인가요​

앱에서 어디에서 찾나요​

응답 봉투(envelope)​

공통 본문 필드​

각 엔드포인트의 비용​

서비스​

GET /v1/api/health​

GET /v1/api/me​

토큰 인텔리전스​

POST /v1/api/intel/why-down, 권한 Intelligence (intel:read)​

POST /v1/api/intel/team-wallets, 권한 Intelligence (intel:read)​

POST /v1/api/intel/liquidity, 권한 Liquidity (liquidity:read)​

POST /v1/api/intel/risk, 권한 Intelligence (intel:read)​

POST /v1/api/contract/analysis, 권한 Contract (contract:read)​

지갑 인텔리전스​

POST /v1/api/wallet/pnl, 권한 Intelligence (intel:read)​

POST /v1/api/wallet/approvals, 권한 Security (security:read)​

POST /v1/api/wallet/exact-movements, 권한 Intelligence (intel:read)​

Discover​

GET /v1/api/discover​

아직 제공되지 않는 것​

다음 단계​