> 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 Trade Fills

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.*;
```

## `listPerpetualTrades`

Request model: `PerpetualTradesRequest`.

```java
import com.sixmm.agent.model.PerpetualTradesRequest;
import com.sixmm.agent.model.PerpetualResponse;
import java.util.Collections;

PerpetualTradesRequest request = new PerpetualTradesRequest();
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.listPerpetualTrades(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<String>` | Yes      | Explicitly supply 1–100 unique public platform user IDs belonging to the current partner; omission and an empty array are invalid. |
| `symbol`          | `String`                 | No       | Optional trading-pair filter.                                                                                                      |
| `orderId`         | `String`                 | No       | Ordinary order ID; not a partner transfer order number.                                                                            |
| `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.

## Trade fill details

Interface: `trades`. Requires explicit platformUserIds.

| `data` field   | type    | meaning                                                                                                                            |
| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `fillId`       | string  | Trade fill details ID, corresponding to this record entityId                                                                       |
| `tradeId`      | string  | The matching transaction ID associated with the transaction; does not replace the detailed ID                                      |
| `orderId`      | string  | The general order ID to which this detail belongs                                                                                  |
| `positionId`   | string  | Associated position ID                                                                                                             |
| `symbol`       | string  | trading pair                                                                                                                       |
| `side`         | string  | This player’s buying and selling direction BUY / SELL                                                                              |
| `roleType`     | string  | This player’s transaction character MAKER / TAKER                                                                                  |
| `positionSide` | string  | Position direction, explained according to actual value LONG / SHORT / BOTH etc.                                                   |
| `price`        | string  | This transaction price                                                                                                             |
| `quantity`     | string  | The quantity of this transaction is not the total quantity of the original order.                                                  |
| `tradeValue`   | string  | The nominal value of this transaction comes from the transaction notional                                                          |
| `handlingFee`  | string  | The transaction fee for this transaction retains the source symbol and accuracy, and does not take the absolute value by itself.   |
| `realizedPnl`  | string  | The realized profit and loss corresponding to this transaction; not the real-time floating profit and loss of the current position |
| `tradedAt`     | integer | Transaction time, milliseconds; use this field for time filtering                                                                  |

An order may have multiple fills, which should be saved in detail. Do not merge records of different players/fill roles by tradeId and then discard their record identities.

## 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)