ValueScan đăng ký tín hiệu Token thời gian thực

Môi trường production: https://stream.valuescan.ai

1. Tổng quan

Sau khi người dùng đăng ký các token chỉ định, khi token phát sinh tín hiệu (cơ hội, rủi ro, biến động dòng tiền), máy chủ chủ động đẩy tin nhắn tới client.

Đặc điểm chính:

Đẩy gần thời gian thực theo giây: Tín hiệu được gửi tới client ngay sau khi phát sinh
Nhiều loại tín hiệu: Hỗ trợ tín hiệu cơ hội (OPPORTUNITY), tín hiệu rủi ro (RISK), tín hiệu biến động dòng tiền (FUNDS)
Tự kết nối lại khi mất kết nối: Client tự xử lý ngắt kết nối và thử lại

2. URL đăng ký

GET https://stream.valuescan.ai/stream/signal/subscribe

Tham số xác thực (query string):

Tham số	Kiểu	Bắt buộc	Mô tả
`apiKey`	string	Có	ValueScan Access Key
`sign`	string	Có	Chữ ký HMAC-SHA256
`timestamp`	long	Có	Unix timestamp đơn vị mili giây
`nonce`	string	Có	Chuỗi ngẫu nhiên (chống replay)
`tokens`	string	Có	ID token đăng ký; nhiều token phân tách bằng dấu phẩy, ví dụ `1,2,3`; để trống mặc định là tất cả token

Thuật toán ký:

sign = HMAC-SHA256(SK, timestampMs + nonce)

Trong đó timestampMs là chuỗi timestamp Unix tính bằng mili giây nối với nonce.

Ví dụ (Python):

python

import hashlib
import hmac
import time
import uuid

ts = int(time.time() * 1000)          # Timestamp mili giây
nonce = uuid.uuid4().hex               # Chuỗi ngẫu nhiên
sign = hmac.new(
    SK.encode(),
    (str(ts) + nonce).encode(),
    hashlib.sha256
).hexdigest()

Hiệu lực timestamp: ±300 giây (5 phút); ngoài khoảng này trả về 401.

3. Định dạng sự kiện SSE

Kết nối thành công

event: connected
data: subscribed

Heartbeat (duy trì kết nối)

: heartbeat

event: heartbeat
data: ping

Máy chủ gửi heartbeat mỗi 20 giây.

Đẩy tín hiệu

event: signal
data: {"content":"{...}","tokenId":1,"type":"OPPORTUNITY","ts":1775604300144,"uniqueKey":"1_1775604300144"}

Các trường payload sự kiện signal:

Trường	Kiểu	Mô tả
`tokenId`	long	ID token
`type`	string	Loại tín hiệu
`content`	string	Chi tiết tín hiệu dạng chuỗi JSON
`ts`	long	Timestamp mili giây
`uniqueKey`	string	Khóa khử trùng lặp

4. Ba loại tín hiệu

1. Tín hiệu cơ hội (OPPORTUNITY)

Ý nghĩa: Tin theo dõi thời gian thực do AI, đa chiều dữ liệu, cho các token có tiềm năng tăng trong thị trường hiện tại.

API truy vấn tương ứng: POST /open/v1/ai/getChanceCoinMessageList

Cấu trúc content:

Trường	Kiểu	Mô tả
`vsTokenId`	string	ID token
`symbol`	string	Ký hiệu token, ví dụ BTC
`name`	string	Tên token, ví dụ Bitcoin
`chanceMessageType`	int	Loại tin cơ hội (kiểu hành động tay to)
`scoring`	number	Điểm cơ hội; càng cao tín hiệu càng mạnh
`grade`	int	Cấp tín hiệu
`price`	string	Giá hiện tại
`percentChange24h`	number	Biến động 24 giờ
`gains`	number	Mức tăng
`decline`	number	Mức giảm
`updateTime`	long	Thời điểm cập nhật (timestamp mili giây)

2. Tín hiệu rủi ro (RISK)

Ý nghĩa: Tin theo dõi thời gian thực do AI, đa chiều dữ liệu, cho các token có rủi ro giảm giá trong thị trường hiện tại.

API truy vấn tương ứng: POST /open/v1/ai/getRiskCoinMessageList

Cấu trúc content:

