퀵스타트
첫 Cognivo API 호출
Cognivo Developer API를 사용하면 dApp과 Cognivo 채팅에서 물어볼 수 있는 것과 동일한 온체인 질문을 여러분의 코드에서 직접 물어볼 수 있습니다. 이 페이지는 그 과정을 가장 짧은 경로로 안내합니다. 프로젝트를 만들고, 키를 만들고, 실제 호출을 한 번 실행하고, 답을 읽습니다.
언제 사용하나요
트레이딩 봇, 내부 대시보드, 알림 작업, 백엔드 서비스처럼 여러분이 만들고 있는 무언가 안에서 토큰, 지갑, 유동성 체크를 실행하고 싶을 때 API를 사용하세요. 매번 dApp을 클릭해 들어갈 필요가 없어집니다. 수동으로만 체크를 실행하고 싶다면 dApp과 채팅이 이미 그 일을 하므로 키가 필요하지 않습니다.
어디에서 찾나요
dApp에 로그인한 뒤 사이드바에서 Account를 열고 Developers를 선택하세요. 로그아웃 상태의 방문자에게는 안내 화면만 표시되므로 먼저 로그인하세요. 이 페이지의 모든 작업은 그 한 화면에서 이루어집니다.
프로젝트를 만들고 키를 만들기
프로젝트는 API 키와 그 사용량을 함께 묶어 관리하는 단위이므로, 프로젝트부터 시작하세요.
- 새 프로젝트를 선택하면 프로젝트 선택기 아래에 짧은 양식이 열립니다.
- 프로젝트 이름에 이름을 입력해 나중에 프로젝트를 구분할 수 있게 합니다.
- 만들기를 선택해 프로젝트를 추가하거나, 취소를 선택해 저장하지 않고 양식을 닫습니다.
- 라이브 키 만들기를 선택해 그 프로젝트의 키를 만든 뒤, 직접 작성한 코드에서 요청과 함께 보냅니다.
프로젝트 이름은 여러분을 위한 라벨일 뿐입니다. 요청에는 나타나지 않으며, 페이지에 표시된 한도까지 프로젝트를 여러 개 만들 수 있습니다.
Create live key를 선택하면 Cognivo가 전체 키를 딱 한 번, 복사 버튼이 있는 대화 상자에 표시합니다. 그때 복사해서 안전한 곳에 보관하세요. 이후에는 접두사와 마지막 네 글자만 남은 마스킹된 버전만 표시됩니다. Cognivo가 키를 다시 읽어낼 수 없는 형태로 저장하기 때문입니다. 키를 잃어버렸거나 유출된 것 같다면 키 행의 Rotate 또는 Revoke를 사용하세요. 기존 키는 즉시 작동을 멈춥니다.
각 키에는 무엇을 호출할 수 있는지 제어하는 Permissions도 함께 있습니다. Intelligence, Security, Liquidity 세 가지입니다. 키에는 꼭 필요한 권한만 부여하세요. 아래 예제에는 Liquidity가 필요합니다.
같은 카드에 버튼이 두 개 더 있습니다. Top up credits는 결제 페이지로 이동합니다. Enterprise access는 지원 절차를 열며, 맞춤 요금이나 더 높은 한도를 위해 요청이 필요한 유일한 경로입니다. 일반 라이브 키는 승인이 필요 없고 만드는 즉시 작동합니다.
예제 호출 실행하기
Quickstart 탭을 여세요. 직접 아무것도 작성하지 않고 복사해서 실행할 수 있는 동작하는 예제가 들어 있습니다.
Test keys vs live keys 카드는 그 차이를 설명합니다. 테스트 키는 엄격한 한도로 안전한 호출을 하므로 연동 작업에 적합합니다. 라이브 키는 실제 호출을 하며 Cognivo 크레딧 잔액에서 과금됩니다. 이어지는 Test a live endpoint 카드는 번호가 매겨진 다섯 단계와 복사 아이콘이 붙은 명령어 자체를 제공합니다.
이 명령어는 실제 Base 컨트랙트에 대한 실제 유동성 체크입니다:
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"}'
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,
"Content-Type": "application/json",
},
body: JSON.stringify({ chain: "base", address: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();
if (json.ok) {
console.log(json.data);
console.log(json.meta.request_id);
} else {
console.error(json.error);
}
무엇이 돌아오나요
모든 엔드포인트는 동일한 봉투(envelope) 형태로 응답하며, Quickstart 탭의 Expected response 블록이 이를 보여줍니다:
{
"ok": true,
"data": { "identity": { "name": "...", "symbol": "..." }, "marketSnapshot": {} },
"meta": {
"chain": "base",
"request_id": "capi_...",
"credits_charged": 0,
"generated_at": "..."
}
}
data에는 결과가 담깁니다. meta.request_id는 기록해 둘 가치가 있습니다. 지원팀이 이 값으로 개별 호출을 찾아볼 수 있기 때문입니다. meta.credits_charged는 그 호출의 정확한 비용을 알려줍니다.
어떤 필드는 비어 있거나 알 수 없음 또는 이용 불가로 돌아올 수 있습니다. 이는 Cognivo가 접근할 수 있는 데이터로 그 값을 검증하지 못했다는 뜻이지, 아무것도 없다는 뜻이 아닙니다. "확인되지 않음"으로 읽고, 조용한 결과를 이상 없음으로 받아들이지 마세요. Cognivo는 무엇을 확인했고 무엇을 발견했는지를 보고할 뿐이며, 응답의 어떤 내용도 토큰이 사기임을 증명하거나 안전함을 증명하지 않습니다.
실패한 호출은 ok가 false이고 error 코드와 request_id가 함께 돌아옵니다. 실패한 호출에는 과금되지 않습니다.
비용, 체인, 한도
- 일부 엔드포인트는 활성 키만 있으면 무료입니다. 나머지는 성공한 호출마다 Cognivo 크레딧 잔액에서 과금됩니다. Endpoints 탭에 각 엔드포인트와 Cognivo 크레딧 기준 가격이, 무료인 경우 Free가 표시되므로 해당 엔드포인트로 개발하기 전에 그곳에서 확인하세요.
- 성공한 호출에 대해서만 과금되며,
meta.credits_charged가 그 금액을 확인해 줍니다. 오류, 타임아웃, 차단된 호출에는 비용이 들지 않습니다. - 모든 계정은 매일 5 무료 크레딧을 받습니다. UTC 자정에 초기화되며, 유료 크레딧보다 먼저 사용됩니다.
- API는 현재 Ethereum, Base, BNB Chain을 지원합니다. 일부 엔드포인트는 다른 엔드포인트보다 적은 수의 체인을 지원합니다.
- 테스트 키는 상한이 엄격하며 무료 프로덕션 등급이 아닙니다. Keys 탭의 각 키 행에는 Cognivo가 지금 그 키에 적용 중인 한도가 표시되며, 이는 등급 기본값보다 낮을 수 있습니다.
- 정지된 키, 또는 정지된 프로젝트에 속한 키는 아무것도 실행할 수 없으며, 포털에 그 이유가 표시됩니다.
키를 안전하게 보관하세요
API는 서버에서 호출하고, 브라우저나 모바일 앱 코드에서는 절대 호출하지 마세요. 키는 환경 변수나 시크릿 매니저에 보관하고, 공개 저장소나 채팅 메시지, 스크린샷에는 절대 넣지 마세요. 키가 유출되었을 가능성이 있다면 Keys 탭에서 로테이션하거나 폐기하세요.
다음 단계
권한과 키 관리 전반은 인증과 API 키를, 각 호출이 무엇을 반환하고 비용이 얼마인지는 엔드포인트를, 재시도와 오류 코드는 속도 제한과 오류를 읽어보세요. 크레딧 잔액과 충전은 결제와 크레딧을 참고하세요.