> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.6mm.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.6mm.com/_mcp/server. # Постоянные запросы и нумерация страниц Это руководство предназначено для **Agent Java SDK `v0.3.0`**, Java 8+ и помеченного публичного контракта. Примеры выполняются в серверной части партнера после инициализации `client` в [Быстрый старт](/ru/sdk/agent-sdk/java/quick-start). ## Пример предварительных условий Фрагменты Java разделяют этот импорт. Инициализируйте `client` с помощью быстрого запуска и получите `platformUserId` из сохраненной привязки. Примеры идентификаторов пользователей/заказов необходимо заменить вашими собственными сохраненными значениями. ```java import com.sixmm.agent.*; import com.sixmm.agent.model.*; import java.util.*; ``` ## Запрос данных бессрочного контракта ### Шесть типов интерфейсов и методы Java Все запросы подписываются POST общим префиксом `/v1/agent/perpetual`. | суффикс пути | Java Метод/Тип запроса | диапазон игрока | | -------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------- | | `/orders/current` | `listCurrentPerpetualOrders(CurrentPerpetualOrdersRequest)` | NORMAL Игрока можно не указывать; CONDITIONAL Игрок должен быть указан | | `/orders/history` | `listPerpetualOrderHistory(PerpetualOrderHistoryRequest)` | То же, что и выше | | `/trades` | `listPerpetualTrades(PerpetualTradesRequest)` | Игрок должен быть указан | | `/positions/current` | `listCurrentPerpetualPositions(CurrentPerpetualPositionsRequest)` | Игроки могут быть опущены | | `/positions/history` | `listPerpetualPositionHistory(PerpetualPositionHistoryRequest)` | Игроки могут быть опущены | | `/account/ledger` | `listPerpetualLedger(PerpetualLedgerRequest)` | Игроки могут быть опущены | `platformUserIds` — это строковый массив идентификаторов общедоступных платформ. Если указано, требуется от 1 до 100 уникальных игроков, имеющих доступ; на конечных точках, допускающих пропуск, запрашивается только диапазон прямых игроков, к которым имеет доступ текущий торговец. Запросы торгового заполнения всегда требуют этот массив; Запросы условного порядка также требуют явных идентификаторов пользователей. Пропуск не эквивалентен `[]`, а пустые массивы недопустимы. Область действия определяется подписавшим продавцом, и другие идентификаторы продавца не могут быть переданы для расширения области действия. Значения массива сериализуются как компактные JSON перед присоединением к подписывающим полезным данным. Например, `platformUserIds` обозначается как `["1188041528"]`, что дает `platformUserIds=["1188041528"]` в полезных данных `k=v` . Сохранять порядок элементов массива, двойные кавычки и идентификаторы строк; не вставляйте пробелы форматирования и не используйте Java `List.toString()` (например, `[1188041528]`). SDK автоматически обрабатывает эту сериализацию. Запрос заказа должен передать `orderCategory=NORMAL` или `CONDITIONAL`. Используйте `orderId` для обычных заказов и `conditionId` для условных заказов. Их нельзя смешивать по категориям. Условные ордера и обычные ордера, созданные в результате их срабатывания, обрабатываются отдельно как сущности. ### Условия фильтра | Запрос | Доступные бизнес-фильтры | | -------------------- | -------------------------------------------------------------------------------------------------------------- | | Текущий заказ | `orderCategory`, `symbol` | | исторический порядок | `orderCategory`, `symbol`, `startTime`, `endTime`, `orderId`, `conditionId`, `clientOrderId`, `side`, `status` | | заключить сделку | `symbol`, `startTime`, `endTime`, `orderId` | | Текущая позиция | `symbol` | | Исторические позиции | `symbol`, `startTime`, `endTime`, `positionSide` | | Изменения контракта | `startTime`, `endTime`, `assetType`, `changeType` | Время исторического запроса — Unix **миллисекунды**, а интервал — `[startTime, endTime)`; время запроса подписи — `timestamp` — Unix **секунд**. Рекомендуется исправить временное окно UTC и запрос по сегментам; используйте UTC для ежедневной сверки. Статус и тип используют перечисление контрактов платформы и сами по себе не переводятся на китайские строки. `limit` Значение по умолчанию: 500, диапазон: 1–1000; размер страницы не гарантирует, что каждый раз будет возвращаться одно и то же число. Шесть интерфейсов в настоящее время разделяют квоту запросов 2 раза в секунду и 4 пакета на каждого продавца, а максимальный предел одновременности для каждого продавца в экземпляре равен 2. Сторона продавца использует единую очередь, и рекомендуется начинать с последовательной пейджинговой связи и меньшего окна истории. ### Java примеры запросов Запросите текущий обычный порядок игрока: ```java CurrentPerpetualOrdersRequest current = new CurrentPerpetualOrdersRequest(); current.orderCategory = "NORMAL"; current.platformUserIds = Collections.singletonList(platformUserId); current.symbol = "BTCUSDT"; current.limit = 100; PerpetualResponse currentPage = client.listCurrentPerpetualOrders(current); ``` Запросите изменения контракта за последний час и обработайте курсор. В следующем примере повторная попытка не выполняется автоматически; Когда фактическое приложение сталкивается с текущим ограничением или временным сбоем, следуйте соответствующему руководству по ссылке, чтобы восстановить ту же страницу. ```java PerpetualLedgerRequest ledger = new PerpetualLedgerRequest(); ledger.platformUserIds = Collections.singletonList(platformUserId); ledger.endTime = System.currentTimeMillis(); ledger.startTime = ledger.endTime - 3_600_000L; ledger.limit = 100; Set 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. } ``` ### Структура возврата и правила сохранения Видеть [Общий ответ и нумерация страниц](#common-response-and-pagination) для общих полей. Поля ресурсов описаны в [Заказы](/ru/sdk/agent-sdk/java/perpetual-orders), [Торговля заполняет](/ru/sdk/agent-sdk/java/perpetual-trades), [Позиции](/ru/sdk/agent-sdk/java/perpetual-positions) и [Книга контрактов](/ru/sdk/agent-sdk/java/perpetual-ledger). Шесть интерфейсов одинаково возвращают `PerpetualResponse`: ```json { "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`. | Бизнес-код | Типичное значение | Умение обращаться | | ---------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `102001` | Отсутствуют обязательные параметры, например, в запросе условного порядка отсутствуют игроки. | Укажите недостающие параметры | | `102002` | Недопустимые параметры, пустой массив, несовпадающий курсор или срок действия истек. | Исправьте параметры; перепроверьте фиксированное окно после очистки просроченного курсора и сохраните его идемпотентно. | | `102003` | Недопустимый лимит, количество игроков или временной диапазон. | Узкая или правильная сфера применения | | `6001` | Ошибка подписи | Проверьте ключ, сериализацию массива и поля подписи. | | `6009` | Метод или область доступа продавца запрещены. | Проверьте разрешения продавца и владельца игрока | | `6904` | Служба временно недоступна, защита ресурсов одновременного доступа или запросов | Уменьшите параллелизм и уменьшите окна; обратитесь в службу поддержки, если ошибка не исчезнет | | `6905` | Общая квота на шесть типов запросов исчерпана | Отступите и повторите попытку исходной неудачной страницы. | `cursor` и все условия фильтра исходной ошибочной страницы будут сохранены после ограничения тока, тайм-аута или временного сбоя; каждый раз, когда SDK повторно вызывается, будут генерироваться новые `timestamp`, `nonce`, `sign`. Вы не можете сразу перейти к следующей странице и не можете рассматривать неудачи как пустые результаты. SDK не несет ответственности за автоматические повторные попытки транзакций средств. ## Общий ответ и нумерация страниц | Поле | JSON тип | иллюстрировать | | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `code` | integer | Бизнес-код, 0 означает успех; если оно не равно 0, это будет рассматриваться как ошибка, а неудача не будет рассматриваться как пустая страница. | | `message` | string | Описание результатов не является единственным основанием для принятия деловых решений. | | `data` | object | Разбивка на страницы результатов в случае успеха | | `data.items` | array | Записи на этой странице; допустимая пустая страница — `[]` | | `data.nextCursor` | string | Курсор следующей страницы; обычно пустая строка, если нет последующих страниц | | `data.hasMore` | boolean | Есть ли последующие страницы; если это правда, используйте nextCursor для продолжения того же запроса | Структура каждого `data.items[]`: | Поле | JSON тип | иллюстрировать | | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `platformUserId` | string | Публичный идентификатор пользователя платформы, сохраненный в виде строки; не внутренний идентификатор пользователя базы данных | | `entityType` | string | Тип сущности, к которой принадлежит запись, см. в таблице ниже. | | `entityId` | string | Идентификатор текущего объекта объединяется с пользователем платформы и типом объекта для создания локального идемпотентного ключа. | | `data` | object | Сферы деятельности этой организации; разные поля ресурсов различны | | Запросить ресурсы | `entityType` | `entityId` Переписка | | ---------------------------- | ----------------- | -------------------------------------------------------------------------------------- | | Обычный заказ | `ORDER` | `data.orderId` | | условные заказы | `CONDITION_ORDER` | `data.conditionId` | | Детали торгового заполнения | `TRADE_FILL` | `data.fillId`, а не tradeId | | Текущие/исторические позиции | `POSITION` | `data.positionId` | | Записи книги контрактов | `ACCOUNT_LEDGER` | Идентификация деталей изменения одного аккаунта, \*\* не является данными.ledgerId\*\* | Один и тот же `ledgerId` может отделять несколько деталей, таких как плата за обработку, прибыль и убыток и т. д.; нажатие ledgerId для удаления дубликатов приведет к потере данных. ID с разных ресурсов смешивать нельзя. Правила разбиения на страницы и сохранения полей см. в соответствующем руководстве Руководства по доступу. ## Типы, единицы измерения и пропущенные поля * Сумма, цена, количество и идентификатор объекта используют строку; используйте десятичные числа для обработки сумм и не можете использовать числа с плавающей запятой или преобразовывать длинные идентификаторы в числа JavaScript. Валюта суммы и единица измерения объясняются в соответствии со спецификациями торговой пары/контракта. * В рабочем времени используется целое число (int64), оба являются миллисекундами Unix; временная метка запроса аутентификации и учетные данные для входа expireAt занимают секунды и не могут быть перепутаны. * Строковые бизнес-поля обычно не выводятся, если они пусты, а некоторые из них будут опущены, если числовые поля равны 0. **Отсутствующее поле не означает, что бизнес-значение равно 0**. * `reduceOnly`, `closeOnly`, `makerOnly` в общей модели записи не опускают false, поэтому эти три false также могут появляться в транзакциях или позициях. Они объясняются только в ресурсах заказа; нельзя считать, что сделка/позиция выполнила соответствующие правила ордера. * `closePosition` — необязательное логическое значение: предоставляется условными заказами, обычно опускается для других ресурсов. Отсутствие имеет другое значение, чем ложь. * Таблица ниже «предоставляется в настоящее время» означает, что логика чтения имеет источник поля; необязательные поля по-прежнему могут быть опущены, поскольку они не имеют значения. Поля, существующие в модели, не обязательно будут заполнены в каждом интерфейсе. ## Разница между статусом и режимом маржи | ресурс | текущее возвращаемое значение | | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | Текущий статус обычного заказа | NEW, PENDING, PARTIALLY_FILLED | | Исторический статус обычного заказа | FILLED, CANCELED, REJECTED, PARTIAL_FILLED_CANCELED или PARTIALLY_FILLED_CANCELED; сохраните фактическое написание источника | | Текущее состояние заказа / triggerStatus | PENDING_ACTIVATION, PENDING, TRIGGERING | | Статус заказа по историческому состоянию / triggerStatus | TRIGGERED, CANCELLED, REJECTED, FIRED | | Текущий статус позиции | Цифровая строка «1» в позиции, «3» в стадии ликвидации | | Статус исторической позиции | Цифровая строка «2» закрыла позицию, «4» привела к принудительной ликвидации. | Написание CANCELED для обычного заказа отличается от написания CANCELLED для условного заказа; срабатывание условного ордера не означает, что сгенерированный обычный ордер исполнен. Не используйте повторно один и тот же набор таблиц преобразования состояний для всех ресурсов. Условный заказ marginMode возвращает CROSS / ISOLATED; исторические обычные ордера и позиции в настоящее время возвращают «1» / «2», что соответствует перекрестной/изолированной марже соответственно. marginMode в настоящее время недоступен для обычных заказов. Продавцы могут нормализовать по ресурсам на своем собственном слое отображения, при этом исходные значения все равно необходимо сохранить. ## Поля, объявленные в модели, но не предоставленные в этом запросе. Generic RecordData / Java Модель PerpetualData также объявляет следующие поля, но текущая производственная логика чтения с шестью категориями не заполняет их. \*\*Не следует указывать как доступные бизнес-данные, а также не следует заменять значения полей по умолчанию реальными результатами. \*\* | Поле | Тип модели | текущая граница | | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `closeReason` | string | Причины закрытия исторических позиций не указаны. | | `walletDelta` | string | Интерфейс смены аккаунта не возвращает дельту кошелька | | `frozenDelta` | string | Интерфейс смены аккаунта не возвращает замороженную дельту. | | `usedDelta` | string | Интерфейс смены аккаунта не возвращает использованную дельту маржи. | | `feeDelta` | string | Интерфейс смены аккаунта не возвращает разницу комиссий. | | `pnlDelta` | string | Интерфейс смены аккаунта не возвращает дельту прибылей и убытков. | | `accountVersion` | string | Интерфейс изменения учетной записи не возвращает версию учетной записи и не может использоваться для надежной добавочной синхронизации. | | `occurredAt` | integer | Интерфейс смены учетной записи использует createdAt и не предоставляет другой набор времени возникновения событий. | Фактический объем полевого применения зависит от приведенных выше таблиц ресурсов; когда платформа обновляет поля или перечисления, они должны быть адаптированы в соответствии с новым описанием интерфейса и версией SDK. ## Источник и связанные руководства * [Официальный источник v0.3.0](https://github.com/6mm-com/agent-java-sdk/tree/54aa3c1) * [Финансирование кошелька](/ru/sdk/agent-sdk/java/funding-wallet) * [Руководство по обновлению](/ru/sdk/agent-sdk/java/upgrade)