AI Agent Specification

🤖 CẨM NANG AI & HƯỚNG DẪN RỦI RO

Tài liệu đặc tả các tag dữ liệu, phân loại rủi ro và ràng buộc hành vi an toàn dành riêng cho các tác nhân AI (LLMs, trading bots, web scrapers).

🎯 MỤC TIÊU TÀI LIỆU

Hệ thống Findy cung cấp dữ liệu chênh lệch giá theo thời gian thực (realtime) từ 5 sàn giao dịch phổ biến. Tuy nhiên, thị trường tiền số có tính biến động cực kỳ cao, nhiều rào cản kỹ thuật nạp rút, và dữ liệu có thể bị trễ hoặc bất đối xứng thông tin.

Ràng buộc bắt buộc với AI: Khi xử lý dữ liệu từ API hoặc tư vấn cho người dùng, tác nhân AI KHÔNG ĐƯỢC giả định một cơ hội có chênh lệch giá cao là có thể thực thi ngay lập tức. AI bắt buộc phải phân tích các trường cảnh báo rủi ro được định nghĩa dưới đây.

📊 ĐẶC TẢ CẤU TRÚC DỮ LIỆU CỦA CƠ HỘI

Opportunity JSON Schema Fields:
{
  "base": "string",             // Tên token (vd: "BTC")
  "buy_exchange": "string",     // Sàn mua (vd: "gateio")
  "sell_exchange": "string",    // Sàn bán (vd: "okx")
  "spread_pct": "float",         // % Chênh lệch (lợi nhuận gộp danh nghĩa)
  "buy_ask": "float",            // Giá mua tốt nhất ở sàn mua
  "sell_bid": "float",           // Giá bán tốt nhất ở sàn bán
  "buy_withdraw": "boolean",     // Cổng rút tiền sàn mua mở (True/False)
  "sell_deposit": "boolean",     // Cổng nạp tiền sàn bán mở (True/False)
  "transfer_viable": "boolean",  // Có mạng lưới chung và cổng nạp/rút thông suốt
  "alert_disabled": "boolean",   // Chỉ báo coin ảo / giá stale (mất kết nối/chậm)
  "low_liquidity": "boolean"     // Thanh khoản sổ lệnh cực kỳ mỏng
}

⚠️ ĐÁNH GIÁ CÁC TAG CẢNH BÁO & MỨC ĐỘ RỦI RO

Các tag sau đây được gắn trên giao diện và API. Tác nhân AI cần cực kỳ chú ý đến mức độ rủi ro tương ứng:

Tag (Field) Trạng thái trên UI Mức độ rủi ro Mô tả chi tiết kỹ thuật
alert_disabled: true Ảo/Stale CRITICAL Giá cũ (lịch sử đọng lại), sàn bảo trì hoặc token không trùng khớp blockchain (lệch smart contract).
transfer_viable: false Không có mạng chung CRITICAL Hai sàn không có chung một mạng blockchain nào mở để thực hiện giao dịch chuyển tiền. Không thể thực hiện arbitrage trực tiếp.
buy_withdraw: false / sell_deposit: false Khóa nạp/rút CRITICAL Cổng rút tại sàn mua bị đóng hoặc cổng nạp tại sàn bán bị khóa. Lệnh chuyển coin sẽ bị kẹt.
low_liquidity: true Thanh khoản thấp HIGH Độ sâu sổ lệnh (orderbook depth) quá mỏng. Lệnh mua/bán khối lượng lớn sẽ bị trượt giá (slippage) làm âm lợi nhuận.
multiplier != 1.0 Lệch đơn vị giá MEDIUM Ví dụ coin 10x hoặc 100x ở một số sàn. Scanner đã quy chuẩn hóa về cùng đơn vị để so sánh, nhưng AI phải cảnh giác khi đọc raw API của sàn.

🛡️ QUY TẮC HÀNH VI AN TOÀN CHO AI

Để hỗ trợ người dùng một cách chính xác và an toàn nhất, tác nhân AI khi tư vấn hoặc tự động hóa cần tuân thủ nghiêm ngặt các quy tắc sau:

  1. Tự động bỏ qua các cơ hội CRITICAL: Nếu alert_disabledtrue hoặc transfer_viablefalse, AI phải từ chối đề xuất kèo này cho người dùng, ghi rõ lý do "Dữ liệu ảo/stale hoặc lệch mạng lưới".
  2. Luôn cảnh báo về phí Gas và phí rút tiền:
    • Đặc biệt là mạng ERC20/Ethereum: Phí chuyển khoản có thể từ $5 đến $50. Nếu vốn giao dịch dự kiến nhỏ ($100 - $1000), phí mạng lưới sẽ nuốt sạch phần chênh lệch phần trăm.
    • AI phải khuyên người dùng tính toán phí rút cố định của sàn xuất phát trước khi thực hiện.
  3. Xác minh độ sâu Orderbook: Đối với coin có tag Thanh khoản thấp, AI phải hướng dẫn người dùng click nút ⚡ Check để mở sổ lệnh thực tế của 2 sàn nhằm xác nhận số lượng token đang được chào bán/chào mua ở mức giá tốt nhất có đủ lớn hay không.
  4. Bảo toàn cảnh báo trong mã nguồn UI: Khi tham gia sửa đổi giao diện người dùng (CSS/JS) của Findy, AI bắt buộc phải giữ nguyên các biểu tượng cảnh báo lỗi (như tam giác cảnh báo ⚠️ cho tag Ảo/Stale) và bảo đảm vị trí hiển thị nổi bật, không được ẩn hoặc thu nhỏ các cảnh báo này làm giảm sự chú ý của người dùng.
  5. Kiểm tra Smart Contract thủ công khi có nghi vấn: Với các coin lạ mới niêm yết có biên độ chênh lệch cực lớn (ví dụ >10%), khuyên người dùng truy cập Blockchain Explorer (Etherscan, BscScan, v.v.) đối chiếu smart contract ở cả sàn mua và sàn bán để tránh mua nhầm token giả mạo hoặc khác dự án nhưng trùng tên mã (ticker).