API Combo thử nghiệm

Combo giao dịch các chân quyền chọn theo một tỷ lệ cố định dưới dạng một lệnh duy nhất. Một lần khớp sẽ thực hiện đồng thời mọi chân bắt buộc. Vị thế của bạn vẫn là các quyền chọn riêng lẻ.

Hợp đồng thử nghiệm

Tất cả endpoint /experimental và các thông điệp WebSocket được đánh dấu rõ là thử nghiệm đều không ổn định. Các thay đổi phá vỡ tương thích có thể có hiệu lực với thông báo trước một ngày (24 giờ), bao gồm xóa hoặc đổi tên trường hay endpoint, thay đổi kiểu dữ liệu của trường, và thay đổi hành vi của yêu cầu hoặc phản hồi. Các thay đổi được thông báo trong nhật ký thay đổi API. Client phải theo dõi các thông báo này và cập nhật trước thời điểm có hiệu lực đã nêu. Các hợp đồng API hiện có không thuộc diện thử nghiệm nằm ngoài chính sách này.

Khả năng sử dụng phụ thuộc vào môi trường của bạn. Trang này mô tả giao diện thử nghiệm; trang không thông báo về việc ra mắt trên mạng chính hay một giao diện mới trong ứng dụng giao dịch.

Hãy sử dụng tài liệu tham chiếu REST, hướng dẫn xác thực và hướng dẫn WebSocket để biết các quy ước chung về kết nối và ký.

Khám phá một combo

Yêu cầu	Kết quả
GET /experimental/combos	Một trang có giới hạn gồm các định nghĩa chưa đáo hạn, có thể lọc theo underlying
GET /experimental/combos/{symbol}	Một định nghĩa chưa đáo hạn cùng các chân quyền chọn đã được phân giải

Tạo bằng lệnh đầu tiên: gửi một combo_definition chuẩn tắc cùng POST /order khi combo chưa thể khám phá được. Lệnh đầu tiên được chấp nhận sẽ công bố định nghĩa của combo, kể cả lệnh được khớp ngay lập tức. Lệnh bị từ chối không công bố gì cả. Không có endpoint tạo riêng.

Thời gian khám phá: một định nghĩa vẫn có thể khám phá được cho đến khi chân đầu tiên của nó đáo hạn, ngay cả khi không có lệnh chờ nào.

Phân trang: phản hồi chứa combos và next_cursor. Đặt limit trong khoảng 1–1,000 (mặc định 100). Truyền con trỏ được trả về vào cursor ở yêu cầu tiếp theo, giữ nguyên bộ lọc underlying. Con trỏ null nghĩa là không quan sát thấy hàng nào tiếp theo. Giá trị limit hoặc con trỏ không hợp lệ trả về HTTP 400.

GET /experimental/combos?underlying=BTC&limit=100
GET /experimental/combos?underlying=BTC&limit=100&cursor=<next_cursor>

Thứ tự trang: theo ngày đáo hạn sớm nhất của các chân, sau đó theo combo ID. Hãy coi con trỏ là dữ liệu không trong suốt. Mỗi trang phản ánh trạng thái khám phá hiện tại; các định nghĩa có thể đáo hạn hoặc được thêm vào giữa các yêu cầu. Hãy dùng các bản cập nhật tạo mới hoặc khởi động lại quá trình khám phá để nắm bắt các định nghĩa mới được tạo có thứ tự đứng trước một con trỏ đã lưu.

Định danh: một symbol gồm COMBO- theo sau là 64 ký tự thập lục phân viết thường. ID gắn với nội dung của nó cố định các công cụ của từng chân và các tỷ lệ số nguyên có dấu. Một symbol đã tồn tại không thể thay đổi ý nghĩa.

Phạm vi ban đầu: từ hai đến tám chân quyền chọn khác nhau có cùng tài sản cơ sở. Mỗi chân phải được niêm yết, chưa đáo hạn và đủ điều kiện cho tuyến khớp lệnh được yêu cầu.

