Query e impaginazione perpetua

Questa guida è rivolta a Agent Java SDK v0.3.0, Java 8+ e agli appalti pubblici contrassegnati. Gli esempi vengono eseguiti nel backend di un partner dopo aver inizializzato client in Avvio rapido.

Prerequisiti di esempio

Gli snippet Java condividono queste importazioni. Inizializza client utilizzando Quick Start e ottieni platformUserId dall’associazione salvata. Gli ID utente/ordine di esempio devono essere sostituiti con i tuoi valori persistenti.

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

Interrogare i dati del contratto perpetuo

Sei tipi di interfacce e metodi Java.

Tutte le richieste sono firmate POST con il prefisso comune /v1/agent/perpetual.

platformUserIds è un array di stringhe di ID di piattaforma pubblica. Quando specificato, sono richiesti da 1 a 100 giocatori unici che hanno accesso; sugli endpoint che consentono l’omissione, viene interrogata solo la gamma di giocatori diretti a cui ha accesso il commerciante attuale. Le query di riempimento richiedono sempre questa matrice; anche le query di ordine condizionale richiedono ID utente espliciti. L’omissione non è equivalente a [] e gli array vuoti sono illegali. L’ambito è determinato dal commerciante firmatario e non è possibile trasmettere altri ID commerciante per espandere l’ambito.

I valori dell’array vengono serializzati come compatti JSON prima di unirsi al payload della firma. Ad esempio, platformUserIds viene indicato come ["1188041528"], fornendo platformUserIds=["1188041528"] nel payload k=v. Conserva l’ordine degli elementi dell’array, le virgolette doppie e gli ID delle stringhe; non inserire spazi di formattazione né utilizzare Java List.toString() (ad esempio [1188041528]). Il SDK gestisce questa serializzazione automaticamente.

La query dell’ordine deve superare orderCategory=NORMAL o CONDITIONAL. Utilizza orderId per gli ordini ordinari e conditionId per gli ordini condizionati. Non possono essere mescolati tra le categorie. Gli ordini condizionati e gli ordini ordinari generati dalla loro attivazione vengono elaborati separatamente come entità.

Condizioni del filtro

Il tempo della query storica è Unix millisecondi e l’intervallo è [startTime, endTime); il tempo di richiesta della firma è timestamp è Unix secondi. Si consiglia di fissare la finestra temporale UTC e di eseguire query in segmenti; utilizzare UTC per la riconciliazione quotidiana. Lo stato e il tipo utilizzano l’enumerazione del contratto della piattaforma e non vengono tradotti automaticamente in stringhe cinesi.

limit Il valore predefinito è 500, l’intervallo è 1~1000; la dimensione della pagina non garantisce che venga restituito ogni volta lo stesso numero. Le sei interfacce attualmente condividono una quota di query di 2 volte al secondo e 4 burst per commerciante e il limite massimo di concorrenza per ciascun commerciante all’interno dell’istanza è 2. Il lato commerciante utilizza una coda unificata e si consiglia di iniziare con il paging sequenziale e una finestra della cronologia più piccola.

Java esempi di query

Interroga l’attuale ordine ordinario di un giocatore:

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

Interroga le modifiche del contratto nell’ultima ora ed elabora il cursore. L’esempio seguente non riprova automaticamente; quando l’applicazione effettiva incontra limitazioni attuali o guasti temporanei, seguire la guida correlata collegata per ripristinare la stessa pagina.

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

Struttura dei rendimenti e regole di salvataggio

Vedere Risposta comune e impaginazione per i campi condivisi. I campi delle risorse sono documentati in Ordini, Il commercio si riempie, Posizioni E Registro dei contratti.

Le sei interfacce restituiscono uniformemente PerpetualResponse:

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

Ciascun items contiene platformUserId, entityType, entityId, data. I tipi di entità includono ORDER, CONDITION_ORDER, TRADE_FILL, POSITION, ACCOUNT_LEDGER. Utilizza questi tre campi di identità per creare una chiave idempotente; non considerare l’ID dell’ordine condizionato, l’ID dell’ordine e l’ID di riempimento come lo stesso numero.

data Fornisce campi quali prezzo, quantità, stato, spesa, profitti e perdite o variazione del saldo per risorsa. Importo, prezzo, quantità e ID entità vengono gestiti come stringhe; il tempo lavorativo è espresso in millisecondi. I campi mancanti non vengono compilati fino a 0 e non vengono dedotti da altre entità.

