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

# Truy vấn & phân trang vĩnh viễn

Hướng dẫn này hướng tới **Agent Java SDK `v0.3.0`**, Java 8+ và hợp đồng công khai được gắn thẻ. Các ví dụ chạy trong phần phụ trợ của đối tác sau khi khởi tạo `client` trong [Bắt đầu nhanh](/vi/sdk/agent-sdk/java/quick-start).

## Điều kiện tiên quyết mẫu

Đoạn mã Java chia sẻ những nội dung nhập này. Khởi tạo `client` bằng cách sử dụng Bắt đầu nhanh và lấy `platformUserId` từ liên kết đã lưu. ID người dùng/đơn đặt hàng mẫu phải được thay thế bằng các giá trị cố định của riêng bạn.

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

## Truy vấn dữ liệu hợp đồng vĩnh cửu

### Sáu loại giao diện và phương thức Java

Tất cả các yêu cầu đều được ký POST với tiền tố chung là `/v1/agent/perpetual`.

| hậu tố đường dẫn     | Java Phương thức/Loại yêu cầu                                     | phạm vi người chơi                                                              |
| -------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `/orders/current`    | `listCurrentPerpetualOrders(CurrentPerpetualOrdersRequest)`       | NORMAL Người chơi có thể được bỏ qua; CONDITIONAL Người chơi phải được chỉ định |
| `/orders/history`    | `listPerpetualOrderHistory(PerpetualOrderHistoryRequest)`         | Tương tự như trên                                                               |
| `/trades`            | `listPerpetualTrades(PerpetualTradesRequest)`                     | Người chơi phải được chỉ định                                                   |
| `/positions/current` | `listCurrentPerpetualPositions(CurrentPerpetualPositionsRequest)` | Người chơi có thể được bỏ qua                                                   |
| `/positions/history` | `listPerpetualPositionHistory(PerpetualPositionHistoryRequest)`   | Người chơi có thể được bỏ qua                                                   |
| `/account/ledger`    | `listPerpetualLedger(PerpetualLedgerRequest)`                     | Người chơi có thể được bỏ qua                                                   |

`platformUserIds` là một chuỗi ID nền tảng công cộng. Khi được chỉ định, cần có 1 đến 100 người chơi duy nhất có quyền truy cập; trên các điểm cuối cho phép bỏ qua, chỉ có phạm vi người chơi trực tiếp mà người bán hiện tại có quyền truy cập mới được truy vấn. Các truy vấn điền vào giao dịch luôn yêu cầu mảng này; truy vấn thứ tự có điều kiện cũng yêu cầu ID người dùng rõ ràng. Thiếu sót không tương đương với `[]` và mảng trống là bất hợp pháp. Phạm vi được xác định bởi người bán ký tên và các ID người bán khác không thể được chuyển để mở rộng phạm vi.

Các giá trị mảng được tuần tự hóa dưới dạng JSON nhỏ gọn trước khi tham gia tải trọng ký. Ví dụ: `platformUserIds` ký hiệu là `["1188041528"]`, cung cấp `platformUserIds=["1188041528"]` trong tải trọng `k=v`. Giữ nguyên thứ tự phần tử mảng, dấu ngoặc kép và ID chuỗi; không chèn khoảng trắng định dạng hoặc sử dụng Java `List.toString()` (chẳng hạn như `[1188041528]`). SDK tự động xử lý việc tuần tự hóa này.

Truy vấn thứ tự phải vượt qua `orderCategory=NORMAL` hoặc `CONDITIONAL`. Sử dụng `orderId` cho các lệnh thông thường và `conditionId` cho các lệnh có điều kiện. Chúng không thể được trộn lẫn giữa các danh mục. Lệnh có điều kiện và lệnh thông thường được tạo bằng cách kích hoạt chúng được xử lý riêng biệt dưới dạng thực thể.

### Điều kiện lọc

