인증과 API 키
API 키란 무엇인가요
API 키는 어떤 요청이 여러분의 것임을 Cognivo가 알 수 있도록 코드가 보내는 비밀 값입니다. 모든 Developer API 호출에는 키가 하나씩 담깁니다. 키는 프로젝트 안에 속하며, 프로젝트는 키와 그 사용량을 함께 묶어 관리합니다.
첫 호출을 하기 전에, 키가 무엇을 할 수 있는지 알아야 할 때, 또는 키가 유출되어 사용을 중지해야 할 때 이 페이지를 읽으세요.
어디에서 찾나요
Cognivo dApp에 로그인한 뒤 왼쪽 사이드바에서 Account를 열고 Developers를 선택하세요. 로그아웃 상태에서는 안내 화면만 표시됩니다.
Developers 페이지에는 Keys, Usage, Endpoints, Quickstart 네 개의 탭이 있습니다. 이 페이지의 모든 작업은 Keys 탭에서 이루어집니다.
라이브 접근과 크레딧 잔액
페이지 상단의 배너가 접근 모델을 분명하게 알려줍니다. 일부 엔드포인트는 활성 키만 있으면 무료이고, 나머지는 성공한 호출마다 Cognivo 크레딧 잔액에서 과금됩니다. 조금 아래의 Live API access 카드는 라이브 키가 만들어지는 즉시 작동한다는 점을 확인해 줍니다. 승인 단계도, 대기 목록도 없습니다.
그 옆에는 현재 크레딧 잔액, Top up credits 버튼, Enterprise access 버튼이 표시됩니다. Enterprise는 맞춤 요금이나 더 높은 한도를 위해 요청을 거치는 유일한 접근 경로입니다. 그 외에는 모두 셀프 서비스입니다.
모든 Cognivo 계정은 매일 5 무료 크레딧도 받으며, UTC 자정에 초기화됩니다. 잔액이 어떻게 동작하는지는 결제와 크레딧을, 엔드포인트별 가격은 속도 제한, 오류, 결제를 참고하세요.
Keys 탭
Project 드롭다운에서 프로젝트를 고르거나 New project로 하나 만드세요. 그러면 Keys 탭에 그 프로젝트에 속한 모든 키가 나열됩니다.
각 키 행에는 여러분이 지정한 이름, 테스트 키인지 라이브 키인지, 적용되는 시간당 한도, 보유한 권한, 생성 시각과 마지막 사용 시각이 표시됩니다. Last used: Never는 그 키로 호출이 한 번도 이루어지지 않았다는 뜻입니다.
키는 접두사와 마지막 네 글자만 표시됩니다. Cognivo는 다시 읽어낼 수 있는 다른 정보를 저장하지 않으며, 그래서 전체 키가 딱 한 번만 표시됩니다.
키 만들기
+ New key를 선택하세요. 양식은 세 가지를 묻습니다. 키를 구분하는 데 도움이 되는 선택적 이름, Test 또는 Live 모드, 그리고 최소 한 개의 권한입니다.
Live를 선택하면 모드 드롭다운 아래에 크레딧 잔액이 표시되어, 라이브 호출은 실제 호출이며 그 잔액에서 과금된다는 점을 상기시켜 줍니다. Test를 선택하면 절대 과금되지 않고 한도가 엄격한 샌드박스 키가 만들어집니다.
Create key를 선택하면 전체 키가 대화 상자에 한 번 표시됩니다.
- 화면에 남아 있는 동안 복사 아이콘으로 전체 키를 복사하세요. 다시는 표시되지 않습니다.
- 나중에 찾을 수 있는 곳에 키를 보관한 뒤 완료를 선택합니다.
키를 잃어버리면 복구할 수 없습니다. 대신 키를 로테이션하세요. 아래에서 다룹니다.
키 보내기
표준 헤더는 X-API-Key입니다:
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":"eth","address":"0xTOKEN_CONTRACT"}'
Authorization: Bearer YOUR_API_KEY는 그 방식을 선호하는 클라이언트 라이브러리를 위한 별칭으로 허용됩니다. 키는 서버에 두세요. 절대 브라우저 코드에 넣지 마세요.
API는 현재 공용 chain 파라미터에서 Ethereum, Base, BNB Chain을 지원합니다. Robinhood Chain은 Cognivo에서 이미 사용할 수 있으며, 공용 엔드포인트의 chain 값이 아니라 API의 전용 엔드포인트로 제공됩니다.
권한
키는 기본적으로 거부(default deny)입니다. 키는 생성할 때 부여한 엔드포인트 그룹만 호출할 수 있습니다. 권한은 세 가지이며, 각각이 일련의 엔드포인트를 열어줍니다.
Intelligence(intel:read)는 일상적으로 쓰는 권한입니다. "이 토큰이나 지갑에 무슨 일이 일어나고 있는가?"에 답합니다. 가격 하락 요인, 리스크 신호, 팀 지갑 행동, 실현 손익, 정확한 이동 내역입니다. POST /v1/api/intel/why-down, POST /v1/api/intel/team-wallets, POST /v1/api/intel/risk, POST /v1/api/wallet/pnl, POST /v1/api/wallet/exact-movements를 열어줍니다.
Security(security:read)는 지갑이 무엇을 승인했는지, 어떤 컨트랙트가 그 토큰을 사용할 수 있는지, 어떤 허용량이 무제한인지 확인할 수 있게 합니다. 읽기 전용입니다. 이 권한을 가진 키는 절대 자금을 옮기거나 승인을 취소할 수 없습니다. POST /v1/api/wallet/approvals를 열어줍니다.
Liquidity(liquidity:read)는 풀 맥락, LP 보관 상태, 잠금과 소각 맥락을 읽을 수 있게 합니다. POST /v1/api/intel/liquidity를 열어줍니다.
GET /v1/api/health는 키가 전혀 필요 없습니다. GET /v1/api/me와 GET /v1/api/discover는 권한과 무관하게 유효한 키라면 어떤 것으로도 동작합니다.
권한은 키를 만들 때 확정됩니다. 변경하려면 필요한 권한을 가진 새 키를 만들고 기존 키를 폐기하세요. 호출이 403 scope_denied로 실패한다면 그 엔드포인트에 필요한 권한을 키가 갖고 있지 않다는 뜻입니다.
테스트 키와 라이브 키
| 접두사 | 용도 | 과금 | 요청 상한 |
|---|---|---|---|
cogv_test_ | API 시험용. 포털에 Test 및 Sandbox로 표시됩니다. 라이브 인텔리전스는 실행할 수 없습니다. | 절대 과금되지 않음 | 시간당 25 요청, 일 100 요청, 초당 1 요청 |
cogv_live_ | 실제 트래픽용. 셀프 서비스이며 즉시 작동합니다. | 성공한 호출당 Cognivo 크레딧. 실패한 호출에는 절대 과금되지 않습니다. | 시작 시 시간당 1,000 요청, 속도 제한 참고 |
테스트 키는 무료 프로덕션 키가 아닙니다. 테스트 키로 라이브 호출을 하면 403 sandbox_limited가 반환됩니다. 현재 Developer API 호출에 대한 과금은 꺼져 있어, 호출이 성공해도 아무것도 차감되지 않고 잔액도 변하지 않습니다.
포털은 각 키의 접근 모드도 표시합니다. Paid는 일반적인 종량제입니다. Trial은 종료일이 있는 임시 평가 허용량입니다. Partner와 Enterprise는 Cognivo와 맺은 계약입니다. Suspended는 그 키가 아무것도 실행할 수 없다는 뜻이며, 포털에 그 이유가 표시됩니다. 셀프 서비스 결제 이전에 만들어진 소수의 오래된 키는 메타데이터 엔드포인트만 호출할 수 있어 라이브 호출은 403 access_required로 응답합니다. 새 라이브 키를 만들어 종량제로 옮기세요.
GET /v1/api/me는 키의 접근 모드, 권한, credits_balance, 충전 안내를 알려줍니다. 잔액으로 호출 비용을 감당할 수 없으면 402 payment_required가 반환되고 아무것도 과금되지 않습니다. 충전한 뒤 다시 시도하세요.
로테이션과 폐기
두 컨트롤 모두 각 키 행의 오른쪽에 있습니다.
- 이름 옆의 Test와 Sandbox 배지를 보고 어떤 종류의 키인지 확인하고, 그 옆에 표시된 시간당 한도도 함께 확인하세요.
- 로테이션을 선택하면 이 키가 새 키로 교체됩니다. 새 키는 한 번만 표시되고 이전 키는 즉시 작동을 멈춥니다.
- 폐기를 선택하면 키가 영구히 꺼집니다. 예를 들어 더 이상 필요하지 않거나 다른 사람이 봤다고 생각될 때 사용하세요.
Rotate는 먼저 확인을 요청하며, 대화 상자가 무슨 일이 일어날지 정확히 알려줍니다.
로테이션된 키는 이름, 권한, 등급, 네트워크 제한, 만료일, 남은 허용량을 그대로 유지하므로 로테이션은 안전하며 키의 권한 범위를 조용히 넓히지 않습니다. 교체된 키는 새 키와 동일한 대화 상자에서 한 번 표시됩니다. 폐기는 영구적이며, 모든 엔드포인트에서 그 키가 즉시 작동을 멈춥니다.
유출이 의심될 때마다, 그리고 정기적으로 로테이션하세요.
Cognivo가 키에 적용할 수 있는 제한
이 제한들은 포털 양식이 아니라 키 레코드에 설정되며, 모든 요청에 적용됩니다. 여러분의 키에 무엇이 적용되는지는 GET /v1/api/me로 확인할 수 있습니다.
- 네트워크 제한. 키를 특정 네트워크로 제한할 수 있습니다. 다른 네트워크를 지정한 요청은
403 chain_denied로 거부됩니다. 이 거부는 Cognivo가 상위 서비스를 호출하기 전에, 그리고 허용량이 사용되기 전에 일어나므로 키에 허용되지 않은 호출은 절대 비용이 들지 않습니다.allowed_chains로 보고되며,null은 제한 없음을 뜻합니다. - 만료. 키에 종료일을 지정할 수 있습니다. 그 날짜가 지나면 키는
GET /v1/api/me를 포함해 모든 곳에서 작동을 멈추고403 key_expired를 반환합니다.expires_at으로 보고되며,null은 만료되지 않음을 뜻합니다. 트라이얼 허용량에도 종료일이 있다면 둘 중 먼저 오는 쪽이 적용됩니다. - Origin 및 IP 허용 목록. 키를
https://*.yourapp.com처럼 와일드카드 서브도메인을 포함한 특정 origin으로, 또는 특정 IP 주소와 CIDR 범위로 제한할 수 있습니다. 그 밖의 곳에서 온 요청은403 origin_denied로 거부됩니다. 목록이 비어 있으면 제한이 없다는 뜻입니다.
다음 단계
키를 손에 넣었다면 퀵스타트에서 첫 호출을 해보고, 엔드포인트 레퍼런스에서 각 엔드포인트가 무엇을 반환하고 비용이 얼마인지 살펴보세요. 알아볼 수 없는 오류 코드가 돌아온다면 속도 제한, 오류, 결제에 모든 코드가 정리되어 있습니다.