> 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. # Posições Perpétuas Este guia é dirigido a **Agent Java SDK `v0.3.0`**, Java 8+ e ao contrato público assinalado. Os exemplos são executados num back-end de parceiro após a inicialização de `client` em [Início rápido](/pt-PT/sdk/agent-sdk/java/quick-start). ## Pré-requisitos de exemplo Os trechos Java partilham estas importações. Inicialize `client` utilizando o Quick Start e obtenha `platformUserId` a partir da ligação guardada. Os exemplos de IDs de utilizador/encomenda devem ser substituídos pelos seus próprios valores persistentes. ```java import com.sixmm.agent.*; import com.sixmm.agent.model.*; import java.util.*; ``` ## `listCurrentPerpetualPositions` Modelo de pedido: `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); ``` ### Campos de solicitação | Campo | Java tipo | Obrigatório | Significado | | ----------------- | ------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `platformUserIds` | `java.util.List` | Condicional | 1–100 IDs públicos exclusivos; necessário para os preenchimentos e pedidos condicionais. Omitir consultas suportadas para o âmbito do player direto; \[] é inválido. | | `symbol` | `String` | Não | Filtro opcional de pares de negociação. | | `limit` | `Integer` | Não | Padrão 500; 1–1000. | | `cursor` | `String` | Não | Utilize o nextCursor devolvido com filtros inalterados; parar quando hasMore for falso. | O exemplo lê uma página. Para campos obrigatórios, âmbito do leitor, semântica de filtro, limite, cursor e novas tentativas limitadas, siga [Visão geral da consulta](/pt-PT/sdk/agent-sdk/java/perpetual-queries). Mantenha todos os filtros inalterados durante a paginação; não interprete um erro como um resultado vazio. ## `listPerpetualPositionHistory` Modelo de pedido: `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); ``` ### Campos de solicitação | Campo | Java tipo | Obrigatório | Significado | | ----------------- | ------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `platformUserIds` | `java.util.List` | Condicional | 1–100 IDs públicos exclusivos; necessário para os preenchimentos e pedidos condicionais. Omitir consultas suportadas para o âmbito do player direto; \[] é inválido. | | `symbol` | `String` | Não | Filtro opcional de pares de negociação. | | `positionSide` | `String` | Não | Filtre utilizando a enumeração do lado da posição de origem. | | `startTime` | `Long` | Não | Milissegundos Unix inclusivos; utilize uma janela de histórico fixa UTC. | | `endTime` | `Long` | Não | Milissegundos Unix exclusivos. | | `limit` | `Integer` | Não | Padrão 500; 1–1000. | | `cursor` | `String` | Não | Utilize o nextCursor devolvido com filtros inalterados; parar quando hasMore for falso. | O exemplo lê uma página. Para campos obrigatórios, âmbito do leitor, semântica de filtro, limite, cursor e novas tentativas limitadas, siga [Visão geral da consulta](/pt-PT/sdk/agent-sdk/java/perpetual-queries). Mantenha todos os filtros inalterados durante a paginação; não interprete um erro como um resultado vazio. ## Posições: Atuais e Históricas | Campo `data` | tipo | Posição atual | Posições históricas | significado | | ----------------- | ------- | -------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `positionId` | string | suprimento | suprimento | ID da posição, correspondente a entityId | | `symbol` | string | suprimento | suprimento | par de negociação | | `positionSide` | string | suprimento | suprimento | LONG / SHORT / BOTH e outras direções de posição | | `status` | string | suprimento | suprimento | String com o estado numérico da posição, ver a visão geral da consulta | | `leverage` | integer | suprimento | suprimento | Aproveite vários | | `marginMode` | string | suprimento | suprimento | String de enumeração numérica "1" para posição completa, "2" para posição isolada | | `quantity` | string | suprimento | Não disponível | Quantidade da posição atual | | `entryPrice` | string | suprimento | suprimento | Preço médio de abertura das posições armazenadas | | `margin` | string | suprimento | Não disponível | O valor da margem de posição atual, e não o saldo total da carteira do contrato do utilizador | | `maxQuantity` | string | Não disponível | suprimento | O número máximo de posições registadas nesta posição histórica | | `closeQuantity` | string | Não disponível | suprimento | O número cumulativo de posições fechadas durante o ciclo de vida histórico da posição | | `closePrice` | string | Não disponível | suprimento | Preço médio de fecho armazenado | | `pnl` | string | Não disponível | suprimento | Lucros e perdas de posição histórica; não combinar com a transação realizedPnl para simplesmente repetir e acumular | | `roe` | string | Não disponível | suprimento | O valor proporcional do retorno histórico da posição, não multiplicado por 100; por exemplo, `"0.043"` representa `4.3%`, `"-0.05"` representa `-5%` | | `fundingFeeAccum` | string | suprimento | suprimento | Taxa de financiamento acumulada, mantendo o símbolo da fonte e a precisão | | `openedAt` | integer | suprimento | suprimento | Tempo de abertura da posição, milissegundos | | `updatedAt` | integer | suprimento | Não disponível | Tempo de atualização da posição atual, milissegundos | | `closedAt` | integer | Não disponível | suprimento | Tempo de fecho, milissegundos; utilize este campo para filtrar o tempo histórico da posição | O calibre de cálculo do histórico `roe` é `pnl / (entryPrice × maxQuantity / leverage)`, e a interface devolve diretamente o valor da proporção guardada. Ao apresentar a percentagem, utilize a operação decimal e multiplique por 100, depois adicione `%`; o denominador utiliza a margem nominal do registo histórico da posição, e não o saldo da carteira da conta. Quando o preço de abertura ou a quantidade máxima de posição é 0, a alavancagem é inválida, etc. e não pode ser calculado, a fonte é guardada como 0. Assim, não se pode inferir que o lucro ou prejuízo seja 0 apenas com base em `roe=0`. A posição atual não tem preço de marca em tempo real, lucros e perdas flutuantes em tempo real, ROE em tempo real ou preço de liquidação em tempo real. Reflete o estado da posição armazenada e não pode utilizar os campos de tempo e margem de atualização para reivindicar os resultados atuais do controlo de risco em tempo real. ## Exemplo de envelope de resposta Esta é uma página em branco ilustrativa, não uma amostra de uma negociação concluída. As tabelas de campos específicos de recursos acima descrevem `items[].data` preenchido. ```json {"code":0,"message":"success","data":{"items":[],"nextCursor":"","hasMore":false}} ``` ## Fonte e guias relacionados * [Fonte oficial v0.3.0](https://github.com/6mm-com/agent-java-sdk/tree/54aa3c1) * [Visão geral da consulta e paginação](/pt-PT/sdk/agent-sdk/java/perpetual-queries) * [Carteira de financiamento](/pt-PT/sdk/agent-sdk/java/funding-wallet) * [Guia de atualização](/pt-PT/sdk/agent-sdk/java/upgrade)