Trường	Kiểu	Mô tả
`vsTokenId`	string	ID token
`symbol`	string	Ký hiệu token
`name`	string	Tên token
`riskMessageType`	int	Loại tin rủi ro
`scoring`	number	Điểm rủi ro (có thể rỗng)
`grade`	int	Cấp tín hiệu (có thể rỗng)
`price`	string	Giá hiện tại
`percentChange24h`	number	Biến động 24 giờ
`riskDecline`	number	Mức giảm rủi ro (biên độ giảm giá)
`rebound`	number	Biên độ phục hồi
`updateTime`	long	Thời điểm cập nhật (timestamp mili giây)

3. Tín hiệu biến động dòng tiền (FUNDS)

Ý nghĩa: Tin theo dõi thời gian thực về biến động dòng tiền tay to trong giao dịch spot hoặc phái sinh trên sàn tập trung.

API truy vấn tương ứng: POST /open/v1/ai/getFundsCoinMessageList

Cấu trúc content:

Trường	Kiểu	Mô tả
`vsTokenId`	string	ID token
`symbol`	string	Ký hiệu token
`name`	string	Tên token
`tradeType`	int	Loại giao dịch (1: spot, 2: hợp đồng, 3: hợp đồng giao hạn)
`price`	string	Giá hiện tại
`percentChange24h`	number	Biến động 24 giờ
`fundsMovementType`	int	Loại dòng tiền (1: spot; 2: hợp đồng; v.v.)
`updateTime`	long	Thời điểm cập nhật (timestamp mili giây)

5. Ví dụ đăng ký

Python (khuyến nghị)

python

import hashlib
import hmac
import json
import time
import uuid
import urllib.request
from urllib.parse import urlencode

AK = "your-access-key"
SK = "your-secret-key"
TOKENS = "1,2,3"          # ID token đăng ký

ts = int(time.time() * 1000)
nonce = uuid.uuid4().hex
sign = hmac.new(
    SK.encode(),
    (str(ts) + nonce).encode(),
    hashlib.sha256,
).hexdigest()

params = urlencode({
    "apiKey": AK,
    "sign": sign,
    "timestamp": ts,
    "nonce": nonce,
    "tokens": TOKENS,
})

url = f"https://stream.valuescan.ai/stream/signal/subscribe?{params}"
req = urllib.request.Request(url, headers={"Accept": "text/event-stream"})

with urllib.request.urlopen(req, timeout=300) as resp:
    event_name = ""
    data_str = ""
    for raw in resp:
        line = raw.decode("utf-8").rstrip("\r\n")

        if line.startswith(":"):
            print("♥ Heartbeat")
            continue

        if line == "":
            if data_str:
                handle_event(event_name, data_str)
            event_name = ""
            data_str = ""
        elif line.startswith("event:"):
            event_name = line[6:].strip()
        elif line.startswith("data:"):
            data_str = line[5:].strip()


def handle_event(event_name: str, data_str: str) -> None:
    if event_name == "signal":
        payload = json.loads(data_str)
        token_id = payload["tokenId"]
        signal_type = payload["type"]
        content = json.loads(payload["content"])
        print(f"[Tín hiệu] tokenId={token_id} type={signal_type} content={content}")
    elif event_name == "connected":
        print(f"[Kết nối] {data_str}")

cURL (kiểm tra nhanh)

bash

# Tạo lệnh curl đã ký
python3 -c "
import hashlib, hmac, time, uuid, urllib.parse
SK='your-secret-key'
ts=int(time.time()*1000)
nonce=uuid.uuid4().hex
sign=hmac.new(SK.encode(), (str(ts)+nonce).encode(), hashlib.sha256).hexdigest()
params=urllib.parse.urlencode({'apiKey':'your-access-key','sign':sign,'timestamp':ts,'nonce':nonce,'tokens':'1,2'})
print(f'curl -N \"https://stream.valuescan.ai/stream/signal/subscribe?{params}\" -H \"Accept: text/event-stream\"')
'"

Sao chép và chạy lệnh in ra.

6. Kết nối lại khi mất kết nối

Kết nối SSE có thể bị ngắt do mạng hoặc máy chủ khởi động lại. Nên triển khai backoff theo cấp số nhân trên client:

python

import time

