Hướng Dẫn Sử Dụng Kalshi API: Thị Trường Dự Đoán

Điều gì sẽ xảy ra nếu bạn có thể sử dụng các API cấp tổ chức trên một sàn giao dịch được CFTC quản lý để giao dịch thị trường dự đoán theo chương trình? Cung cấp các giao diện REST, WebSocket và FIX 4.4 cho thị trường dự đoán được liên bang ủy quyền đầu tiên tại Hoa Kỳ, Kalshi đã làm được điều đó. Chỉ riêng trong nửa đầu năm 2025, công ty đã tạo ra doanh thu hơn 200 triệu đô la.

Các thị trường dự đoán đã bùng nổ về mức độ phổ biến, nhưng các nhà phát triển phải đối mặt với sự lựa chọn giữa cơ sở hạ tầng được quy định và sự linh hoạt của tiền điện tử. Các nền tảng không được quản lý hoạt động trong các vùng xám pháp lý, yêu cầu ví blockchain và khiến người dùng gặp rủi ro hợp đồng thông minh. Kalshi loại bỏ những điểm khó khăn này bằng cách hoạt động như một Thị trường Hợp đồng được Chỉ định dưới sự giám sát của CFTC, cung cấp thanh toán dựa trên tiền pháp định, các mẫu API truyền thống và tuân thủ các quy định tài chính của Hoa Kỳ. Bạn xây dựng các ứng dụng giao dịch mà các tổ chức thực sự có thể sử dụng.

Mục lục:

Hiểu về Kiến trúc của Kalshi
Xác thực và Thiết lập
Các Điểm cuối API Cốt lõi
Dữ liệu Thời gian thực với WebSocket
Kalshi so với Polymarket dành cho Nhà phát triển
Kết luận

💡

Xây dựng tích hợp thị trường dự đoán đòi hỏi phải kiểm thử API đáng tin cậy trên các giao thức REST, WebSocket và FIX. Apidog cung cấp kiểm thử API trực quan, tạo tài liệu tự động và các tính năng cộng tác nhóm được thiết kế đặc biệt cho các ứng dụng giao dịch tài chính. Hãy dùng thử Apidog miễn phí để tối ưu hóa việc phát triển API Kalshi của bạn—không cần thẻ tín dụng.

button

Hiểu về Kiến trúc của Kalshi

Kalshi hoạt động như một sàn giao dịch tập trung với các hợp đồng sự kiện tự chứng nhận. Việc hiểu kiến trúc này giúp bạn thiết kế các tích hợp mạnh mẽ.

Tình trạng Thị trường Hợp đồng Được Chỉ định

Kalshi nắm giữ giấy phép CFTC cho phép nó cung cấp hợp đồng sự kiện hợp pháp trên tất cả 50 tiểu bang Hoa Kỳ. Không giống như cá cược thể thao do tiểu bang quản lý, Kalshi hoạt động dưới quyền tài phán liên bang, bỏ qua mớ hỗn độn các luật cờ bạc của tiểu bang. Tình trạng này yêu cầu tuân thủ nghiêm ngặt: mọi thị trường đều trải qua đánh giá của CFTC, thanh toán tuân theo các quy tắc đã công bố và sàn giao dịch duy trì hệ thống giám sát để phát hiện thao túng.

Sổ lệnh giới hạn trung tâm (CLOB)

Kalshi khớp lệnh thông qua một CLOB truyền thống—lệnh mua và lệnh bán gặp nhau ở các mức giá cụ thể với độ sâu hiển thị. Điều này khác với các nhà tạo lập thị trường tự động (AMM) được sử dụng bởi các sàn giao dịch phi tập trung. CLOB cung cấp sự minh bạch về giá, cho phép đặt lệnh giới hạn và cho phép các chiến lược tạo lập thị trường. Các nhà tạo lập thị trường nhận được khoảng 35.000 đô la hàng ngày dưới dạng ưu đãi thanh khoản (hàng năm khoảng 12,7 triệu đô la), đảm bảo chênh lệch giá mua-bán thấp ngay cả trong các thị trường ít hoạt động.

Cấu trúc Hợp đồng Sự kiện

Mỗi hợp đồng đại diện cho một kết quả nhị phân: Có trả $1,00, Không trả $0,00. Giá dao động từ $0,01 đến $0,99, phản ánh xác suất ngụ ý của thị trường. Một hợp đồng giao dịch ở mức $0,63 ngụ ý 63% khả năng sự kiện xảy ra. Thanh toán xảy ra ở mức $1,00 hoặc $0,00 sau khi xác minh kết quả.

