Giao dịch qua API

Vui lòng sử dụng hướng dẫn này nếu bạn đang tích hợp một nhà tạo lập thị trường, hệ thống báo giá hoặc dịch vụ khớp lệnh với Hypercall.

API production

REST base URL: https://api.hypercall.xyz

WebSocket URL: wss://api.hypercall.xyz/ws

Trạng thái testnet: testnet tạm thời bị tắt cho đến khi Hypercall có thêm HYPE testnet. Các tích hợp nhà tạo lập thị trường mới nên sử dụng production, trừ khi Hypercall cung cấp cho bạn một môi trường riêng.

Luồng dữ liệu theo danh sách cho phép

Luồng báo giá tham khảo (indicative quote-provider streaming) hiện chưa được mở rộng rãi. Hypercall có thể bật tính năng này cho các tích hợp đã được phê duyệt, nhưng quy trình tích hợp nhà tạo lập thị trường thông thường nên sử dụng dữ liệu thị trường qua REST cùng với các kênh WebSocket đã xác thực cho lệnh, khớp lệnh và danh mục.

Danh sách kiểm tra khi tích hợp

Ví giao dịch: ví EVM có khả năng ký dữ liệu có kiểu EIP-712.
Nạp vốn: nạp USDC trên production tại app.hypercall.xyz.
Quyền truy cập: vui lòng liên hệ Hypercall nếu bạn cần hạn mức dành cho nhà tạo lập thị trường hoặc luồng báo giá tham khảo.
Môi trường: các URL REST và WebSocket production ở trên. Không nên mặc định rằng testnet đang hoạt động.
Đối soát: tự lưu trữ client order ID, nonce, lệnh, khớp lệnh và snapshot vị thế của bạn.

Các phương thức tích hợp

TypeScript SDK

Cài đặt gói TypeScript chính thức để có REST client có kiểu, xác thực request lúc chạy và các hàm hỗ trợ ký EIP-712:

npm install @hypercallxyz/sdk

Xem hướng dẫn TypeScript SDK để biết cách đọc dữ liệu thị trường, truy vấn tài khoản, gửi thao tác ghi có chữ ký, xử lý lỗi và các entry point của gói. TypeScript SDK hiện hỗ trợ REST và ký. Để nhận cập nhật dạng streaming, vui lòng kết nối trực tiếp với WebSocket API.

Rust Crates

Hypercall phát hành các Rust crate công khai cho phạm vi tích hợp được hỗ trợ tại github.com/hypercall-public/hypercall-rust. Các crate này không có trên crates.io. Vui lòng thêm chúng dưới dạng git dependency và ghim theo tag hoặc commit.

Crate	Mục đích sử dụng
`hypercall-client`	REST client, WebSocket client, hàm hỗ trợ ký EIP-712, ký cục bộ và ký qua AWS KMS
`hypercall-sdk-types`	Các DTO request và response công khai dùng chung với client
`hypercall-ws-protocol`	Các kiểu message WebSocket công khai
`hypercall-hyperliquid`	Crate hỗ trợ Hyperliquid tùy chọn, dành cho các tích hợp đồng thời phòng hộ trên Hyperliquid
`hypercall-liquidator`	Client tham chiếu cho thanh lý Standard Margin. Không bắt buộc đối với hoạt động tạo lập thị trường thông thường

Nên sử dụng các crate này khi có thể. Chúng đã mã hóa sẵn signing domain hiện tại, cấu trúc request, quy tắc route và quy tắc định dạng chuỗi, vốn là những phần dễ sai khi tự viết tay.

REST và WebSocket thuần

Nếu bạn không dùng Rust, vui lòng xem các trang API Reference, Xác thực & Ký và WebSocket API làm nguồn tham chiếu chính thức.

1. Khám phá thị trường

Bắt đầu bằng việc tải các thị trường đang hoạt động và thông số công cụ:

curl https://api.hypercall.xyz/markets
curl "https://api.hypercall.xyz/instrument-specs?currency=BTC"
curl "https://api.hypercall.xyz/options-summary?currency=BTC"

Sử dụng:

GET /markets để lấy các nhóm tài sản cơ sở và ngày đáo hạn đang niêm yết.
GET /instrument-specs?currency=BTC để lấy thông số các quyền chọn có thể giao dịch.
GET /options-summary?currency=BTC để lấy các trường tóm tắt cấp chuỗi quyền chọn như giá mua tốt nhất, giá bán tốt nhất, giá mark và các chỉ số Greeks.

2. Thiết lập ký

Các thao tác ghi sử dụng chữ ký EIP-712.