Il cursore è la posizione di paginazione di una query, non una sottoscrizione incrementale affidabile, né uno snapshot atomico garantito su più pagine. Il cursore attuale ha validità 24 ore dal primo turno di generazione; la paginazione successiva mantiene gli stessi commercianti, risorse, collezioni di giocatori e condizioni di filtro. La finestra fissa per il pull storico è idempotente se tirata ripetutamente; lo stato dell’ordine/posizione corrente viene aggiornato dopo aver ripetuto la query. Quando è necessaria un’interfaccia in tempo reale, viene utilizzato il meccanismo dei dati del front-end della piattaforma e l’interfaccia di polling sei non può essere considerata un’interfaccia di mercato ad alta frequenza.

Errori e ripristino

HTTP successo non significa successo aziendale, devi verificare code. Java SDK genererà un errore aziendale come AgentApiException.

Il cursor e tutte le condizioni del filtro della pagina originale non riuscita verranno mantenuti dopo la limitazione corrente, il timeout o il guasto temporaneo; ad ogni richiamo di SDK verranno generati nuovi timestamp, nonce, sign. Non è possibile passare direttamente alla pagina successiva e non è possibile trattare gli errori come risultati vuoti. SDK non è responsabile del nuovo tentativo automatico di transazioni di fondi.

Risposta comune e impaginazione

La struttura di ciascun data.items[]:

Lo stesso ledgerId può separare più dettagli come commissioni di gestione, profitti e perdite, ecc.; premendo ledgerId per rimuovere i duplicati si causerà la perdita di dati. Gli ID di risorse diverse non possono essere mischiati. Consultare la guida correlata collegata della Guida all’accesso per le regole di paginazione e salvataggio dei campi.

Tipi, unità e campi omessi

• Stringa di utilizzo di importo, prezzo, quantità e ID entità; utilizzare i decimali per elaborare gli importi e non è possibile utilizzare numeri a virgola mobile o convertire ID lunghi in numeri JavaScript. La valuta dell’importo e l’unità di quantità vengono spiegate in base alle specifiche della coppia di trading/contratto.
• L’ora aziendale utilizza il numero intero (int64), entrambi sono millisecondi Unix; il timestamp di autenticazione della richiesta e le credenziali di accesso expireAt utilizzano secondi e non possono essere confusi.
• I campi aziendali stringa in genere non vengono restituiti quando sono vuoti e alcuni verranno omessi quando i campi numerici sono 0. Il campo mancante non significa che il valore aziendale è 0.
• reduceOnly, closeOnly, makerOnly nel modello di record generale non omettono false, quindi queste tre false possono apparire anche in transazioni o posizioni. Sono spiegati solo nelle risorse dell’ordine; non si può ritenere che la transazione/posizione abbia eseguito le regole dell’ordine corrispondenti.
• closePosition è un valore booleano opzionale: fornito da ordini condizionati, solitamente omesso per altre risorse. Mancante ha un significato diverso da falso.
• La tabella seguente “attualmente fornita” significa che la logica di lettura ha un’origine campo; i campi facoltativi possono comunque essere omessi perché non hanno valore. Non è garantito che i campi presenti nel modello vengano compilati in ogni interfaccia.

La differenza tra stato e modalità margine

L’ortografia di CANCELED per un ordine ordinario è diversa da quella di CANCELLED per un ordine condizionato; l’attivazione di un ordine condizionato non significa che l’ordine ordinario generato sia stato eseguito. Non riutilizzare lo stesso set di tabelle di conversione dello stato per tutte le risorse.

L’ordine condizionale marginMode restituisce CROSS / ISOLATED; gli ordini e le posizioni ordinari storici attualmente restituiscono “1” / “2”, che sono rispettivamente margine incrociato/isolato. marginMode al momento non è disponibile per gli ordini ordinari. I commercianti possono normalizzare in base alle risorse nel proprio livello di visualizzazione e i valori originali devono ancora essere salvati.

Campi dichiarati nel modello ma non forniti in questa query

Generic RecordData / Java Il modello PerpetualData dichiara inoltre i seguenti campi, ma l’attuale logica di lettura della produzione a sei categorie non li popola. **Non devono essere elencati come dati aziendali disponibili, né i valori predefiniti dei campi devono essere sostituiti con risultati reali. **

L’effettivo ambito di applicazione sul campo è soggetto alle tabelle delle risorse di cui sopra; quando la piattaforma aggiorna campi o enumerazioni, deve essere adattata in base alla nuova descrizione dell’interfaccia e alla versione SDK.

Fonte e guide correlate

• Fonte ufficiale v0.3.0
• Portafoglio di finanziamento
• Guida all’aggiornamento