> 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.*;
```

## 지갑 문의 및 이체

### 세 개의 지갑을 구별하세요

| 지갑            | 잔액 소스                         | 사용                       |
| ------------- | ----------------------------- | ------------------------ |
| 가맹점 자체 사용자 지갑 | 가맹점 자체 회계 시스템                 | 사용자가 판매자 측에서 사용할 수 있는 잔액 |
| 플랫폼 펀딩        | `queryUserAssets` 중 `funding` | 초 트레이딩 자금 및 펀딩/계약 상호 이체  |
| 플랫폼 계약        | `queryUserAssets`의 계약 자산 필드   | 무기한 계약 증거금 및 양도 가능 잔액    |

`queryAccount` 판매자 사용자 지갑이 아닌 판매자 플랫폼 마진 계정을 쿼리합니다. 이 인터페이스에는 `environment` 매개변수가 없으며 시뮬레이션된 사용자 자산으로 쿼리할 수 없습니다.

시뮬레이션된 사용자의 두 플랫폼 지갑을 쿼리합니다.

```java
QueryUserAssetsResponse assets = client.queryUserAssets(
        QueryUserAssetsRequest.of(platformUserId)
                .withFunding()
                .withEnvironment(ExecutionEnvironment.SIMULATED));
```

인터페이스: `POST /v1/agent/query-user-assets`. `includeFunding=true`인 경우에만 자금이 요청됩니다. 기본적으로 원래 계약 자산 쿼리 의미 체계가 사용됩니다.

| 응답 필드                                                                               | 의미                                                           |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `walletBalance`, `availableBalance`, `frozenMargin`, `usedMargin`, `isolatedMargin` | 계약 지갑 관련 금액                                                  |
| `funding.assetCode`                                                                 | 현재 USDT                                                      |
| `funding.availableAmount`, `heldAmount`, `totalAmount`                              | 사용 가능한 자금, 점유 및 총 금액                                         |
| `funding.materialized`                                                              | 펀딩 계좌가 구현됐나요?                                                |
| `environment`                                                                       | 이 필드는 환경이 명시적으로 전달될 때 에코됩니다. 환경을 생략한 이전 요청은 이 필드를 반환하지 않습니다. |
| `isSimulatedUser`                                                                   | 계정 분류 거래 환경 선택을 대체할 수 없습니다.                                  |

금액은 `float`/`double`가 아닌 문자열 또는 `BigDecimal`로 처리됩니다.

### 자금 이체 방향

생성: `POST /v1/agent/wallet-transfer`, SDK `walletTransfer`.

| `direction`           | 자금 흐름              | `transferAll`           |
| --------------------- | ------------------ | ----------------------- |
| `PARTNER_TO_FUNDING`  | 가맹점 → 플랫폼 펀딩       | 고정금액만                   |
| `FUNDING_TO_PARTNER`  | 플랫폼 펀딩 → 가맹점       | 고정금액만                   |
| `FUNDING_TO_CONTRACT` | 동일환경 플랫폼 펀딩 → 계약   | 고정 금액 또는 모든 출금 가능 자금 지원 |
| `CONTRACT_TO_FUNDING` | 동일환경 플랫폼 계약 → 자금조달 | 고정 금액 또는 모든 출금 가능 자금 지원 |

현재 통화는 USDT만 지원합니다. 고정금액은 소수점 이하 8자리까지의 양수 문자열이어야 하며 과학적 표기법을 사용할 수 없습니다. `transferAll=true`인 경우 `amount`를 생략하고 최종 응답 `amount`로 기록합니다. "모두"에는 인출 가능한 자금만 포함됩니다.

예: 판매자는 10 USDT를 시뮬레이션 자금으로 이체합니다. 먼저 판매자 시스템에 비즈니스 주문 및 환경을 저장한 후 요청을 보냅니다.

```java
String fundingOrderNo = "SIM-FUNDING-20261010-000001";
WalletTransferResponse transfer = client.walletTransfer(
        WalletTransferRequest.of(fundingOrderNo, "merchant-user-001",
                "PARTNER_TO_FUNDING", "10.00000000", false)
                .withEnvironment(ExecutionEnvironment.SIMULATED));
```

자금 모의 계약으로 이체할 수 있는 모든 자금을 이체합니다.

```java
WalletTransferResponse move = client.walletTransfer(
        WalletTransferRequest.of("SIM-F2C-20261010-000001", "merchant-user-001",
                "FUNDING_TO_CONTRACT", null, true)
                .withEnvironment(ExecutionEnvironment.SIMULATED));
```

동일한 작업에서는 원본 `agentOrderNo`을 계속 사용해야 합니다. 다양한 작업과 환경에서는 서로 다른 주문 번호를 사용합니다. 동일한 주문번호로 금액, 사용자, 방향, 환경 변경은 거부됩니다. 펀딩/계약 이체는 동일한 환경 내에서만 가능하며, 모의자금을 실제자금으로 이체할 수 없습니다.

### 결과 확인 및 알 수 없는 결과 복구

자금 응답은 `status`, `SUCCESS`, `PROCESSING` 또는 `FAILED`로 표시되며 `orderNo`, `direction`, `currency`로 반환됩니다. `amount`, `resultCode` 등. `code=0`는 요청이 성공적으로 처리되었으며 `status`를 계속 판단해야 함을 의미할 뿐입니다.

| 결과                                      | 판매자 처리                                                                              |
| --------------------------------------- | ----------------------------------------------------------------------------------- |
| `SUCCESS`                               | 실제금액 기준으로 현지회계처리 완료                                                                 |
| `PROCESSING`                            | 확인을 위해 현지에 보관하고 원래 주문을 확인하세요.                                                       |
| HTTP 시간 초과, 네트워크 오류, 결과를 구문 분석할 수 없습니다. | 결과는 알 수 없는 것으로 간주되며 원래 순서가 쿼리됩니다. 직접적으로 실패로 판단할 수도 없고, 새로운 주문을 생성하여 다시 시도할 수도 없습니다. |
| 식별됨 `FAILED`                            | 명확한 실패 결과에 따라 로컬 예약을 해제합니다. 사업을 다시 시작해야 할 때 새로운 사업 주문을 생성합니다.                       |

자금 조회는 전용 인터페이스 `POST /v1/agent/wallet-transfer-status`를 사용합니다.

```java
WalletTransferResponse recovered = client.queryWalletTransfer(
        WalletTransferQueryRequest.of(fundingOrderNo)
                .withEnvironment(ExecutionEnvironment.SIMULATED));