Chain ID production: 999
Domain name: Hypercall
Domain version: 1
Verifying contract: 0x0000000000000000000000000000000000000000

Nhà tạo lập thị trường thường nên sử dụng ví agent:

Ví chủ sở hữu phê duyệt một agent bằng POST /approve-agent.
Ví agent ký lệnh và hủy lệnh thay cho ví chủ sở hữu.
Ví chủ sở hữu vẫn là danh tính của danh mục, nguồn vốn và rủi ro.

Xem Xác thực & Ký để biết chính xác các struct và tên trường.

3. Báo giá bằng lệnh hàng loạt

Đối với báo giá của nhà tạo lập thị trường, vui lòng sử dụng POST /bulk_order với route: "book_only".

curl -X POST https://api.hypercall.xyz/bulk_order \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [
      {
        "wallet": "0x...",
        "symbol": "BTC-20260131-100000-C",
        "price": "100.0",
        "size": "0.1",
        "side": "Buy",
        "tif": "gtc",
        "route": "book_only",
        "client_id": "mm-bid-1",
        "mmp_enabled": true,
        "nonce": 1791273600000,
        "signature": "0x..."
      },
      {
        "wallet": "0x...",
        "symbol": "BTC-20260131-100000-C",
        "price": "101.0",
        "size": "0.1",
        "side": "Sell",
        "tif": "gtc",
        "route": "book_only",
        "client_id": "mm-ask-1",
        "mmp_enabled": true,
        "nonce": 1791273600001,
        "signature": "0x..."
      }
    ]
  }'

Các quy tắc quan trọng:

price và size là chuỗi trong cả payload được ký và JSON body.
Định dạng chuỗi phải khớp chính xác giữa chữ ký và JSON body.
Mỗi request lệnh hàng loạt tối đa 50 lệnh.
Route của lệnh hàng loạt chỉ vào sổ lệnh. route có thể là book_only hoặc bỏ trống. route: "best_execution" bị từ chối với lệnh hàng loạt; hãy dùng POST /order cho route này. route: "rfq_only" hiện bị từ chối trên mọi endpoint đặt lệnh.
Nonce là timestamp tính bằng mili giây. Nonce nằm ngoài khoảng từ hai ngày trước đến một ngày sau thời gian máy chủ sẽ bị từ chối. Xem Quản lý nonce.
Phần lớn các lệnh bị từ chối vẫn trả về HTTP 200 với status: "REJECTED". Luôn kiểm tra từng kết quả.

4. Làm mới báo giá

Sử dụng PUT /bulk_order khi bạn muốn hủy các lệnh báo giá hiện có và đặt lệnh thay thế trong cùng một request.

curl -X PUT https://api.hypercall.xyz/bulk_order \
  -H "Content-Type: application/json" \
  -d '{
    "replacements": [
      {
        "wallet": "0x...",
        "order_id": 12345,
        "symbol": "BTC-20260131-100000-C",
        "price": "99.5",
        "size": "0.1",
        "side": "Buy",
        "tif": "gtc",
        "client_id": "mm-bid-1",
        "mmp_enabled": true,
        "nonce": 1791273600002,
        "signature": "0x..."
      }
    ]
  }'

Lệnh thay thế không có trường route và được ký dưới dạng ReplaceOrder, trong đó bổ sung orderId cũ vào các trường của lệnh. Xem Xác thực & Ký.

PUT /bulk_order hủy lô cũ trước khi tạo lô mới. Kết quả được trả về cho từng lệnh thay thế theo thứ tự trong request. Nếu hủy thất bại, lệnh thay thế tương ứng sẽ không được tạo.

Với một lệnh thay thế đơn lẻ nhạy cảm về độ trễ, vui lòng sử dụng PUT /order.

5. Đăng ký nhận cập nhật

Kết nối với WebSocket production:

const ws = new WebSocket("wss://api.hypercall.xyz/ws");

ws.onopen = () => {
  ws.send(JSON.stringify({ type: "Authenticate", wallet: "0xYourWallet" }));
  ws.send(JSON.stringify({ type: "Subscribe", channel: "order_updates" }));
  ws.send(JSON.stringify({ type: "Subscribe", channel: "fills" }));
  ws.send(JSON.stringify({ type: "Subscribe", channel: "portfolio" }));
};

Sử dụng:

order_updates cho các thay đổi trạng thái lệnh, bao gồm PARTIALLY_FILLED. Trường filled_size là tổng khối lượng đã khớp lũy kế của lệnh.
fills cho từng lần khớp lệnh riêng lẻ và khối lượng của mỗi lần khớp.
portfolio cho các cập nhật trạng thái tài khoản.
orderbook, trades, options_chain và index_prices cho dữ liệu thị trường công khai.

