Торгівля через API

Використовуйте цей посібник, якщо ви інтегруєте маркетмейкера, систему котирування або сервіс виконання з Hypercall.

Продакшн API

Базовий URL REST: https://api.hypercall.xyz

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

Статус тестнету: тестнет тимчасово вимкнено, доки Hypercall не отримає більше тестнет-HYPE. Нові інтеграції маркетмейкерів повинні використовувати продакшн, якщо Hypercall не надасть вам виділене середовище.

Стріми за списком дозволених

Стрімінг індикативних котирувань від постачальників ще не є загальнодоступним. Hypercall може увімкнути його для схвалених інтеграцій, але звичайне підключення маркетмейкерів має використовувати ринкові дані через REST, а також автентифіковані WebSocket-канали ордерів, виконань і портфеля.

Чекліст підключення

Торговий гаманець: EVM-гаманець, здатний підписувати типізовані дані EIP-712.
Фінансування: поповнення USDC у продакшні на app.hypercall.xyz.
Доступ: зв'яжіться з Hypercall, якщо вам потрібні ліміти маркетмейкера, доступ райтера або стрімінг індикативних котирувань.
Середовище: продакшн REST та WebSocket URL, наведені вище. Не припускайте, що тестнет доступний.
Звірка: зберігайте власні клієнтські ідентифікатори ордерів, нонси, ордери, виконання та знімки позицій.

Шляхи інтеграції

Rust-крейти

Hypercall публікує публічні Rust-крейти для підтримуваної поверхні інтеграції:

Публічний Rust-репозиторій: github.com/hypercall-public/hypercall-rust.

Крейт	Призначення
`hypercall-client`	REST-клієнт, WebSocket-клієнт, хелпери для підписання EIP-712, локальне підписання та підписання через AWS KMS
`hypercall-sdk-types`	Публічні DTO запитів і відповідей, які використовує клієнт
`hypercall-ws-protocol`	Публічні типи WebSocket-повідомлень
`hypercall-hyperliquid`	Необов'язковий хелпер-крейт для Hyperliquid для інтеграцій, які також хеджуються на Hyperliquid
`hypercall-liquidator`	Референсний клієнт ліквідації для Standard Margin. Він не потрібен для звичайного маркетмейкінгу

За можливості використовуйте крейти. Вони кодують поточний домен підписання, форми запитів, правила маршрутів і правила форматування рядків, у яких легко помилитися вручну.

Прямий REST і WebSocket

Якщо ви не використовуєте Rust, використовуйте сторінки API Reference, Аутентифікація та підписання і WebSocket API як джерело істини.

1. Виявлення ринків

Почніть із завантаження активних ринків та специфікацій інструментів:

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

Використовуйте:

GET /markets для лістингованих груп базових активів та експірацій.
GET /instrument-specs?currency=BTC для специфікацій доступних для торгівлі опціонів.
GET /options-summary?currency=BTC для найкращого біда, найкращого аска, маркувальної ціни та зведених полів у стилі греків на рівні ланцюжка.

2. Налаштування підписання

Операції запису використовують підписи EIP-712.

Chain ID продакшну: 999
Ім'я домену: Hypercall
Версія домену: 1
Верифікуючий контракт: 0x0000000000000000000000000000000000000000

Маркетмейкерам зазвичай варто використовувати гаманець-агент:

Гаманець-власник схвалює агента через POST /approve-agent.
Гаманець-агент підписує ордери та скасування від імені гаманця-власника.
Гаманець-власник залишається ідентичністю портфеля, фінансування та ризику.

Див. Аутентифікація та підписання для точних структур і назв полів.

3. Котирування через масові ордери

Для котирувань маркетмейкера використовуйте POST /bulk_order з 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..."
      }
    ]
  }'

Важливі правила:

price і size — це рядки як у підписаному payload, так і в JSON-тілі.
Форматування рядків має точно збігатися між підписом і JSON-тілом.
Розмір масового ордера обмежений 50 ордерами на запит.
Масовий маршрут працює лише з книгою заявок. route: "best_execution" і route: "rfq_only" — це шляхи для одиночних ордерів, а не для масових котирувань.
Більшість торгових відхилень повертають HTTP 200 зі status: "REJECTED". Завжди перевіряйте кожен результат.

