Постійні запити та розбиття на сторінки

Цей посібник призначений для Agent Java SDK v0.3.0, Java 8+ і публічного контракту з тегами. Приклади виконуються в серверній частині партнера після ініціалізації client у Швидкий старт.

Приклад передумов

Фрагменти Java поділяють ці імпортовані файли. Ініціалізуйте client за допомогою швидкого запуску та отримайте platformUserId із збереженого зв’язування. Приклади ідентифікаторів користувача/замовлення потрібно замінити вашими постійними значеннями.

import com.sixmm.agent.*;
import com.sixmm.agent.model.*;
import java.util.*;

Запит даних безстрокового контракту

Шість типів інтерфейсів і Java методів

Усі запити підписуються POST із загальним префіксом /v1/agent/perpetual.

platformUserIds — це рядковий масив загальнодоступних ідентифікаторів платформи. Якщо вказано, потрібні від 1 до 100 унікальних гравців, які мають доступ; на кінцевих точках, які допускають пропуск, запитується лише діапазон прямих гравців, до яких має доступ поточний продавець. Запити Trade-fill завжди потребують цього масиву; запити умовного порядку також вимагають явних ідентифікаторів користувачів. Пропуск не еквівалентний [], а порожні масиви є незаконними. Обсяг визначається продавцем, який підписує, і інші ідентифікатори продавця не можна передати для розширення обсягу.

Значення масиву серіалізуються як компактний JSON перед приєднанням до корисного навантаження підпису. Наприклад, platformUserIds підписується як ["1188041528"], надаючи platformUserIds=["1188041528"] у корисному навантаженні k=v. Зберігати порядок елементів масиву, подвійні лапки та ідентифікатори рядків; не вставляйте пробіли форматування та не використовуйте Java List.toString() (наприклад, [1188041528]). SDK обробляє цю серіалізацію автоматично.

Запит на замовлення має передати orderCategory=NORMAL або CONDITIONAL. Використовуйте orderId для звичайних замовлень і conditionId для умовних замовлень. Їх не можна змішувати між категоріями. Умовні замовлення та звичайні замовлення, створені шляхом їх запуску, обробляються окремо як сутності.

Умови фільтрації

Час історичного запиту – Unix мілісекунди, а інтервал – [startTime, endTime); час запиту підпису timestamp — це секунди Unix. Рекомендовано виправити UTC часове вікно та запит у сегментах; використовуйте UTC для щоденного узгодження. Статус і тип використовують перерахування контракту платформи й самі по собі не перекладаються на китайські рядки.

limit За замовчуванням 500, діапазон 1~1000; розмір сторінки не гарантує, що кожного разу повертатиметься однаковий номер. Наразі шість інтерфейсів спільно використовують квоту запитів 2 рази на секунду та 4 пакети для кожного продавця, а максимальний ліміт одночасності для кожного продавця в екземплярі становить 2. Сторона продавця використовує уніфіковану чергу, тому рекомендується починати з послідовного пейджінгу та меншого вікна історії.

Java приклади запитів

Запит поточного звичайного порядку гравця:

CurrentPerpetualOrdersRequest current = new CurrentPerpetualOrdersRequest();
current.orderCategory = "NORMAL";
current.platformUserIds = Collections.singletonList(platformUserId);
current.symbol = "BTCUSDT";
current.limit = 100;
PerpetualResponse currentPage = client.listCurrentPerpetualOrders(current);

Запитайте зміни контракту за останню годину та обробіть курсор. У наступному прикладі не виконується повторна спроба автоматично; коли фактична програма стикається з поточним обмеженням або тимчасовим збоєм, дотримуйтеся відповідного посібника, щоб відновити ту саму сторінку.

PerpetualLedgerRequest ledger = new PerpetualLedgerRequest();
ledger.platformUserIds = Collections.singletonList(platformUserId);
ledger.endTime = System.currentTimeMillis();
ledger.startTime = ledger.endTime - 3_600_000L;
ledger.limit = 100;
Set<String> seenCursors = new HashSet<>();
while (true) {
    PerpetualResponse page = client.listPerpetualLedger(ledger);
    for (PerpetualRecord row : page.data.items) {
        // Persist records idempotently by platformUserId, entityType and entityId.
    }
    if (!page.data.hasMore) {
        break;
    }
    String next = page.data.nextCursor;
    if (next == null || next.isEmpty() || !seenCursors.add(next)) {
        throw new IllegalStateException("游标未推进，停止查询并排查");
    }
    ledger.cursor = next;
    Thread.sleep(650L); // Other queries must share the same partner rate-limit queue.
}

Структура повернення та правила збереження

див Загальна відповідь і сторінки для спільних полів. Поля ресурсів задокументовані в Замовлення, Торгівля наповнює, посади і Договірна книга.

Шість інтерфейсів однаково повертають PerpetualResponse:

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [],
    "nextCursor": "",
    "hasMore": false
  }
}

