Ständige Abfragen und Paginierung

Dieser Leitfaden richtet sich an Agent Java SDK v0.3.0, Java 8+ und den getaggten öffentlichen Auftrag. Beispiele werden nach der Initialisierung von client in einem Partner-Backend ausgeführt Schnellstart.

Beispielvoraussetzungen

Die Java-Snippets teilen diese Importe. Initialisieren Sie client mit Quick Start und rufen Sie platformUserId aus der gespeicherten Bindung ab. Beispiel-Benutzer-/Bestell-IDs müssen durch Ihre eigenen persistenten Werte ersetzt werden.

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

Fragen Sie unbefristete Vertragsdaten ab

Sechs Arten von Schnittstellen und Java-Methoden

Alle Anfragen werden mit POST mit dem gemeinsamen Präfix /v1/agent/perpetual signiert.

platformUserIds ist ein String-Array öffentlicher Plattform-IDs. Sofern angegeben, sind 1 bis 100 einzelne Spieler mit Zugriff erforderlich; Auf Endpunkten, die das Auslassen zulassen, wird nur der Bereich der direkten Spieler abgefragt, auf den der aktuelle Händler Zugriff hat. Trade-Fill-Abfragen erfordern immer dieses Array; Abfragen mit bedingter Reihenfolge erfordern auch explizite Benutzer-IDs. Auslassung ist nicht gleichbedeutend mit [] und leere Arrays sind unzulässig. Der Geltungsbereich wird vom unterzeichnenden Händler bestimmt und andere Händler-IDs können nicht weitergegeben werden, um den Geltungsbereich zu erweitern.

Array-Werte werden als kompakte JSON serialisiert, bevor sie der Signierungsnutzlast hinzugefügt werden. Beispielsweise signiert platformUserIds als ["1188041528"] und ergibt platformUserIds=["1188041528"] in der Nutzlast k=v. Behalten Sie die Reihenfolge der Array-Elemente, doppelte Anführungszeichen und String-IDs bei. Fügen Sie keine Formatierungsleerzeichen ein und verwenden Sie nicht Java List.toString() (z. B. [1188041528]). Der SDK übernimmt diese Serialisierung automatisch.

Die Bestellabfrage muss orderCategory=NORMAL oder CONDITIONAL bestehen. Verwenden Sie orderId für normale Bestellungen und conditionId für bedingte Bestellungen. Sie können nicht kategorienübergreifend gemischt werden. Bedingte Bestellungen und die durch ihre Auslösung generierten gewöhnlichen Bestellungen werden separat als Einheiten verarbeitet.

Filterbedingungen

Die Zeit der historischen Abfrage beträgt Unix Millisekunden und das Intervall beträgt [startTime, endTime); Die Zeit für die Signaturanforderung beträgt timestamp und beträgt unter Unix Sekunden. Es wird empfohlen, das Zeitfenster UTC festzulegen und segmentweise abzufragen. Verwenden Sie UTC für den täglichen Abgleich. Status und Typ verwenden die Aufzählung von Plattformverträgen und werden nicht selbst in chinesische Zeichenfolgen übersetzt.

limit Der Standardwert ist 500, der Bereich liegt zwischen 1 und 1000; Die Seitengröße garantiert nicht, dass jedes Mal dieselbe Zahl zurückgegeben wird. Die sechs Schnittstellen teilen sich derzeit ein Abfragekontingent von 2 Mal pro Sekunde und 4 Bursts pro Händler, und die maximale Parallelitätsgrenze für jeden Händler innerhalb der Instanz beträgt 2. Die Händlerseite verwendet eine einheitliche Warteschlange, und es wird empfohlen, mit sequenziellem Paging und einem kleineren Verlaufsfenster zu beginnen.

Java Abfragebeispiele

Fragen Sie die aktuelle normale Reihenfolge eines Spielers ab:

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

Fragen Sie die Vertragsänderungen der letzten Stunde ab und verarbeiten Sie den Cursor. Das folgende Beispiel führt keinen automatischen Wiederholungsversuch durch; Wenn bei der eigentlichen Anwendung eine aktuelle Einschränkung oder ein vorübergehender Fehler auftritt, befolgen Sie die verlinkte entsprechende Anleitung, um dieselbe Seite wiederherzustellen.

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

Rückgabestruktur und Sparregeln

Sehen Gemeinsame Antwort und Paginierung für gemeinsam genutzte Felder. Ressourcenfelder sind in dokumentiert Bestellungen, Handelsfüllungen, Positionen Und Vertragsbuch.

Die sechs Schnittstellen geben einheitlich PerpetualResponse zurück:

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

Jedes items enthält platformUserId, entityType, entityId, data. Zu den Entitätstypen gehören ORDER, CONDITION_ORDER, TRADE_FILL, POSITION, ACCOUNT_LEDGER. Verwenden Sie diese drei Identitätsfelder, um einen idempotenten Schlüssel zu erstellen; Behandeln Sie die bedingte Bestell-ID, die Bestell-ID und die Füll-ID nicht als dieselbe Nummer.

data Stellt Felder wie Preis, Menge, Status, Aufwand, Gewinn und Verlust oder Saldoänderung nach Ressource bereit. Betrag, Preis, Menge und Entitäts-ID werden als Zeichenfolgen behandelt; Die Geschäftszeit wird in Millisekunden angegeben. Fehlende Felder werden nicht auf 0 ausgefüllt und nicht von anderen Entitäten abgeleitet.