Hiểu về chiều, giá và khối lượng

Với một định nghĩa chuẩn tắc có tỷ lệ +1 A, -1 B:

• Mua một gói: mua một A và bán một B.
• Bán một gói: bán một A và mua một B.
• Giá ròng: price(A) - price(B), được báo giá theo mỗi gói.
• Giới hạn: lệnh mua chấp nhận giá ròng bằng hoặc thấp hơn giới hạn; lệnh bán chấp nhận giá ròng bằng hoặc cao hơn giới hạn.

Giá âm và giá bằng không đều hợp lệ. Nếu A giao dịch ở $8 và B ở$10, giá ròng chuẩn tắc là -2. Người mua gói đó nhận $2 trước phí. Người bán gói đó trả$2 trước phí. Mỗi chân quyền chọn thực tế vẫn có giá khớp dương.

Bước lệnh: khối lượng gói dùng đơn vị hợp đồng theo cách đọc thông thường với bước 0.000001; giá giới hạn ròng dùng bước 0.000001. Mỗi chân được khớp cũng phải thỏa mãn bước khối lượng và bước giá riêng của nó. Một lần khớp một phần giữ nguyên mọi tỷ lệ và khớp một lượng gói hoàn chỉnh được phép.

Phí: áp dụng mức phí và điều kiện hiện hành cho từng chân, không có chiết khấu theo gói. Lệnh đến là bên taker trên các chân của chính nó, với thông tin builder đã gửi kèm. Trong tuyến outright-qua-combo, lệnh combo cha nhận phân bổ phí taker thông thường trên các chân hỗ trợ bổ sung đối với các maker outright hỗ trợ; các chân đó không có phân bổ builder. Phần dự trữ cho combo đang chờ tính một cách thận trọng cả phí taker tiềm năng trên giá trị gộp của các chân. Cơ chế khớp Standard Margin hiện tại yêu cầu phí giao dịch bằng không đối với các lần khớp trên sổ lệnh và RFQ; một tuyến có sự tham gia của tài khoản SM không thể khớp với phí giao dịch khác không.

Ký quỹ: sàn kiểm tra các vị thế quyền chọn phát sinh và mức phơi nhiễm lệnh còn lại cho từng tài khoản. Combo không gộp tài sản thế chấp giữa các ví và không cam kết mức giảm ký quỹ cụ thể nào. Nếu cấp tài khoản của bạn chỉ cho phép bán quyền chọn có bảo đảm (covered), các lệnh outright đang chờ và các chân bán của mọi lệnh combo cha sẽ dùng chung lượng vị thế long đã khớp. Các lệnh cha riêng biệt và các lần khớp tách rời không thể mỗi bên tái sử dụng lượng vị thế đó; các chân mua chưa khớp không tăng thêm phần bảo đảm.

Đặt lệnh

Sử dụng yêu cầu POST /order có chữ ký hiện có với symbol của combo. Các trường ký lệnh không thay đổi. Hãy ký đúng các chuỗi symbol, size và price mà bạn gửi, bao gồm cả dấu trừ của giá âm. Với một combo mới, thêm combo_definition chuẩn tắc của nó như mô tả bên dưới. Symbol gắn với nội dung đã được ký cam kết với định nghĩa đó; định nghĩa không khớp sẽ bị từ chối. Các combo đã biết có thể bỏ qua trường này.

{
  "wallet": "<your wallet>",
  "symbol": "<discovered COMBO symbol>",
  "side": "Buy",
  "size": "1",
  "price": "-2",
  "tif": "gtc",
  "route": "best_execution",
  "client_id": "spread-001",
  "reduce_only": false,
  "mmp_enabled": false,
  "nonce": 1,
  "signature": "<signed order>"
}

Hãy thay các placeholder và nonce bằng giá trị thực tế của bạn. Giá ở đây chỉ mang tính minh họa, không phải báo giá thị trường hiện tại.

