> 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.

# Ciągłe zapytania i paginacja

Ten przewodnik jest przeznaczony dla **Agent Java SDK `v0.3.0`**, Java 8+ i oznaczonych zamówień publicznych. Przykłady działają w zapleczu partnera po inicjalizacji `client` w [Szybki start](/pl/sdk/agent-sdk/java/quick-start).

## Przykładowe wymagania wstępne

Fragmenty Java dzielą ten import. Zainicjuj `client` za pomocą Szybki start i uzyskaj `platformUserId` z zapisanego powiązania. Przykładowe identyfikatory użytkowników/zamówień należy zastąpić własnymi, utrwalonymi wartościami.

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

## Zapytanie o dane dotyczące umowy bezterminowej

### Sześć typów interfejsów i metod Java.

Wszystkie żądania są podpisane POST wspólnym prefiksem `/v1/agent/perpetual`.

| przyrostek ścieżki   | Java Metoda/typ żądania                                           | zasięg gracza                                                          |
| -------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `/orders/current`    | `listCurrentPerpetualOrders(CurrentPerpetualOrdersRequest)`       | NORMAL Gracz może zostać pominięty; CONDITIONAL Należy określić gracza |
| `/orders/history`    | `listPerpetualOrderHistory(PerpetualOrderHistoryRequest)`         | To samo co powyżej                                                     |
| `/trades`            | `listPerpetualTrades(PerpetualTradesRequest)`                     | Należy określić gracza                                                 |
| `/positions/current` | `listCurrentPerpetualPositions(CurrentPerpetualPositionsRequest)` | Graczy można pominąć                                                   |
| `/positions/history` | `listPerpetualPositionHistory(PerpetualPositionHistoryRequest)`   | Graczy można pominąć                                                   |
| `/account/ledger`    | `listPerpetualLedger(PerpetualLedgerRequest)`                     | Graczy można pominąć                                                   |

`platformUserIds` to tablica ciągów zawierająca identyfikatory platform publicznych. Jeśli określono, wymaganych jest od 1 do 100 unikalnych graczy mających dostęp; na punktach końcowych, które pozwalają na pominięcie, sprawdzany jest tylko zakres bezpośrednich graczy, do których bieżący sprzedawca ma dostęp. Zapytania wypełniające transakcje zawsze wymagają tej tablicy; zapytania kolejności warunkowej również wymagają jawnych identyfikatorów użytkowników. Pominięcie nie jest równoznaczne z `[]`, a puste tablice są nielegalne. Zakres jest określany przez sprzedawcę podpisującego i nie można przekazać innych identyfikatorów sprzedawców w celu rozszerzenia zakresu.

Wartości tablicy są serializowane jako kompaktowe JSON przed dołączeniem do ładunku podpisującego. Na przykład `platformUserIds` znakuje jako `["1188041528"]`, podając `platformUserIds=["1188041528"]` w ładunku `k=v`. Zachowaj kolejność elementów tablicy, podwójne cudzysłowy i identyfikatory ciągów; nie wstawiaj spacji formatujących ani nie używaj Java `List.toString()` (np. `[1188041528]`). SDK automatycznie obsługuje tę serializację.

Zapytanie o zamówienie musi przejść `orderCategory=NORMAL` lub `CONDITIONAL`. Użyj `orderId` dla zleceń zwykłych i `conditionId` dla zleceń warunkowych. Nie można ich mieszać w różnych kategoriach. Zlecenia warunkowe oraz zlecenia zwykłe generowane w wyniku ich uruchomienia przetwarzane są oddzielnie jako byty.

### Warunki filtra

| Zapytanie              | Dostępne filtry biznesowe                                                                                      |
| ---------------------- | -------------------------------------------------------------------------------------------------------------- |
| Aktualne zamówienie    | `orderCategory`, `symbol`                                                                                      |
| porządek historyczny   | `orderCategory`, `symbol`, `startTime`, `endTime`, `orderId`, `conditionId`, `clientOrderId`, `side`, `status` |
| zawrzeć umowę          | `symbol`, `startTime`, `endTime`, `orderId`                                                                    |
| Aktualna pozycja       | `symbol`                                                                                                       |
| Stanowiska historyczne | `symbol`, `startTime`, `endTime`, `positionSide`                                                               |
| Zmiany w umowie        | `startTime`, `endTime`, `assetType`, `changeType`                                                              |

Czas zapytania historycznego to Unix **milisekundy**, a interwał to `[startTime, endTime)`; czas żądania podpisu to `timestamp` to Unix **sekund**. Zalecane jest naprawienie okna czasowego UTC i zapytanie w segmentach; używaj UTC do codziennego pojednania. Status i typ korzystają z wyliczenia umów platformy i nie są same w sobie tłumaczone na chińskie ciągi znaków.