Các hợp đồng chỉ định các điều kiện thanh toán chính xác: định nghĩa sự kiện, nguồn dữ liệu có thẩm quyền và phương pháp giải quyết. Ví dụ, một hợp đồng "Liệu CPI có vượt quá 3,5% vào tháng Giêng không?" sẽ chỉ rõ bản phát hành của Cục Thống kê Lao động và cách giải thích các điều chỉnh theo mùa.

Oracle và Thanh toán

Kalshi sử dụng một oracle tập trung do nhân viên sàn giao dịch vận hành. Kết quả được giải quyết dựa trên các nguồn chính thức—báo cáo của chính phủ, nhà cung cấp dữ liệu uy tín hoặc các tổ chức tin tức đã được thành lập. Việc giải quyết thường hoàn tất trong vòng vài giờ sau khi sự kiện kết thúc. Mô hình tập trung này ưu tiên tốc độ và sự rõ ràng hơn là phi tập trung, với sự giám sát của CFTC đảm bảo trách nhiệm giải trình.

Xác thực và Thiết lập

Xác thực của Kalshi yêu cầu các yêu cầu được ký bằng RSA sử dụng khóa riêng được tạo trong bảng điều khiển tài khoản của bạn. Điều này cung cấp xác minh mật mã cho các lệnh gọi API.

Thiết lập Môi trường

Kalshi cung cấp hai môi trường:

Demo: https://demo-api.kalshi.co/v1 — Thử nghiệm với tiền ảo
Sản phẩm (Production): https://api.kalshi.com/v1 — Giao dịch thực với USD

Luôn phát triển với môi trường demo trước. Các môi trường này giống hệt nhau về chức năng, nhưng thị trường demo có thể có thanh khoản mô phỏng.

Tạo Khóa API

Điều hướng đến Cài đặt → API trong bảng điều khiển Kalshi của bạn. Tạo một cặp khóa mới:

Nhấp vào "Tạo Khóa API"
Lưu trữ ID Khóa API (bắt đầu bằng kalshi_prod_ hoặc kalshi_demo_)
Tải xuống khóa riêng ngay lập tức—Kalshi sẽ không bao giờ hiển thị lại khóa này
Bảo mật khóa riêng bằng quyền truy cập tệp (chmod 600)

Khóa riêng sử dụng ký RSA-PSS. Kalshi cung cấp các SDK chính thức xử lý việc ký tự động, hoặc bạn có thể tự thực hiện thủ công bằng cách sử dụng các thư viện mật mã tiêu chuẩn.

Cài đặt SDK

Kalshi cung cấp các SDK chính thức cho Python (đồng bộ và bất đồng bộ) và TypeScript:

# Python synchronous
pip install kalshi-python-sync

# Python asynchronous
pip install kalshi-python-async

# TypeScript/Node.js
npm install @kalshi/sdk

Các SDK cộng đồng tồn tại cho Go và các ngôn ngữ khác, nhưng các SDK chính thức cung cấp các triển khai ký đáng tin cậy nhất và an toàn kiểu (type safety).

Xác thực thủ công (Không dùng SDK)

Nếu triển khai ký tùy chỉnh, hãy làm theo quy trình này:

import requests
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
import base64
import json
from datetime import datetime, timezone

class KalshiAuth:
    def __init__(self, api_key_id, private_key_path):
        self.api_key_id = api_key_id
        with open(private_key_path, "rb") as key_file:
            self.private_key = serialization.load_pem_private_key(
                key_file.read(),
                password=None
            )
        self.base_url = "https://api.kalshi.com/v1"

    def sign_request(self, method, path, body=None):
        # Create timestamp
        timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")[:-3] + "Z"

        # Build string to sign
        string_to_sign = f"{timestamp}{method}{path}"
        if body:
            string_to_sign += json.dumps(body, separators=(',', ':'))

        # Sign with RSA-PSS
        signature = self.private_key.sign(
            string_to_sign.encode('utf-8'),
            padding.PSS(mgf=padding.MGF1(hashes.SHA256()), salt_length=32),
            hashes.SHA256()
        )

        return {
            "KALSHI-ACCESS-KEY": self.api_key_id,
            "KALSHI-ACCESS-TIMESTAMP": timestamp,
            "KALSHI-ACCESS-SIGNATURE": base64.b64encode(signature).decode('utf-8'),
            "Content-Type": "application/json"
        }

    def request(self, method, path, body=None):
        url = f"{self.base_url}{path}"
        headers = self.sign_request(method, path, body)

        if method == "GET":
            response = requests.get(url, headers=headers)
        elif method == "POST":
            response = requests.post(url, headers=headers, json=body)
        elif method == "DELETE":
            response = requests.delete(url, headers=headers)

        return response.json()