Thiết lập	Hành vi
route: "book_only"	Khớp với thanh khoản trực tiếp và thanh khoản ngụ ý được hỗ trợ hiện có, sau đó áp dụng time in force
route: "best_execution"	Xem xét một phiên đấu giá cải thiện giá cho trọn gói, sau đó chuyển về khớp trên sổ lệnh khi phù hợp
route: "rfq_only"	Bị từ chối trên /order
tif: "gtc"	Để phần gói chưa khớp còn lại chờ trên sổ lệnh
tif: "ioc"	Hủy phần chưa khớp còn lại
tif: "fok"	Khớp toàn bộ lượng gói được yêu cầu hoặc không khớp gì cả

Cải thiện giá so sánh giá ròng có dấu của trọn gói với một mức tham chiếu trên sổ lệnh có thể khớp với đủ khối lượng. Nhà cung cấp báo giá phải cung cấp mọi chân theo đúng tỷ lệ và khối lượng được yêu cầu. Xếp hạng một báo giá chỉ dựa trên chân đầu tiên là không đủ. Cả thanh khoản combo trực tiếp lẫn các tuyến ngụ ý được hỗ trợ đều có thể góp phần vào mức tham chiếu. Nếu mức tham chiếu không khả dụng hoặc không đầy đủ, lệnh sẽ được chuyển sang khớp trên sổ lệnh.

Điều kiện báo giá: các quy tắc phí RFQ hiện hành cũng được áp dụng. Nếu một trong hai bên tham gia sử dụng Standard Margin, khớp RFQ yêu cầu phí giao dịch bằng không. Báo giá không vượt qua kiểm tra phí, tài sản thế chấp hoặc phân bổ chính xác sẽ để việc khớp lệnh tiếp tục theo đường sổ lệnh hiện tại; nó không khớp một phần các chân.

Khớp ngụ ý có thể kết hợp một combo với thanh khoản quyền chọn outright hỗ trợ cho nó. Ví dụ, một lệnh outright A có thể giao dịch nguyên tử với một combo A trừ B và thanh khoản B. Khách hàng chỉ giao dịch A sẽ không nhận vị thế B nào.

Việc tìm kiếm ngụ ý có giới hạn tài nguyên. Nếu một lệnh outright chạm các giới hạn đó, thanh khoản hỗ trợ trở nên không khả dụng, hoặc tuyến tùy chọn không thể biểu diễn bước lệnh outright, lệnh vẫn có thể giao dịch với sổ lệnh quyền chọn trực tiếp theo các quy tắc lệnh thông thường. Hỗ trợ combo không thay đổi bước khối lượng hay bước giá được chấp nhận của lệnh outright. Quyền chọn mục tiêu phải tiếp tục đủ điều kiện giao dịch trên sổ lệnh. Lệnh combo vượt quá giới hạn tìm kiếm sẽ bị từ chối mà không có phân bổ một phần.

Hạn chế hiện tại: lệnh combo gốc yêu cầu mmp_enabled: false. Các bên tham gia outright được bảo vệ vẫn giữ MMP. Một gói kích hoạt ngưỡng sẽ hoàn tất các chân của nó và dừng khớp tiếp; một lệnh FOK chưa hoàn tất hoặc một lần thay thế nguyên tử sẽ hoàn tác toàn bộ ứng viên. Lệnh reduce-only bỏ qua phiên đấu giá cải thiện giá và dùng cơ chế tiếp nhận trên sổ lệnh, trong đó mỗi chân phát sinh phải vượt qua kiểm tra reduce-only. Hủy một combo đang chờ bằng ID lệnh cha hoặc ID lệnh client thông qua các endpoint hủy hiện có.

Thay thế: PUT /order có thể thay thế nguyên tử một lệnh cha trong cùng một định nghĩa combo. Lần thay thế bị từ chối sẽ giữ nguyên lệnh trước đó. Các mục combo gốc trong thay thế hàng loạt cũng dùng một lệnh nguyên tử cho mỗi lệnh cha; cả lô không phải là một giao dịch tất cả hoặc không có gì. Việc thay thế giữa combo và outright, hoặc giữa các định nghĩa combo khác nhau, sẽ bị từ chối.