`limit` Wartość domyślna to 500, zakres to 1\~1000; rozmiar strony nie gwarantuje, że za każdym razem zostanie zwrócona ta sama liczba. Sześć interfejsów ma obecnie wspólny limit zapytań wynoszący 2 razy na sekundę i 4 serie na sprzedawcę, a maksymalny limit współbieżności dla każdego sprzedawcy w instancji wynosi 2. Strona sprzedawcy korzysta z ujednoliconej kolejki i zaleca się rozpoczęcie od stronicowania sekwencyjnego i mniejszego okna historii.

### Java przykłady zapytań

Zapytaj o bieżący zwyczajny porządek gracza:

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

Zapytaj o zmiany w umowie w ciągu ostatniej godziny i przetwórz kursor. Poniższy przykład nie powoduje automatycznego ponawiania próby; gdy rzeczywista aplikacja napotka bieżące ograniczenie lub tymczasową awarię, postępuj zgodnie z powiązanym przewodnikiem, aby przywrócić tę samą stronę.

```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<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.
}
```

### Struktura zwrotów i zasady zapisywania

Widzieć [Wspólna odpowiedź i paginacja](#common-response-and-pagination) dla wspólnych pól. Pola zasobów są udokumentowane w [Święcenia](/pl/sdk/agent-sdk/java/perpetual-orders), [Handel wypełnia](/pl/sdk/agent-sdk/java/perpetual-trades), [Pozycje](/pl/sdk/agent-sdk/java/perpetual-positions) I [Księga kontraktowa](/pl/sdk/agent-sdk/java/perpetual-ledger).

Sześć interfejsów równomiernie zwraca `PerpetualResponse`:

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

Każde `items` zawiera `platformUserId`, `entityType`, `entityId`, `data`. Typy jednostek obejmują `ORDER`, `CONDITION_ORDER`, `TRADE_FILL`, `POSITION`, `ACCOUNT_LEDGER`. Użyj tych trzech pól tożsamości, aby zbudować klucz idempotentny; nie traktuj identyfikatora zamówienia warunkowego, identyfikatora zamówienia i identyfikatora wypełnienia jako tego samego numeru.

`data` Zawiera pola, takie jak cena, ilość, status, wydatek, zysk i strata lub zmiana salda według zasobu. Kwota, cena, ilość i identyfikator jednostki są traktowane jako ciągi znaków; czas biznesowy jest podawany w milisekundach. Brakujące pola nie są uzupełniane do wartości 0 i nie są wnioskowane z innych podmiotów.

Kursor to pozycja stronicowania zapytania, a nie niezawodna subskrypcja przyrostowa ani gwarantowana migawka atomowa między stronami. Aktualny kursor obowiązuje przez 24 godziny od pierwszej rundy generowania; kolejne strony zachowują tych samych sprzedawców, zasoby, kolekcje graczy i warunki filtrów. Stałe okno historycznego ściągania jest idempotentne przy wielokrotnym wyciąganiu; status bieżącego zamówienia/pozycji jest odświeżany po ponownym zapytaniu. Gdy potrzebny jest interfejs czasu rzeczywistego, używany jest mechanizm danych frontonu platformy, a interfejsu odpytywania szóstego nie można uważać za interfejs rynkowy o wysokiej częstotliwości.

### Błędy i odzyskiwanie

HTTP sukces nie oznacza sukcesu biznesowego, musisz sprawdzić `code`. Java SDK zgłosi błąd biznesowy jako `AgentApiException`.

| Kod biznesowy | Typowe znaczenie                                                                              | Obsługiwanie                                                                                                |
| ------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `102001`      | Brakuje wymaganych parametrów, na przykład w zapytaniu o zamówienie warunkowe brakuje graczy. | Podaj brakujące parametry                                                                                   |
| `102002`      | Niedozwolone parametry, pusta tablica, niedopasowany kursor lub wygasły                       | Popraw parametry; ponownie sprawdź stałe okno po wyczyszczeniu wygasłego kursora i zapisz je idempotentnie. |
| `102003`      | Niedozwolony limit, liczba graczy lub zakres czasu                                            | Wąski lub prawidłowy zakres                                                                                 |
| `6001`        | Błąd podpisu                                                                                  | Sprawdź klucz, serializację tablicy i pola podpisu                                                          |
| `6009`        | Metoda dostępu sprzedawcy lub zakres dostępu są niedozwolone                                  | Sprawdź uprawnienia sprzedawcy i własność gracza                                                            |
| `6904`        | Usługa jest chwilowo niedostępna, ochrona zasobów współbieżności lub zapytań                  | Zmniejsz współbieżność i zmniejsz okna; skontaktuj się z pomocą techniczną, jeśli błąd będzie się powtarzał |
| `6905`        | Udostępniony limit dla sześciu typów zapytań został wyczerpany                                | Wycofaj się, a następnie spróbuj ponownie uruchomić oryginalną stronę, która się nie powiodła               |

`cursor` i wszystkie warunki filtra oryginalnej strony, która uległa awarii, zostaną zachowane po ograniczeniu prądu, przekroczeniu limitu czasu lub tymczasowej awarii; za każdym razem, gdy zostanie ponownie wywołane SDK, zostaną wygenerowane nowe `timestamp`, `nonce`, `sign`. Nie możesz przejść bezpośrednio do następnej strony i nie możesz traktować niepowodzeń jako pustych rezultatów. SDK nie jest odpowiedzialny za automatyczne ponawianie transakcji funduszami.

## Wspólna odpowiedź i paginacja

| Pole              | JSON typ | zilustrować                                                                                                                             |
| ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `code`            | integer  | Kod biznesowy, 0 oznacza sukces; jeśli nie jest to 0, będzie to traktowane jako błąd, a awaria nie będzie traktowana jako pusta strona. |
| `message`         | string   | Opis wyników nie jest jedyną podstawą oceny biznesowej.                                                                                 |
| `data`            | object   | Paginowane wyniki w przypadku sukcesu                                                                                                   |
| `data.items`      | array    | Rekordy na tej stronie; legalna pusta strona to `[]`                                                                                    |
| `data.nextCursor` | string   | Kursor następnej strony; zwykle pusty ciąg znaków, jeśli nie ma kolejnych stron                                                         |
| `data.hasMore`    | boolean  | Czy istnieją kolejne strony; jeśli prawda, użyj nextCursor, aby kontynuować to samo zapytanie                                           |

Struktura każdego `data.items[]`:

| Pole             | JSON typ | zilustrować                                                                                                                                      |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `platformUserId` | string   | Publiczny identyfikator użytkownika platformy, zapisany w postaci ciągu znaków; nie wewnętrzny identyfikator użytkownika bazy danych             |
| `entityType`     | string   | Typ jednostki, do której należy rekord, patrz tabela poniżej                                                                                     |
| `entityId`       | string   | Identyfikator bieżącej jednostki jest łączony z użytkownikiem platformy i typem jednostki w celu skonstruowania lokalnego idempotentnego klucza. |
| `data`           | object   | Obszary działalności tego podmiotu; różne pola zasobów są różne                                                                                  |

| Zapytanie o zasoby               | `entityType`      | `entityId` Korespondencja                                                             |
| -------------------------------- | ----------------- | ------------------------------------------------------------------------------------- |
| Zwykły porządek                  | `ORDER`           | `data.orderId`                                                                        |
| zamówienia warunkowe             | `CONDITION_ORDER` | `data.conditionId`                                                                    |
| Szczegóły wypełnienia transakcji | `TRADE_FILL`      | `data.fillId`, a nie tradeId                                                          |
| Aktualne/historyczne pozycje     | `POSITION`        | `data.positionId`                                                                     |
| Zapisy w księdze kontraktów      | `ACCOUNT_LEDGER`  | Identyfikacja szczegółów zmiany pojedynczego konta, \*\* nie jest danymi.ledgerId\*\* |

To samo `ledgerId` może oddzielić wiele szczegółów, takich jak opłaty manipulacyjne, zyski i straty itp.; naciśnięcie ledgerId w celu usunięcia duplikatów spowoduje utratę danych. Nie można mieszać identyfikatorów z różnych zasobów. Zobacz powiązany przewodnik w Przewodniku dostępu, aby zapoznać się z zasadami stronicowania i zapisywania pól.

## Rodzaje, jednostki i pola pomijane

* Kwota, cena, ilość i ciąg znaków identyfikacyjny jednostki; używaj liczb dziesiętnych do przetwarzania kwot i nie możesz używać liczb zmiennoprzecinkowych ani konwertować długich identyfikatorów na liczby JavaScript. Waluta kwoty i jednostka ilości są wyjaśnione zgodnie ze specyfikacjami pary handlowej/kontraktu.
* Czas biznesowy wykorzystuje liczbę całkowitą (int64), obie są milisekundami uniksowymi; sygnatura czasowa żądania uwierzytelnienia i dane uwierzytelniające expireAt używają sekund i nie można ich pomylić.
* Pola biznesowe typu string zwykle nie są wyświetlane, gdy są puste, a niektóre zostaną pominięte, gdy pola numeryczne mają wartość 0. **Brakujące pole nie oznacza, że ​​wartość biznesowa wynosi 0**.
* `reduceOnly`, `closeOnly`, `makerOnly` w ogólnym modelu rekordu nie pomijają fałszu, więc te trzy fałsze mogą również pojawić się w transakcjach lub pozycjach. Są one wyjaśnione jedynie w zasobach zamówienia; nie można uznać, że transakcja/pozycja wykonała odpowiednie reguły dotyczące zleceń.
* `closePosition` to opcjonalna wartość logiczna: dostarczana przez zamówienia warunkowe, zwykle pomijana w przypadku innych zasobów. Brak ma inne znaczenie niż fałsz.
* Poniższa tabela „obecnie dostępna” oznacza, że ​​logika odczytu ma źródło pola; pola opcjonalne można w dalszym ciągu pominąć, ponieważ nie mają one żadnej wartości. Nie ma gwarancji, że pola istniejące w modelu zostaną wypełnione w każdym interfejsie.

## Różnica między trybem statusu i marginesu

| ratunek                                             | bieżąca wartość zwracana                                                                                                  |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Aktualny stan zamówienia zwykłego                   | NEW, PENDING, PARTIALLY_FILLED                                                                                            |
| Historyczny status zamówienia zwykłego              | FILLED, CANCELED, REJECTED, PARTIAL_FILLED_CANCELED lub PARTIALLY_FILLED_CANCELED; zachowaj rzeczywistą pisownię źródłową |
| Stan aktualny status zamówienia / triggerStatus     | PENDING_ACTIVATION, PENDING, TRIGGERING                                                                                   |
| Stan zamówienia stanu historycznego / triggerStatus | TRIGGERED, CANCELLED, REJECTED, FIRED                                                                                     |
| Aktualny stan pozycji                               | Ciąg numeryczny „1” jest na pozycji, „3” jest w likwidacji                                                                |
| Stan pozycji historycznej                           | Ciąg numeryczny „2” zamknął pozycję, „4” wymusił likwidację                                                               |

Pisownia CANCELED w przypadku zamówienia zwykłego różni się od pisowni CANCELLED w przypadku zamówienia warunkowego; uruchomienie zlecenia warunkowego nie oznacza, że ​​wygenerowane zlecenie zwykłe zostało zrealizowane. Nie używaj ponownie tego samego zestawu tabel translacji statusów dla wszystkich zasobów.

Kolejność warunkowa marginMode zwraca CROSS / ISOLATED; historyczne zwykłe zlecenia i pozycje obecnie zwracają „1” / „2”, które stanowią odpowiednio depozyt krzyżowy/izolowany. marginMode nie jest obecnie dostępny dla zwykłych zamówień. Sprzedawcy mogą normalizować zasoby we własnej warstwie wyświetlania, a oryginalne wartości nadal muszą zostać zapisane.

## Pola zadeklarowane w modelu, ale nie podane w tym zapytaniu

Generic RecordData / Java Model PerpetualData deklaruje również następujące pola, ale bieżąca logika odczytu produkcyjnego sześciu kategorii nie wypełnia ich. \*\*Nie należy podawać jako dostępnych danych biznesowych ani nie należy zastępować rzeczywistych wyników wartościami domyślnymi pól. \*\*

| Pole             | Typ modelu | obecną granicę                                                                                                   |
| ---------------- | ---------- | ---------------------------------------------------------------------------------------------------------------- |
| `closeReason`    | string     | Nie podano powodów zamknięcia pozycji historycznych                                                              |
| `walletDelta`    | string     | Interfejs zmiany konta nie zwraca delty portfela                                                                 |
| `frozenDelta`    | string     | Interfejs zmiany konta nie zwraca zamrożonej delty                                                               |
| `usedDelta`      | string     | Interfejs zmiany konta nie zwraca wykorzystanej delty depozytu zabezpieczającego                                 |
| `feeDelta`       | string     | Interfejs zmiany konta nie zwraca różnicy opłat                                                                  |
| `pnlDelta`       | string     | Interfejs zmiany konta nie zwraca delty zysków i strat                                                           |
| `accountVersion` | string     | Interfejs zmiany konta nie zwraca wersji konta i nie można go używać do niezawodnej synchronizacji przyrostowej. |
| `occurredAt`     | integer    | Interfejs zmiany konta wykorzystuje createdAt i nie zapewnia innego zestawu czasów wystąpienia zdarzeń.          |

Rzeczywisty zakres zastosowań terenowych podlega powyższym tabelom zasobów; w przypadku aktualizacji pól lub wyliczeń platforma zostanie dostosowana zgodnie z nowym opisem interfejsu i wersją SDK.

## Źródło i powiązane przewodniki

* [Oficjalne źródło v0.3.0](https://github.com/6mm-com/agent-java-sdk/tree/54aa3c1)
* [Portfel finansowania](/pl/sdk/agent-sdk/java/funding-wallet)
* [Przewodnik po aktualizacji](/pl/sdk/agent-sdk/java/upgrade)