> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.6mm.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.6mm.com/_mcp/server. # 영구 쿼리 및 페이지 매김 이 가이드는 **Agent Java SDK `v0.3.0`**, Java 8+ 및 태그된 공개 계약을 대상으로 합니다. 예제는 `client`를 초기화한 후 파트너 백엔드에서 실행됩니다. [빠른 시작](/ko/sdk/agent-sdk/java/quick-start). ## 예시 전제조건 Java 조각은 이러한 가져오기를 공유합니다. 빠른 시작을 사용하여 `client`를 초기화하고 저장된 바인딩에서 `platformUserId`를 가져옵니다. 예시 사용자/주문 ID는 고유한 지속 값으로 대체되어야 합니다. ```java import com.sixmm.agent.*; import com.sixmm.agent.model.*; import java.util.*; ``` ## 무기한 계약 데이터 쿼리 ### 6가지 유형의 인터페이스와 Java 메소드 모든 요청은 공통 접두사 `/v1/agent/perpetual`를 사용하여 POST로 서명됩니다. | 경로 접미사 | Java 메서드/요청 유형 | 플레이어 범위 | | -------------------- | ----------------------------------------------------------------- | -------------------------------------------------- | | `/orders/current` | `listCurrentPerpetualOrders(CurrentPerpetualOrdersRequest)` | NORMAL 플레이어는 생략 가능합니다. CONDITIONAL 플레이어를 지정해야 합니다. | | `/orders/history` | `listPerpetualOrderHistory(PerpetualOrderHistoryRequest)` | 위와 동일 | | `/trades` | `listPerpetualTrades(PerpetualTradesRequest)` | 플레이어를 지정해야 합니다. | | `/positions/current` | `listCurrentPerpetualPositions(CurrentPerpetualPositionsRequest)` | 선수 생략 가능 | | `/positions/history` | `listPerpetualPositionHistory(PerpetualPositionHistoryRequest)` | 선수 생략 가능 | | `/account/ledger` | `listPerpetualLedger(PerpetualLedgerRequest)` | 선수 생략 가능 | `platformUserIds`는 공개 플랫폼 ID의 문자열 배열입니다. 지정된 경우 액세스 권한이 있는 고유 플레이어는 1\~100명이 필요합니다. 생략을 허용하는 엔드포인트에서는 현재 판매자가 액세스할 수 있는 직접 플레이어의 범위만 쿼리됩니다. 교환 채우기 쿼리에는 항상 이 배열이 필요합니다. 조건부 순서 쿼리에는 명시적인 사용자 ID도 필요합니다. 생략은 `[]`와 동일하지 않으며 빈 배열은 불법입니다. 범위는 서명한 판매자에 의해 결정되며, 범위 확장을 위해 다른 판매자 ID를 전달할 수 없습니다. 배열 값은 서명 페이로드에 합류하기 전에 압축된 JSON로 직렬화됩니다. 예를 들어, `platformUserIds`는 `["1188041528"]`로 서명되어 `k=v` 페이로드에 `platformUserIds=["1188041528"]`를 제공합니다. 배열 요소 순서, 큰따옴표 및 문자열 ID를 유지합니다. 서식 지정 공백을 삽입하거나 Java `List.toString()`(예: `[1188041528]`)를 사용하지 마세요. SDK는 이 직렬화를 자동으로 처리합니다. 주문 쿼리는 `orderCategory=NORMAL` 또는 `CONDITIONAL`를 전달해야 합니다. 일반 주문에는 `orderId`를 사용하고 조건부 주문에는 `conditionId`를 사용합니다. 카테고리 간에 혼합될 수 없습니다. 조건부 주문과 이를 실행하여 생성된 일반 주문은 별도로 개체로 처리됩니다. ### 필터 조건 | 질문 | 사용 가능한 비즈니스 필터 | | ------ | -------------------------------------------------------------------------------------------------------------- | | 현재 주문 | `orderCategory`, `symbol` | | 역사적 질서 | `orderCategory`, `symbol`, `startTime`, `endTime`, `orderId`, `conditionId`, `clientOrderId`, `side`, `status` | | 거래를 하다 | `symbol`, `startTime`, `endTime`, `orderId` | | 현재 위치 | `symbol` | | 역사적 위치 | `symbol`, `startTime`, `endTime`, `positionSide` | | 계약 변경 | `startTime`, `endTime`, `assetType`, `changeType` | 기록 쿼리 시간은 Unix **밀리초**이고 간격은 `[startTime, endTime)`입니다. 서명을 요청하는 시간은 `timestamp`이며 Unix **초**입니다. UTC 기간을 수정하고 세그먼트 단위로 쿼리하는 것이 좋습니다. 일일 조정에는 UTC를 사용하세요. 상태 및 유형은 플랫폼 계약 열거를 사용하며 자체적으로 중국어 문자열로 변환되지 않습니다. `limit` 기본값은 500, 범위는 1\~1000입니다. 페이지 크기가 매번 동일한 숫자가 반환된다는 것을 보장하지는 않습니다. 6개의 인터페이스는 현재 초당 2회, 판매자당 버스트 4개의 쿼리 할당량을 공유하고 있으며 인스턴스 내 각 판매자의 최대 동시성 제한은 2입니다. 판매자 측은 통합 대기열을 사용하며 순차 페이징과 더 작은 기록 창으로 시작하는 것이 좋습니다. ### Java 쿼리 예시 플레이어의 현재 일반 주문을 쿼리합니다. ```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시간 동안의 계약 변경 사항을 쿼리하고 커서를 처리합니다. 다음 예에서는 자동으로 재시도하지 않습니다. 실제 애플리케이션에 현재 제한 사항이나 일시적인 오류가 발생하는 경우 링크된 관련 가이드에 따라 동일한 페이지를 복원하세요. ```java PerpetualLedgerRequest ledger = new PerpetualLedgerRequest(); ledger.platformUserIds = Collections.singletonList(platformUserId); ledger.endTime = System.currentTimeMillis(); ledger.startTime = ledger.endTime - 3_600_000L; ledger.limit = 100; Set 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. } ``` ### 반환 구조 및 저장 규칙 보다 [일반적인 응답 및 페이지 매김](#common-response-and-pagination) 공유 필드의 경우. 리소스 필드는 다음 문서에 설명되어 있습니다. [명령](/ko/sdk/agent-sdk/java/perpetual-orders), [거래 채우기](/ko/sdk/agent-sdk/java/perpetual-trades), [직위](/ko/sdk/agent-sdk/java/perpetual-positions) 그리고 [계약 원장](/ko/sdk/agent-sdk/java/perpetual-ledger). 6개의 인터페이스는 `PerpetualResponse`를 균일하게 반환합니다. ```json { "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`로 비즈니스 오류를 발생시킵니다. | 사업 코드 | 일반적인 의미 | 손질 | | -------- | ------------------------------------------------- | ----------------------------------------------------- | | `102001` | 필수 매개변수가 누락되었습니다. 예를 들어 조건부 주문 쿼리에 플레이어가 누락되었습니다. | 누락된 매개변수를 제공하세요. | | `102002` | 잘못된 매개변수, 빈 배열, 일치하지 않는 커서 또는 만료됨 | 매개변수를 수정하십시오. 만료된 커서를 지운 후 고정 창을 다시 확인하고 멱등적으로 저장합니다. | | `102003` | 잘못된 제한, 플레이어 수 또는 시간 범위 | 범위가 좁거나 정확함 | | `6001` | 서명 오류 | 키, 배열 직렬화 및 서명 필드 확인 | | `6009` | 판매자 액세스 방법 또는 액세스 범위가 허용되지 않습니다. | 판매자 권한 및 플레이어 소유권 확인 | | `6904` | 서비스를 일시적으로 사용할 수 없음, 동시성 또는 쿼리 리소스 보호 | 동시성을 줄이고 창을 축소합니다. 오류가 지속되면 지원팀에 문의하세요. | | `6905` | 6개 유형의 쿼리에 대한 공유 할당량이 소진되었습니다. | 뒤로 물러난 다음 원래 실패한 페이지를 다시 시도하세요. | `cursor` 및 원래 실패한 페이지의 모든 필터 조건은 전류 제한, 시간 초과 또는 임시 실패 후에도 유지됩니다. SDK가 호출될 때마다 새로운 `timestamp`, `nonce`, `sign`가 생성됩니다. 다음 페이지로 바로 이동할 수 없으며 실패를 빈 결과로 처리할 수도 없습니다. SDK는 자동으로 자금 거래를 재시도하는 것에 대해 책임을 지지 않습니다. ## 일반적인 응답 및 페이지 매김 | 필드 | JSON 유형 | 설명하다 | | ----------------- | ------- | -------------------------------------------------------------- | | `code` | integer | 비즈니스 코드, 0은 성공을 의미합니다. 0이 아니면 오류로 처리되며, 실패해도 빈 페이지로 처리되지 않습니다. | | `message` | string | 결과에 대한 설명은 비즈니스 판단의 유일한 근거가 아닙니다. | | `data` | object | 성공 시 페이지가 매겨진 결과 | | `data.items` | array | 이 페이지의 기록 합법적인 빈 페이지는 `[]`입니다. | | `data.nextCursor` | string | 다음 페이지 커서; 후속 페이지가 없는 경우 일반적으로 빈 문자열입니다. | | `data.hasMore` | boolean | 후속 페이지가 있는지 여부 true인 경우 nextCursor를 사용하여 동일한 쿼리를 계속합니다. | 각 `data.items[]`의 구조: | 필드 | JSON 유형 | 설명하다 | | ---------------- | ------- | ---------------------------------------------------- | | `platformUserId` | string | 문자열로 저장된 플랫폼 공개 사용자 ID. 내부 데이터베이스 사용자 ID가 아님 | | `entityType` | string | 레코드가 속한 엔터티 유형, 아래 표 참조 | | `entityId` | string | 현재 엔터티의 식별자는 플랫폼 사용자 및 엔터티 유형과 결합되어 로컬 멱등성 키를 구성합니다. | | `data` | object | 이 법인의 사업 분야 리소스 필드가 다르면 다릅니다. | | 리소스 쿼리 | `entityType` | `entityId` 대응 | | ----------- | ----------------- | ---------------------------------------- | | 일반 주문 | `ORDER` | `data.orderId` | | 조건부 주문 | `CONDITION_ORDER` | `data.conditionId` | | 거래 채우기 세부정보 | `TRADE_FILL` | `data.fillId`, tradeId 아님 | | 현재/과거 위치 | `POSITION` | `data.positionId` | | 계약 원장 기록 | `ACCOUNT_LEDGER` | 단일 계정 변경 내역 식별, **는 데이터가 아닙니다.ledgerId** | 동일한 `ledgerId`는 처리 수수료, 손익 등과 같은 여러 세부 사항을 분리할 수 있습니다. 중복 항목을 제거하기 위해 ledgerId를 누르면 데이터가 손실됩니다. 서로 다른 리소스의 ID를 혼합할 수 없습니다. 페이징 및 필드 저장 규칙은 액세스 가이드의 링크된 관련 가이드를 참조하세요. ## 유형, 단위 및 생략된 필드 * 금액, 가격, 수량, 엔터티 ID 사용 문자열입니다. 금액을 처리하려면 소수를 사용하고, 부동 소수점 숫자를 사용하거나 긴 ID를 JavaScript 숫자로 변환할 수 없습니다. 거래쌍/계약 사양에 따라 금액 통화 및 수량 단위를 설명합니다. * 업무 시간은 정수(int64)를 사용하며 둘 다 Unix 밀리초입니다. 인증 타임스탬프 및 항목 자격 증명 expireAt을 요청하면 초를 사용하므로 혼동될 수 없습니다. * 문자열 비즈니스 필드는 일반적으로 비어 있으면 출력되지 않으며, 숫자 필드가 0인 경우 일부가 생략됩니다. **누락된 필드가 비즈니스 값이 0이라는 의미는 아닙니다**. * 일반 기록 모델의 `reduceOnly`, `closeOnly`, `makerOnly`는 거짓을 생략하지 않으므로 이 세 가지 거짓이 거래나 포지션에도 나타날 수 있습니다. 이는 주문 리소스에서만 설명됩니다. 해당 거래/포지션이 해당 주문 규칙을 실행했다고 간주할 수 없습니다. * `closePosition`는 선택적 부울입니다. 조건부 순서로 제공되며 일반적으로 다른 리소스에서는 생략됩니다. 누락은 거짓과 다른 의미를 갖습니다. * "현재 제공되는" 아래 표는 읽기 논리에 필드 소스가 있음을 의미합니다. 선택적 필드는 값이 없기 때문에 생략될 수 있습니다. 모델에 존재하는 필드가 모든 인터페이스에 채워지는 것은 아닙니다. ## 상태 모드와 마진 모드의 차이점 | 의지 | 현재 반환 값 | | ------------------------- | ------------------------------------------------------------------------------------------------- | | 현재 일반주문상태 | NEW, PENDING, PARTIALLY_FILLED | | 과거 정상주문현황 | FILLED, CANCELED, REJECTED, PARTIAL_FILLED_CANCELED 또는 PARTIALLY_FILLED_CANCELED; 실제 소스 철자를 유지하세요 | | 현황 주문현황 / triggerStatus | PENDING_ACTIVATION, PENDING, TRIGGERING | | 과거조건 주문현황 / triggerStatus | TRIGGERED, CANCELLED, REJECTED, FIRED | | 현재 위치 상태 | 숫자 문자열 "1"이 위치에 있고 "3"이 청산 중입니다. | | 과거 위치현황 | 숫자 문자열 "2"는 포지션 청산, "4"는 강제 청산됨 | 일반 주문의 CANCELED 철자는 조건부 주문의 CANCELLED 철자와 다릅니다. 조건부 주문이 실행되었다고 해서 생성된 일반 주문이 체결되었다는 의미는 아닙니다. 모든 자원에 대해 동일한 상태 변환 테이블 세트를 재사용하지 마십시오. 조건부 순서 marginMode는 CROSS / ISOLATED를 반환합니다. 과거 일반 주문 및 포지션은 현재 각각 교차/격리 마진인 "1" / "2"를 반환합니다. marginMode은 현재 일반 주문에는 제공되지 않습니다. 판매자는 자체 디스플레이 레이어에서 리소스별로 정규화할 수 있으며 원래 값은 계속 저장해야 합니다. ## 모델에 선언되었지만 이 쿼리에는 제공되지 않은 필드 Generic RecordData / Java PerpetualData 모델은 다음 필드도 선언하지만 현재 6개 범주의 프로덕션 읽기 논리는 해당 필드를 채우지 않습니다. \*\*사용 가능한 비즈니스 데이터로 나열되어서는 안 되며, 실제 결과를 필드 기본값으로 대체해서도 안 됩니다. \*\* | 필드 | 모델 유형 | 현재 경계 | | ---------------- | ------- | --------------------------------------------------------- | | `closeReason` | string | 과거 포지션 마감 이유는 제공되지 않습니다. | | `walletDelta` | string | 계정 변경 인터페이스는 지갑 델타를 반환하지 않습니다. | | `frozenDelta` | string | 계정 변경 인터페이스는 동결된 델타를 반환하지 않습니다. | | `usedDelta` | string | 계정 변경 인터페이스는 사용된 마진 델타를 반환하지 않습니다. | | `feeDelta` | string | 계정 변경 인터페이스는 수수료 델타를 반환하지 않습니다. | | `pnlDelta` | string | 계정 변경 인터페이스는 손익 델타를 반환하지 않습니다. | | `accountVersion` | string | 계정 변경 인터페이스는 계정 버전을 반환하지 않으며 안정적인 증분 동기화에 사용할 수 없습니다. | | `occurredAt` | integer | 계정 변경 인터페이스는 createdAt을 사용하며 별도의 이벤트 발생 시간 세트를 제공하지 않습니다. | 실제 현장 적용 범위는 위의 리소스 테이블에 따릅니다. 플랫폼이 필드 또는 열거를 업데이트할 때 새로운 인터페이스 설명 및 SDK 버전에 따라 조정되어야 합니다. ## 소스 및 관련 가이드 * [공식 v0.3.0 소스](https://github.com/6mm-com/agent-java-sdk/tree/54aa3c1) * [펀딩 지갑](/ko/sdk/agent-sdk/java/funding-wallet) * [업그레이드 가이드](/ko/sdk/agent-sdk/java/upgrade)