Hướng dẫn Xác thực

Tìm hiểu cách xác thực với Smart Money API bằng khóa API, token JWT và OAuth 2.0. Bảo mật tích hợp của bạn với các phương pháp xác thực tiêu chuẩn ngành và các phương pháp tốt nhất.

Tổng quan

Smart Money API hỗ trợ nhiều phương pháp xác thực cho các trường hợp sử dụng khác nhau. Chọn phương pháp phù hợp nhất với tích hợp của bạn:

Khóa API (chính): Gửi khóa của bạn trong X-API-Key tiêu đề yêu cầu cho tất cả các lệnh gọi REST API. Đây là phương pháp được khuyến nghị cho bot và sử dụng máy chủ đến máy chủ.

Phiên JWT (dự phòng): Phiên trình duyệt/bảng điều khiển xác thực bằng phiên JWT qua Authorization: Bearer, có hiệu lực trong 24 giờ. Các máy khách lập trình nên ưu tiên X-API-Key.

OAuth 2.0: Xác thực cấp doanh nghiệp cho các ứng dụng đa người dùng và tích hợp bên thứ ba. Người dùng ủy quyền cho ứng dụng của bạn truy cập dữ liệu của họ.

Tất cả các yêu cầu API phải được thực hiện qua HTTPS. Các yêu cầu HTTP không mã hóa sẽ bị từ chối. Ngoài ra, không bao giờ cam kết khóa API vào kiểm soát phiên bản hoặc chia sẻ chúng công khai.

Khóa API

Khóa API là thông tin xác thực duy nhất được cấp cho tài khoản của bạn. Mỗi khóa đại diện cho một tập hợp quyền và hạn ngạch. Bạn có thể tạo nhiều khóa cho các ứng dụng hoặc môi trường khác nhau (phát triển, staging, sản xuất).

Tạo Khóa API

Tạo khóa API từ bảng điều khiển tài khoản của bạn:

Điều hướng đến Smart Money Console
Chọn "Khóa API" từ thanh bên
Nhấp "Tạo Khóa Mới"
Chọn loại khóa (Phát triển, Staging, Sản xuất)
Đặt giới hạn tốc độ và tính năng
Sao chép và lưu trữ khóa một cách an toàn

Lưu khóa API của bạn ngay lập tức! Bạn sẽ không thể xem lại nó. Nếu bạn mất nó, bạn sẽ cần tạo một khóa mới.

Định dạng Khóa

Khóa API tuân theo định dạng tiêu chuẩn:

Định dạng Khóa

sk_live_4e3e4d0f1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z
sk_test_8f4g5h6i7j8k9l0m1n2o3p4q5r6s7t8u9v0w1x2y3z4a5b6c7d8e9f
sk_dev_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b

Tiền tố khóa chỉ định môi trường:

sk_live_ — Khóa sản xuất với hạn ngạch đầy đủ

sk_test_ — Khóa kiểm tra với hạn ngạch giảm và dữ liệu phát triển

sk_dev_ — Khóa phát triển cá nhân với dữ liệu sandbox

Tiêu đề X-API-Key (chính)

Gửi khóa API của bạn trong X-API-Key tiêu đề yêu cầu cho tất cả các yêu cầu API. Không bao giờ đặt khóa của bạn trong URL.

Tiêu đề HTTP

HTTP

GET /v1/whales/events HTTP/1.1
Host: api.smartmoneyapi.com
X-API-Key: sm_your_key
Content-Type: application/json

Ví dụ cURL

Shell

curl -X GET https://api.smartmoneyapi.com/v1/whales/events \
  -H "X-API-Key: sm_your_key" \
  -H "Content-Type: application/json"

Ví dụ Python

Python

import requests

api_key = "sm_your_key"
headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.smartmoneyapi.com/v1/whales/events",
    headers=headers
)

data = response.json()

Xác thực Token JWT

Đối với các phiên dài hạn và giao tiếp máy chủ đến máy chủ, trao đổi khóa API của bạn để lấy token JWT. Token JWT có hiệu lực trong 24 giờ và giảm nhu cầu lưu trữ khóa API trong mã ứng dụng.

