Tham chiếu endpoint

Trang này là gì

Cognivo Developer API cho phép mã nguồn của bạn hỏi Cognivo chính những câu hỏi mà ứng dụng trả lời. Mọi endpoint đều nằm dưới https://api.cognivolabs.io/v1/api.

Hãy dùng nó khi bạn muốn một kiểm tra của Cognivo chạy ở nơi khác ngoài ứng dụng: bên trong bot của riêng bạn, một bảng điều khiển, một tác vụ bảng tính, hoặc một kịch bản chạy hằng đêm theo dõi một danh sách token.

Các endpoint trí tuệ là POST với thân JSON. Điều đó là có chủ đích: một bản xem trước liên kết, một trình thu thập dữ liệu hay một lần nạp trước của trình duyệt sẽ không bao giờ có thể kích hoạt một lần thực thi chỉ bằng cách tải một URL. GET chỉ tồn tại cho health, me và discover.

Tìm phần này trong ứng dụng ở đâu

Đăng nhập vào ứng dụng Cognivo, mở Developers ở thanh bên trái dưới mục Account, rồi chọn tab Endpoints.

Tab Endpoints trên trang Developers, nơi từng endpoint của Cognivo được liệt kê kèm quyền mà nó cần và chi phí của nó.Phóng to hình ảnh

Tab này là một tài liệu tham chiếu, không phải nơi chạy lệnh. Nó liệt kê mọi endpoint đang hoạt động kèm một ví dụ có thể sao chép, quyền mà key cần, và giá tính bằng tín dụng. Thẻ Permissions explained gom các quyền đó thành ba nhóm: Intelligence (vì sao token giảm giá, ví đội ngũ, rủi ro, PnL ví, dịch chuyển chính xác), Security (phê duyệt token) và Liquidity (thanh khoản, khóa và đốt). Chỉ cấp cho mỗi key những quyền mà nó cần.

Bạn thích một phiên bản mà máy đọc được? Đặc tả OpenAPI đầy đủ bao phủ mọi thứ trên trang này.

Lớp vỏ phản hồi

Mọi endpoint đều trả lời bằng cùng một lớp vỏ. Các id và dấu thời gian trong ví dụ bên dưới là giá trị mẫu. Thành công:

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

• data chính là kết quả. Hình dạng của nó thay đổi theo từng endpoint.
• meta.request_id là một id duy nhất cho lệnh gọi này. Hãy giữ lại, bộ phận hỗ trợ có thể truy vết một lệnh gọi từ nó.
• meta.credits_charged là chi phí của lệnh gọi: giá của endpoint đối với một lệnh gọi trả phí thành công, và 0 với các endpoint miễn phí cũng như với mọi kết quả thất bại hoặc rỗng một cách trung thực.
• meta.generated_at là thời điểm kết quả được tạo ra.
• meta.chain xuất hiện ở các lệnh gọi gắn với một chain cụ thể, còn meta.sources xuất hiện khi kết quả có trích dẫn nguồn.

Thất bại:

{ "ok": false, "error": "invalid_chain", "message": "chain must be one of: eth, base, bsc", "request_id": "capi_..." }

error là một mã ổn định mà máy đọc được. message là gợi ý tùy chọn dành cho con người. Danh sách đầy đủ nằm ở Giới hạn tốc độ và lỗi.

Các trường thân yêu cầu thường gặp

• chain là một trong eth (Ethereum), base (Base) hoặc bsc (BNB Chain), và không phân biệt chữ hoa chữ thường.
• address, wallet và token là các địa chỉ EVM dạng 0x gồm 40 ký tự hex.

Mọi ví dụ đều dùng giá trị mẫu YOUR_API_KEY. Trong mã thật, hãy nạp key từ một biến môi trường hoặc một trình quản lý bí mật. Không bao giờ viết cứng nó.

Mỗi endpoint tốn bao nhiêu

