Consultas perpetuas y paginación

Esta guía está dirigida a Agent Java SDK v0.3.0, Java 8+ y el contrato público etiquetado. Los ejemplos se ejecutan en un backend asociado después de inicializar client en Inicio rápido.

Requisitos previos de ejemplo

Los fragmentos Java comparten estas importaciones. Inicialice client usando el Inicio rápido y obtenga platformUserId del enlace guardado. Los ID de usuario/pedido de ejemplo deben reemplazarse con sus propios valores persistentes.

import com.sixmm.agent.*;
import com.sixmm.agent.model.*;
import java.util.*;

Consultar datos de contrato perpetuo

Seis tipos de interfaces y Java métodos

Todas las solicitudes están firmadas POST con un prefijo común de /v1/agent/perpetual.

platformUserIds es una matriz de cadenas de ID de plataformas públicas. Cuando se especifica, se requieren de 1 a 100 jugadores únicos que tengan acceso; en los puntos finales que permiten la omisión, solo se consulta el rango de jugadores directos a los que tiene acceso el comerciante actual. Las consultas de Trade-fill siempre requieren esta matriz; Las consultas de orden condicional también requieren ID de usuario explícitos. La omisión no es equivalente a [] y las matrices vacías son ilegales. El alcance lo determina el comerciante firmante y no se pueden pasar otros ID de comerciante para ampliar el alcance.

Los valores de la matriz se serializan como JSON compacto antes de unirse a la carga útil de firma. Por ejemplo, platformUserIds firma como ["1188041528"], dando platformUserIds=["1188041528"] en la carga útil k=v. Preservar el orden de los elementos de la matriz, las comillas dobles y los ID de cadenas; no inserte espacios de formato ni utilice Java List.toString() (como [1188041528]). El SDK maneja esta serialización automáticamente.

La consulta de pedido debe pasar orderCategory=NORMAL o CONDITIONAL. Utilice orderId para pedidos ordinarios y conditionId para pedidos condicionales. No se pueden mezclar entre categorías. Las órdenes condicionales y las órdenes ordinarias generadas al activarlas se procesan por separado como entidades.

Condiciones del filtro

El tiempo de consulta histórica es Unix milisegundos y el intervalo es [startTime, endTime); el tiempo de solicitud de firma es timestamp es Unix segundos. Se recomienda fijar la ventana de tiempo UTC y realizar la consulta en segmentos; utilice UTC para la conciliación diaria. El estado y el tipo utilizan la enumeración del contrato de plataforma y no se traducen a cadenas chinas por sí solos.

limit El valor predeterminado es 500, el rango es 1~1000; el tamaño de la página no garantiza que se devolverá el mismo número cada vez. Actualmente, las seis interfaces comparten una cuota de consultas de 2 veces por segundo y 4 ráfagas por comerciante, y el límite máximo de concurrencia para cada comerciante dentro de la instancia es 2. El lado del comerciante utiliza una cola unificada y se recomienda comenzar con paginación secuencial y una ventana de historial más pequeña.

Java ejemplos de consulta

Consultar el orden ordinario actual de un jugador:

CurrentPerpetualOrdersRequest current = new CurrentPerpetualOrdersRequest();
current.orderCategory = "NORMAL";
current.platformUserIds = Collections.singletonList(platformUserId);
current.symbol = "BTCUSDT";
current.limit = 100;
PerpetualResponse currentPage = client.listCurrentPerpetualOrders(current);

Consulta los cambios de contrato en la última hora y procesa el cursor. El siguiente ejemplo no reintenta automáticamente; Cuando la aplicación real encuentre una limitación actual o una falla temporal, siga la guía relacionada vinculada para restaurar la misma 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.
}

Estructura de devolución y reglas de ahorro.

Ver Respuesta común y paginación. para campos compartidos. Los campos de recursos están documentados en Órdenes, Rellenos comerciales, Posiciones y Libro mayor de contratos.

Las seis interfaces devuelven uniformemente PerpetualResponse:

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [],
    "nextCursor": "",
    "hasMore": false
  }
}

Cada items contiene platformUserId, entityType, entityId, data. Los tipos de entidad incluyen ORDER, CONDITION_ORDER, TRADE_FILL, POSITION, ACCOUNT_LEDGER. Utilice estos tres campos de identidad para crear una clave idempotente; no trate el ID de pedido condicional, el ID de pedido y el ID de llenado como el mismo número.