Ngăn tự khớp: quá trình khớp dừng lại trước khi một tuyến khiến tài khoản giao dịch với chính nó, và hủy lệnh maker đang chờ. Các lần khớp đã hoàn tất trước đó được giữ nguyên, còn phần còn lại của lệnh đến bị hủy. Nếu không có lần khớp nào trước đó, lệnh đến bị từ chối. Lệnh FOK và các lần thay thế nguyên tử thất bại giữ nguyên hành vi tất cả hoặc không có gì, bao gồm cả việc hoàn tác các lần hủy maker tạm thời.

Định nghĩa combo trong lệnh đầu tiên

Chuẩn tắc hóa trước khi ký: gộp các instrument ID trùng lặp, loại bỏ tỷ lệ bằng không, sắp xếp ID theo giá trị số, chia các tỷ lệ cho ước chung lớn nhất của chúng, và làm cho tỷ lệ đầu tiên dương. Nếu quá trình chuẩn hóa đảo ngược các tỷ lệ, hãy đảo chiều lệnh dự định và đổi dấu giá ròng. Nếu quá trình này chia các tỷ lệ cho một hệ số, hãy nhân khối lượng gói với hệ số đó và chia giá ròng cho hệ số đó.

ID phiên bản một là Keccak-256 của chuỗi nối sau:

UTF-8("hypercall:combo-definition\0")
|| version as unsigned 16-bit big-endian (1)
|| leg count as unsigned 16-bit big-endian
|| each sorted leg:
     instrument ID as 32 big-endian bytes
     ratio as signed 64-bit two's-complement big-endian

Instrument ID là Keccak-256 của UTF-8 "instrument" theo sau là symbol quyền chọn chuẩn tắc chính xác. Combo ID được công bố là toàn bộ digest, mã hóa dưới dạng 0x cộng 64 ký tự thập lục phân viết thường. Symbol của combo dùng cùng các chữ số hex đó sau COMBO-.

Đưa combo_definition vào phần thân POST /order có chữ ký thông thường. Định nghĩa chứa version, id và legs; mỗi chân chứa instrument_id và ratio. Mã hóa ID dưới dạng 0x cộng 64 chữ số thập lục phân viết thường và tỷ lệ dưới dạng chuỗi thập phân có dấu chuẩn tắc, chẳng hạn "1" hoặc "-1". Số JSON, dấu cộng ở đầu và số không ở đầu đều bị từ chối đối với tỷ lệ.

{
  "combo_definition": {
    "version": 1,
    "id": "<canonical content hash as 0x plus 64 hex digits>",
    "legs": [
      {"instrument_id": "<first canonical instrument ID>", "ratio": "1"},
      {"instrument_id": "<second canonical instrument ID>", "ratio": "-1"}
    ]
  }
}

Đoạn này được thêm vào ví dụ lệnh đầy đủ ở trên. Hãy thay các placeholder bằng ID thực tế và dùng symbol COMBO- tương ứng. Không có chữ ký định nghĩa bổ sung hay nonce công bố riêng. Dịch vụ xác minh nội dung chuẩn tắc và định danh của nó so với symbol đã ký; lệnh outright phải bỏ qua combo_definition.

Chấp nhận và khám phá: mỗi lệnh combo được chấp nhận đều lưu định nghĩa của nó trong bản ghi lệnh bền vững và đảm bảo một cách idempotent rằng mục danh mục tồn tại. Lệnh sau không ghi đè bản ghi tạo đầu tiên. Lệnh được khớp ngay lập tức vẫn tạo dữ liệu khám phá; lệnh bị từ chối thì không. Dữ liệu khám phá có thể trễ hơn xác nhận lệnh vì nó được chiếu từ dữ liệu đã cam kết. Việc gửi lại cùng một định nghĩa trong lệnh sau được hỗ trợ, kể cả khi mục danh mục đầu tiên vẫn đang cập nhật.

