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

Khởi động nhanh

Lệnh gọi đầu tiên của bạn trong 30 giây: tạo một dự án, tạo một live key, kiểm tra số dư, dán một lệnh. Live key hoạt động theo mô hình tự phục vụ và dùng được ngay lập tức; bạn bị tính 2 tín dụng khi lệnh gọi ví dụ thành công, và không bao giờ bị tính phí cho một lệnh gọi thất bại.

1. Tạo một dự án và một live key​

  1. Mở cổng nhà phát triển và đăng nhập bằng tài khoản Cognivo của bạn.
  2. Tạo một dự án (ví dụ "Bot giao dịch của tôi").
  3. Tạo một live API key. Chọn các quyền (scope) mà nó cần - với hướng dẫn này, hãy cấp Trí tuệ token và ví (intel:read) và Đọc thanh khoản (liquidity:read).
  4. Sao chép key ngay bây giờ. Nó chỉ được hiển thị đúng một lần; sau đó chỉ còn thấy phiên bản che một phần (cogv_live_****abcd). Nếu bạn làm mất key, hãy xoay vòng (rotate) nó.

Key có hai môi trường:

  • cogv_live_... - key tiêu chuẩn. Tự phục vụ: nó hoạt động ngay lập tức, được tính phí trả theo mức dùng bằng tín dụng Cognivo cho mỗi lệnh gọi thành công, trừ từ số dư tín dụng của tài khoản bạn. Không cần trial hay phê duyệt.
  • cogv_test_... - Sandbox key, được ghi nhãn rõ ràng là Sandbox, chỉ dành cho demo giới hạn và kiểm thử tích hợp. Chúng không thể chạy trí tuệ trực tiếp và bị giới hạn chặt (25 yêu cầu/giờ, 100/ngày, 1/giây).

2. Kiểm tra key và số dư của bạn​

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

Bạn sẽ nhận lại key đã che, dự án, môi trường, các scope và giới hạn tốc độ theo giờ của mình, cùng với access_mode, credits_balance của tài khoản bạn (để bạn biết có đủ tiền cho lệnh gọi tiếp theo hay không) và hướng dẫn top_up. Lệnh gọi này luôn miễn phí.

3. Chạy lệnh gọi trực tiếp đầu tiên của bạn (curl)​

Các endpoint trí tuệ dùng POST với body JSON. Lệnh chính xác này thực hiện một kiểm tra thanh khoản thật trên một token Base thật (RWA Inc, một hợp đồng công khai chúng tôi dùng trong demo). Nó chạy ngay lập tức trên live key mới của bạn:

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

Bạn sẽ thấy "ok": true cùng danh tính token (tên/ký hiệu), một ảnh chụp thị trường và bối cảnh LP/khóa trong data. Khi thành công, bạn bị tính giá của endpoint - 2 tín dụng cho thanh khoản - và meta.credits_charged xác nhận điều đó. Nếu thay vào đó bạn nhận lỗi 402 với mã payment_required, số dư tín dụng Cognivo của bạn không đủ cho lệnh gọi: không có gì bị tính phí, hãy nạp thêm trên trang thanh toán của tài khoản Cognivo và chạy lại cùng lệnh đó. Các lệnh gọi thất bại không bao giờ bị tính phí. Thay address bằng bất kỳ hợp đồng token nào trên eth, base hoặc bsc khi bạn sẵn sàng.

Giữ bí mật key của bạn

Không bao giờ dán một API key thật vào repo công khai, cuộc trò chuyện hay mã phía client. Key chỉ được hiển thị một lần khi tạo; nếu bị rò rỉ, hãy xoay vòng nó trong cổng nhà phát triển.

4. Cùng lệnh gọi đó bằng 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);     // e.g. "payment_required": top up, then retry
}

5. Cấu trúc phản hồi​

Mọi endpoint đều trả lời với cùng một phong bì (envelope); các id và mốc thời gian bên dưới là giá trị ví dụ:

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

Khi thất bại (không bao giờ bị tính phí):

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

Tính phí và nạp tín dụng​

  • Trả theo mức dùng, theo từng lệnh gọi thành công. Mỗi lệnh gọi thành công trừ giá tín dụng đã công bố của endpoint từ số dư tín dụng Cognivo của chủ dự án (cùng loại tín dụng bạn dùng trong Chat và dApp). Không có gói thuê bao và không có mức tối thiểu.
  • Nạp tín dụng ở đâu. Trên trang thanh toán của tài khoản Cognivo trong dApp. GET /v1/api/me hiển thị credits_balance hiện tại và hướng dẫn top_up của bạn.
  • Các lệnh gọi thất bại không bao giờ bị tính phí. Lỗi, hết thời gian chờ và lệnh gọi bị từ chối không tốn gì. Bản thân 402 payment_required là miễn phí: nạp thêm và thử lại.
  • Kết quả rỗng trung thực là miễn phí. wallet/pnl trả về 422 khi một ví không có giao dịch được định giá với token đó, và một danh sách wallet/approvals rỗng là câu trả lời hợp lệ; cả hai đều không bị tính phí.
  • Thử lại là an toàn. Một lệnh gọi thành công chỉ bị tính phí đúng một lần; các lần gửi trùng lặp của cùng một thao tác không thể tính phí bạn hai lần. Với 5xx hoặc 429, thử lại với backoff; với 402, nạp thêm trước.
  • Đình chỉ. Một key bị đình chỉ (hoặc một dự án bị vô hiệu hóa) không thể thực thi bất cứ thứ gì và không bao giờ bị tính phí; cổng nhà phát triển hiển thị lý do.

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

  • Gọi API từ máy chủ, không bao giờ từ mã trình duyệt hay client di động.
  • Lưu key trong biến môi trường hoặc trình quản lý bí mật.
  • Nếu một key có khả năng đã bị rò rỉ, hãy thu hồi hoặc xoay vòng nó trong cổng nhà phát triển - key cũ ngừng hoạt động trong vòng một phút.