Tham chiếu endpoint

Tất cả các endpoint nằm dưới https://api.cognivolabs.io/v1/api. Các endpoint trí tuệ dùng POST với body JSON (điều này ngăn bản xem trước liên kết, trình thu thập dữ liệu và trình tải trước kích hoạt một lần thực thi). GET chỉ tồn tại cho health, me và discover.

Muốn phiên bản máy đọc được? Đặc tả OpenAPI đầy đủ bao trùm mọi thứ trên trang này.

Phong bì phản hồi

Mọi endpoint đều trả lời với cùng một phong bì. Thành công:

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

data - bản thân kết quả trí tuệ; cấu trúc của nó thay đổi theo từng endpoint
meta.request_id - id duy nhất cho lệnh gọi này; hãy giữ lại, đội hỗ trợ có thể truy vết một lệnh gọi từ nó
meta.credits_charged - số tín dụng lệnh gọi này tốn: 0 cho các endpoint miễn phí, hạn mức demo sandbox hoặc hạn mức trial, và bất kỳ kết quả thất bại hay rỗng nào; giá tín dụng của endpoint khi sử dụng trả phí
meta.generated_at - thời điểm kết quả được tạo ra
meta.chain xuất hiện trong các lệnh gọi gắn với chain cụ thể, và meta.sources (một mảng nhãn nguồn) xuất hiện khi kết quả 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 (xem Giới hạn tốc độ và lỗi); message là gợi ý tùy chọn dành cho con người.

Các trường body chung

chain - một trong eth, base, bsc (không phân biệt hoa thường)
address / wallet / token - một địa chỉ EVM dạng 0x… (40 ký tự hex)

Mọi ví dụ bên dưới dùng placeholder YOUR_API_KEY; trong mã thật, hãy nạp key từ biến môi trường hoặc trình quản lý bí mật, không bao giờ mã hóa cứng nó.

Quyền truy cập và chi phí tín dụng

Các endpoint trí tuệ có thể thực thi yêu cầu quyền truy cập trial, đối tác, trả phí hoặc enterprise. Không có quyền truy cập, chúng không chạy miễn phí: bạn nhận một lỗi 403 rõ ràng như access_required (xem Giới hạn tốc độ và lỗi). Sử dụng trả phí được tính bằng tín dụng Cognivo cho mỗi lệnh gọi thành công; các lệnh gọi thất bại không bị tính phí. Chi phí theo từng endpoint (áp dụng cho sử dụng trả phí; hiển thị để minh bạch):

Endpoint	Tín dụng 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
`GET health`, `GET me`	miễn phí
`GET discover`	miễn phí, với giới hạn tốc độ chặt

Dịch vụ

GET /v1/api/health

Kiểm tra tình trạng 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 (không phải phong bì chuẩn, đây là chủ ý):

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

Giới hạn: nếu API công khai bị tắt, bạn cũng nhận 404 public_api_disabled tại đây, nên endpoint này đồng thời đóng vai trò kiểm tra khả dụng.

GET /v1/api/me

Tra cứu thông tin của key đang gọi. Scope: bất kỳ key hợp lệ nào. Miễn phí. Với các key live tự phục vụ, nó cũng hiển thị credits_balance của tài khoản sở hữu (null nếu tạm thời không khả dụng) và hướng dẫn top_up, cùng với 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();

Phản hồi:

{
  "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": "Top up Cognivo credits on your account billing page in the dApp."
  },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

Giới hạn: chỉ hiển thị key đã che, không bao giờ hiển thị nội dung key đầy đủ. credits_balance là số dư tín dụng Cognivo của tài khoản sở hữu và có thể là null nếu tạm thời không khả dụng.

Trí tuệ token

POST /v1/api/intel/why-down - scope `intel:read`

Vì sao token này giảm giá: một cách đọc có căn cứ về hoạt động on-chain gần đây để tìm yếu tố chi phối (lệnh bán, rút LP, dịch chuyển của chủ sở hữu).

Quyền truy cập và chi phí: yêu cầu quyền truy cập trực tiếp (trial, đối tác, trả phí hoặc enterprise); 3 tín dụng mỗi lệnh gọi thành công khi sử dụng trả phí.

