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.

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.

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.

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

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:

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.

PerpetualLedgerRequest ledger = new PerpetualLedgerRequest();
ledger.platformUserIds = Collections.singletonList(platformUserId);
ledger.endTime = System.currentTimeMillis();
ledger.startTime = ledger.endTime - 3_600_000L;
ledger.limit = 100;
Set<String> 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 para campos compartilhados. Os campos de recursos estão documentados em Pedidos, Preenchimentos comerciais, Posições e Livro razão de contrato.

As seis interfaces retornam uniformemente PerpetualResponse:

{
  "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.

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

A estrutura de cada data.items[]:

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

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

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
• Carteira de financiamento
• Guia de atualização