Chuyển tới nội dung chính

Bắt đầu nhanh

Lệnh gọi Cognivo API đầu tiên của bạn​

Cognivo Developer API cho phép mã nguồn của bạn đặt ra chính những câu hỏi on-chain mà bạn có thể hỏi trong dApp và trong Trò chuyện Cognivo. Trang này đi con đường ngắn nhất qua đó: tạo một dự án, tạo một key, chạy một lệnh gọi thật, đọc câu trả lời.

Khi nào nên dùng​

Hãy dùng API khi bạn muốn có các kiểm tra token, ví hoặc thanh khoản bên trong thứ bạn đang xây dựng, chẳng hạn một bot giao dịch, một bảng điều khiển nội bộ, một tác vụ cảnh báo hoặc một dịch vụ backend, thay vì phải bấm qua dApp mỗi lần. Nếu bạn chỉ muốn chạy các kiểm tra bằng tay thì dApp và Trò chuyện đã làm được điều đó và bạn không cần key.

Tìm ở đâu​

Đăng nhập vào dApp, mở Account ở thanh bên, rồi chọn Developers. Khách chưa đăng nhập chỉ thấy màn hình giới thiệu, nên hãy đăng nhập trước. Mọi thứ trên trang này diễn ra trên đúng màn hình đó.

Tạo một dự án, rồi tạo một key​

Một dự án gom các API key của bạn và mức sử dụng của chúng lại với nhau, nên hãy bắt đầu từ đó.

  1. Chọn New project để mở biểu mẫu ngắn bên dưới bộ chọn dự án.
  2. Nhập một tên vào Project name để sau này bạn phân biệt được các dự án.
  3. Chọn Create để thêm dự án, hoặc Cancel để đóng biểu mẫu mà không lưu.
  4. Chọn Create live key để tạo key cho dự án, rồi gửi nó kèm các yêu cầu từ mã của chính bạn.
Các điều khiển dự án trên trang Developers, nơi bạn thiết lập một dự án trước khi tạo key.Phóng to hình ảnh

Tên dự án chỉ là nhãn cho riêng bạn. Nó không xuất hiện trong các yêu cầu của bạn và bạn có thể tạo nhiều hơn một dự án, tối đa tới giới hạn hiển thị trên trang.

Khi bạn chọn Create live key, Cognivo hiển thị key đầy đủ đúng một lần, trong một hộp thoại có nút sao chép. Hãy sao chép ngay lúc đó và cất giữ ở nơi an toàn. Sau đó trang chỉ hiển thị bản che bớt, gồm tiền tố và bốn ký tự cuối, vì Cognivo lưu key ở dạng mà chính nó không đọc ngược lại được. Nếu bạn làm mất một key, hoặc nghĩ rằng nó đã bị lộ, hãy dùng Rotate hoặc Revoke trên dòng của key đó. Key cũ ngừng hoạt động ngay lập tức.

Mỗi key cũng mang theo Permissions, quyết định nó được gọi những gì: Intelligence, Security và Liquidity. Chỉ cấp cho một key những quyền mà nó cần. Ví dụ bên dưới cần Liquidity.

Hai nút nữa nằm trên cùng thẻ đó. Top up credits đưa bạn tới trang thanh toán. Enterprise access mở luồng hỗ trợ, và đó là con đường duy nhất có kèm một yêu cầu, dành cho giá tùy chỉnh hoặc giới hạn cao hơn. Một live key thông thường không cần phê duyệt và hoạt động ngay khoảnh khắc bạn tạo ra nó.

Chạy lệnh gọi ví dụ​

Mở tab Quickstart. Nó có sẵn một ví dụ chạy được mà bạn có thể sao chép và chạy mà không phải tự viết gì.

Tab Quickstart trên trang Developers, nơi bạn sao chép một lệnh gọi mẫu chạy được.Phóng to hình ảnh

Thẻ Test keys vs live keys giải thích sự khác biệt. Một test key thực hiện các lệnh gọi an toàn với giới hạn chặt, rất hợp để đấu nối ban đầu. Một live key thực hiện các lệnh gọi thật và bị tính phí từ số dư tín dụng Cognivo của bạn. Thẻ Test a live endpoint sau đó đưa ra năm bước được đánh số cùng chính câu lệnh, kèm biểu tượng sao chép.