# Usage
kalshi = KalshiAuth(
    api_key_id="kalshi_prod_abc123",
    private_key_path="~/.kalshi/private_key.pem"
)

# Get markets
markets = kalshi.request("GET", "/markets")
print(markets)

Chuỗi ký kết hợp dấu thời gian, phương thức HTTP, đường dẫn và nội dung JSON (nếu có). RSA-PSS với SHA-256 cung cấp xác minh mật mã rằng các yêu cầu bắt nguồn từ tài khoản của bạn.

Phiên dựa trên Mã thông báo (Token)

# Login to get session token
login_response = kalshi.request("POST", "/log_in")
session_token = login_response["token"]

# Use token for subsequent requests (valid for 30 minutes)
headers = {
    "Authorization": f"Bearer {session_token}",
    "Content-Type": "application/json"
}

Các mã thông báo hết hạn sau mỗi 30 phút. Triển khai logic làm mới tự động trước khi hết hạn để duy trì các phiên liên tục.

Mẹo chuyên nghiệpApidog

Các Điểm cuối API Cốt lõi

API REST của Kalshi tuân theo các quy ước tiêu chuẩn với cấu trúc điểm cuối logic theo loại tài nguyên.

Dữ liệu Thị trường (Công khai)

Truy xuất các thị trường có sẵn:

curl "https://api.kalshi.com/v1/markets" \
  -H "Content-Type: application/json"

Nhận chi tiết thị trường cụ thể:

curl "https://api.kalshi.com/v1/markets/INXCHI-25JAN31-T69.5" \
  -H "Content-Type: application/json"

Định dạng mã cổ phiếu (ticker) mã hóa chi tiết hợp đồng: INXCHI-25JAN31-T69.5 đại diện cho một thị trường Chỉ số Hoạt động Quốc gia Fed Chicago/Lạm phát hết hạn vào ngày 31 tháng 1 năm 2025, với ngưỡng là 69,5.

Truy vấn độ sâu sổ lệnh:

curl "https://api.kalshi.com/v1/markets/INXCHI-25JAN31-T69.5/orderbook" \
  -H "Content-Type: application/json"

Phản hồi trả về các mức giá mua và bán với số lượng, cho phép bạn đánh giá thanh khoản trước khi đặt lệnh.

MẹoApidog

Các Hoạt động Giao dịch (Đã xác thực)

Đặt lệnh mua:

order = kalshi.request("POST", "/orders", {
    "market_id": "INXCHI-25JAN31-T69.5",
    "side": "yes",
    "order_type": "limit",
    "price": 6500,  # $0.65 in cents
    "quantity": 100,  # Number of contracts
    "client_order_id": "my-strategy-001"  # Optional tracking ID
})

Giá của Kalshi được tính bằng xu (1 = $0,01). Lệnh giới hạn ở mức 6500 sẽ được thực hiện ở mức $0,65 hoặc tốt hơn.

Hủy một lệnh mở:

kalshi.request("DELETE", f"/orders/{order['id']}")

Liệt kê các lệnh mở của bạn:

curl "https://api.kalshi.com/v1/orders" \
  -H "Authorization: Bearer $SESSION_TOKEN"

Danh mục và Tài khoản

Kiểm tra số dư tài khoản:

curl "https://api.kalshi.com/v1/portfolio/balance" \
  -H "Authorization: Bearer $SESSION_TOKEN"

Truy xuất vị thế:

curl "https://api.kalshi.com/v1/portfolio/positions" \
  -H "Authorization: Bearer $SESSION_TOKEN"

Điểm cuối vị thế trả về các khoản nắm giữ hiện tại của bạn trên tất cả các thị trường, bao gồm P&L chưa thực hiện dựa trên giá giao dịch cuối cùng.

Lấy lịch sử giao dịch:

curl "https://api.kalshi.com/v1/portfolio/fills" \
  -H "Authorization: Bearer $SESSION_TOKEN"

Các lệnh khớp bao gồm các lệnh đã thực hiện với dấu thời gian, giá cả và phí đã trả.

Thanh toán và Giải quyết

Truy vấn trạng thái thanh toán cho các thị trường đã hết hạn:

curl "https://api.kalshi.com/v1/markets/INXCHI-25JAN31-T69.5/settlement" \
  -H "Authorization: Bearer $SESSION_TOKEN"

Sau khi giải quyết, các hợp đồng thắng sẽ ghi $1,00 cho mỗi cổ phiếu vào tài khoản của bạn; các vị thế thua sẽ thanh toán ở mức $0,00.