Đọc lệnh và các lần khớp

Yêu cầu	Mục đích
GET /experimental/orders	Đọc lệnh với phân loại công cụ rõ ràng, bao gồm các lệnh combo cha
GET /experimental/trades	Mặc định đọc giao dịch thực của từng chân, hoặc bản tóm tắt gói cho một combo với view=packages&symbol=<COMBO symbol>
GET /experimental/fills	Mặc định đọc các lần khớp của ví, hoặc bản tóm tắt gói của ví với view=packages

Hãy dùng tài liệu tham chiếu REST để biết các bộ lọc và con trỏ được hỗ trợ. Các chế độ xem gói phân trang bằng limit (1 đến 1,000, mặc định 100) và before_execution_id, không dùng offset: truyền next_before_execution_id được trả về để lấy trang tiếp theo. Giao dịch theo gói yêu cầu symbol COMBO- chuẩn tắc; lần khớp theo gói nhận wallet và một symbol tùy chọn. Bản tóm tắt gói là bản ghi nhóm: execution ID và trade ID của từng chân cho phép bạn liên kết chúng với các lần khớp quyền chọn thực tế. Không cộng khối lượng gói, phí quyền chọn hay phí giao dịch vào các lần khớp thành phần khi tính tổng tài khoản.

Độ chính xác của định danh: order ID thử nghiệm, package execution ID, trade/order ID thành phần, ID lệnh cha và con trỏ phân trang gói đều là chuỗi thập phân. Hãy giữ chúng dưới dạng chuỗi trong client của bạn; chuyển đổi sang kiểu số JavaScript có thể làm mất độ chính xác. Các phản hồi view=legs cũ giữ nguyên cách biểu diễn hiện có.

Tương thích: cơ chế khám phá công cụ và chế độ xem lệnh cũ giữ nguyên hợp đồng outright. Các lần khớp chân quyền chọn thực tế tiếp tục xuất hiện trong các luồng trade/fill cũ, và vị thế vẫn là vị thế quyền chọn. Lệnh cha của combo không phải là tập hợp các lệnh chân chờ độc lập.

Đăng ký rõ ràng

Các kênh riêng tư thử nghiệm yêu cầu bước xác thực WebSocket hiện có và một lần đăng ký rõ ràng. Chúng chỉ công bố các bản ghi lệnh cha của ví đã xác thực.

Kênh	Thông điệp	Đối tượng
experimental_order_updates	ExperimentalOrderUpdate với ID lệnh cha, symbol, loại công cụ (option, perp hoặc combo), trạng thái, khối lượng, khối lượng đã khớp và giá ròng	Ví đã xác thực
experimental_combo_trades	ComboTrade với execution ID, symbol, khối lượng gói, giá ròng và trade ID của các chân	Công khai
experimental_combo_fills	ComboFill với ID lệnh cha của ví, chiều lệnh và lần khớp gói	Ví đã xác thực

{"type":"Subscribe","channel":"experimental_order_updates"}

ExperimentalOrderUpdate.status dùng Acked, Open, PartiallyFilled, Filled, Canceled hoặc Rejected, không dùng các giá trị viết hoa của OrderUpdate. ID và khối lượng là chuỗi.

Đăng ký kênh sổ lệnh hiện có bằng một symbol combo đã khám phá:

{"type":"Subscribe","channel":"orderbook","symbols":["<discovered COMBO symbol>"]}

Cập nhật khám phá thị trường có thể lặp lại cùng một định nghĩa bất biến; hãy loại trùng theo combo ID. Chúng dùng MarketUpdate trên market_updates, với action: "ComboCreated", symbol của combo, ID, các chân chuẩn tắc và dấu thời gian. Hãy coi dữ liệu khám phá, trạng thái lệnh cha, bản tóm tắt khớp gói và các lần khớp chân thực tế là những bản ghi riêng biệt khi đối soát trong client của bạn.