Live key là tự phục vụ và trả theo mức dùng. Một live key mới chạy được ngay các endpoint này, và mỗi lệnh gọi thành công được tính bằng tín dụng Cognivo từ số dư tài khoản của bạn. Lệnh gọi thất bại không bao giờ bị tính phí, và một lệnh gọi thành công chỉ bị tính đúng một lần, nên việc gửi lại cùng một thao tác không thể tính phí bạn hai lần.

Mỗi tài khoản 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. 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 trên trang thanh toán tài khoản rồi thử lại. Key sandbox (cogv_test_) không chạy được trí tuệ trực tiếp. Xem Thanh toán và tín dụng.

Endpoint	Tín dụng cho mỗi lệnh gọi thành công
POST intel/liquidity	2
POST intel/risk	2
POST wallet/approvals	2
POST intel/why-down	3
POST intel/team-wallets	5
POST wallet/exact-movements	5
POST wallet/pnl	10
POST contract/analysis	miễn phí
GET health, GET me	miễn phí
GET discover	miễn phí, với trần tốc độ chặt

Dịch vụ

GET /v1/api/health

Kiểm tra rằng Cognivo API đang hoạt động. Không cần API key.

curl 'https://api.cognivolabs.io/v1/api/health'

const res = await fetch("https://api.cognivolabs.io/v1/api/health");
const json = await res.json();

Phản hồi, vốn không theo lớp vỏ tiêu chuẩn, và đó là chủ ý:

{ "ok": true, "service": "cognivo-public-api", "version": "v1", "generated_at": "2026-07-09T00:00:00.000Z" }

Nếu API công khai bị tắt, bạn cũng nhận 404 public_api_disabled ở đây, nên endpoint này đồng thời đóng vai trò một phép kiểm tra tình trạng sẵn sàng.

GET /v1/api/me

Hiển thị chi tiết về key đang gọi: hạng, quyền và giới hạn tốc độ của nó. Hoạt động với bất kỳ key đang hoạt động nào, và miễn phí. Với các live key tự phục vụ, nó cũng hiển thị credits_balance của tài khoản chủ sở hữu và hướng dẫn top_up, cùng access_mode của key.

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