Body yêu cầu:

{ "chain": "base", "address": "0xTOKEN_CONTRACT" }

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: phong bì chuẩn; data chứa phân tích cú giảm giá (yếu tố chi phối, các quan sát on-chain hỗ trợ) với meta.chain được thiết lập.

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

POST /v1/api/intel/team-wallets - scope `intel:read`

Quét ví đội ngũ và ví kiểm soát của một token: các ví deployer, owner và controller cùng hành vi gần đây của chúng.

Quyền truy cập và chi phí: yêu cầu quyền truy cập trực tiếp (trial, đối tác, trả phí hoặc enterprise); 5 tín dụng mỗi lệnh gọi thành công khi sử dụng trả phí.

Body yêu cầu:

{ "chain": "eth", "address": "0xTOKEN_CONTRACT" }

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

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

Phản hồi: phong bì chuẩn; data liệt kê các ví đội ngũ/kiểm soát đã nhận diện và hành vi gần đây của chúng, thường kèm meta.sources.

Giới hạn: nhận diện ví từ các mối quan hệ on-chain (deploy, sở hữu, kiểm soát); nó không thể nhìn thấy cấu trúc đội ngũ ngoài chain.

POST /v1/api/intel/liquidity - scope `liquidity:read`

Trạng thái pool/LP của một token: bối cảnh pool, quyền nắm giữ LP và bối cảnh khóa/đốt.

Quyền truy cập và chi phí: yêu cầu quyền truy cập trực tiếp (trial, đối tác, trả phí hoặc enterprise); 2 tín dụng mỗi lệnh gọi thành công khi sử dụng trả phí.

Body yêu cầu (các boolean tùy chọn metadata, locks và full bổ sung metadata pool có căn cứ, bằng chứng khóa theo thời gian và bản đọc đầy đủ nhất hiện có):

{ "chain": "base", "address": "0xTOKEN_CONTRACT", "locks": true }

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

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

Phản hồi: phong bì chuẩn; data chứa danh tính token, một ảnh chụp thị trường, quyền nắm giữ LP cùng bối cảnh khóa/đốt.

Giới hạn: nguồn gốc đốt lịch sử sâu chưa được cung cấp trong v1; bối cảnh khóa bao phủ các mẫu locker được nhận diện, và một locker tùy biến không được nhận diện có thể bị đọc thành quyền nắm giữ chưa khóa.

POST /v1/api/intel/risk - scope `intel:read`

Tín hiệu rủi ro Cognivo theo từng chain cho một token (đọc red-flag làm phương án dự phòng).

Body yêu cầu:

{ "chain": "bsc", "address": "0xTOKEN_CONTRACT" }

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

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

Phản hồi: phong bì chuẩn; data chứa các tín hiệu rủi ro và các cờ tìm thấy cho token.

Giới hạn: kết quả sạch không bao giờ có nghĩa là "an toàn"; nó nghĩa là không tìm thấy red flag đã biết nào tại thời điểm đọc.

Trí tuệ ví

POST /v1/api/wallet/pnl - scope `intel:read`

PnL đã hiện thực hóa của một ví trên một token, từ hoạt động ví có căn cứ. Cả wallet và token đều bắt buộc.

Quyền truy cập và chi phí: yêu cầu quyền truy cập trực tiếp (trial, đối tác, trả phí hoặc enterprise); 10 tín dụng mỗi lệnh gọi thành công khi sử dụng trả phí.

Body yêu cầu:

{ "chain": "base", "wallet": "0xWALLET", "token": "0xTOKEN_CONTRACT" }

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

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

Phản hồi: phong bì chuẩn; data chứa kết quả tính PnL đã hiện thực hóa cho cặp ví/token đó.

Giới hạn: trả về 422 (ví dụ insufficient_data) khi ví không có giao dịch được định giá với token đó, nên không thể tính một con số công bằng. Cognivo không bao giờ bịa ra một con số, và một 422 không bao giờ bị tính phí. Chỉ PnL đã hiện thực hóa; các vị thế chưa hiện thực hóa (còn đang nắm giữ) không được định giá ở đây.

