영구 쿼리 및 페이지 매김

이 가이드는 Agent Java SDK v0.3.0, Java 8+ 및 태그된 공개 계약을 대상으로 합니다. 예제는 client를 초기화한 후 파트너 백엔드에서 실행됩니다. 빠른 시작.

예시 전제조건

Java 조각은 이러한 가져오기를 공유합니다. 빠른 시작을 사용하여 client를 초기화하고 저장된 바인딩에서 platformUserId를 가져옵니다. 예시 사용자/주문 ID는 고유한 지속 값으로 대체되어야 합니다.

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

무기한 계약 데이터 쿼리

6가지 유형의 인터페이스와 Java 메소드

모든 요청은 공통 접두사 /v1/agent/perpetual를 사용하여 POST로 서명됩니다.

platformUserIds는 공개 플랫폼 ID의 문자열 배열입니다. 지정된 경우 액세스 권한이 있는 고유 플레이어는 1~100명이 필요합니다. 생략을 허용하는 엔드포인트에서는 현재 판매자가 액세스할 수 있는 직접 플레이어의 범위만 쿼리됩니다. 교환 채우기 쿼리에는 항상 이 배열이 필요합니다. 조건부 순서 쿼리에는 명시적인 사용자 ID도 필요합니다. 생략은 []와 동일하지 않으며 빈 배열은 불법입니다. 범위는 서명한 판매자에 의해 결정되며, 범위 확장을 위해 다른 판매자 ID를 전달할 수 없습니다.

배열 값은 서명 페이로드에 합류하기 전에 압축된 JSON로 직렬화됩니다. 예를 들어, platformUserIds는 ["1188041528"]로 서명되어 k=v 페이로드에 platformUserIds=["1188041528"]를 제공합니다. 배열 요소 순서, 큰따옴표 및 문자열 ID를 유지합니다. 서식 지정 공백을 삽입하거나 Java List.toString()(예: [1188041528])를 사용하지 마세요. SDK는 이 직렬화를 자동으로 처리합니다.

주문 쿼리는 orderCategory=NORMAL 또는 CONDITIONAL를 전달해야 합니다. 일반 주문에는 orderId를 사용하고 조건부 주문에는 conditionId를 사용합니다. 카테고리 간에 혼합될 수 없습니다. 조건부 주문과 이를 실행하여 생성된 일반 주문은 별도로 개체로 처리됩니다.

필터 조건

기록 쿼리 시간은 Unix 밀리초이고 간격은 [startTime, endTime)입니다. 서명을 요청하는 시간은 timestamp이며 Unix 초입니다. UTC 기간을 수정하고 세그먼트 단위로 쿼리하는 것이 좋습니다. 일일 조정에는 UTC를 사용하세요. 상태 및 유형은 플랫폼 계약 열거를 사용하며 자체적으로 중국어 문자열로 변환되지 않습니다.

limit 기본값은 500, 범위는 1~1000입니다. 페이지 크기가 매번 동일한 숫자가 반환된다는 것을 보장하지는 않습니다. 6개의 인터페이스는 현재 초당 2회, 판매자당 버스트 4개의 쿼리 할당량을 공유하고 있으며 인스턴스 내 각 판매자의 최대 동시성 제한은 2입니다. 판매자 측은 통합 대기열을 사용하며 순차 페이징과 더 작은 기록 창으로 시작하는 것이 좋습니다.

Java 쿼리 예시

플레이어의 현재 일반 주문을 쿼리합니다.

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

지난 1시간 동안의 계약 변경 사항을 쿼리하고 커서를 처리합니다. 다음 예에서는 자동으로 재시도하지 않습니다. 실제 애플리케이션에 현재 제한 사항이나 일시적인 오류가 발생하는 경우 링크된 관련 가이드에 따라 동일한 페이지를 복원하세요.

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

반환 구조 및 저장 규칙

보다 일반적인 응답 및 페이지 매김 공유 필드의 경우. 리소스 필드는 다음 문서에 설명되어 있습니다. 명령, 거래 채우기, 직위 그리고 계약 원장.

6개의 인터페이스는 PerpetualResponse를 균일하게 반환합니다.

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

각 items에는 platformUserId, entityType, entityId, data가 포함됩니다. 항목 유형에는 ORDER, CONDITION_ORDER, TRADE_FILL, POSITION, ACCOUNT_LEDGER가 포함됩니다. 멱등성 키를 구축하려면 다음 세 가지 ID 필드를 사용하세요. 조건부 주문 ID, 주문 ID, 채우기 ID를 동일한 번호로 처리하지 마십시오.

data 자원별 가격, 수량, 상태, 비용, 손익, 잔액 변동 등의 필드를 제공합니다. 금액, 가격, 수량 및 엔터티 ID는 문자열로 처리됩니다. 비즈니스 시간은 밀리초 단위입니다. 누락된 필드는 0으로 채워지지 않으며 다른 엔터티에서 추론되지 않습니다.