const res = await fetch("https://api.cognivolabs.io/v1/api/me", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const json = await res.json();

{
  "ok": true,
  "data": {
    "key": "cogv_live_****abcd",
    "project_id": "…",
    "environment": "live",
    "tier": "basic",
    "access_mode": "live",
    "scopes": ["intel:read", "liquidity:read"],
    "rate_limit_per_hour": 1000,
    "credits_balance": 1250,
    "top_up": "Manage credits from your Cognivo account billing page."
  },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

Hạn chế: nó chỉ hiển thị key đã che bớt, không bao giờ hiển thị nội dung key đầy đủ. credits_balance có thể trả về null, nghĩa là Cognivo không đọc được số dư vào thời điểm đó, chứ không phải số dư bằng không.

Các endpoint còn lại đều theo cùng hình dạng lệnh gọi như các ví dụ bên dưới. Chỉ cần đổi đường dẫn và các trường trong thân yêu cầu.

Trí tuệ về token

POST /v1/api/intel/why-down, quyền Intelligence (intel:read)

Một cách đọc bằng ngôn ngữ đời thường về lý do giá của một token đang giảm, dựng từ hoạt động on-chain gần đây: bán tháo mạnh, thanh khoản bị rút, ví chủ sở hữu hoặc ví đội ngũ dịch chuyển.

Giá niêm yết: 3 tín dụng 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í. 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.

curl -X POST 'https://api.cognivolabs.io/v1/api/intel/why-down' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"base","address":"0xTOKEN_CONTRACT"}'

const res = await fetch("https://api.cognivolabs.io/v1/api/intel/why-down", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "base", address: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();

Phản hồi: lớp vỏ tiêu chuẩn. data chứa yếu tố chi phối và các quan sát on-chain đứng sau nó, với meta.chain được đặt.

Hạn chế: cách đọc này cần hoạt động gần đây thì mới nói được điều gì hữu ích, nên một token có rất ít lịch sử giao dịch sẽ cho câu trả lời mỏng. Đây là các tín hiệu, không phải lời khuyên tài chính.

POST /v1/api/intel/team-wallets, quyền Intelligence (intel:read)

Làm lộ ra các ví liên kết với đội ngũ hoặc ngân quỹ của một token: ví triển khai, ví chủ sở hữu và ví điều khiển, cùng những gì chúng đã làm gần đây.

Giá niêm yết: 5 tín dụng 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í. 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.

curl -X POST 'https://api.cognivolabs.io/v1/api/intel/team-wallets' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"eth","address":"0xTOKEN_CONTRACT"}'

Phản hồi: lớp vỏ tiêu chuẩn. data liệt kê các ví được xác định và hành vi gần đây của chúng, thường kèm meta.sources.

Hạn chế: các ví được xác định từ quan hệ on-chain như triển khai, quyền sở hữu và quyền điều khiển. Cognivo không thấy được cấu trúc đội ngũ ngoài chain, nên một danh sách rỗng nghĩa là không có gì liên kết được trên chain, chứ không phải token đó không có đội ngũ.

POST /v1/api/intel/liquidity, quyền Liquidity (liquidity:read)

Kiểm tra thanh khoản, khóa và đốt của một token bằng bằng chứng on-chain: bối cảnh pool, ai đang giữ token LP, cùng bối cảnh khóa hoặc đốt.

Giá niêm yết: 2 tín dụng 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í. 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ác giá trị boolean tùy chọn metadata, locks và full bổ sung siêu dữ liệu pool, bằng chứng khóa có mốc thời gian, và cách đọc đầy đủ nhất hiện có.

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":"0xTOKEN_CONTRACT","locks":true}'

Phản hồi: lớp vỏ tiêu chuẩn. data chứa danh tính token, một ảnh chụp thị trường, và quyền giữ LP kèm bối cảnh khóa hoặc đốt.

Hạn chế: nguồn gốc lịch sử sâu của việc đốt không được phơi bày trong v1. Bối cảnh khóa bao phủ các mẫu locker được nhận diện, nên một locker tùy chỉnh khác thường có thể được đọc thành quyền giữ thông thường chứ không phải một lần khóa. Hãy đọc điều đó là "chưa được xác minh", không phải "không được khóa".

POST /v1/api/intel/risk, quyền Intelligence (intel:read)

Cognivo Risk Signals cho một hợp đồng token, có nhận biết chain, kèm cách đọc cờ đỏ làm phương án dự phòng.

Giá niêm yết: 2 tín dụng 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í. 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.

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":"bsc","address":"0xTOKEN_CONTRACT"}'

Phản hồi: lớp vỏ tiêu chuẩn. data chứa các tín hiệu và cờ tìm được cho token đó.

Hạn chế: một kết quả sạch không có nghĩa là token an toàn. Nó có nghĩa là không tìm thấy cờ đỏ đã biết nào vào thời điểm đọc.

POST /v1/api/contract/analysis, quyền Contract (contract:read)

Bằng chứng về hợp đồng và quyền điều khiển cho một địa chỉ hợp đồng: nó có tồn tại không, ai sở hữu nó, quyền sở hữu đã được từ bỏ chưa, nó có phải proxy không và ai quản trị nó, ai đã triển khai nó, những ví nào có thể quy cho là bên điều khiển hoặc đội ngũ, và mã nguồn đã được xác minh chưa.

Chi phí: 0 tín dụng. Endpoint này miễn phí theo quyết định, trên mọi gói. Không có gì bị trừ.

curl -X POST 'https://api.cognivolabs.io/v1/api/contract/analysis' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"base","address":"0xTOKEN_CONTRACT"}'

