> 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. # Consultas e paginação 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.*; ``` ## Consultar dados de contrato perpétuo ### Seis tipos de interfaces e métodos Java Todas as solicitações são assinadas POST com um prefixo comum de `/v1/agent/perpetual`. | sufixo do caminho | Java Método/Tipo de solicitação | gama de jogadores | | -------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | | `/orders/current` | `listCurrentPerpetualOrders(CurrentPerpetualOrdersRequest)` | NORMAL O jogador pode ser omitido; CONDITIONAL O jogador deve ser especificado | | `/orders/history` | `listPerpetualOrderHistory(PerpetualOrderHistoryRequest)` | Igual ao acima | | `/trades` | `listPerpetualTrades(PerpetualTradesRequest)` | O jogador deve ser especificado | | `/positions/current` | `listCurrentPerpetualPositions(CurrentPerpetualPositionsRequest)` | Os jogadores podem ser omitidos | | `/positions/history` | `listPerpetualPositionHistory(PerpetualPositionHistoryRequest)` | Os jogadores podem ser omitidos | | `/account/ledger` | `listPerpetualLedger(PerpetualLedgerRequest)` | Os jogadores podem ser omitidos | `platformUserIds` é uma matriz de strings de IDs de plataforma pública. Quando especificado, são necessários de 1 a 100 jogadores únicos com acesso; nos endpoints que permitem a omissão, apenas é consultada a gama de players diretos aos quais o comerciante atual tem acesso. Consultas de preenchimento comercial sempre exigem essa matriz; consultas de ordem condicional também exigem IDs de usuário explícitos. A omissão não é equivalente a `[]` e matrizes vazias são ilegais. O escopo é determinado pelo comerciante assinante e outros IDs de comerciante não podem ser transmitidos para expandir o escopo. Os valores da matriz são serializados como compactos JSON antes de ingressar na carga útil de assinatura. Por exemplo, `platformUserIds` assina como `["1188041528"]`, fornecendo `platformUserIds=["1188041528"]` na carga útil `k=v`. Preservar a ordem dos elementos do array, aspas duplas e IDs de string; não insira espaços de formatação nem use Java `List.toString()` (como `[1188041528]`). O SDK lida com essa serialização automaticamente. A consulta do pedido deve passar `orderCategory=NORMAL` ou `CONDITIONAL`. Use `orderId` para pedidos normais e `conditionId` para pedidos condicionais. Eles não podem ser misturados entre categorias. As ordens condicionais e as ordens ordinárias geradas pelo seu acionamento são processadas separadamente como entidades. ### Condições de filtro | Consulta | Filtros de negócios disponíveis | | -------------------- | -------------------------------------------------------------------------------------------------------------- | | Pedido atual | `orderCategory`, `symbol` | | ordem histórica | `orderCategory`, `symbol`, `startTime`, `endTime`, `orderId`, `conditionId`, `clientOrderId`, `side`, `status` | | fazer um acordo | `symbol`, `startTime`, `endTime`, `orderId` | | Posição atual | `symbol` | | Posições históricas | `symbol`, `startTime`, `endTime`, `positionSide` | | Mudanças contratuais | `startTime`, `endTime`, `assetType`, `changeType` | O tempo da consulta histórica é Unix **milissegundos** e o intervalo é `[startTime, endTime)`; o tempo de solicitação de assinatura é `timestamp` é Unix **segundos**. Recomenda-se corrigir a janela de tempo UTC e a consulta em segmentos; use UTC para reconciliação diária. O status e o tipo usam a enumeração do contrato da plataforma e não são traduzidos sozinhos para strings em chinês. `limit` O padrão é 500, o intervalo é 1\~1000; o tamanho da página não garante que o mesmo número será retornado todas as vezes. As seis interfaces atualmente compartilham uma cota de consulta de 2 vezes por segundo e 4 rajadas por comerciante, e o limite máximo de simultaneidade para cada comerciante na instância é 2. O lado do comerciante usa uma fila unificada e é recomendado começar com paginação sequencial e uma janela de histórico menor. ### Java exemplos de consulta Consultar a ordem normal atual de um jogador: ```java CurrentPerpetualOrdersRequest current = new CurrentPerpetualOrdersRequest(); current.orderCategory = "NORMAL"; current.platformUserIds = Collections.singletonList(platformUserId); current.symbol = "BTCUSDT"; current.limit = 100; PerpetualResponse currentPage = client.listCurrentPerpetualOrders(current); ``` Consulte as alterações do contrato na última hora e processe o cursor. O exemplo a seguir não tenta novamente automaticamente; quando o aplicativo real encontrar limitação atual ou falha temporária, siga o guia relacionado vinculado para restaurar a mesma página. ```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 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. } ``` ### Estrutura de retorno e regras de salvamento Ver [Resposta comum e paginação](#common-response-and-pagination) para campos compartilhados. Os campos de recursos estão documentados em [Pedidos](/pt-BR/sdk/agent-sdk/java/perpetual-orders), [Preenchimentos comerciais](/pt-BR/sdk/agent-sdk/java/perpetual-trades), [Posições](/pt-BR/sdk/agent-sdk/java/perpetual-positions) e [Livro razão de contrato](/pt-BR/sdk/agent-sdk/java/perpetual-ledger). As seis interfaces retornam uniformemente `PerpetualResponse`: ```json { "code": 0, "message": "success", "data": { "items": [], "nextCursor": "", "hasMore": false } } ``` Cada `items` contém `platformUserId`, `entityType`, `entityId`, `data`. Os tipos de entidade incluem `ORDER`, `CONDITION_ORDER`, `TRADE_FILL`, `POSITION`, `ACCOUNT_LEDGER`. Use esses três campos de identidade para construir uma chave idempotente; não trate o ID do pedido condicional, o ID do pedido e o ID de preenchimento como o mesmo número. `data` Fornece campos como preço, quantidade, status, despesas, lucros e perdas ou alteração de saldo por recurso. Valor, preço, quantidade e ID da entidade são tratados como strings; o tempo comercial é em milissegundos. Os campos ausentes não são preenchidos com 0 e não são inferidos de outras entidades. O cursor é a posição de paginação de uma consulta, não uma assinatura incremental confiável, nem um instantâneo atômico garantido entre páginas. O cursor atual é válido por 24 horas a partir da primeira rodada de geração; a paginação subsequente mantém os mesmos comerciantes, recursos, coleções de jogadores e condições de filtro. A janela fixa para pull histórico é idempotente quando puxada repetidamente; o status da ordem/posição atual é atualizado após uma nova consulta. Quando uma interface em tempo real é necessária, o mecanismo de dados do front-end da plataforma é usado, e a interface polling six não pode ser considerada uma interface de mercado de alta frequência. ### Erros e recuperação HTTP sucesso não significa sucesso nos negócios, você deve verificar `code`. Java SDK gerará um erro de negócios como `AgentApiException`. | Código comercial | Significado típico | Manuseio | | ---------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `102001` | Faltam parâmetros obrigatórios, por exemplo, faltam jogadores na consulta de ordem condicional. | Forneça os parâmetros ausentes | | `102002` | Parâmetros ilegais, matriz vazia, cursor incompatível ou expirado | Corrija os parâmetros; verifique novamente a janela corrigida após limpar o cursor expirado e salve-o de forma idempotente. | | `102003` | Limite ilegal, número de jogadores ou intervalo de tempo | Escopo estreito ou correto | | `6001` | Erro de assinatura | Verifique os campos de chave, serialização de array e assinatura | | `6009` | O método ou escopo de acesso do comerciante não é permitido | Verifique as permissões do comerciante e a propriedade do jogador | | `6904` | O serviço está temporariamente indisponível, simultaneidade ou proteção de recurso de consulta | Reduza a simultaneidade e reduza as janelas; entre em contato com o suporte se o erro persistir | | `6905` | A cota compartilhada para seis tipos de consultas foi esgotada | Recue e tente novamente a página original com falha | O `cursor` e todas as condições de filtro da página original com falha serão retidas após limitação de corrente, tempo limite ou falha temporária; cada vez que SDK for chamado novamente, novos `timestamp`, `nonce`, `sign` serão gerados. Você não pode ir diretamente para a próxima página e não pode tratar as falhas como resultados vazios. SDK não é responsável por repetir automaticamente as transações de fundos. ## Resposta comum e paginação | Campo | JSON tipo | ilustrar | | ----------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------- | | `code` | integer | Código comercial, 0 significa sucesso; se não for 0, será tratado como um erro e a falha não será tratada como uma página vazia. | | `message` | string | A descrição dos resultados não é a única base para julgamento empresarial. | | `data` | object | Resultados paginados sobre sucesso | | `data.items` | array | Registros nesta página; a página vazia legal é `[]` | | `data.nextCursor` | string | Cursor da próxima página; geralmente uma string vazia se não houver páginas subsequentes | | `data.hasMore` | boolean | Se existem páginas subsequentes; quando verdadeiro, use nextCursor para continuar a mesma consulta | A estrutura de cada `data.items[]`: | Campo | JSON tipo | ilustrar | | ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `platformUserId` | string | ID de usuário público da plataforma, salvo como string; não ID de usuário do banco de dados interno | | `entityType` | string | O tipo de entidade a que pertence o registro, veja a tabela abaixo | | `entityId` | string | O identificador da entidade atual é combinado com o usuário da plataforma e o tipo de entidade para construir uma chave idempotente local. | | `data` | object | As áreas de negócio desta entidade; diferentes campos de recursos são diferentes | | Consultar recursos | `entityType` | `entityId` Correspondência | | ----------------------------------- | ----------------- | -------------------------------------------------------------------------------------- | | Ordem normal | `ORDER` | `data.orderId` | | ordens condicionais | `CONDITION_ORDER` | `data.conditionId` | | Detalhes de preenchimento comercial | `TRADE_FILL` | `data.fillId`, não tradeId | | Posições atuais/históricas | `POSITION` | `data.positionId` | | Registros do razão de contrato | `ACCOUNT_LEDGER` | Identificação de detalhes de alteração de conta única, \*\* não são dados.ledgerId\*\* | O mesmo `ledgerId` pode separar vários detalhes, como taxas de manuseio, lucros e perdas, etc.; pressionar ledgerId para remover duplicatas causará perda de dados. IDs de recursos diferentes não podem ser misturados. Consulte o guia relacionado vinculado do Guia de acesso para regras de paginação e salvamento de campos. ## Tipos, unidades e campos omitidos * Valor, preço, quantidade e string de uso do ID da entidade; usa decimal para processar valores e não pode usar números de ponto flutuante ou converter IDs longos em números JavaScript. A moeda do valor e a unidade de quantidade são explicadas de acordo com as especificações do par de negociação/contrato. * O horário comercial usa número inteiro (int64), ambos são milissegundos Unix; solicitar carimbo de data e hora de autenticação e credenciais de entrada expireAt usam segundos e não podem ser confundidos. * Os campos comerciais de string geralmente não são gerados quando estão vazios e alguns serão omitidos quando os campos numéricos forem 0. **O campo ausente não significa que o valor comercial seja 0**. * `reduceOnly`, `closeOnly`, `makerOnly` no modelo de registro geral não omite falso, portanto esses três falsos também podem aparecer em transações ou posições. Eles são explicados apenas nos recursos do pedido; não se pode considerar que a transação/posição executou as regras de ordem correspondentes. * `closePosition` é um booleano opcional: fornecido por pedidos condicionais, geralmente omitido para outros recursos. Ausente tem um significado diferente de falso. * A tabela abaixo "fornecida atualmente" significa que a lógica de leitura possui uma fonte de campo; campos opcionais ainda podem ser omitidos porque não têm valor. Não é garantido que os campos existentes no modelo sejam preenchidos em todas as interfaces. ## A diferença entre status e modo de margem | recurso | valor de retorno atual | | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | | Status atual do pedido normal | NEW, PENDING, PARTIALLY_FILLED | | Status histórico do pedido ordinário | FILLED, CANCELED, REJECTED, PARTIAL_FILLED_CANCELED, ou PARTIALLY_FILLED_CANCELED; mantenha a ortografia original | | Status do pedido de condição atual / triggerStatus | PENDING_ACTIVATION, PENDING, TRIGGERING | | Status histórico do pedido de condição / triggerStatus | TRIGGERED, CANCELLED, REJECTED, FIRED | | Status da posição atual | A sequência numérica "1" está em posição, "3" está em liquidação | | Status histórico da posição | A string numérica "2" fechou a posição, "4" forçou a liquidação | A grafia de CANCELED para uma ordem ordinária é diferente daquela de CANCELLED para uma ordem condicional; o acionamento de uma ordem condicional não significa que a ordem ordinária gerada tenha sido atendida. Não reutilize o mesmo conjunto de tabelas de conversão de status para todos os recursos. Ordem condicional marginMode retorna CROSS / ISOLATED; ordens e posições ordinárias históricas atualmente retornam "1" / "2", que são margens cruzadas/isoladas, respectivamente. marginMode atualmente não está disponível para pedidos normais. Os comerciantes podem normalizar por recurso em sua própria camada de exibição, e os valores originais ainda precisam ser salvos. ## Campos declarados no modelo, mas não fornecidos nesta consulta Generic RecordData / Java O modelo PerpetualData também declara os campos a seguir, mas a lógica atual de leitura de produção de seis categorias não os preenche. \*\*Não devem ser listados como dados comerciais disponíveis, nem os padrões de campo devem ser substituídos por resultados reais. \*\* | Campo | Tipo de modelo | limite atual | | ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `closeReason` | string | As razões para fechar posições históricas não são fornecidas | | `walletDelta` | string | A interface de alteração de conta não retorna delta da carteira | | `frozenDelta` | string | A interface de alteração de conta não retorna delta congelado | | `usedDelta` | string | A interface de alteração de conta não retorna o delta da margem utilizada | | `feeDelta` | string | A interface de alteração de conta não retorna o delta da taxa | | `pnlDelta` | string | A interface de alteração de conta não retorna delta de lucros e perdas | | `accountVersion` | string | A interface de alteração de conta não retorna a versão da conta e não pode ser usada para sincronização incremental confiável. | | `occurredAt` | integer | A interface de alteração de conta usa createdAt e não fornece outro conjunto de horários de ocorrência de eventos. | O escopo real da aplicativo em campo está sujeito às tabelas de recursos acima; quando a plataforma atualizar campos ou enumerações, deverá ser adaptado de acordo com a nova descrição da interface e versão SDK. ## Fonte e guias relacionados * [Fonte oficial v0.3.0](https://github.com/6mm-com/agent-java-sdk/tree/54aa3c1) * [Carteira de financiamento](/pt-BR/sdk/agent-sdk/java/funding-wallet) * [Guia de atualização](/pt-BR/sdk/agent-sdk/java/upgrade)