커서는 신뢰할 수 있는 증분 구독이나 보장된 페이지 간 원자 스냅샷이 아닌 쿼리의 페이징 위치입니다. 현재 커서는 첫 번째 생성 라운드로부터 24시간 동안 유효합니다. 후속 페이징에서는 동일한 판매자, 리소스, 플레이어 컬렉션 및 필터 조건을 유지합니다. 기록 가져오기에 대한 고정 창은 반복적으로 가져오는 경우 멱등성을 갖습니다. 현재 주문/포지션의 상태는 다시 쿼리한 후 새로 고쳐집니다. 실시간 인터페이스가 필요한 경우 플랫폼 프런트 엔드의 데이터 메커니즘이 사용되며 폴링 6 인터페이스는 고주파 시장 인터페이스로 간주될 수 없습니다.

오류 및 복구

HTTP 성공이 사업 성공을 의미하는 것은 아니며, 반드시 code를 확인하셔야 합니다. Java SDK는 AgentApiException로 비즈니스 오류를 발생시킵니다.

cursor 및 원래 실패한 페이지의 모든 필터 조건은 전류 제한, 시간 초과 또는 임시 실패 후에도 유지됩니다. SDK가 호출될 때마다 새로운 timestamp, nonce, sign가 생성됩니다. 다음 페이지로 바로 이동할 수 없으며 실패를 빈 결과로 처리할 수도 없습니다. SDK는 자동으로 자금 거래를 재시도하는 것에 대해 책임을 지지 않습니다.

일반적인 응답 및 페이지 매김

각 data.items[]의 구조:

동일한 ledgerId는 처리 수수료, 손익 등과 같은 여러 세부 사항을 분리할 수 있습니다. 중복 항목을 제거하기 위해 ledgerId를 누르면 데이터가 손실됩니다. 서로 다른 리소스의 ID를 혼합할 수 없습니다. 페이징 및 필드 저장 규칙은 액세스 가이드의 링크된 관련 가이드를 참조하세요.

유형, 단위 및 생략된 필드

• 금액, 가격, 수량, 엔터티 ID 사용 문자열입니다. 금액을 처리하려면 소수를 사용하고, 부동 소수점 숫자를 사용하거나 긴 ID를 JavaScript 숫자로 변환할 수 없습니다. 거래쌍/계약 사양에 따라 금액 통화 및 수량 단위를 설명합니다.
• 업무 시간은 정수(int64)를 사용하며 둘 다 Unix 밀리초입니다. 인증 타임스탬프 및 항목 자격 증명 expireAt을 요청하면 초를 사용하므로 혼동될 수 없습니다.
• 문자열 비즈니스 필드는 일반적으로 비어 있으면 출력되지 않으며, 숫자 필드가 0인 경우 일부가 생략됩니다. 누락된 필드가 비즈니스 값이 0이라는 의미는 아닙니다.
• 일반 기록 모델의 reduceOnly, closeOnly, makerOnly는 거짓을 생략하지 않으므로 이 세 가지 거짓이 거래나 포지션에도 나타날 수 있습니다. 이는 주문 리소스에서만 설명됩니다. 해당 거래/포지션이 해당 주문 규칙을 실행했다고 간주할 수 없습니다.
• closePosition는 선택적 부울입니다. 조건부 순서로 제공되며 일반적으로 다른 리소스에서는 생략됩니다. 누락은 거짓과 다른 의미를 갖습니다.
• “현재 제공되는” 아래 표는 읽기 논리에 필드 소스가 있음을 의미합니다. 선택적 필드는 값이 없기 때문에 생략될 수 있습니다. 모델에 존재하는 필드가 모든 인터페이스에 채워지는 것은 아닙니다.

상태 모드와 마진 모드의 차이점

일반 주문의 CANCELED 철자는 조건부 주문의 CANCELLED 철자와 다릅니다. 조건부 주문이 실행되었다고 해서 생성된 일반 주문이 체결되었다는 의미는 아닙니다. 모든 자원에 대해 동일한 상태 변환 테이블 세트를 재사용하지 마십시오.

조건부 순서 marginMode는 CROSS / ISOLATED를 반환합니다. 과거 일반 주문 및 포지션은 현재 각각 교차/격리 마진인 “1” / “2”를 반환합니다. marginMode은 현재 일반 주문에는 제공되지 않습니다. 판매자는 자체 디스플레이 레이어에서 리소스별로 정규화할 수 있으며 원래 값은 계속 저장해야 합니다.

모델에 선언되었지만 이 쿼리에는 제공되지 않은 필드

Generic RecordData / Java PerpetualData 모델은 다음 필드도 선언하지만 현재 6개 범주의 프로덕션 읽기 논리는 해당 필드를 채우지 않습니다. **사용 가능한 비즈니스 데이터로 나열되어서는 안 되며, 실제 결과를 필드 기본값으로 대체해서도 안 됩니다. **

실제 현장 적용 범위는 위의 리소스 테이블에 따릅니다. 플랫폼이 필드 또는 열거를 업데이트할 때 새로운 인터페이스 설명 및 SDK 버전에 따라 조정되어야 합니다.

소스 및 관련 가이드

• 공식 v0.3.0 소스
• 펀딩 지갑
• 업그레이드 가이드