Dữ liệu Thời gian thực với WebSocket

Việc truy vấn REST gây ra độ trễ. API WebSocket của Kalshi truyền các cập nhật sổ lệnh, thực hiện giao dịch và thay đổi trạng thái thị trường theo thời gian thực.

Kết nối với WebSocket

const WebSocket = require('ws');

const ws = new WebSocket('wss://api.kalshi.com/v1/ws', {
  headers: {
    'Authorization': `Bearer ${sessionToken}`
  }
});

ws.on('open', () => {
  console.log('Connected to Kalshi WebSocket');

  // Subscribe to order book updates for specific market
  ws.send(JSON.stringify({
    type: 'subscribe',
    channels: ['orderbook:INXCHI-25JAN31-T69.5']
  }));
});

ws.on('message', (data) => {
  const message = JSON.parse(data);

  switch(message.type) {
    case 'orderbook_update':
      console.log('Order book changed:', message.data);
      break;
    case 'trade':
      console.log('Trade executed:', message.data);
      break;
    case 'market_status':
      console.log('Market status:', message.data);
      break;
  }
});

// Heartbeat to maintain connection
setInterval(() => {
  ws.send(JSON.stringify({ type: 'ping' }));
}, 30000);

Kết nối WebSocket yêu cầu các tín hiệu nhịp tim định kỳ (mỗi 30 giây) để ngăn chặn hết thời gian chờ. Triển khai logic kết nối lại tự động cho các ứng dụng sản xuất.

Các Kênh Đăng ký

Các kênh có sẵn bao gồm:

orderbook:{market_id} — Cập nhật giá mua/bán
trades:{market_id} — Các giao dịch gần đây
market_status:{market_id} — Tạm dừng giao dịch, thanh toán
user_orders — Thay đổi trạng thái lệnh của bạn
user_fills — Các giao dịch đã thực hiện của bạn

Đăng ký nhiều kênh trong một thông báo duy nhất để truyền dữ liệu hiệu quả.

Apidog

button

Kalshi so với Polymarket dành cho Nhà phát triển

Cả hai nền tảng đều cung cấp API thị trường dự đoán, nhưng kiến trúc của chúng phục vụ các trường hợp sử dụng khác nhau.

Tình trạng Quy định

Kalshi hoạt động như một Thị trường Hợp đồng được Chỉ định được CFTC quản lý. Điều này cung cấp sự rõ ràng pháp lý cho người dùng Hoa Kỳ nhưng yêu cầu tuân thủ KYC/AML và hạn chế quyền truy cập ở 42 tiểu bang (trừ Arizona, Illinois, Massachusetts, Maryland, Michigan, Montana, New Jersey, Ohio).

Polymarket gần đây đã nhận được sự chấp thuận của CFTC thông qua việc mua lại QCX LLC và nắm giữ giấy phép DCM kèm theo Thư không hành động (No-Action Letter). Hiện tại, nó hoạt động quốc tế với khả năng truy cập hạn chế tại Hoa Kỳ trong khi chờ triển khai đầy đủ. Trước đây đã bị phạt 1,4 triệu đô la vì hoạt động mà không đăng ký (tháng 1 năm 2022).

Kiến trúc Kỹ thuật

Kalshi sử dụng cơ sở hạ tầng tập trung với khớp lệnh ngoài chuỗi và thanh toán USD tiền pháp định. Truy cập API tuân theo các mẫu truyền thống: REST qua HTTPS, WebSocket để truyền dữ liệu, FIX 4.4 để giao dịch tổ chức. Thời gian phản hồi được đo bằng mili giây.

Polymarket hoạt động trên blockchain Polygon với kiến trúc CLOB lai—khớp lệnh ngoài chuỗi, thanh toán trên chuỗi qua Khung mã thông báo có điều kiện (Conditional Tokens Framework). Việc tích hợp yêu cầu tương tác blockchain: các lệnh được ký EIP-712, lệnh gọi hợp đồng thông minh, giao dịch USDC. Việc hoàn tất thanh toán yêu cầu xác nhận blockchain (từ vài giây đến vài phút).

Các Mô hình Xác thực

Kalshi sử dụng các yêu cầu được ký bằng RSA-PSS với khóa API, các phiên dựa trên mã thông báo hết hạn sau mỗi 30 phút. Yêu cầu lưu trữ khóa riêng an toàn và ký mật mã.

Polymarket sử dụng chữ ký ví blockchain (MetaMask, WalletConnect). Người dùng ký lệnh bằng khóa riêng kiểm soát địa chỉ Polygon của họ. Không có mã thông báo phiên—mỗi giao dịch yêu cầu chữ ký mới.