Кожен items містить platformUserId, entityType, entityId, data. Типи об’єктів включають ORDER, CONDITION_ORDER, TRADE_FILL, POSITION, ACCOUNT_LEDGER. Використовуйте ці три поля ідентичності, щоб створити ідемпотентний ключ; не розглядайте ідентифікатор умовного замовлення, ідентифікатор замовлення та ідентифікатор заповнення як одне й те саме число.

data Надає такі поля, як ціна, кількість, статус, витрати, прибуток і збиток або зміна балансу за ресурсом. Сума, ціна, кількість і ідентифікатор об’єкта обробляються як рядки; робочий час у мілісекундах. Відсутні поля не заповнюються до 0 і не виводяться з інших сутностей.

Курсор — це позиція запиту на сторінку, а не надійна додаткова підписка чи гарантований міжсторінковий атомарний знімок. Поточний курсор дійсний протягом 24 годин від першого раунду генерації; наступне розбиття сторінок зберігає тих самих торговців, ресурси, колекції гравців і умови фільтрації. Фіксоване вікно для історичного підтягування є ідемпотентним при повторному підтягуванні; статус поточного замовлення/позиції оновлюється після повторного запиту. Коли потрібен інтерфейс реального часу, використовується механізм даних інтерфейсу платформи, а інтерфейс опитування шести не можна розглядати як високочастотний ринковий інтерфейс.

Помилки та відновлення

HTTP успіх не означає успіх у бізнесі, ви повинні перевірити code. Java SDK викличе бізнес-помилку як AgentApiException.

cursor і всі умови фільтра початкової невдалої сторінки буде збережено після поточного обмеження, тайм-ауту або тимчасової помилки; щоразу, коли SDK повторно викликається, генеруватимуться нові timestamp, nonce, sign. Ви не можете перейти безпосередньо до наступної сторінки, і ви не можете розглядати помилки як порожні результати. SDK не несе відповідальності за автоматичну повторну спробу грошових транзакцій.

Загальна відповідь і сторінки

Структура кожного data.items[]:

Той самий ledgerId може розділити кілька деталей, таких як комісія за обробку, прибутки та збитки тощо; натискання ledgerId для видалення дублікатів призведе до втрати даних. Ідентифікатори з різних ресурсів не можна змішувати. Перегляньте пов’язаний посібник із посібника з доступу, щоб дізнатися про правила збереження сторінок і полів.

Типи, одиниці вимірювання та пропущені поля

• Сума, ціна, кількість і ідентифікатор організації використовують рядок; використовувати десяткову систему для обробки сум і не можна використовувати числа з плаваючою комою або перетворювати довгі ідентифікатори на числа JavaScript. Валюта суми та одиниця кількості пояснюються відповідно до специфікацій торгової пари/контракту.
• Бізнес-час використовує ціле число (int64), обидва є мілісекундами Unix; мітка часу запиту автентифікації та облікові дані входу expireAt використовують секунди, і їх не можна сплутати.
• Рядкові бізнес-поля зазвичай не виводяться, якщо вони порожні, а деякі будуть пропущені, якщо числові поля дорівнюють 0. Відсутнє поле не означає, що бізнес-значення дорівнює 0.
• reduceOnly, closeOnly, makerOnly у загальній моделі запису не пропускають false, тому ці три false також можуть з’являтися в транзакціях або позиціях. Вони пояснюються лише в ресурсах замовлення; не можна вважати, що транзакція/позиція виконувала відповідні правила замовлення.
• closePosition є необов’язковим логічним значенням: надається умовними замовленнями, які зазвичай опускаються для інших ресурсів. Missing має інше значення, ніж false.
• Таблиця нижче «надано на даний момент» означає, що логіка читання має джерело поля; необов’язкові поля все ще можуть бути пропущені, оскільки вони не мають значення. Поля, які існують у моделі, не гарантовано будуть заповнені в кожному інтерфейсі.

Різниця між статусом і маржинальним режимом

Написання CANCELED для звичайного замовлення відрізняється від CANCELLED для умовного замовлення; спрацьовування умовного замовлення не означає, що згенероване звичайне замовлення виконано. Не використовуйте один і той самий набір таблиць перекладу стану для всіх ресурсів.

Умовний порядок marginMode повертає CROSS / ISOLATED; історичні звичайні замовлення та позиції наразі повертають “1” / “2”, що є перехресною/ізольованою маржею відповідно. marginMode наразі недоступний для звичайних замовлень. Торговці можуть нормалізувати за ресурсом у своєму власному шарі відображення, а вихідні значення все одно потрібно зберегти.

Поля, оголошені в моделі, але не надані в цьому запиті

Generic RecordData / Java Модель PerpetualData також оголошує наступні поля, але поточна логіка читання з шести категорій не заповнює їх. **Не слід вказувати як доступні бізнес-дані, а також не можна замінювати справжні результати полями за замовчуванням. **

Фактичний обсяг польового застосування залежить від наведених вище таблиць ресурсів; коли платформа оновлює поля або перерахування, вона повинна бути адаптована відповідно до нового опису інтерфейсу та версії SDK.

Джерело та відповідні посібники

• Офіційне джерело v0.3.0
• Гаманець для фінансування
• Посібник з оновлення