Lấy Token JWT

POST khóa API của bạn đến điểm cuối JWT để lấy token:

cURL

curl -X POST https://api.smartmoneyapi.com/auth/jwt \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "sk_live_4e3e4d0f1b2c3d4e5f6g7h8i9j0k1l2m"
  }'

Phản hồi JWT

JSON

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE6MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Sử dụng Token JWT

Sử dụng token JWT trong tiêu đề Authorization giống như khóa API:

Python

import requests
import json
from datetime import datetime, timedelta

class JWTAuth:
    def __init__(self, api_key):
        self.api_key = api_key
        self.token = None
        self.token_expires = None

    def get_valid_token(self):
        # Kiểm tra xem token hiện tại còn hợp lệ không
        if self.token and self.token_expires > datetime.now():
            return self.token

        # Lấy token mới
        response = requests.post(
            "https://api.smartmoneyapi.com/auth/jwt",
            json={"api_key": self.api_key}
        )

        data = response.json()
        self.token = data["token"]
        self.token_expires = datetime.now() + timedelta(seconds=data["expires_in"])

        return self.token

    def request(self, method, url, **kwargs):
        token = self.get_valid_token()
        headers = kwargs.get("headers", {})
        headers["Authorization"] = f"Bearer {token}"
        kwargs["headers"] = headers

        return requests.request(method, url, **kwargs)

# Sử dụng
auth = JWTAuth("sk_live_4e3e4d0f1b2c3d4e5f6g7h8i9j0k1l2m")
response = auth.request(
    "GET",
    "https://api.smartmoneyapi.com/v1/whales/events"
)
print(response.json())

OAuth 2.0

OAuth 2.0 dành cho các ứng dụng cần truy cập nhiều tài khoản người dùng. Người dùng cấp quyền cho ứng dụng của bạn truy cập dữ liệu của họ mà không chia sẻ khóa API của họ.

Luồng OAuth 2.0

Smart Money API hỗ trợ luồng Authorization Code cho các ứng dụng web:

Người dùng nhấp vào nút "Kết nối với Smart Money"
Trình duyệt chuyển hướng đến trang ủy quyền
Người dùng cấp quyền cho ứng dụng của bạn
Trình duyệt chuyển hướng lại với mã ủy quyền
Backend của bạn trao đổi mã để lấy token truy cập
Bây giờ bạn có thể truy cập dữ liệu người dùng thay mặt họ

Bước 1: Yêu cầu Ủy quyền

Chuyển hướng người dùng đến điểm cuối ủy quyền:

URL

https://auth.smartmoneyapi.com/authorize?
client_id=YOUR_CLIENT_ID&
redirect_uri=https://yourapp.com/callback&
response_type=code&
scope=whale_positions+funding_rates+liquidations&
state=random_state_string

Bước 2: Trao đổi Token

Sau khi người dùng cấp quyền, trao đổi mã để lấy token truy cập:

cURL

curl -X POST https://auth.smartmoneyapi.com/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=AUTH_CODE&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&redirect_uri=https://yourapp.com/callback"

Phản hồi Token OAuth

JSON

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p",
  "scope": "whale_positions funding_rates liquidations"
}

Các phương pháp bảo mật tốt nhất

Lưu trữ Khóa An toàn

Không bao giờ cam kết khóa API vào kiểm soát phiên bản, mã hóa cứng chúng trong ứng dụng hoặc chia sẻ chúng trong tài liệu. Sử dụng biến môi trường hoặc dịch vụ quản lý khóa an toàn như AWS Secrets Manager, HashiCorp Vault hoặc tương tự.

Chỉ sử dụng HTTPS

Tất cả các yêu cầu API phải sử dụng HTTPS (TLS 1.2 trở lên). Các yêu cầu HTTP sẽ bị từ chối. Điều này đảm bảo khóa API và dữ liệu của bạn được mã hóa trong quá trình truyền tải.

