Постоянные запросы и нумерация страниц

Это руководство предназначено для 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 уникальных игроков, имеющих доступ; на конечных точках, допускающих пропуск, запрашивается только диапазон прямых игроков, к которым имеет доступ текущий торговец. Запросы торгового заполнения всегда требуют этот массив; Запросы условного порядка также требуют явных идентификаторов пользователей. Пропуск не эквивалентен [], а пустые массивы недопустимы. Область действия определяется подписавшим продавцом, и другие идентификаторы продавца не могут быть переданы для расширения области действия.

Значения массива сериализуются как компактные 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 для удаления дубликатов приведет к потере данных. ID с разных ресурсов смешивать нельзя. Правила разбиения на страницы и сохранения полей см. в соответствующем руководстве Руководства по доступу.

Типы, единицы измерения и пропущенные поля

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

Разница между статусом и режимом маржи

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

Условный заказ marginMode возвращает CROSS / ISOLATED; исторические обычные ордера и позиции в настоящее время возвращают «1» / «2», что соответствует перекрестной/изолированной марже соответственно. marginMode в настоящее время недоступен для обычных заказов. Продавцы могут нормализовать по ресурсам на своем собственном слое отображения, при этом исходные значения все равно необходимо сохранить.

Поля, объявленные в модели, но не предоставленные в этом запросе.

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

Фактический объем полевого применения зависит от приведенных выше таблиц ресурсов; когда платформа обновляет поля или перечисления, они должны быть адаптированы в соответствии с новым описанием интерфейса и версией SDK.

Источник и связанные руководства

• Официальный источник v0.3.0
• Финансирование кошелька
• Руководство по обновлению