Xem WebSocket API để biết định dạng các kênh và cơ chế kiểm tra kết nối.

6. Đối soát trạng thái

Hãy chạy vòng lặp đối soát ngay cả khi kết nối WebSocket của bạn đang ổn định.

Trạng thái	REST dự phòng	Kênh WebSocket
Lệnh	`GET /orders?wallet=...`	`order_updates`
Khớp lệnh	`GET /fills?wallet=...`	`fills`
Danh mục	`GET /portfolio?wallet=...`	`portfolio`
Thị trường	`GET /markets`, `GET /instrument-specs`	`market_updates`, `options_chain`

Vòng lặp khuyến nghị:

Tải thị trường khi khởi động.
Tải các lệnh đang mở và các lần khớp gần nhất trước khi báo giá.
Đăng ký nhận cập nhật WebSocket.
Báo giá với client ID xác định (deterministic).
Định kỳ truy vấn REST để khôi phục sau khi mất kết nối hoặc bỏ lỡ message.
Dừng báo giá khi trạng thái không xác định cho đến khi trạng thái REST và WebSocket khớp nhau trở lại.

7. Hiểu phạm vi ra mắt

Mainnet Alpha được giới hạn có chủ đích.

Ký quỹ: cả Standard Margin và Portfolio Margin đều đã hoạt động. Bất kỳ Account nào cũng có thể chuyển sang Portfolio Margin khi tài khoản HyperCore của Account đó ở chế độ unified.
Vị thế bán quyền chọn: vị thế bán (short) quyền chọn trong Standard Margin đã được bật, tùy thuộc vào ký quỹ và hạn mức theo cấp (tier) của bạn. Kiểm tra GET /risk/limits?wallet=... để xem standard_margin_shorts_enabled.
Perp: lệnh perp sử dụng signing domain và endpoint riêng. Xem Xác thực & Ký.
Luồng báo giá tham khảo: các luồng quote-provider chỉ dành cho danh sách cho phép và chưa phải là phương thức tích hợp công khai chung.
Công cụ thanh lý: crate liquidator công khai dành cho quy trình thanh lý Standard Margin, không dành cho hoạt động tạo lập thị trường thông thường.
Testnet: không khả dụng cho đến khi Hypercall có thêm HYPE testnet.

Các vấn đề thường gặp

Xác minh chữ ký thất bại

Kiểm tra rằng price và size là chuỗi JSON.
Kiểm tra rằng các chuỗi được ký khớp chính xác với các chuỗi được gửi.
Sử dụng chain ID 999 cho production.
Sử dụng nonce mới cho mỗi thao tác ghi có chữ ký.
Xác nhận người ký là chính ví đó hoặc một agent đã được phê duyệt.

Không đủ ký quỹ

Kiểm tra GET /portfolio?wallet=....
Nạp thêm tài sản thế chấp hoặc giảm khối lượng báo giá.
Xác nhận ví của bạn có cấp truy cập cần thiết cho chiến lược bạn đang báo giá.

Lệnh bán bị từ chối do quyền truy cập hoặc yêu cầu bảo chứng

Kiểm tra GET /risk/limits?wallet=.... Một số cấp chỉ cho phép lệnh bán được bảo chứng bởi vị thế mua (long) đã khớp.
Vui lòng liên hệ Hypercall nếu ví của bạn cần một cấp khác.

Không nhận được khớp lệnh qua WebSocket

Gửi message Authenticate trước khi đăng ký các kênh cần xác thực.
Đăng ký kênh fills, không chỉ order_updates.
Chuyển sang dùng GET /fills?wallet=... sau khi kết nối lại.

Bước tiếp theo

Xác thực: Xác thực & Ký
Giao thức WebSocket: WebSocket API
Giới hạn tốc độ: Giới hạn tốc độ
Lỗi: Lỗi & Lý do từ chối
Tham chiếu: API Reference

Danh sách kiểm tra khi tích hợp​

Các phương thức tích hợp​

TypeScript SDK​

Rust Crates​

REST và WebSocket thuần​

1. Khám phá thị trường​

2. Thiết lập ký​

3. Báo giá bằng lệnh hàng loạt​

4. Làm mới báo giá​

5. Đăng ký nhận cập nhật​

6. Đối soát trạng thái​

7. Hiểu phạm vi ra mắt​

Các vấn đề thường gặp​

Xác minh chữ ký thất bại​

Không đủ ký quỹ​

Lệnh bán bị từ chối do quyền truy cập hoặc yêu cầu bảo chứng​

Không nhận được khớp lệnh qua WebSocket​

Bước tiếp theo​