data Proporciona campos como precio, cantidad, estado, gastos, pérdidas y ganancias o cambio de saldo por recurso. El monto, el precio, la cantidad y el ID de la entidad se manejan como cadenas; El tiempo comercial está en milisegundos. Los campos faltantes no se completan hasta 0 y no se infieren de otras entidades.

El cursor es la posición de paginación de una consulta, no una suscripción incremental confiable ni una instantánea atómica entre páginas garantizada. El cursor actual es válido durante 24 horas desde la primera ronda de generación; La paginación posterior conserva los mismos comerciantes, recursos, colecciones de jugadores y condiciones de filtro. La ventana fija para la atracción histórica es idempotente cuando se la tira repetidamente; el estado del pedido/posición actual se actualiza después de volver a realizar la consulta. Cuando se necesita una interfaz en tiempo real, se utiliza el mecanismo de datos del front-end de la plataforma y la interfaz de sondeo seis no puede considerarse como una interfaz de mercado de alta frecuencia.

Errores y recuperación

HTTP el éxito no significa éxito empresarial, debes verificar code. Java SDK arrojará un error comercial como AgentApiException.

El cursor y todas las condiciones de filtro de la página fallida original se conservarán después de la limitación actual, el tiempo de espera o una falla temporal; Cada vez que se vuelve a llamar SDK, se generarán nuevos timestamp, nonce, sign. No puede saltar directamente a la página siguiente y no puede tratar los errores como resultados vacíos. SDK no es responsable de reintentar automáticamente las transacciones de fondos.

Respuesta común y paginación.

La estructura de cada data.items[]:

El mismo ledgerId puede separar múltiples detalles como tarifas de manejo, pérdidas y ganancias, etc.; presionar ledgerId para eliminar duplicados provocará la pérdida de datos. No se pueden mezclar identificaciones de diferentes recursos. Consulte la guía relacionada vinculada de la Guía de acceso para conocer las reglas de paginación y guardado de campos.

Tipos, unidades y campos omitidos

• Cantidad, precio, cantidad e ID de entidad utilizan cadena; use decimales para procesar cantidades y no puede usar números de punto flotante ni convertir ID largos en números de JavaScript. La moneda de la cantidad y la unidad de cantidad se explican de acuerdo con las especificaciones del par comercial/contrato.
• El tiempo comercial utiliza números enteros (int64), ambos son milisegundos de Unix; solicitar marca de tiempo de autenticación y credenciales de entrada expireAt usa segundos y no se puede confundir.
• Los campos comerciales de cadena generalmente no se muestran cuando están vacíos y algunos se omitirán cuando los campos numéricos sean 0. El campo que falta no significa que el valor comercial sea 0.
• reduceOnly, closeOnly, makerOnly en el modelo de registro general no omiten falso, por lo que estos tres falsos también pueden aparecer en transacciones o posiciones. Sólo se explican en los recursos del pedido; no se puede considerar que la transacción/posición haya ejecutado las reglas de orden correspondientes.
• closePosition es un booleano opcional: proporcionado por órdenes condicionales, generalmente omitido para otros recursos. Desaparecido tiene un significado diferente al de falso.
• La siguiente tabla “proporcionada actualmente” significa que la lógica de lectura tiene un origen de campo; Los campos opcionales aún pueden omitirse porque no tienen valor. No se garantiza que los campos que existen en el modelo se completen en todas las interfaces.

La diferencia entre estado y modo de margen

La ortografía de CANCELED para una orden ordinaria es diferente a la de CANCELLED para una orden condicional; La activación de una orden condicional no significa que la orden ordinaria generada se haya ejecutado. No reutilice el mismo conjunto de tablas de traducción de estado para todos los recursos.

Orden condicional marginMode devuelve CROSS / ISOLATED; Las órdenes y posiciones ordinarias históricas actualmente devuelven “1” / “2”, que son márgenes cruzados/aislados respectivamente. marginMode actualmente no está disponible para pedidos ordinarios. Los comerciantes pueden normalizar por recurso en su propia capa de visualización y aún es necesario guardar los valores originales.

Campos declarados en el modelo pero no proporcionados en esta consulta

Generic RecordData / Java El modelo PerpetualData también declara los siguientes campos, pero la lógica de lectura de producción actual de seis categorías no los completa. **No deben figurar como datos comerciales disponibles, ni los campos predeterminados deben sustituirse por resultados reales. **

El alcance real de la aplicación de campo está sujeto a las tablas de recursos anteriores; cuando la plataforma actualice campos o enumeraciones, se adaptará según la nueva descripción de la interfaz y la versión SDK.

Guías fuente y relacionadas

• Fuente oficial v0.3.0
• Cartera de financiación
• Guía de actualización