> 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` у [Швидкий старт](/uk/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 унікальних гравців, які мають доступ; на кінцевих точках, які допускають пропуск, запитується лише діапазон прямих гравців, до яких має доступ поточний продавець. Запити Trade-fill завжди потребують цього масиву; запити умовного порядку також вимагають явних ідентифікаторів користувачів. Пропуск не еквівалентний `[]`, а порожні масиви є незаконними. Обсяг визначається продавцем, який підписує, і інші ідентифікатори продавця не можна передати для розширення обсягу. Значення масиву серіалізуються як компактний 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) для спільних полів. Поля ресурсів задокументовані в [Замовлення](/uk/sdk/agent-sdk/java/perpetual-orders), [Торгівля наповнює](/uk/sdk/agent-sdk/java/perpetual-trades), [посади](/uk/sdk/agent-sdk/java/perpetual-positions) і [Договірна книга](/uk/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 | Чи є наступні сторінки; якщо true, використовуйте 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 для видалення дублікатів призведе до втрати даних. Ідентифікатори з різних ресурсів не можна змішувати. Перегляньте пов’язаний посібник із посібника з доступу, щоб дізнатися про правила збереження сторінок і полів. ## Типи, одиниці вимірювання та пропущені поля * Сума, ціна, кількість і ідентифікатор організації використовують рядок; використовувати десяткову систему для обробки сум і не можна використовувати числа з плаваючою комою або перетворювати довгі ідентифікатори на числа JavaScript. Валюта суми та одиниця кількості пояснюються відповідно до специфікацій торгової пари/контракту. * Бізнес-час використовує ціле число (int64), обидва є мілісекундами Unix; мітка часу запиту автентифікації та облікові дані входу expireAt використовують секунди, і їх не можна сплутати. * Рядкові бізнес-поля зазвичай не виводяться, якщо вони порожні, а деякі будуть пропущені, якщо числові поля дорівнюють 0. **Відсутнє поле не означає, що бізнес-значення дорівнює 0**. * `reduceOnly`, `closeOnly`, `makerOnly` у загальній моделі запису не пропускають false, тому ці три false також можуть з’являтися в транзакціях або позиціях. Вони пояснюються лише в ресурсах замовлення; не можна вважати, що транзакція/позиція виконувала відповідні правила замовлення. * `closePosition` є необов’язковим логічним значенням: надається умовними замовленнями, які зазвичай опускаються для інших ресурсів. Missing має інше значення, ніж false. * Таблиця нижче «надано на даний момент» означає, що логіка читання має джерело поля; необов'язкові поля все ще можуть бути пропущені, оскільки вони не мають значення. Поля, які існують у моделі, не гарантовано будуть заповнені в кожному інтерфейсі. ## Різниця між статусом і маржинальним режимом | ресурс | поточне значення, що повертається | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Поточний статус звичайного замовлення | 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) * [Гаманець для фінансування](/uk/sdk/agent-sdk/java/funding-wallet) * [Посібник з оновлення](/uk/sdk/agent-sdk/java/upgrade)