Câu lệnh này là một kiểm tra thanh khoản thật trên một hợp đồng Base thật:

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

Cũng lệnh gọi đó từ JavaScript hoặc 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);
}

Kết quả trả về là gì​

Mọi endpoint đều trả lời bằng cùng một lớp vỏ, đúng như khối Expected response trên tab Quickstart hiển thị:

{
  "ok": true,
  "data": { "identity": { "name": "...", "symbol": "..." }, "marketSnapshot": {} },
  "meta": {
    "chain": "base",
    "request_id": "capi_...",
    "credits_charged": 0,
    "generated_at": "..."
  }
}

data chứa kết quả. meta.request_id rất đáng ghi log, vì bộ phận hỗ trợ có thể tra cứu một lệnh gọi đơn lẻ theo giá trị đó. meta.credits_charged cho bạn biết chính xác lệnh gọi đó tốn bao nhiêu.

Một trường có thể trả về rỗng, không rõ hoặc không khả dụng. Điều đó nghĩa là Cognivo không xác minh được nó từ dữ liệu mà nó tiếp cận được, chứ không phải là ở đó không có gì. Hãy đọc nó là "chưa được xác nhận", và đừng coi một kết quả im lặng là dấu hiệu an toàn. Cognivo báo cáo những gì nó đã kiểm tra và những gì nó tìm thấy, và không có gì trong một phản hồi chứng minh một token là lừa đảo hay chứng minh một token là an toàn.

Một lệnh gọi thất bại trả lời với ok đặt thành false, một mã error và một request_id. Các lệnh gọi thất bại không bị tính phí.

Chi phí, chain và giới hạn​

  • Một số endpoint miễn phí với bất kỳ key đang hoạt động nào. 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. Tab Endpoints liệt kê từng endpoint kèm giá tính bằng tín dụng Cognivo, hoặc ghi Free ở nơi miễn phí, nên hãy kiểm tra ở đó trước khi bạn xây dựng dựa trên một endpoint.
  • Bạn chỉ bị tính phí cho một lệnh gọi thành công, và meta.credits_charged xác nhận số tiền. Lỗi, hết thời gian chờ và các lệnh gọi bị chặn đều không tốn gì.
  • Mỗi tài khoản nhận 5 tín dụng miễn phí mỗi ngày. Chúng đặt lại vào nửa đêm UTC và được dùng trước bất kỳ tín dụng trả phí nào.
  • Hiện tại API bao phủ Ethereum, Base và BNB Chain. Một số endpoint hỗ trợ ít chain hơn các endpoint khác.
  • Test key bị giới hạn rất chặt và không phải là một hạng miễn phí dùng cho môi trường production. Mỗi dòng key trên tab Keys hiển thị các giới hạn mà Cognivo đang áp cho key đó ngay lúc này, và chúng có thể thấp hơn mặc định của hạng.
  • Một key bị đình chỉ, hoặc một key nằm trong dự án bị đình chỉ, không chạy được gì cả, và cổng nhà phát triển hiển thị lý do.

Giữ an toàn cho key của bạn​

Hãy gọi API từ một máy chủ, không bao giờ từ mã trình duyệt hay mã ứng dụng di động. Giữ key trong một biến môi trường hoặc một trình quản lý bí mật, không bao giờ để trong kho mã công khai, một tin nhắn trò chuyện hay một ảnh chụp màn hình. Nếu một key có thể đã bị lộ, hãy xoay vòng hoặc thu hồi nó trên tab Keys.

Bước tiếp theo​

Đọc Xác thực và API key để nắm đầy đủ về quyền và cách xử lý key, Tham chiếu endpoint để biết mỗi lệnh gọi trả về gì và tốn bao nhiêu, và Giới hạn tốc độ và lỗi để biết cách thử lại và các mã lỗi. Về số dư tín dụng và nạp thêm, xem Thanh toán và tín dụng.