퀵스타트

제로에서 첫 실제 인텔리전스 결과까지 약 1분: 키를 만들고, 명령어 하나를 붙여넣고, 답을 읽으면 됩니다.

1. API 키 만들기

1. Developer 포털을 열고 Cognivo 계정으로 로그인합니다.
2. 프로젝트를 만듭니다 (예: "My trading bot").
3. API 키를 만듭니다. 필요한 권한(스코프)을 선택하세요. 이 퀵스타트에서는 Token and wallet intelligence(intel:read)와 Liquidity reads(liquidity:read)를 부여합니다.
4. 키를 지금 바로 복사하세요. 딱 한 번만 표시되며, 이후에는 마스킹된 버전(cogv_live_****abcd)만 볼 수 있습니다. 잃어버렸다면 키를 로테이션하세요.

키에는 두 가지 환경이 있습니다:

• cogv_test_... - 라이브 체인 데이터에 대한 통합 테스트용 샌드박스 키. 상한이 엄격하며(시간당 25 요청, 일 100 요청), 관리자가 활성화한 경우에만 소량의 라이브 데모 허용량을 실행할 수 있습니다.
• cogv_live_... - 프로덕션 키. 라이브 인텔리전스 엔드포인트에는 트라이얼, 파트너, 유료 또는 엔터프라이즈 접근이 필요합니다. 접근 모드를 참고하세요.

2. 키 확인하기

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

마스킹된 키, 프로젝트, 환경, 스코프, 시간당 속도 제한이 반환됩니다.

3. 라이브 엔드포인트 하나 시도해 보기 (curl)

인텔리전스 엔드포인트는 JSON 본문이 있는 POST를 사용합니다. 아래 명령은 실제 Base 토큰(RWA Inc, 데모에 사용하는 공개 컨트랙트)에 대해 실제 유동성 체크를 실행합니다. 접근 권한이 있는 키에서 실행됩니다: 관리자가 라이브 데모 허용량을 활성화한 샌드박스 키, 또는 트라이얼, 파트너, 유료, 엔터프라이즈 접근을 가진 키:

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":"0xe2b1dc2d4a3b4e59fdf0c47b71a7a86391a8b35a"}'

접근 권한이 있다면 "ok": true와 함께 data에 토큰 식별 정보(이름/심볼), 시장 스냅샷, LP/잠금 현황이 보일 것입니다. meta.credits_charged는 이 호출의 비용을 보여 줍니다: 샌드박스 데모나 트라이얼 허용량에서는 0, 유료 사용에서는 해당 엔드포인트의 크레딧 가격(유동성은 2 크레딧)입니다. 실패한 호출에는 절대 과금되지 않습니다. 접근 권한이 없으면 호출은 무료로 실행되지 않고 access_required 같은 명확한 403 오류가 반환되며, 포털에서 트라이얼 또는 엔터프라이즈 접근을 요청할 수 있습니다. 준비가 되면 address를 eth, base, bsc의 아무 토큰 컨트랙트로 바꿔 보세요.

키를 비밀로 유지하세요

실제 API 키를 공개 저장소, 채팅, 클라이언트 사이드 코드에 절대 붙여넣지 마세요. 키는 생성 시 한 번만 표시됩니다. 유출됐다면 포털에서 로테이션하세요.

4. 같은 호출을 JavaScript / TypeScript로

const res = await fetch("https://api.cognivolabs.io/v1/api/intel/liquidity", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.COGNIVO_API_KEY, // never hardcode keys
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ chain: "base", address: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();
if (json.ok) {
  console.log(json.data);        // the intelligence result
  console.log(json.meta.request_id); // keep for support/debugging
} else {
  console.error(json.error);
}

5. 응답 형태

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

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

실패 시:

{ "ok": false, "error": "invalid_chain", "request_id": "capi_..." }

키를 안전하게 지키기

• API는 반드시 서버에서 호출하고, 브라우저나 모바일 클라이언트 코드에서는 절대 호출하지 마세요.
• 키는 환경 변수나 시크릿 매니저에 저장하세요.
• 키가 유출됐을 가능성이 있다면 포털에서 폐기(revoke)하거나 로테이션하세요. 이전 키는 1분 이내에 작동을 멈춥니다.