| Truy vấn                 | Bộ lọc doanh nghiệp có sẵn                                                                                     |
| ------------------------ | -------------------------------------------------------------------------------------------------------------- |
| Thứ tự hiện tại          | `orderCategory`, `symbol`                                                                                      |
| trật tự lịch sử          | `orderCategory`, `symbol`, `startTime`, `endTime`, `orderId`, `conditionId`, `clientOrderId`, `side`, `status` |
| thực hiện một thỏa thuận | `symbol`, `startTime`, `endTime`, `orderId`                                                                    |
| Vị trí hiện tại          | `symbol`                                                                                                       |
| Vị trí lịch sử           | `symbol`, `startTime`, `endTime`, `positionSide`                                                               |
| Thay đổi hợp đồng        | `startTime`, `endTime`, `assetType`, `changeType`                                                              |

Thời gian của truy vấn lịch sử là Unix **mili giây** và khoảng thời gian là `[startTime, endTime)`; thời điểm yêu cầu chữ ký là `timestamp` là Unix **giây**. Bạn nên sửa cửa sổ thời gian và truy vấn UTC theo từng phân đoạn; sử dụng UTC để đối chiếu hàng ngày. Trạng thái và loại liệt kê hợp đồng nền tảng sử dụng và bản thân chúng không được dịch sang chuỗi tiếng Trung.

`limit` Mặc định là 500, phạm vi là 1\~1000; kích thước trang không đảm bảo rằng cùng một số sẽ được trả về mỗi lần. Sáu giao diện hiện chia sẻ hạn mức truy vấn 2 lần mỗi giây và 4 cụm cho mỗi người bán, đồng thời giới hạn đồng thời tối đa cho mỗi người bán trong phiên bản là 2. Phía người bán sử dụng hàng đợi thống nhất và bạn nên bắt đầu với phân trang tuần tự và cửa sổ lịch sử nhỏ hơn.

### Java ví dụ về truy vấn

Truy vấn thứ tự thông thường hiện tại của người chơi:

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

Truy vấn các thay đổi hợp đồng trong giờ qua và xử lý con trỏ. Ví dụ sau không tự động thử lại; khi ứng dụng thực tế gặp phải giới hạn hiện tại hoặc lỗi tạm thời, hãy làm theo hướng dẫn liên quan được liên kết để khôi phục cùng một trang.

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

### Cấu trúc trả về và quy tắc lưu