4. Оновлення котирувань

Використовуйте PUT /bulk_order, коли хочете скасувати наявні ордери-котирування та розмістити замінники в одному запиті.

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 скасовує старий пакет перед створенням нового. Результати повертаються по кожній заміні в порядку запиту. Невдале скасування запобігає створенню відповідного ордера-заміни.

Для однієї чутливої до затримки заміни використовуйте PUT /order.

5. Підписка на оновлення

Підключіться до продакшн WebSocket:

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" }));
};

Використовуйте:

order_updates для змін статусу ордерів. Оновлення часткових виконань тут навмисно відсутні.
fills як джерело істини для часткових виконань та здійснених угод.
portfolio для оновлень стану облікового запису.
orderbook, trades, options_chain та index_prices для публічних ринкових даних.

Див. WebSocket API для форматів каналів і поведінки перевірки активності.

6. Звірка стану

Виконуйте цикл звірки, навіть якщо ваше WebSocket-з'єднання працює стабільно.

Стан	REST-резерв	WebSocket-канал
Ордери	`GET /orders?wallet=...`	`order_updates`
Виконання	`GET /fills?wallet=...`	`fills`
Портфель	`GET /portfolio?wallet=...`	`portfolio`
Ринки	`GET /markets`, `GET /instrument-specs`	`market_updates`, `options_chain`

Рекомендований цикл:

Завантажте ринки під час запуску.
Завантажте відкриті ордери та останні виконання перед котируванням.
Підпишіться на WebSocket-оновлення.
Котируйте з детермінованими клієнтськими ідентифікаторами.
Періодично опитуйте REST, щоб відновлюватися після розривів з'єднання або пропущених повідомлень.
Припиняйте котирування за невідомого стану, доки стани REST та WebSocket знову не збіжаться.

7. Розуміння обмежень запуску

Mainnet Alpha свідомо обмежена.

Маржа: Standard Margin працює. Portfolio Margin загалом не увімкнено.
Доступ райтера: коротка експозиція за опціонами потребує схваленого доступу.
Індикативний стрімінг: стріми постачальників котирувань доступні лише за списком дозволених і поки не є загальним публічним шляхом інтеграції.
Інструменти ліквідації: публічний крейт ліквідатора призначений для робочих процесів ліквідації Standard Margin, а не для звичайного маркетмейкінгу.
Тестнет: недоступний, доки Hypercall не отримає більше тестнет-HYPE.

Поширені проблеми

Не вдалося верифікувати підпис

Перевірте, що price і size — це JSON-рядки.
Перевірте, що підписані рядки точно збігаються з надісланими рядками.
Використовуйте chain ID 999 для продакшну.
Використовуйте свіжий нонс для кожного підписаного запису.
Переконайтеся, що підписувач — це гаманець або схвалений агент.

Недостатня маржа

Перевірте GET /portfolio?wallet=....
Додайте забезпечення або зменште розмір котирування.
Переконайтеся, що ваш гаманець має рівень доступу, необхідний для стратегії, яку ви котируєте.

Продаж відхилено через доступ або покриття

Переконайтеся, що продаж покривається заповненою довгою позицією, або зв'яжіться з Hypercall для отримання доступу райтера.
Не припускайте, що доступ райтера увімкнено для нового гаманця.

Немає виконань у WebSocket

Надішліть повідомлення Authenticate перед підпискою на автентифіковані канали.
Підпишіться на fills, а не лише на order_updates.
Використовуйте GET /fills?wallet=... як резерв після перепідключення.

Наступні кроки

Аутентифікація: Аутентифікація та підписання
Протокол WebSocket: WebSocket API
Ліміти запитів: Ліміти запитів
Помилки: Помилки та причини відхилень
Довідник: API Reference

Чекліст підключення​

Шляхи інтеграції​

Rust-крейти​

Прямий REST і WebSocket​

1. Виявлення ринків​

2. Налаштування підписання​

3. Котирування через масові ордери​

4. Оновлення котирувань​

5. Підписка на оновлення​

6. Звірка стану​

7. Розуміння обмежень запуску​

Поширені проблеми​

Не вдалося верифікувати підпис​

Недостатня маржа​

Продаж відхилено через доступ або покриття​

Немає виконань у WebSocket​

Наступні кроки​