Phản hồi: lớp vỏ tiêu chuẩn. data chứa contract, ownership, proxy, deployer, controllers, source_verification, limitations và unavailable.

Mọi trường đều cho bạn biết nó đến từ đâu. meta.provenance ánh xạ mỗi trường tới đúng một trong các nhãn sau:

Nhãn	Ý nghĩa
verified_onchain	Đọc từ một node của mạng đó vào thời điểm bạn gửi yêu cầu. Một sự thật.
augmented	Cognivo Augmented Intelligence: do một nguồn bên ngoài cung cấp, đã được đối chiếu nhưng chưa được Cognivo chứng minh.
interpretation	Cách Cognivo đọc các sự kiện. Một phán đoán, không phải một sự thật.
unavailable	Cognivo không lấy được thứ này. Lý do nằm trong data.unavailable.

Không có gì bị đoán mò, đặt mặc định hay trả về bằng không để lấp chỗ trống.

meta.chain_data_source.cognivo_grounded cho bạn biết Cognivo có vận hành hạ tầng mà lần đọc đó lấy dữ liệu từ đó hay không. Cognivo chạy node Ethereum của riêng mình, nên các lần đọc Ethereum là true. Các lần đọc Base và BNB Chain đến từ hạ tầng RPC bên ngoài, nên chúng là false. Những lần đọc đó vẫn chính xác, nhưng chúng không được phục vụ từ phần cứng do Cognivo kiểm soát, và Cognivo nói rõ điều đó thay vì để bạn tự cho là khác đi.

Các hạn chế trên Base, cũng được trả về trong data.limitations:

• Đồ thị điều khiển sâu chỉ có trên Ethereum. Trên Base, việc quy kết bên điều khiển và đội ngũ đến từ một cách đọc vai trò ví hẹp hơn.
• Bằng chứng về ví triển khai trên Base đến từ một nguồn bên ngoài, không phải một lần đọc kho lưu trữ của Cognivo. Hãy coi đó là một manh mối mạnh, không phải một sự thật đã được chứng minh.
• Lịch khóa thanh khoản không được giải mã trên Base. Hãy dùng POST /v1/api/intel/liquidity để lấy bằng chứng về quyền giữ LP và việc đốt, và đừng đọc một lần khóa bị thiếu thành một lần khóa không tồn tại.

Endpoint này chỉ báo cáo bằng chứng về quyền điều khiển hợp đồng. Nó không nói gì về thanh khoản, và một kết quả sạch không bao giờ có nghĩa là hợp đồng an toàn.

Chỉ đọc: không có gì được ký, không có giao dịch nào được dựng, không có gì được phát đi, và không có ví nào bị ủy quyền.

Trí tuệ về ví

POST /v1/api/wallet/pnl, quyền Intelligence (intel:read)

Lãi và lỗ của một ví trên một token, được tính từ các giao dịch hoán đổi on-chain có căn cứ. Cả wallet lẫn token đều bắt buộc.

Giá niêm yết: 10 tín dụng cho mỗi lệnh gọi thành công. Lệnh gọi thất bại, và các kết quả 422 không có dữ liệu, không bao giờ bị tính phí. 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.

curl -X POST 'https://api.cognivolabs.io/v1/api/wallet/pnl' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"base","wallet":"0xWALLET","token":"0xTOKEN_CONTRACT"}'

Phản hồi: lớp vỏ tiêu chuẩn. data chứa con số đã hiện thực hóa, và một con số chưa hiện thực hóa cho phần vị thế vẫn đang nắm giữ khi tồn tại một cơ sở giá vốn có thể bảo vệ được.