Giới hạn Quyền Khóa

Tạo các khóa API riêng biệt cho các ứng dụng và môi trường khác nhau. Sử dụng phạm vi để giới hạn những gì mỗi khóa có thể truy cập. Không sử dụng khóa sản xuất trong phát triển.

Giám sát Sử dụng Khóa

Thường xuyên xem xét việc sử dụng API trong bảng điều khiển của bạn. Thiết lập cảnh báo cho các hoạt động bất thường hoặc hạn ngạch sắp đạt giới hạn. Xóa các khóa bạn không còn sử dụng.

Luân chuyển Khóa

Thường xuyên luân chuyển khóa API của bạn để giảm nguy cơ bị xâm phạm. Chúng tôi khuyến nghị luân chuyển khóa mỗi 90 ngày:

Tạo khóa API mới trong bảng điều khiển của bạn
Cập nhật ứng dụng của bạn để sử dụng khóa mới
Kiểm tra mọi thứ hoạt động chính xác
Xóa khóa cũ từ bảng điều khiển của bạn

Phạm vi & Quyền

Khi tạo khóa API hoặc sử dụng OAuth, hãy chỉ định tài nguyên mà khóa của bạn có thể truy cập:

Phạm vi	Mô tả	Cấp độ
whale_positions	Đọc vị thế ví cá voi	Trader+
funding_rates	Đọc dữ liệu tỷ lệ funding	Free+
liquidations	Đọc thông tin thanh lý	Free+
open_interest	Đọc dữ liệu open interest	Trader+
confirmation_scores	Đọc điểm xác nhận AI	Pro+
on_chain	Đọc chỉ số on-chain	Pro+

Ví dụ mã xác thực

Tích hợp Python hoàn chỉnh

Python

import requests
from typing import Optional, Dict
from datetime import datetime, timedelta

class SmartMoneyAuth:
    """Xử lý mọi phương thức xác thực cho Smart Money API"""

    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.smartmoneyapi.com"
        self.jwt_token = None
        self.jwt_expires = None

    def get_jwt_token(self) -> str:
        """Lấy hoặc làm mới token JWT"""
        if self.jwt_token and self.jwt_expires > datetime.now():
            return self.jwt_token

        response = requests.post(
            f"{self.base_url}/auth/jwt",
            json={"api_key": self.api_key}
        )
        data = response.json()
        self.jwt_token = data["token"]
        self.jwt_expires = datetime.now() + timedelta(seconds=data["expires_in"] - 300)
        return self.jwt_token

    def headers_bearer(self) -> Dict:
        """Lấy headers cho xác thực Bearer token"""
        return {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }

    def headers_jwt(self) -> Dict:
        """Lấy headers cho xác thực JWT"""
        token = self.get_jwt_token()
        return {
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json"
        }

    def request(self, method: str, endpoint: str, use_jwt: bool = False, **kwargs) -> Dict:
        """Thực hiện yêu cầu xác thực"""
        headers = self.headers_jwt() if use_jwt else self.headers_bearer()
        response = requests.request(
            method,
            f"{self.base_url}{endpoint}",
            headers=headers,
            **kwargs
        )
        return response.json()

# Cách dùng
auth = SmartMoneyAuth("sk_live_abc123xyz789")

# Phương thức Bearer token
whales = auth.request("GET", "/v1/whales/events?symbol=BTCUSDT")

# Phương thức JWT (tự động làm mới)
whales_jwt = auth.request("GET", "/v1/whales/events?symbol=BTCUSDT", use_jwt=True)

print(f"Found {whales['data']['total']} whale positions")

Cần trợ giúp?

Xem lại tài liệu API của chúng tôi hoặc liên hệ hỗ trợ nếu bạn cần trợ giúp về xác thực.

Tài liệu tham khảo API

Tạo khóa API đầu tiên của bạn

Bắt đầu với Smart Money API. Tạo tài khoản và tạo thông tin xác thực trong vài phút.

Truy cập bảng điều khiển