```

이 전용 엔드포인트를 사용하여 원래 자금 조달 작업을 복구하세요. `queryOrder`은(는) 대체할 수 없습니다. 원래 환경을 저장하고 복구 중에 명시적으로 전달합니다. `wallet-transfer-status`에서 `environment`을 생략하면 서버는 시뮬레이션 주문을 포함하여 원래 주문에 저장된 환경을 사용합니다. 명시적으로 충돌하는 환경은 `102002` (`order environment mismatch`)를 반환합니다. 호출자가 환경을 생략하면 응답에서도 `environment`가 생략됩니다. 이는 원래 주문이 생산 주문이라는 의미는 아닙니다.

판매자의 현지 입출금은 멱등원입니다. 지속적인 주문과 잔액은 시작 전에 예약되며, 결과를 알 수 없는 경우 확인을 위해 예약됩니다. 자금 액세스는 전용 쿼리를 사용하여 최종 상태를 확인합니다. 이전 계약 양도Webhook 또는 취소 방법이 자금 조달에 자동으로 적용된다고 가정하지 마십시오.

### 기존 계약 이전 흐름

원본 `transfer`, `transferAllOut`, `reverse`, `queryOrder`, `listOrders`는 원본 계약 이전 프로세스를 계속 처리합니다. `queryOrder`는 자금 이체 주문을 쿼리하고 있으며, `listOrders`는 이체 조정 목록입니다. 대신에, [지속적인 쿼리](/ko/sdk/agent-sdk/java/perpetual-queries) 영구 거래 주문에 사용됩니다.

원래 자금 조달 응답은 `orderStatus`를 사용합니다. 자금 조달 응답은 `status`를 사용하므로 혼합하지 마십시오. 원본 전송 Webhook은 `X-Agent-Timestamp`, `X-Agent-Nonce`, `X-Agent-Signature`를 사용하여 확인되며 원본 서명 텍스트는 `timestamp + nonce + rawBody`입니다. 원래 요청 본문이 먼저 확인된 다음 역직렬화되고 멱등성이 있습니다. 명시적인 시뮬레이션 환경 알림에는 `environment=SIMULATED`이 포함되어 있으며 프로덕션 알림은 이전 필드와 계속 호환됩니다. 금액, 주문번호, 상태, 환경 등은 현지 거래 주문서로 확인이 필요합니다.

## 소스 및 관련 가이드

* [공식 v0.3.0 소스](https://github.com/6mm-com/agent-java-sdk/tree/54aa3c1)
* [쿼리 개요 및 페이지 매김](/ko/sdk/agent-sdk/java/perpetual-queries)
* [업그레이드 가이드](/ko/sdk/agent-sdk/java/upgrade)

## 자금 요청 필드

| 필드                             | 필수의      | 의미                                                    |
| ------------------------------ | -------- | ----------------------------------------------------- |
| `agentOrderNo`                 | 예        | 전 세계적으로 고유한 파트너 주문 번호 보내기 전에 지속하십시오.                  |
| `agentUserId / platformUserId` | 하나       | 바인딩된 사용자를 식별합니다. 둘 다 제공되면 일치해야 합니다.                   |
| `direction`                    | 예        | 위에 설명된 네 가지 방향 중 하나입니다.                               |
| `currency`                     | 기본값 USDT | USDT만 지원됩니다.                                          |
| `transferAll`                  | 기본값은 거짓  | 자금/계약 내부 이체만 true를 지원합니다.                             |
| `amount`                       | 가정 어구    | 고정 전송의 경우 양의 10진수 문자열입니다. transferAll=true인 경우 생략합니다. |
| `environment`                  | 선택 과목    | 신규양도시 생략시 제작 SIMULATED는 시뮬레이션 자금을 선택합니다.              |

## 자금 응답 필드

| 필드                             | 의미                                                        |
| ------------------------------ | --------------------------------------------------------- |
| `orderNo`                      | 반환된 작업 식별자입니다. 원래 파트너 주문 번호와 함께 보관하십시오.                   |
| `status`                       | SUCCESS / PROCESSING / FAILED; 사업완료를 결정합니다.               |
| `direction / currency`         | 이체 방향 및 자산을 확인했습니다.                                       |
| `amount`                       | 문자열로 표시된 실제 이체 금액입니다.                                     |
| `transferAll`                  | 이 작업에서 인출 가능한 모든 자금을 요청했는지 여부입니다.                         |
| `agentUserId / platformUserId` | 반환된 사용자 ID 저장된 순서와 비교해 보세요.                               |
| `resultCode`                   | 작업결과 세부정보 화해와 지원을 위해 유지합니다.                               |
| `environment`                  | 호출자가 명시적으로 제공한 경우 에코됩니다. 부재는 원래 주문 상태 쿼리에 대한 생산 증거가 아닙니다. |