Hạn chế: khi không thể thiết lập một cơ sở giá vốn có thể bảo vệ được, con số chưa hiện thực hóa trả về null thay vì một con số bịa ra. Khi ví hoàn toàn không có giao dịch nào được định giá trong token đó, lệnh gọi trả về 422 (ví dụ insufficient_data), nghĩa là Cognivo không tính được một con số công bằng, chứ không phải lợi nhuận bằng không. Một lỗi 422 không bao giờ bị tính phí. Các giao dịch hoán đổi mà Cognivo không định giá được sẽ được hiển thị là chưa định giá thay vì bị bỏ đi.

POST /v1/api/wallet/approvals, quyền Security (security:read)

Liệt kê các phê duyệt chi tiêu token mà một ví đã cấp, và đánh dấu các hạn mức không giới hạn.

Giá niêm yết: 2 tín dụng 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í. 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ác tham số tùy chọn limit và offset giúp phân trang qua những tập phê duyệt lớn.

curl -X POST 'https://api.cognivolabs.io/v1/api/wallet/approvals' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"eth","address":"0xWALLET"}'

Phản hồi: lớp vỏ tiêu chuẩn. data chứa danh sách phê duyệt kèm bối cảnh về bên được phép chi tiêu, token và hạn mức.

Hạn chế: đây là chức năng chỉ đọc. Cognivo không bao giờ chuyển tiền và không thể thu hồi một phê duyệt thay bạn. Việc thu hồi luôn được thực hiện từ chính ví của bạn. Một danh sách rỗng là một câu trả lời thành công hợp lệ, và nó không bị tính phí.

POST /v1/api/wallet/exact-movements, quyền Intelligence (intel:read)

Liệt kê các dịch chuyển token chính xác của một ví: mua, bán và chuyển. token là tùy chọn và thu hẹp cách đọc về một token duy nhất.

Giá niêm yết: 5 tín dụng 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í. 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.

curl -X POST 'https://api.cognivolabs.io/v1/api/wallet/exact-movements' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"base","wallet":"0xWALLET"}'

Phản hồi: lớp vỏ tiêu chuẩn. data chứa danh sách dịch chuyển kèm số lượng.

Hạn chế: lệnh gọi trả về các dịch chuyển gần đây nhất, tối đa 25 mỗi lệnh gọi. Một ví không có dịch chuyển nào khớp sẽ trả về 422 thay vì một lịch sử bịa ra.

Discover

GET /v1/api/discover

Nguồn cấp Discover công khai: các thẻ trí tuệ on-chain gần đây đã được ẩn danh, mỗi thẻ kèm danh tính token, một câu dẫn và các gạch đầu dòng. Hoạt động với bất kỳ key đang hoạt động nào. Miễn phí, dưới một giới hạn hằng ngày chặt.

Tham số truy vấn: limit (1 tới 50, mặc định 20) và chain tùy chọn (eth, base, bsc).

curl 'https://api.cognivolabs.io/v1/api/discover?limit=10&chain=base' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "ok": true,
  "data": { "cards": [ { "...": "public intelligence card" } ], "total": 10 },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

Hạn chế: các giá trị limit nằm ngoài khoảng 1 tới 50 sẽ bị kẹp về trong khoảng. Nguồn cấp chỉ chứa những trí tuệ mà người dùng đã chọn công bố, nên đó là một mẫu, không phải độ phủ đầy đủ.

Chưa khả dụng

Những mục sau được liệt kê để minh bạch và hiện chưa trả về gì:

• Dấu vết ví sâu qua API (wallet/trace). Luồng tác vụ bất đồng bộ hiện chỉ có trong trò chuyện và ứng dụng.
• Lấy báo cáo theo id (reports/:id).
• Webhooks.
• Các endpoint Solana.

Bước tiếp theo

Thực hiện lệnh gọi đầu tiên của bạn với Bắt đầu nhanh, tạo và giới hạn phạm vi một key ở Xác thực và API key, và đọc Giới hạn tốc độ và lỗi trước khi bạn đưa bất cứ thứ gì vào chạy theo lịch.