Consultas e paginação 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.

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.

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

Todos os pedidos são assinados POST com um prefixo comum de /v1/agent/perpetual.

platformUserIds é uma matriz de strings de IDs de plataformas públicas. Quando especificado, são necessários 1 a 100 jogadores únicos com acesso; nos endpoints que permitem a omissão, apenas é consultada a gama de players diretos a que o comerciante atual tem acesso. As consultas de preenchimento comercial exigem sempre esta matriz; as consultas de ordem condicional também exigem IDs de utilizador explícitos. A omissão não é equivalente a [] e as matrizes vazias são ilegais. O âmbito é determinado pelo comerciante subscritor e outros IDs de comerciante não podem ser transmitidos para expandir o âmbito.

Os valores da matriz são serializados como compactos JSON antes de se juntarem à 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, as aspas duplas e os IDs de string; não introduza espaços de formatação nem utilize Java List.toString() (como [1188041528]). O SDK trata esta serialização automaticamente.

A consulta do pedido deve passar orderCategory=NORMAL ou CONDITIONAL. Utilize orderId para encomendas normais e conditionId para encomendas condicionais. 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 pedido de assinatura é timestamp é Unix segundos. Recomenda-se a correção da janela temporal UTC e da consulta em segmentos; utilize UTC para a reconciliação diária. O estado e o tipo utilizam a enumeração do contrato da plataforma e não são traduzidos sozinhos para strings em chinês.

limit O predefinido é 500, o intervalo é 1~1000; o tamanho da página não garante que o mesmo número seja devolvido sempre. As seis interfaces partilham atualmente uma quota 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 utiliza uma fila unificada e é recomendado começar com paginação sequencial e uma janela de histórico mais pequena.

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 seguinte não tenta novamente automaticamente; quando a aplicação real encontrar limitação atual ou falha temporária, siga o guia relacionado ligado 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 partilhados. Os campos de recursos estão documentados em Pedidos, Preenchimentos comerciais, Posições e Livro de razão de contrato.

As seis interfaces devolvem 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. Utilize estes três campos 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, estado, despesas, lucros e perdas ou alteração de saldo por recurso. O valor, o preço, a quantidade e o ID da entidade são tratados como strings; o tempo comercial é em milissegundos. Os campos em falta não são preenchidos com 0 e não são inferidos a partir de outras entidades.

O cursor é a posição de paginação de uma consulta, não uma assinatura incremental fiável, nem um instantâneo atómico garantido entre páginas. O cursor atual é válido durante 24 horas a partir da primeira ronda de geração; a paginação subsequente mantém os mesmos comerciantes, características, coleções de jogadores e condições de filtro. A janela fixa para o pull histórico é idempotente quando puxada repetidamente; o estado da ordem/posição atual é atualizado após uma nova consulta. Quando é necessária uma interface em tempo real, é utilizado o mecanismo de dados do front-end da plataforma, 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 empresarial, deve verificar code. Java SDK irá gerar um erro de negócio 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, serão gerados novos timestamp, nonce, sign. Não pode ir diretamente para a página seguinte e não pode tratar as falhas como resultados vazios. SDK não é responsável pela repetição automática das 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 manuseamento, lucros e perdas, etc.; premir ledgerId para remover duplicados provocará a perda de dados. Os diferentes IDs de recursos não podem ser misturados. Consulte o guia relacionado ligado do Guia de acesso para obter as regras de paginação e de gravação de campos.

Tipos, unidades e campos omitidos

• Valor, preço, quantidade e string de utilização do ID da entidade; utiliza decimal para processar valores e não pode utilizar 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 negociação/contrato.
• O horário de trabalho utiliza o número inteiro (int64), ambos são milissegundos Unix; solicitar o carimbo de data e hora de autenticação e as credenciais de entrada expireAt utilizam segundos e não podem ser confundidos.
• Os campos comerciais de cadeia de caracteres não são geralmente gerados quando estão vazios e alguns serão omitidos quando os campos numéricos forem 0. O campo em falta não significa que o valor comercial seja 0.
• reduceOnly, closeOnly, makerOnly no modelo de registo geral não omite falso, pelo que estes três falsos também podem aparecer em transações ou posições. São explicados apenas nos recursos do pedido; não se pode considerar que a transação/posição tenha executado 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 tem uma fonte de campo; os campos opcionais podem ainda 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 o estado e o modo de margem

A grafia de CANCELED para uma ordem ordinária é diferente da de CANCELLED para uma ordem condicional; o acionamento de uma ordem condicional não significa que a ordem ordinária gerada tenha sido cumprida. Não reutilize o mesmo conjunto de tabelas de conversão de estado para todos os recursos.

Ordem condicional marginMode returns CROSS / ISOLATED; ordens e posições ordinárias históricas devolvem atualmente “1” / “2”, que são margens cruzadas/isoladas, respetivamente. marginMode não está atualmente disponível para encomendas normais. Os comerciantes podem normalizar por recurso na sua própria camada de visualização, e os valores originais ainda precisam de ser guardados.

Campos declarados no modelo, mas não fornecidos nesta consulta

Generic RecordData / Java O modelo PerpetualData também declara os campos seguintes, 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 âmbito real da aplicação no terreno 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