Der Cursor ist die Paging-Position einer Abfrage, weder ein zuverlässiges inkrementelles Abonnement noch ein garantierter seitenübergreifender atomarer Snapshot. Der aktuelle Cursor ist ab der ersten Generierungsrunde 24 Stunden lang gültig; Beim nachfolgenden Paging bleiben die gleichen Händler, Ressourcen, Spielersammlungen und Filterbedingungen erhalten. Das feste Fenster für den historischen Pull ist bei wiederholtem Pull idempotent; Der Status der aktuellen Bestellung/Position wird nach einer erneuten Abfrage aktualisiert. Wenn eine Echtzeitschnittstelle benötigt wird, wird der Datenmechanismus des Plattform-Frontends verwendet, und die Polling-Sechs-Schnittstelle kann nicht als Hochfrequenz-Marktschnittstelle betrachtet werden.

Fehler und Wiederherstellung

HTTP Erfolg bedeutet nicht gleich Geschäftserfolg, Sie müssen code überprüfen. Java SDK gibt einen Geschäftsfehler als AgentApiException aus.

Der cursor und alle Filterbedingungen der ursprünglich fehlgeschlagenen Seite bleiben nach Strombegrenzung, Zeitüberschreitung oder vorübergehendem Ausfall erhalten; Jedes Mal, wenn SDK erneut aufgerufen wird, werden neue timestamp, nonce, sign generiert. Sie können nicht direkt zur nächsten Seite springen und Fehler nicht als leere Ergebnisse behandeln. SDK ist nicht für die automatische Wiederholung von Geldtransaktionen verantwortlich.

Gemeinsame Antwort und Paginierung

Die Struktur jedes data.items[]:

Dasselbe ledgerId kann mehrere Details wie Bearbeitungsgebühren, Gewinn und Verlust usw. trennen; Das Drücken von ledgerId zum Entfernen von Duplikaten führt zu Datenverlust. IDs verschiedener Ressourcen können nicht gemischt werden. Informationen zu Paging- und Feldspeicherregeln finden Sie im verlinkten zugehörigen Leitfaden des Access Guide.

Typen, Einheiten und ausgelassene Felder

• Menge, Preis, Menge und Entitäts-ID-Verwendungszeichenfolge; Verwenden Sie Dezimalzahlen, um Beträge zu verarbeiten, und können Sie keine Gleitkommazahlen verwenden oder lange IDs in JavaScript-Zahlen konvertieren. Die Betragswährung und die Mengeneinheit werden entsprechend den Handelspaar-/Kontraktspezifikationen erläutert.
• Die Geschäftszeit verwendet eine Ganzzahl (int64). Beide sind Unix-Millisekunden. Der Zeitstempel der Anforderungsauthentifizierung und die Zugangsdaten expireAt verwenden Sekunden und können nicht verwechselt werden.
• String-Geschäftsfelder werden normalerweise nicht ausgegeben, wenn sie leer sind, und einige werden weggelassen, wenn numerische Felder 0 sind. Das fehlende Feld bedeutet nicht, dass der Geschäftswert 0 ist.
• reduceOnly, closeOnly, makerOnly lassen im allgemeinen Datensatzmodell „false“ nicht aus, daher können diese drei „false“ auch in Transaktionen oder Positionen vorkommen. Sie werden lediglich in den Bestellressourcen erläutert; Es kann nicht davon ausgegangen werden, dass die Transaktion/Position die entsprechenden Orderregeln ausgeführt hat.
• closePosition ist ein optionaler boolescher Wert: wird von bedingten Befehlen bereitgestellt und normalerweise für andere Ressourcen weggelassen. Fehlend hat eine andere Bedeutung als falsch.
• Die nachstehende Tabelle „aktuell bereitgestellt“ bedeutet, dass die Leselogik über eine Feldquelle verfügt; Optionale Felder können weiterhin weggelassen werden, da sie keinen Wert haben. Es kann nicht garantiert werden, dass die im Modell vorhandenen Felder in jeder Schnittstelle ausgefüllt werden.

Der Unterschied zwischen Status- und Randmodus

Die Schreibweise von CANCELED für eine gewöhnliche Bestellung unterscheidet sich von der Schreibweise von CANCELLED für eine bedingte Bestellung. Das Auslösen einer bedingten Bestellung bedeutet nicht, dass die generierte normale Bestellung ausgeführt wurde. Verwenden Sie nicht für alle Ressourcen denselben Satz von Statusübersetzungstabellen wieder.

Bedingte Reihenfolge marginMode gibt CROSS / ISOLATED zurück; Historische gewöhnliche Aufträge und Positionen geben derzeit „1“ / „2“ zurück, wobei es sich jeweils um Kreuz-/isolierte Margen handelt. marginMode ist derzeit nicht für normale Bestellungen verfügbar. Händler können in ihrer eigenen Anzeigeebene nach Ressourcen normalisieren, die Originalwerte müssen jedoch weiterhin gespeichert werden.

Felder, die im Modell deklariert, aber in dieser Abfrage nicht bereitgestellt werden

Generic RecordData / Java Das PerpetualData-Modell deklariert auch die folgenden Felder, aber die aktuelle Produktionsleselogik mit sechs Kategorien füllt sie nicht. **Sollten weder als verfügbare Geschäftsdaten aufgeführt werden, noch sollten Feldstandards durch echte Ergebnisse ersetzt werden. **

Der tatsächliche Anwendungsbereich vor Ort unterliegt den oben genannten Ressourcentabellen. Wenn die Plattform Felder oder Aufzählungen aktualisiert, muss sie entsprechend der neuen Schnittstellenbeschreibung und der SDK-Version angepasst werden.

Quelle und zugehörige Leitfäden

• Offizielle Quelle v0.3.0
• Funding-Wallet
• Upgrade-Anleitung