def listen_with_retry(url: str, max_retries: int = 10) -> None:
    retries = 0
    while retries <= max_retries:
        try:
            req = urllib.request.Request(url, headers={"Accept": "text/event-stream"})
            with urllib.request.urlopen(req, timeout=300) as resp:
                # Thoát bình thường (người dùng ngắt) — không kết nối lại
                _read_sse(resp)
                break
        except KeyboardInterrupt:
            print("Người dùng ngắt, thoát.")
            break
        except Exception as e:
            retries += 1
            wait = min(2 ** retries, 60)
            print(f"Mất kết nối ({e}), lần kết nối lại thứ {retries} sau {wait}s...")
            time.sleep(wait)
    else:
        print("Hết số lần thử, thoát.")

7. Ví dụ phân tích nội dung

Trường content là chuỗi JSON, cần parse hai lần:

python

def parse_signal_content(content_str: str) -> dict:
    return json.loads(content_str)

# Ví dụ
payload = json.loads(data_str)
content = parse_signal_content(payload["content"])

if payload["type"] == "OPPORTUNITY":
    print(f"Tín hiệu cơ hội: {content['name']} ({content['symbol']}) "
          f"giá={content['price']} điểm={content['scoring']}")
elif payload["type"] == "RISK":
    print(f"Tín hiệu rủi ro: {content['name']} ({content['symbol']}) "
          f"giá={content['price']} mức giảm rủi ro={content['riskDecline']}%")
elif payload["type"] == "FUNDS":
    trade = "Spot" if content["tradeType"] == 1 else "Hợp đồng"
    print(f"Biến động dòng tiền: {content['name']} ({content['symbol']}) "
          f"{trade} giá={content['price']}")

8. Tích hợp SDK (Python)

Khuyến nghị dùng SDK chính thức; đăng ký khoảng 20 dòng code:

python

from agent.sdk.client import SseClient

def on_event(event_name: str, payload: dict) -> None:
    if event_name == "signal":
        import json
        content = json.loads(payload["content"])
        print(f"[{payload['type']}] {content.get('name', '')} "
              f"{content.get('price', '')}")

client = SseClient(
    url="https://stream.valuescan.ai/stream/signal/subscribe?<tham số truy vấn đã ký>",
    on_event=on_event,
)
client.start()

SDK xử lý nội bộ: parse heartbeat, kết nối lại (backoff theo cấp số nhân), phân phối sự kiện.

9. Mã lỗi

HTTP	Mô tả
200	Kết nối thành công
400	Thiếu tham số hoặc định dạng sai
401	Chữ ký không hợp lệ hoặc timestamp ngoài phạm vi
404	URL đăng ký sai
503	Dịch vụ không khả dụng (lỗi kết nối backend xác thực)

ValueScan đăng ký tín hiệu Token thời gian thực ​

1. Tổng quan ​

2. URL đăng ký ​

3. Định dạng sự kiện SSE ​

Kết nối thành công ​

Heartbeat (duy trì kết nối) ​

Đẩy tín hiệu ​

4. Ba loại tín hiệu ​

1. Tín hiệu cơ hội (OPPORTUNITY) ​

2. Tín hiệu rủi ro (RISK) ​

3. Tín hiệu biến động dòng tiền (FUNDS) ​

5. Ví dụ đăng ký ​

Python (khuyến nghị) ​

cURL (kiểm tra nhanh) ​

6. Kết nối lại khi mất kết nối ​

7. Ví dụ phân tích nội dung ​

8. Tích hợp SDK (Python) ​

9. Mã lỗi ​

ValueScan đăng ký tín hiệu Token thời gian thực

1. Tổng quan

2. URL đăng ký

3. Định dạng sự kiện SSE

Kết nối thành công

Heartbeat (duy trì kết nối)

Đẩy tín hiệu

4. Ba loại tín hiệu

1. Tín hiệu cơ hội (OPPORTUNITY)

2. Tín hiệu rủi ro (RISK)

3. Tín hiệu biến động dòng tiền (FUNDS)

5. Ví dụ đăng ký

Python (khuyến nghị)

cURL (kiểm tra nhanh)

6. Kết nối lại khi mất kết nối

7. Ví dụ phân tích nội dung

8. Tích hợp SDK (Python)

9. Mã lỗi