POST /v1/api/wallet/approvals - scope `security:read`

Các approval token đang tồn tại trên một ví, gắn cờ các allowance không giới hạn. Chỉ đọc: Cognivo không bao giờ di chuyển tiền và không thể thu hồi thay bạn.

Body yêu cầu (limit và offset tùy chọn để phân trang qua các tập approval lớn):

{ "chain": "eth", "address": "0xWALLET" }

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

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

Phản hồi: phong bì chuẩn; data chứa danh sách approval với bối cảnh spender, token và allowance.

Giới hạn: kết quả rỗng (không tìm thấy approval nào) là một câu trả lời hợp lệ, thành công và không bị tính phí.

POST /v1/api/wallet/exact-movements - scope `intel:read`

Các dịch chuyển gần đây chính xác của một ví (kiểu đọc owner/deployer). token là tùy chọn và thu hẹp việc đọc về một token.

Body yêu cầu:

{ "chain": "base", "wallet": "0xWALLET", "token": "0xTOKEN_CONTRACT" }

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

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

Phản hồi: phong bì chuẩn; data chứa danh sách dịch chuyển kèm số lượng.

Giới hạn: trả về các dịch chuyển gần nhất (tối đa 25 mỗi lệnh gọi); một ví không có dịch chuyển phù hợp trả về 422 thay vì một lịch sử bịa đặt.

Discover

GET /v1/api/discover

Nguồn cấp Discover công khai: các thẻ trí tuệ công khai chất lượng cao gần đây (danh tính token, câu dẫn, các gạch đầu dòng). Scope: bất kỳ key hợp lệ nào. Miễn phí, với giới hạn tốc độ chặt.

Tham số truy vấn: limit (1-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'

const res = await fetch("https://api.cognivolabs.io/v1/api/discover?limit=10&chain=base", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const json = await res.json();

Phản hồi:

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

Giới hạn: các giá trị limit ngoài khoảng 1-50 sẽ bị ép vào trong khoảng; nguồn cấp chỉ chứa trí tuệ mà người dùng đã chọn công bố, nên nó là một mẫu, không phải độ phủ toàn bộ.

Đã lên kế hoạch (chưa hoạt động)

Những mục này được ghi lại để minh bạch lộ trình và hiện tại không trả về gì:

Truy vết ví sâu qua API (wallet/trace) - luồng job bất đồng bộ hiện chỉ dành cho chat/dApp
Lấy báo cáo theo id (reports/:id)
Webhooks
Các endpoint Solana

Phong bì phản hồi​

Các trường body chung​

Quyền truy cập và chi phí tín dụng​

Dịch vụ​

GET /v1/api/health​

GET /v1/api/me​

Trí tuệ token​

POST /v1/api/intel/why-down - scope intel:read​

POST /v1/api/intel/team-wallets - scope intel:read​

POST /v1/api/intel/liquidity - scope liquidity:read​

POST /v1/api/intel/risk - scope intel:read​

Trí tuệ ví​

POST /v1/api/wallet/pnl - scope intel:read​

POST /v1/api/wallet/approvals - scope security:read​

POST /v1/api/wallet/exact-movements - scope intel:read​

Discover​

GET /v1/api/discover​

Đã lên kế hoạch (chưa hoạt động)​

Phong bì phản hồi

Các trường body chung

Quyền truy cập và chi phí tín dụng

Dịch vụ

GET /v1/api/health

GET /v1/api/me

Trí tuệ token

POST /v1/api/intel/why-down - scope `intel:read`

POST /v1/api/intel/team-wallets - scope `intel:read`

POST /v1/api/intel/liquidity - scope `liquidity:read`

POST /v1/api/intel/risk - scope `intel:read`

Trí tuệ ví

POST /v1/api/wallet/pnl - scope `intel:read`

POST /v1/api/wallet/approvals - scope `security:read`

POST /v1/api/wallet/exact-movements - scope `intel:read`

Discover

GET /v1/api/discover

Đã lên kế hoạch (chưa hoạt động)