Tiền tệ Thanh toán

Kalshi thanh toán bằng USD qua chuyển khoản ngân hàng, ACH, thẻ ghi nợ, PayPal, Apple Pay, Google Pay. Rút tiền tối thiểu thường là $10. Thời gian xử lý 1-3 ngày làm việc đối với ACH, nhanh hơn đối với chuyển khoản.

Polymarket thanh toán bằng USDC trên blockchain Polygon. Thanh toán tức thì sau khi giải quyết, nhưng yêu cầu ví tiền điện tử và cơ sở hạ tầng on-ramp/off-ramp. Áp dụng phí gas cho việc rút tiền.

Các Giao thức API

Kalshi cung cấp ba giao thức:

REST: HTTP tiêu chuẩn cho tất cả các hoạt động
WebSocket: Truyền dữ liệu thời gian thực cho dữ liệu thị trường và cập nhật lệnh
FIX 4.4: Giao thức tiêu chuẩn ngành cho giao dịch tần suất cao của tổ chức

Polymarket yêu cầu:

GraphQL: Truy vấn linh hoạt cho dữ liệu blockchain
EIP-712: Ký dữ liệu đã định kiểu cho các lệnh
Lệnh gọi Hợp đồng thông minh: Tương tác blockchain trực tiếp để thanh toán

Khuyến nghị Trường hợp sử dụng

Chọn Kalshi cho:

Các bàn giao dịch tổ chức yêu cầu tuân thủ quy định
Các ứng dụng phục vụ người dùng bán lẻ Hoa Kỳ
Các cổng vào/ra tiền pháp định không phức tạp về tiền điện tử
Giao dịch thuật toán độ trễ thấp
Tích hợp tài chính truyền thống

Chọn Polymarket cho:

Các giao thức DeFi yêu cầu khả năng kết hợp hợp đồng thông minh
Người dùng toàn cầu bên ngoài các khu vực pháp lý của Hoa Kỳ
Các ứng dụng tiền điện tử có cơ sở hạ tầng ví hiện có
Tạo thị trường nhanh chóng (vài giờ so với vài ngày để phê duyệt)
Xác minh và minh bạch trên chuỗi

Độ phức tạp tích hợp

Tích hợp Kalshi yêu cầu 2-4 tuần cho dữ liệu thị trường cơ bản và chức năng giao dịch, giả sử có kinh nghiệm về API REST. Các mẫu HTTP quen thuộc giúp giảm đường cong học tập.

Tích hợp Polymarket yêu cầu 3-6 tháng cho các thị trường hợp đồng thông minh sẵn sàng sản xuất, bao gồm kiểm toán bảo mật (ngân sách 50K-200K đô la), tích hợp oracle và khởi tạo thanh khoản. Kiến thức chuyên môn về Blockchain là bắt buộc.

Cấu trúc Chi phí

Kalshi tính phí giao dịch dựa trên lợi nhuận dự kiến (0,7-3,5%, trung bình 0,8%). Truy cập API miễn phí—bạn chỉ trả phí giao dịch. Không có phí rút tiền cho ACH.

Polymarket tính phí người nhận 0,01% trên các thị trường cốt lõi, cùng với phí gas cho các giao dịch blockchain. Không có phí trên một số thị trường, nhưng áp dụng chi phí mạng.

Kết luận

API của Kalshi cung cấp quyền truy cập được quản lý vào các thị trường dự đoán thông qua các giao thức REST và WebSocket quen thuộc. Bạn xác thực bằng các yêu cầu được ký bằng RSA, giao dịch hợp đồng sự kiện qua sổ lệnh giới hạn trung tâm và thanh toán bằng USD thông qua ngân hàng truyền thống. Sự giám sát của CFTC đảm bảo tuân thủ pháp luật cho các ứng dụng tại Hoa Kỳ, trong khi doanh thu ước tính 200 triệu đô la cho thấy khả năng tồn tại của tổ chức.

Bắt đầu với môi trường demo để kiểm thử các mẫu tích hợp. Triển khai quản lý khóa và ký yêu cầu đúng cách trước khi chuyển sang môi trường sản phẩm. Sử dụng truyền dữ liệu WebSocket cho các ứng dụng thời gian thực yêu cầu độ trễ thấp. Theo dõi việc hết hạn mã thông báo sau 30 phút và triển khai logic làm mới để hoạt động liên tục.

Bắt đầu với Apidog ngay hôm nay—nhập các điểm cuối API Kalshi của bạn trong vài giây và bắt đầu kiểm thử các chiến lược thị trường dự đoán của bạn mà không cần cấu hình.

button