Giao dịch qua API

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ụ thực thi lệnh với Hypercall.

API Production

URL gốc REST: https://api.hypercall.xyz

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

Trạng thái testnet: testnet tạm thời bị vô hiệu hóa 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 cấp cho bạn một môi trường riêng.

Luồng dữ liệu được cấp phép

Streaming báo giá chỉ định (indicative quote-provider) chưa được cung cấp rộng rãi. Hypercall có thể kích hoạt tính năng này cho các tích hợp đã được phê duyệt, nhưng quy trình onboarding 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 Onboarding

Ví giao dịch: ví EVM có khả năng ký dữ liệu typed data theo chuẩn EIP-712.
Nạp vốn: nạp USDC production tại app.hypercall.xyz.
Quyền truy cập: liên hệ Hypercall nếu bạn cần hạn mức nhà tạo lập thị trường, quyền writer, hoặc streaming báo giá chỉ định.
Môi trường: các URL REST và WebSocket production ở trên. Không mặc định rằng testnet khả dụng.
Đối soát: lưu trữ riêng các client order ID, nonce, lệnh, khớp lệnh và snapshot vị thế của bạn.

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

Rust Crates

Hypercall công bố các Rust crate công khai cho bề mặt tích hợp được hỗ trợ:

Repository Rust công khai là github.com/hypercall-public/hypercall-rust.

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

Hãy 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 — những thứ rất dễ sai nếu làm thủ công.

REST và WebSocket thuần

Nếu bạn không sử dụng Rust, hãy dùng các trang API Reference, Authentication & Signing, 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ố kỹ thuật của các 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 cho các nhóm tài sản cơ sở và ngày đáo hạn được niêm yết.
GET /instrument-specs?currency=BTC cho thông số của các quyền chọn có thể giao dịch.
GET /options-summary?currency=BTC cho các trường tổng hợp ở cấp độ chain gồm giá mua tốt nhất, giá bán tốt nhất, giá mark và các chỉ số kiểu Greeks.

2. Thiết lập ký

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

Chain ID production: 999
Tên domain: Hypercall
Phiên bản domain: 1
Verifying contract: 0x0000000000000000000000000000000000000000

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

Ví owner phê duyệt một agent bằng POST /approve-agent.
Ví agent ký lệnh và hủy lệnh thay cho ví owner.
Ví owner vẫn là danh tính về danh mục, vốn và rủi ro.

Xem Authentication & Signing để 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 (Bulk Orders)

Đối với báo giá của nhà tạo lập thị trườ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": 1001,
        "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": 1002,
        "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.
Kích thước bulk order giới hạn tối đa 50 lệnh mỗi request.
Route bulk chỉ dành cho sổ lệnh (book-only). route: "best_execution" và route: "rfq_only" là các đường dẫn cho lệnh đơn, không phải đường dẫn báo giá hàng loạt.
Hầu hết 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",
        "route": "book_only",
        "client_id": "mm-bid-1",
        "nonce": 1003,
        "signature": "0x..."
      }
    ]
  }'

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

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

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

Kết nối tớ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. Cập nhật khớp lệnh một phần được chủ đích loại bỏ ở kênh này.
fills làm nguồn tham chiếu chính thức cho khớp lệnh một phần và các giao dịch đã thực thi.
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 kênh và hành vi liveness.

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

Chạy một 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 danh sách thị trường khi khởi động.
Tải các lệnh đang mở và các khớp lệnh mới nhất trước khi báo giá.
Đăng ký các cập nhật WebSocket.
Báo giá với các client ID có tính xác định (deterministic).
Poll REST định kỳ để khôi phục sau khi mất kết nối hoặc bỏ lỡ message.
Ngừng báo giá khi gặp 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 giai đoạn ra mắt

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

Ký quỹ: Standard Margin đã hoạt động. Portfolio Margin chưa được kích hoạt rộng rãi.
Quyền writer: mức độ phơi nhiễm quyền chọn ở vị thế bán / short yêu cầu quyền truy cập đã được phê duyệt.
Streaming báo giá chỉ định: các luồng quote-provider chỉ dành cho danh sách được cấp phép và chưa phải là đường 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 ký.
Xác nhận người ký là ví chính hoặc một agent đã được phê duyệt.

Ký quỹ không đủ

Kiểm tra GET /portfolio?wallet=....
Bổ sung tài sản thế chấp hoặc giảm kích thước 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 do không được bảo chứng

Đảm bảo lệnh bán được bảo chứng bởi tồn kho vị thế mua / long đã khớp, hoặc liên hệ Hypercall để xin quyền writer.
Không mặc định rằng quyền writer đã được kích hoạt cho ví mới.

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

Gửi message Authenticate trước khi đăng ký các kênh yêu cầu xác thực.
Đăng ký kênh fills, không chỉ order_updates.
Dự phòng bằng GET /fills?wallet=... sau khi kết nối lại.

Các bước tiếp theo

Xác thực: Authentication & Signing
Giao thức WebSocket: WebSocket API
Giới hạn tốc độ: Rate Limits
Lỗi: Errors & Rejection Reasons
Tham chiếu: API Reference

Danh sách kiểm tra Onboarding​

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

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 (Bulk Orders)​

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 giai đoạn ra mắt​

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

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

Ký quỹ không đủ​

Lệnh bán bị từ chối do quyền truy cập hoặc do không được bảo chứng​

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

Các bước tiếp theo​