> 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. # Perpetual Positions This guide targets **Agent Java SDK `v0.3.0`**, Java 8+, and the tagged public contract. Examples run in a partner backend after initializing `client` in [Quick Start](/sdk/agent-sdk/java/quick-start). ## Example prerequisites The Java snippets share these imports. Initialize `client` using Quick Start and obtain `platformUserId` from the saved binding. Example user/order IDs must be replaced with your own persisted values. ```java import com.sixmm.agent.*; import com.sixmm.agent.model.*; import java.util.*; ``` ## `listCurrentPerpetualPositions` Request model: `CurrentPerpetualPositionsRequest`. ```java import com.sixmm.agent.model.CurrentPerpetualPositionsRequest; import com.sixmm.agent.model.PerpetualResponse; import java.util.Collections; CurrentPerpetualPositionsRequest request = new CurrentPerpetualPositionsRequest(); request.platformUserIds = Collections.singletonList("1188041528"); request.limit = 100; request.symbol = "BTCUSDT"; PerpetualResponse response = client.listCurrentPerpetualPositions(request); System.out.println(response.data.items.size()); System.out.println(response.data.hasMore); System.out.println(response.data.nextCursor); ``` ### Request fields | Field | Java type | Required | Meaning | | ----------------- | ------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `platformUserIds` | `java.util.List` | Conditional | 1–100 unique public IDs; required for fills and conditional orders. Omit on supported queries for direct-player scope; \[] is invalid. | | `symbol` | `String` | No | Optional trading-pair filter. | | `limit` | `Integer` | No | Default 500; 1–1000. | | `cursor` | `String` | No | Use the returned nextCursor with unchanged filters; stop when hasMore is false. | The example reads one page. For required fields, player scope, filter semantics, limit, cursor and bounded retries, follow [Query overview](/sdk/agent-sdk/java/perpetual-queries). Keep all filters unchanged while paging; do not interpret an error as an empty result. ## `listPerpetualPositionHistory` Request model: `PerpetualPositionHistoryRequest`. ```java import com.sixmm.agent.model.PerpetualPositionHistoryRequest; import com.sixmm.agent.model.PerpetualResponse; import java.util.Collections; PerpetualPositionHistoryRequest request = new PerpetualPositionHistoryRequest(); request.platformUserIds = Collections.singletonList("1188041528"); request.limit = 100; request.symbol = "BTCUSDT"; request.endTime = System.currentTimeMillis(); request.startTime = request.endTime - 3_600_000L; PerpetualResponse response = client.listPerpetualPositionHistory(request); System.out.println(response.data.items.size()); System.out.println(response.data.hasMore); System.out.println(response.data.nextCursor); ``` ### Request fields | Field | Java type | Required | Meaning | | ----------------- | ------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `platformUserIds` | `java.util.List` | Conditional | 1–100 unique public IDs; required for fills and conditional orders. Omit on supported queries for direct-player scope; \[] is invalid. | | `symbol` | `String` | No | Optional trading-pair filter. | | `positionSide` | `String` | No | Filter using the source position-side enum. | | `startTime` | `Long` | No | Inclusive Unix milliseconds; use a fixed UTC history window. | | `endTime` | `Long` | No | Exclusive Unix milliseconds. | | `limit` | `Integer` | No | Default 500; 1–1000. | | `cursor` | `String` | No | Use the returned nextCursor with unchanged filters; stop when hasMore is false. | The example reads one page. For required fields, player scope, filter semantics, limit, cursor and bounded retries, follow [Query overview](/sdk/agent-sdk/java/perpetual-queries). Keep all filters unchanged while paging; do not interpret an error as an empty result. ## Positions: Current and Historical | `data` field | type | Current position | Historical positions | meaning | | ----------------- | ------- | ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `positionId` | string | supply | supply | Position ID, corresponding to entityId | | `symbol` | string | supply | supply | trading pair | | `positionSide` | string | supply | supply | LONG / SHORT / BOTH and other position directions | | `status` | string | supply | supply | String with the numerical status of the position, see the query overview | | `leverage` | integer | supply | supply | Leverage multiple | | `marginMode` | string | supply | supply | Numeric enumeration string "1" for full position, "2" for isolated position | | `quantity` | string | supply | Not available | Current position quantity | | `entryPrice` | string | supply | supply | Average opening price of stored positions | | `margin` | string | supply | Not available | The current position margin amount, not the user’s entire contract wallet balance | | `maxQuantity` | string | Not available | supply | The maximum number of positions recorded in this historical position | | `closeQuantity` | string | Not available | supply | The cumulative number of positions closed during the historical position life cycle | | `closePrice` | string | Not available | supply | Stored average closing price | | `pnl` | string | Not available | supply | Historical position profit and loss; do not combine it with the transaction realizedPnl to simply repeat and accumulate | | `roe` | string | Not available | supply | The proportional value of historical position return, not multiplied by 100; for example, `"0.043"` represents `4.3%`, `"-0.05"` represents `-5%` | | `fundingFeeAccum` | string | supply | supply | Accumulated funding fee, retaining source symbol and accuracy | | `openedAt` | integer | supply | supply | Position opening time, milliseconds | | `updatedAt` | integer | supply | Not available | Current position update time, milliseconds | | `closedAt` | integer | Not available | supply | Closing time, milliseconds; use this field to filter historical position time | The calculation caliber of history `roe` is `pnl / (entryPrice × maxQuantity / leverage)`, and the interface directly returns the saved proportion value. When displaying the percentage, use decimal operation and multiply by 100, then add `%`; the denominator uses the nominal margin of the historical position record, not the account wallet balance. When the opening price or maximum position quantity is 0, the leverage is invalid, etc. and cannot be calculated, the source is saved as 0. Therefore, it cannot be inferred that the profit or loss is 0 just based on `roe=0`. The current position does not have real-time mark price, real-time floating profit and loss, real-time ROE or real-time liquidation price. It reflects the stored position status and cannot use the update time and margin fields to claim the current real-time risk control results. ## Example response envelope This is an illustrative empty page, not a sample of a completed trade. Resource-specific field tables above describe populated `items[].data`. ```json {"code":0,"message":"success","data":{"items":[],"nextCursor":"","hasMore":false}} ``` ## Source and related guides * [Official v0.3.0 source](https://github.com/6mm-com/agent-java-sdk/tree/54aa3c1) * [Query overview and pagination](/sdk/agent-sdk/java/perpetual-queries) * [Funding wallet](/sdk/agent-sdk/java/funding-wallet) * [Upgrade guide](/sdk/agent-sdk/java/upgrade)