Xác thực và API key
API key là gì
API key là bí mật mà mã nguồn của bạn gửi tới Cognivo để chúng tôi biết một yêu cầu là của bạn. Mọi lệnh gọi Developer API đều mang theo một key. Các key nằm bên trong một dự án, và một dự án gom các key của bạn cùng mức sử dụng của chúng lại với nhau.
Hãy đọc trang này trước lệnh gọi đầu tiên của bạn, khi bạn cần biết một key được phép làm gì, hoặc khi một key có thể đã bị lộ và bạn cần tắt nó đi.
Tìm ở đâu
Đăng nhập vào Cognivo dApp, mở Account ở thanh bên trái, rồi chọn Developers. Khi chưa đăng nhập, trang chỉ hiển thị một màn hình giới thiệu.
Trang Developers có bốn tab: Keys, Usage, Endpoints và Quickstart. Mọi thứ trên trang này diễn ra ở tab Keys.
Truy cập live và số dư tín dụng của bạn
Một biểu ngữ ở đầu trang nêu rõ mô hình truy cập: một số endpoint miễn phí với bất kỳ key đang hoạt động nào, còn số khác bị tính phí theo mỗi lệnh gọi thành công từ số dư tín dụng Cognivo của bạn. Xuống dưới nữa, thẻ Live API access xác nhận rằng một live key hoạt động ngay khoảnh khắc bạn tạo ra nó. Không có bước phê duyệt và không có danh sách chờ.
Bên cạnh đó, trang hiển thị số dư tín dụng hiện tại của bạn, một nút Top up credits và một nút Enterprise access. Enterprise là con đường truy cập duy nhất phải đi qua một yêu cầu, dành cho giá tùy chỉnh hoặc giới hạn cao hơn. Mọi thứ khác đều tự phục vụ.
Mỗi tài khoản Cognivo cũng nhận 5 tín dụng miễn phí mỗi ngày, và chúng đặt lại vào nửa đêm UTC. Xem Thanh toán và tín dụng để biết số dư hoạt động ra sao, và Giới hạn tốc độ, lỗi và tính phí để biết giá theo từng endpoint.
Tab Keys
Chọn một dự án từ danh sách thả xuống Project, hoặc tạo một dự án bằng New project. Tab Keys khi đó liệt kê mọi key thuộc về dự án đó.
Mỗi dòng key hiển thị tên bạn đã đặt, key đó là Test hay Live, giới hạn theo giờ đang áp dụng, các quyền nó mang theo, cùng thời điểm nó được tạo và lần dùng gần nhất. Last used: Never nghĩa là chưa từng có lệnh gọi nào được thực hiện với key đó.
Chỉ tiền tố và bốn ký tự cuối của một key được hiển thị. Cognivo không lưu bất cứ thứ gì khác có thể đọc ngược lại, và đó là lý do key đầy đủ chỉ xuất hiện đúng một lần.
Tạo một key
Chọn + New key. Biểu mẫu hỏi ba thứ: một tên tùy chọn để bạn phân biệt các key của mình, một chế độ Test hoặc Live, và ít nhất một quyền.
Chọn Live sẽ hiển thị số dư tín dụng của bạn ngay dưới danh sách chế độ, như một lời nhắc rằng lệnh gọi live là lệnh gọi thật và bị tính phí từ số dư đó. Chọn Test sẽ tạo một key sandbox không bao giờ bị tính phí và có giới hạn chặt.
Chọn Create key và key đầy đủ xuất hiện một lần, trong một hộp thoại.
- Dùng biểu tượng sao chép để sao chép key đầy đủ khi nó còn trên màn hình, vì nó sẽ không hiện lại lần nữa.
- Chọn Done sau khi key đã được lưu ở nơi bạn có thể tìm lại sau này.
Nếu bạn làm mất key, bạn không thể khôi phục lại nó. Thay vào đó hãy xoay vòng key, việc này được nói tới bên dưới.
Gửi key của bạn
Header chuẩn là 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 được chấp nhận như một bí danh cho các thư viện client ưa dùng cách đó. Hãy giữ key trên máy chủ của bạn. Không bao giờ đặt nó trong mã trình duyệt.
Hiện tại API bao phủ Ethereum, Base và BNB Chain.
Quyền
Các key mặc định là từ chối. Một key chỉ có thể gọi những nhóm endpoint mà bạn đã cấp khi tạo nó. Có ba quyền, và mỗi quyền mở khóa một tập endpoint.
Intelligence (intel:read) là quyền dùng hằng ngày. Nó trả lời câu hỏi "chuyện gì đang xảy ra với token hoặc ví này?": nguyên nhân giá giảm, tín hiệu rủi ro, hành vi ví đội ngũ, PnL đã hiện thực hóa và các dịch chuyển chính xác. Nó mở khóa POST /v1/api/intel/why-down, POST /v1/api/intel/team-wallets, POST /v1/api/intel/risk, POST /v1/api/wallet/pnl và POST /v1/api/wallet/exact-movements.
Security (security:read) cho phép một key kiểm tra những gì một ví đã phê duyệt, gồm cả hợp đồng nào có thể tiêu token của ví đó và hạn mức nào là không giới hạn. Nó chỉ đọc. Một key có quyền này không bao giờ có thể chuyển tiền hay thu hồi một phê duyệt. Nó mở khóa POST /v1/api/wallet/approvals.
Liquidity (liquidity:read) cho phép một key đọc bối cảnh pool, quyền giữ LP, cùng bối cảnh khóa và đốt. Nó mở khóa POST /v1/api/intel/liquidity.
GET /v1/api/health hoàn toàn không cần key. GET /v1/api/me và GET /v1/api/discover hoạt động với bất kỳ key hợp lệ nào, bất kể quyền của nó là gì.
Quyền được cố định khi key được tạo. Để thay đổi, hãy tạo một key mới với những quyền bạn cần rồi thu hồi key cũ. Một lệnh gọi thất bại với 403 scope_denied nghĩa là key không mang quyền mà endpoint đó cần.
Test key và live key
| Tiền tố | Dùng để làm gì | Tính phí | Trần tốc độ |
|---|---|---|---|
cogv_test_ | Dùng thử API. Được ghi nhãn Test và Sandbox trong cổng nhà phát triển. Không chạy được trí tuệ trực tiếp. | không bao giờ bị tính phí | 25 yêu cầu mỗi giờ, 100 mỗi ngày, 1 mỗi giây |
cogv_live_ | Lưu lượng thật. Tự phục vụ, hoạt động ngay lập tức. | Tín dụng Cognivo cho mỗi lệnh gọi thành công. Lệnh gọi thất bại không bao giờ bị tính phí. | 1,000 yêu cầu mỗi giờ khi bắt đầu, xem giới hạn tốc độ |
Một test key không phải là một live key miễn phí. Các lệnh gọi live thực hiện bằng test key trả về 403 sandbox_limited. Việc tính phí cho các lệnh gọi Developer API hiện đang tắt, nên một lệnh gọi thành công không trừ gì và số dư của bạn không thay đổi.
Cổng nhà phát triển cũng hiển thị một chế độ truy cập trên mỗi key. Paid là trả theo mức dùng thông thường. Trial là một hạn mức đánh giá tạm thời có ngày kết thúc. Partner và Enterprise là các thỏa thuận được thiết lập với Cognivo. Suspended nghĩa là key không thể thực thi bất cứ thứ gì, và cổng nhà phát triển hiển thị lý do. Một số ít key cũ có từ trước khi có thanh toán tự phục vụ và chỉ gọi được các endpoint siêu dữ liệu, nên các lệnh gọi live trả về 403 access_required. Hãy tạo một live key mới để chuyển chúng sang trả theo mức dùng.
GET /v1/api/me báo cáo chế độ truy cập của key, các quyền của nó, credits_balance của bạn và hướng dẫn nạp thêm. Nếu số dư của bạn không đủ cho một lệnh gọi, bạn nhận 402 payment_required và không có gì bị tính phí. Hãy nạp thêm rồi thử lại.
Xoay vòng và thu hồi
Cả hai nút điều khiển nằm ở bên phải của mỗi dòng key.
- Đọc huy hiệu Test và Sandbox bên cạnh tên để biết đây là loại key nào, cùng với giới hạn theo giờ hiển thị ngay cạnh chúng.
- Chọn Rotate để thay key này bằng một key mới, key mới chỉ hiện một lần và key cũ ngừng hoạt động ngay lập tức.
- Chọn Revoke để tắt hẳn một key, ví dụ khi bạn không còn cần nó hoặc bạn nghĩ đã có người khác nhìn thấy nó.
Xoay vòng yêu cầu bạn xác nhận trước, và hộp thoại nói rõ chính xác điều gì sẽ xảy ra.
Một key đã xoay vòng giữ nguyên tên, quyền, hạng, mọi hạn chế mạng, mọi ngày hết hạn và mọi hạn mức còn lại, nên xoay vòng là an toàn và không bao giờ âm thầm nới rộng những gì key có thể làm. Key thay thế được hiển thị một lần, trong cùng hộp thoại như với một key mới. Thu hồi là vĩnh viễn và làm key ngừng hoạt động trên mọi endpoint ngay lập tức.
Hãy xoay vòng khi nghi ngờ có rò rỉ, và theo một lịch định kỳ.
Các hạn chế Cognivo có thể áp lên một key
Những hạn chế này được đặt trên bản ghi của key thay vì trong biểu mẫu của cổng nhà phát triển, và chúng được thực thi trên mọi yêu cầu. Bạn có thể xác nhận những gì đang áp dụng cho key của mình bằng GET /v1/api/me.
- Hạn chế mạng. Một key có thể bị giới hạn ở những mạng cụ thể. Một yêu cầu nêu một mạng khác sẽ bị từ chối với
403 chain_denied. Việc từ chối xảy ra trước khi Cognivo gọi bất cứ thứ gì ở phía trên và trước khi bất kỳ hạn mức nào bị dùng, nên một lệnh gọi mà key của bạn không được phép thực hiện sẽ không bao giờ tốn của bạn thứ gì. Được báo cáo làallowed_chains, trong đónullnghĩa là không có hạn chế. - Hết hạn. Một key có thể được đặt ngày kết thúc. Sau khi ngày đó qua đi, key ngừng hoạt động ở mọi nơi, kể cả
GET /v1/api/me, và trả về403 key_expired. Được báo cáo làexpires_at, trong đónullnghĩa là nó không hết hạn. Nếu một hạn mức dùng thử cũng có ngày kết thúc, cái nào đến trước sẽ được áp dụng. - Danh sách cho phép Origin và IP. Một key có thể bị giới hạn ở những origin cụ thể, gồm cả tên miền phụ dạng ký tự đại diện như
https://*.yourapp.com, hoặc ở những địa chỉ IP và dải CIDR cụ thể. Yêu cầu từ bất kỳ nơi nào khác sẽ bị từ chối với403 origin_denied. Danh sách rỗng nghĩa là không có hạn chế.
Bước tiếp theo
Khi đã có key trong tay, hãy thực hiện lệnh gọi đầu tiên trong Bắt đầu nhanh, rồi xem qua Tham chiếu endpoint để biết mỗi endpoint trả về gì và tốn bao nhiêu. Nếu một lệnh gọi trả về mã lỗi mà bạn không nhận ra, Giới hạn tốc độ, lỗi và tính phí liệt kê tất cả các mã đó.