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

# 升级至 v0.3.0

本文对应 **Agent Java SDK `v0.3.0`**、Java 8+ 与该标签的公开契约。示例在合作方后端运行；先按[快速开始](/zh-CN/sdk/agent-sdk/java/quick-start)初始化 `client`。

## 旧 SDK 升级

### 是否必须升级

| 商户现状                             | 升级判断                                         |
| -------------------------------- | -------------------------------------------- |
| 只沿用旧 SDK 原有实盘业务，不显式传 environment | 正式接口保留旧响应形状，可继续使用；不因本次查询上线被强制升级              |
| 秒合约已有通用内嵌认证                      | 复用认证和续签，调整产品页面；资金新增能力按下列要求升级                 |
| 要使用 Funding 余额/划转                | 使用包含 `withFunding`、`walletTransfer` 和专用查单的版本 |
| 要显式对接模拟资金环境                      | 使用包含 environment 请求及响应模型的版本                  |
| 要调用六类永续查询                        | 使用公开 Java SDK `v0.3.0`，包含六方法和数组签名            |

升级后客户端 `baseUrl`、`agentCode`、`apiSecret` 配置方式不变；已有订单和用户映射继续保留。

### 固定稳定源码标签安装

公开 Java SDK：[6mm-com/agent-java-sdk](https://github.com/6mm-com/agent-java-sdk)。本指南固定 [v0.3.0](https://github.com/6mm-com/agent-java-sdk/tree/54aa3c1)，使用 Java 8 字节码目标。安装时核对 `HEAD` 与该标签解析出的提交一致。

在新的 SDK 源码目录安装，避免覆盖已有商户改动：

```bash
git clone --branch v0.3.0 --single-branch https://github.com/6mm-com/agent-java-sdk.git agent-java-sdk-v0.3.0
cd agent-java-sdk-v0.3.0
git rev-parse HEAD
git rev-parse 'v0.3.0^{commit}'
mvn install
```

核对两条 `git rev-parse` 输出一致后，在商户项目声明：

```xml
<dependency>
    <groupId>com.sixmm.exchange.sdk</groupId>
    <artifactId>agent</artifactId>
    <version>0.3.0</version>
</dependency>
```

该坐标来自 [v0.3.0 POM](https://github.com/6mm-com/agent-java-sdk/blob/v0.3.0/pom.xml)。GitHub 标签发布不等于 Maven Central 发布：本地 `mvn install` 后本机可以解析；CI 和其他开发机需执行同样安装，或从商户自己的制品私服获取已核对的 JAR/POM。

使用 Maven 检查依赖树，确保只有预期版本：

```bash
mvn dependency:tree -Dincludes=com.sixmm.exchange.sdk:agent
```

若旧项目已有自建 `0.3.0` 制品，核对其是否来自公开 `v0.3.0` 标签，并确认包含六类查询方法及新的请求/响应模型。共享私服中的既有同坐标制品由商户按私服策略处理，不静默覆盖。

### 升级后适配点

1. 请求/响应支持 `environment`。旧请求省略环境保持实盘兼容；显式传环境会回显环境，旧严格 JSON 模型可能不能解析，需升级模型。
2. 资产查询新增可选 Funding：使用 `withFunding()` 后读取 `funding`，避免拿 Contract 余额显示秒合约余额。
3. Funding 使用新 `/wallet-transfer`、`/wallet-transfer-status` 路径；不要调用旧拼写或原合约查单接口。
4. 六查询使用 `platformUserIds` 字符串数组和游标，签名器必须支持紧凑 JSON 数组。旧 Java `List.toString()` 格式不符合新接口签名。
5. 划转订单、永续交易委托、条件单及成交分别保存，响应状态字段按各接口契约解析。
6. 模拟环境回调增加 environment；原始请求体验签方式不变，幂等时同时校验原单环境。
7. 后端 Java SDK 与浏览器 Widget SDK 分别管理版本。后端升级不自动改变页面或前端交易模式；已有通用内嵌认证无需增加预测专用鉴权。

### 自研 HTTP 客户端

不使用 Java SDK 的商户可按 Agent HTTP 契约自行接入。新增能力需要同步适配请求字段、响应模型、环境选择、数组签名和分页逻辑；签名规则见[密钥与 HMAC 签名](/zh-CN/sdk/security/secrets-signing#signing-rule)。

## 来源与相关指南

* [官方 v0.3.0 源码](https://github.com/6mm-com/agent-java-sdk/tree/54aa3c1)
* [合约查询与分页](/zh-CN/sdk/agent-sdk/java/perpetual-queries)
* [Funding 钱包](/zh-CN/sdk/agent-sdk/java/funding-wallet)