Requêtes perpétuelles et pagination

Ce guide cible Agent Java SDK v0.3.0, Java 8+ et le contrat public étiqueté. Exemples exécutés dans un backend partenaire après l’initialisation de client dans Démarrage rapide.

Exemples de prérequis

Les extraits de code Java partagent ces importations. Initialisez client à l’aide de Quick Start et obtenez platformUserId à partir de la liaison enregistrée. Les exemples d’ID utilisateur/commande doivent être remplacés par vos propres valeurs persistantes.

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

Interroger les données du contrat perpétuel

Six types d’interfaces et de méthodes Java

Toutes les demandes sont signées POST avec un préfixe commun de /v1/agent/perpetual.

platformUserIds est un tableau de chaînes d’ID de plate-forme publique. Lorsque spécifié, 1 à 100 joueurs uniques ayant accès sont requis ; sur les points de terminaison qui autorisent l’omission, seule la gamme de joueurs directs auxquels le commerçant actuel a accès est interrogée. Les requêtes de remplissage nécessitent toujours ce tableau ; les requêtes avec ordre conditionnel nécessitent également des ID utilisateur explicites. L’omission n’est pas équivalente à [] et les tableaux vides sont illégaux. La portée est déterminée par le commerçant signataire, et d’autres identifiants de commerçant ne peuvent pas être transmis pour étendre la portée.

Les valeurs du tableau sont sérialisées sous forme compacte JSON avant de rejoindre la charge utile de signature. Par exemple, platformUserIds signe comme ["1188041528"], donnant platformUserIds=["1188041528"] dans la charge utile k=v. Conservez l’ordre des éléments du tableau, les guillemets doubles et les ID de chaîne ; n’insérez pas d’espaces de formatage et n’utilisez pas Java List.toString() (comme [1188041528]). Le SDK gère automatiquement cette sérialisation.

La requête de commande doit transmettre orderCategory=NORMAL ou CONDITIONAL. Utilisez orderId pour les commandes ordinaires et conditionId pour les commandes conditionnelles. Ils ne peuvent pas être mélangés entre catégories. Les ordres conditionnels et les ordres ordinaires générés par leur déclenchement sont traités séparément en tant qu’entités.

Conditions de filtrage

L’heure de la requête historique est Unix millisecondes et l’intervalle est [startTime, endTime) ; l’heure de la demande de signature est timestamp soit Unix secondes. Il est recommandé de corriger la fenêtre horaire et la requête UTC par segments ; utilisez UTC pour le rapprochement quotidien. Le statut et le type utilisent l’énumération du contrat de la plate-forme et ne sont pas traduits eux-mêmes en chaînes chinoises.

limit La valeur par défaut est 500, la plage est de 1 à 1 000 ; la taille de la page ne garantit pas que le même numéro sera renvoyé à chaque fois. Les six interfaces partagent actuellement un quota de requêtes de 2 fois par seconde et 4 rafales par commerçant, et la limite maximale de simultanéité pour chaque commerçant au sein de l’instance est de 2. Le côté commerçant utilise une file d’attente unifiée, et il est recommandé de commencer par une pagination séquentielle et une fenêtre d’historique plus petite.

Java exemples de requêtes

Interrogez l’ordre ordinaire actuel d’un joueur :

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

Recherchez les modifications du contrat au cours de la dernière heure et traitez le curseur. L’exemple suivant ne réessaye pas automatiquement ; lorsque l’application réelle rencontre une limitation actuelle ou une panne temporaire, suivez le guide associé lié pour restaurer la même page.

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

Structure de retour et règles d’épargne

Voir Réponse et pagination communes pour les champs partagés. Les champs de ressources sont documentés dans Ordres, Le commerce remplit, Postes et Grand livre des contrats.

Les six interfaces renvoient uniformément PerpetualResponse :

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

Chaque items contient platformUserId, entityType, entityId, data. Les types d’entités incluent ORDER, CONDITION_ORDER, TRADE_FILL, POSITION, ACCOUNT_LEDGER. Utilisez ces trois champs d’identité pour créer une clé idempotente ; ne traitez pas l’ID de commande conditionnel, l’ID de commande et l’ID de remplissage comme le même numéro.

data Fournit des champs tels que le prix, la quantité, le statut, les dépenses, les profits et pertes ou la modification du solde par ressource. Le montant, le prix, la quantité et l’ID d’entité sont traités comme des chaînes ; le temps de travail est en millisecondes. Les champs manquants ne sont pas remplis à 0 et ne sont pas déduits d’autres entités.