Nhìn thấy [Phản hồi và phân trang chung](#common-response-and-pagination) cho các trường được chia sẻ. Các trường tài nguyên được ghi lại trong [Đơn đặt hàng](/vi/sdk/agent-sdk/java/perpetual-orders), [Giao dịch lấp đầy](/vi/sdk/agent-sdk/java/perpetual-trades), [Vị trí](/vi/sdk/agent-sdk/java/perpetual-positions) Và [Sổ hợp đồng](/vi/sdk/agent-sdk/java/perpetual-ledger).

Sáu giao diện trả về thống nhất `PerpetualResponse`:

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

Mỗi `items` chứa `platformUserId`, `entityType`, `entityId`, `data`. Các loại thực thể bao gồm `ORDER`, `CONDITION_ORDER`, `TRADE_FILL`, `POSITION`, `ACCOUNT_LEDGER`. Sử dụng ba trường nhận dạng này để tạo khóa bình thường; không coi ID đơn hàng có điều kiện, ID đơn hàng và ID điền là cùng một số.

`data` Cung cấp các trường như giá, số lượng, trạng thái, chi phí, lãi và lỗ hoặc thay đổi số dư theo tài nguyên. Số tiền, giá, số lượng và ID thực thể được xử lý dưới dạng chuỗi; thời gian kinh doanh tính bằng mili giây. Các trường bị thiếu không được điền vào 0 và không được suy ra từ các thực thể khác.

Con trỏ là vị trí phân trang của một truy vấn, không phải là đăng ký gia tăng đáng tin cậy cũng không phải là ảnh chụp nhanh nguyên tử xuyên trang được đảm bảo. Con trỏ hiện tại có hiệu lực trong 24 giờ kể từ vòng tạo đầu tiên; phân trang tiếp theo vẫn giữ nguyên các thương gia, tài nguyên, bộ sưu tập người chơi và điều kiện lọc. Cửa sổ cố định cho lực kéo lịch sử là bình thường khi được kéo liên tục; trạng thái của đơn hàng/vị trí hiện tại được làm mới sau khi truy vấn lại. Khi cần giao diện thời gian thực, cơ chế dữ liệu của giao diện người dùng nền tảng sẽ được sử dụng và giao diện thăm dò sáu không thể được coi là giao diện thị trường tần số cao.

### Lỗi và phục hồi

HTTP thành công không có nghĩa là thành công trong kinh doanh, bạn phải đánh dấu vào `code`. Java SDK sẽ đưa ra lỗi kinh doanh dưới dạng `AgentApiException`.

| Mã doanh nghiệp | Ý nghĩa điển hình                                                             | Xử lý                                                                                                  |
| --------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `102001`        | Thiếu tham số bắt buộc, ví dụ: truy vấn thứ tự có điều kiện thiếu người chơi. | Cung cấp các thông số còn thiếu                                                                        |
| `102002`        | Tham số không hợp lệ, mảng trống, con trỏ không khớp hoặc đã hết hạn          | Hiệu chỉnh các thông số; kiểm tra lại cửa sổ đã sửa sau khi xóa con trỏ đã hết hạn và lưu nó tạm thời. |
| `102003`        | Giới hạn bất hợp pháp, số lượng người chơi hoặc phạm vi thời gian             | Phạm vi hẹp hoặc chính xác                                                                             |
| `6001`          | Lỗi chữ ký                                                                    | Kiểm tra khóa, tuần tự hóa mảng và các trường chữ ký                                                   |
| `6009`          | Phương thức truy cập của người bán hoặc phạm vi truy cập không được phép      | Kiểm tra quyền của người bán và quyền sở hữu người chơi                                                |
| `6904`          | Dịch vụ tạm thời không khả dụng, đồng thời hoặc bảo vệ tài nguyên truy vấn    | Giảm tính tương tranh và thu nhỏ cửa sổ; liên hệ với bộ phận hỗ trợ nếu lỗi vẫn còn                    |
| `6905`          | Hạn ngạch chia sẻ cho sáu loại truy vấn đã hết                                | Quay lại, sau đó thử lại trang bị lỗi ban đầu                                                          |

`cursor` và tất cả các điều kiện lọc của trang ban đầu bị lỗi sẽ được giữ lại sau khi giới hạn hiện tại, hết thời gian chờ hoặc lỗi tạm thời; mỗi lần SDK được gọi lại, `timestamp`, `nonce`, `sign` mới sẽ được tạo. Bạn không thể chuyển thẳng sang trang tiếp theo và bạn không thể coi thất bại là kết quả trống rỗng. SDK không chịu trách nhiệm về việc tự động thử lại các giao dịch quỹ.

## Phản hồi và phân trang chung

| Cánh đồng         | JSON loại | minh họa                                                                                                         |
| ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------- |
| `code`            | integer   | Mã doanh nghiệp, 0 nghĩa là thành công; nếu khác 0 thì sẽ bị coi là lỗi và lỗi sẽ không được coi là trang trống. |
| `message`         | string    | Việc mô tả kết quả không phải là cơ sở duy nhất để đánh giá hoạt động kinh doanh.                                |
| `data`            | object    | Kết quả được phân trang khi thành công                                                                           |
| `data.items`      | array     | Hồ sơ trên trang này; trang trống hợp pháp là `[]`                                                               |
| `data.nextCursor` | string    | con trỏ trang tiếp theo; thường là một chuỗi trống nếu không có trang tiếp theo                                  |
| `data.hasMore`    | boolean   | Có trang tiếp theo hay không; khi đúng, hãy sử dụng nextCursor để tiếp tục truy vấn tương tự                     |

Cấu trúc của mỗi `data.items[]`:

| Cánh đồng        | JSON loại | minh họa                                                                                                                      |
| ---------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `platformUserId` | string    | ID người dùng công khai của nền tảng, được lưu dưới dạng chuỗi; không phải ID người dùng cơ sở dữ liệu nội bộ                 |
| `entityType`     | string    | Loại thực thể chứa bản ghi, xem bảng bên dưới                                                                                 |
| `entityId`       | string    | Mã định danh của thực thể hiện tại được kết hợp với người dùng nền tảng và loại thực thể để xây dựng khóa bình thường cục bộ. |
| `data`           | object    | Lĩnh vực kinh doanh của đơn vị này; các trường tài nguyên khác nhau là khác nhau                                              |

| Tài nguyên truy vấn     | `entityType`      | `entityId` Thư từ                                                                       |
| ----------------------- | ----------------- | --------------------------------------------------------------------------------------- |
| Thứ tự thông thường     | `ORDER`           | `data.orderId`                                                                          |
| lệnh có điều kiện       | `CONDITION_ORDER` | `data.conditionId`                                                                      |
| Chi tiết điền giao dịch | `TRADE_FILL`      | `data.fillId`, không phải tradeId                                                       |
| Vị trí hiện tại/lịch sử | `POSITION`        | `data.positionId`                                                                       |
| Sổ nhật ký hợp đồng     | `ACCOUNT_LEDGER`  | Nhận dạng chi tiết thay đổi tài khoản duy nhất, \*\* không phải là dữ liệu.ledgerId\*\* |

Cùng một `ledgerId` có thể phân tách nhiều chi tiết như phí xử lý, lãi lỗ, v.v.; nhấn ledgerId để xóa trùng lặp sẽ gây mất dữ liệu. Không thể trộn lẫn ID từ các nguồn khác nhau. Xem hướng dẫn liên quan được liên kết của Hướng dẫn truy cập để biết các quy tắc phân trang và lưu trường.

## Loại, đơn vị và các trường bị bỏ qua

* Chuỗi sử dụng số lượng, giá cả, số lượng và ID thực thể; sử dụng số thập phân để xử lý số tiền và không thể sử dụng số dấu phẩy động hoặc chuyển đổi ID dài thành Số JavaScript. Số lượng tiền tệ và đơn vị số lượng được giải thích theo thông số kỹ thuật của cặp giao dịch/hợp đồng.
* Thời gian kinh doanh sử dụng số nguyên (int64), cả hai đều là mili giây Unix; yêu cầu dấu thời gian xác thực và thông tin đăng nhập expireAt sử dụng giây và không thể nhầm lẫn.
* Các trường kinh doanh chuỗi thường không được xuất ra khi chúng trống và một số trường sẽ bị bỏ qua khi trường số bằng 0. **Trường bị thiếu không có nghĩa là giá trị kinh doanh là 0**.
* `reduceOnly`, `closeOnly`, `makerOnly` trong mô hình bản ghi chung không bỏ sót sai, vì vậy ba sai này cũng có thể xuất hiện trong các giao dịch hoặc vị thế. Chúng chỉ được giải thích trong tài nguyên đặt hàng; không thể coi giao dịch/vị trí được thực hiện theo các quy tắc lệnh tương ứng.
* `closePosition` là một boolean tùy chọn: được cung cấp bởi các lệnh có điều kiện, thường bị bỏ qua đối với các tài nguyên khác. Thiếu có một ý nghĩa khác với sai.
* Bảng bên dưới "hiện được cung cấp" có nghĩa là logic đọc có nguồn trường; các trường tùy chọn vẫn có thể bị bỏ qua vì chúng không có giá trị. Các trường tồn tại trong mô hình không được đảm bảo sẽ được điền đầy đủ trong mọi giao diện.

## Sự khác biệt giữa trạng thái và chế độ ký quỹ

| tài nguyên                                                | giá trị trả về hiện tại                                                                                               |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Trạng thái đơn hàng thông thường hiện tại                 | NEW, PENDING, PARTIALLY_FILLED                                                                                        |
| Trạng thái đơn hàng thông thường trong lịch sử            | FILLED, CANCELED, REJECTED, PARTIAL_FILLED_CANCELED hoặc PARTIALLY_FILLED_CANCELED; giữ nguyên chính tả nguồn thực tế |
| Trạng thái đơn hàng tình trạng hiện tại / triggerStatus   | PENDING_ACTIVATION, PENDING, TRIGGERING                                                                               |
| Trạng thái đơn đặt hàng điều kiện lịch sử / triggerStatus | TRIGGERED, CANCELLED, REJECTED, FIRED                                                                                 |
| Trạng thái vị trí hiện tại                                | Chuỗi số “1” đang ở vị trí, “3” đang ở trạng thái thanh lý                                                            |
| Trạng thái vị trí lịch sử                                 | Chuỗi số “2” đã đóng vị thế, “4” buộc phải thanh lý                                                                   |

Cách viết của CANCELED đối với lệnh thông thường khác với CANCELLED đối với lệnh có điều kiện; việc kích hoạt lệnh có điều kiện không có nghĩa là lệnh thông thường được tạo đã được khớp. Không sử dụng lại cùng một bộ bảng dịch trạng thái cho tất cả các tài nguyên.

Lệnh có điều kiện marginMode trả về CROSS / ISOLATED; các lệnh và vị thế thông thường trong lịch sử hiện trả về "1" / "2", tương ứng là ký quỹ chéo/cô lập. marginMode hiện không áp dụng cho các đơn hàng thông thường. Người bán có thể chuẩn hóa theo tài nguyên trong lớp hiển thị của riêng họ và vẫn cần lưu các giá trị ban đầu.

## Các trường được khai báo trong mô hình nhưng không được cung cấp trong truy vấn này

Generic RecordData / Java Mô hình PerpetualData cũng khai báo các trường sau, nhưng logic đọc sản xuất sáu danh mục hiện tại không điền chúng. \*\*Không được liệt kê dưới dạng dữ liệu kinh doanh có sẵn và các giá trị mặc định của trường cũng không được thay thế cho kết quả thực. \*\*

| Cánh đồng        | Loại mô hình | ranh giới hiện tại                                                                                                       |
| ---------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `closeReason`    | string       | Lý do đóng các vị trí lịch sử không được cung cấp                                                                        |
| `walletDelta`    | string       | Giao diện đổi tài khoản không trả về ví delta                                                                            |
| `frozenDelta`    | string       | Giao diện thay đổi tài khoản không trả về delta bị đóng băng                                                             |
| `usedDelta`      | string       | Giao diện thay đổi tài khoản không trả về delta ký quỹ đã sử dụng                                                        |
| `feeDelta`       | string       | Giao diện đổi tài khoản không trả về delta phí                                                                           |
| `pnlDelta`       | string       | Giao diện thay đổi tài khoản không trả về lãi lỗ delta                                                                   |
| `accountVersion` | string       | Giao diện thay đổi tài khoản không trả về phiên bản tài khoản và không thể sử dụng để đồng bộ hóa gia tăng đáng tin cậy. |
| `occurredAt`     | integer      | Giao diện thay đổi tài khoản sử dụng createdAt và không cung cấp tập hợp thời gian xảy ra sự kiện khác.                  |

Phạm vi ứng dụng hiện trường thực tế tuân theo các bảng tài nguyên trên; khi nền tảng cập nhật các trường hoặc bảng liệt kê, nó sẽ được điều chỉnh theo mô tả giao diện mới và phiên bản SDK.

## Nguồn và hướng dẫn liên quan

* [Nguồn v0.3.0 chính thức](https://github.com/6mm-com/agent-java-sdk/tree/54aa3c1)
* [Ví tiền tài trợ](/vi/sdk/agent-sdk/java/funding-wallet)
* [Hướng dẫn nâng cấp](/vi/sdk/agent-sdk/java/upgrade)