> 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 é direcionado a **Agent Java SDK `v0.3.0`**, Java 8+ e ao contrato público marcado. Os exemplos são executados em um back-end de parceiro após a inicialização de `client` em [Início rápido](/pt-BR/sdk/agent-sdk/java/quick-start). ## Pré-requisitos de exemplo Os trechos Java compartilham essas importações. Inicialize `client` usando o Quick Start e obtenha `platformUserId` da ligação salva. Os exemplos de IDs de usuário/pedido devem ser substituídos por seus próprios valores persistentes. ```java import com.sixmm.agent.*; import com.sixmm.agent.model.*; import java.util.*; ``` ## `listCurrentPerpetualPositions` Modelo de solicitação: `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 preenchimentos e pedidos condicionais. Omitir consultas suportadas para escopo de 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 | Use o nextCursor retornado com filtros inalterados; pare quando hasMore for falso. | O exemplo lê uma página. Para campos obrigatórios, escopo do player, semântica de filtro, limite, cursor e novas tentativas limitadas, siga [Visão geral da consulta](/pt-BR/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 solicitação: `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 preenchimentos e pedidos condicionais. Omitir consultas suportadas para escopo de player direto; \[] é inválido. | | `symbol` | `String` | Não | Filtro opcional de pares de negociação. | | `positionSide` | `String` | Não | Filtre usando a enumeração do lado da posição de origem. | | `startTime` | `Long` | Não | Milissegundos Unix inclusivos; use 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 | Use o nextCursor retornado com filtros inalterados; pare quando hasMore for falso. | O exemplo lê uma página. Para campos obrigatórios, escopo do player, semântica de filtro, limite, cursor e novas tentativas limitadas, siga [Visão geral da consulta](/pt-BR/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 | fornecer | fornecer | ID da posição, correspondente a entityId | | `symbol` | string | fornecer | fornecer | par de negociação | | `positionSide` | string | fornecer | fornecer | LONG / SHORT / BOTH e outras direções de posição | | `status` | string | fornecer | fornecer | String com o status numérico da posição, veja a visão geral da consulta | | `leverage` | integer | fornecer | fornecer | Aproveite vários | | `marginMode` | string | fornecer | fornecer | String de enumeração numérica "1" para posição completa, "2" para posição isolada | | `quantity` | string | fornecer | Não disponível | Quantidade da posição atual | | `entryPrice` | string | fornecer | fornecer | Preço médio de abertura das posições armazenadas | | `margin` | string | fornecer | Não disponível | O valor da margem de posição atual, não o saldo total da carteira do contrato do usuário | | `maxQuantity` | string | Não disponível | fornecer | O número máximo de posições registradas nesta posição histórica | | `closeQuantity` | string | Não disponível | fornecer | O número cumulativo de posições fechadas durante o ciclo de vida histórico da posição | | `closePrice` | string | Não disponível | fornecer | Preço médio de fechamento armazenado | | `pnl` | string | Não disponível | fornecer | Lucros e perdas de posição histórica; não combine com a transação realizedPnl para simplesmente repetir e acumular | | `roe` | string | Não disponível | fornecer | 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 | fornecer | fornecer | Taxa de financiamento acumulada, mantendo o símbolo da fonte e a precisão | | `openedAt` | integer | fornecer | fornecer | Tempo de abertura da posição, milissegundos | | `updatedAt` | integer | fornecer | Não disponível | Tempo de atualização da posição atual, milissegundos | | `closedAt` | integer | Não disponível | fornecer | Tempo de fechamento, milissegundos; use 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 retorna diretamente o valor da proporção salva. Ao exibir a porcentagem, use a operação decimal e multiplique por 100, depois adicione `%`; o denominador usa a margem nominal do registro histórico da posição, 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 calculada, a fonte é salva como 0. Portanto, não se pode inferir que o lucro ou perda 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. Ele reflete o status da posição armazenada e não pode usar os campos de tempo e margem de atualização para reivindicar os resultados atuais do controle 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-BR/sdk/agent-sdk/java/perpetual-queries) * [Carteira de financiamento](/pt-BR/sdk/agent-sdk/java/funding-wallet) * [Guia de atualização](/pt-BR/sdk/agent-sdk/java/upgrade)