Le curseur est la position de pagination d’une requête, pas un abonnement incrémentiel fiable, ni un instantané atomique garanti sur plusieurs pages. Le curseur actuel est valable 24 heures à compter du premier tour de génération ; la pagination ultérieure conserve les mêmes marchands, ressources, collections de joueurs et conditions de filtrage. La fenêtre fixe pour l’extraction historique est idempotente lorsqu’elle est tirée à plusieurs reprises ; le statut de la commande/position actuelle est actualisé après une nouvelle requête. Lorsqu’une interface en temps réel est nécessaire, le mécanisme de données de l’interface de la plate-forme est utilisé et l’interface de sondage six ne peut pas être considérée comme une interface de marché à haute fréquence.

Erreurs et récupération

Le succès de HTTP ne signifie pas le succès commercial, vous devez cocher code. Java SDK générera une erreur commerciale sous la forme AgentApiException.

Le cursor et toutes les conditions de filtre de la page d’origine ayant échoué seront conservés après une limitation de courant, un délai d’attente ou un échec temporaire ; chaque fois que SDK est rappelé, de nouveaux timestamp, nonce, sign seront générés. Vous ne pouvez pas passer directement à la page suivante et vous ne pouvez pas traiter les échecs comme des résultats vides. SDK n’est pas responsable de la nouvelle tentative automatique de transactions de fonds.

Réponse et pagination communes

La structure de chaque data.items[] :

Le même ledgerId peut séparer plusieurs détails tels que les frais de traitement, les profits et les pertes, etc. ; appuyer sur ledgerId pour supprimer les doublons entraînera une perte de données. Les identifiants de différentes ressources ne peuvent pas être mélangés. Consultez le guide connexe du Guide d’accès pour connaître les règles de pagination et d’enregistrement des champs.

Types, unités et champs omis

• Le montant, le prix, la quantité et l’ID d’entité utilisent la chaîne ; utilisez le mode décimal pour traiter les montants et ne pouvez pas utiliser de nombres à virgule flottante ni convertir des identifiants longs en nombres JavaScript. La devise du montant et l’unité de quantité sont expliquées en fonction des spécifications de la paire commerciale/du contrat.
• Le temps professionnel utilise un nombre entier (int64), les deux sont des millisecondes Unix ; demander l’horodatage d’authentification et les informations d’identification d’entrée expireAt utilisent des secondes et ne peuvent pas être confondus.
• Les champs métier de chaîne ne sont généralement pas affichés lorsqu’ils sont vides, et certains seront omis lorsque les champs numériques sont 0. Le champ manquant ne signifie pas que la valeur métier est 0.
• reduceOnly, closeOnly, makerOnly dans le modèle d’enregistrement général n’omettent pas faux, donc ces trois faux peuvent également apparaître dans les transactions ou les positions. Ils sont uniquement expliqués dans les ressources de la commande ; on ne peut pas considérer que la transaction/position a exécuté les règles d’ordre correspondantes.
• closePosition est un booléen facultatif : fourni par des commandes conditionnelles, généralement omis pour d’autres ressources. Manquant a une signification différente de faux.
• Le tableau ci-dessous « actuellement fourni » signifie que la logique de lecture possède un champ source ; les champs facultatifs peuvent toujours être omis car ils n’ont aucune valeur. Il n’est pas garanti que les champs qui existent dans le modèle soient remplis dans chaque interface.

La différence entre le mode statut et le mode marge

L’orthographe de CANCELED pour une commande ordinaire est différente de celle de CANCELLED pour une commande conditionnelle ; le déclenchement d’un ordre conditionnel ne signifie pas que l’ordre ordinaire généré a été exécuté. Ne réutilisez pas le même ensemble de tables de conversion de statut pour toutes les ressources.

L’ordre conditionnel marginMode renvoie CROSS / ISOLATED ; Les ordres et positions ordinaires historiques renvoient actuellement « 1 » / « 2 », qui sont respectivement des marges croisées/isolées. marginMode n’est actuellement pas disponible pour les commandes ordinaires. Les commerçants peuvent normaliser par ressource dans leur propre couche d’affichage, et les valeurs d’origine doivent toujours être enregistrées.

Champs déclarés dans le modèle mais non fournis dans cette requête

Generic RecordData / Java Le modèle PerpetualData déclare également les champs suivants, mais la logique de lecture de production actuelle à six catégories ne les remplit pas. **Ne doivent pas être répertoriés comme données commerciales disponibles, et les valeurs par défaut des champs ne doivent pas non plus être remplacées par des résultats réels. **

La portée réelle de l’application sur le terrain est soumise aux tableaux de ressources ci-dessus ; lorsque la plateforme met à jour des champs ou des énumérations, elle sera adaptée en fonction de la nouvelle description de l’interface et de la version de SDK.

Source et guides associés

• Source officielle v0.3.0
• Portefeuille de financement
• Guide de mise à niveau