跳到导航
Agent Java SDK

Java 快速开始

Java 快速开始: Agent Java SDK v0.3.0 接入、示例、参数及响应说明。

以 Markdown 格式查看

本文对应 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.*;

依赖引入

Maven 坐标

当前源码中的 Maven 坐标如下：

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

未发布到 Maven 仓库时如何使用

当前 GitHub 仓库只提供源码托管。接入方可以先通过 tag 安装到自己的本地 Maven 仓库：

git clone https://github.com/6mm-com/agent-java-sdk.git
cd agent-java-sdk
git checkout v0.3.0
mvn install

说明：GitHub 仓库只提供源码托管。仓库公开后，接入方可以 clone 源码并执行 git checkout v0.3.0 && mvn install 安装到自己的本地 Maven 仓库，但不能仅凭 GitHub 仓库地址在 pom.xml 中直接引用上面的依赖坐标。要让外部项目直接通过 Maven 引入，需要 额外发布到 Maven 仓库，例如公司私服、Maven Central、GitHub Packages，或接入 JitPack 这类基于 GitHub 构建的服务。

已有项目参见 旧 SDK 升级指南。安装与查阅接入说明均可使用稳定源码标签 v0.3.0。

初始化客户端

普通 Java 项目

import com.sixmm.agent.AgentClient;
import com.sixmm.agent.AgentClientConfig;
AgentClient client = new AgentClient(AgentClientConfig.builder()
        .baseUrl("https://agent-api.6mm.com")
        .agentCode("AGENT001")
        .apiSecret("your-api-secret")
        .defaultCurrency("USDT")
        .build());

Spring Boot 示例

import com.sixmm.agent.AgentClient;
import com.sixmm.agent.AgentClientConfig;
import java.time.Duration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class AgentSdkConfig {
    @Bean
    public AgentClient agentClient(AgentSdkProperties props) {
        return new AgentClient(AgentClientConfig.builder()
                .baseUrl(props.getBaseUrl())
                .agentCode(props.getAgentCode())
                .apiSecret(props.getApiSecret())
                .defaultCurrency("USDT")
                .timeout(Duration.ofSeconds(10))
                .build());
    }
}

建议业务项目通过环境变量或配置中心注入：

agent.sdk.base-url=https://agent-api.6mm.com
agent.sdk.agent-code=AGENT001
agent.sdk.api-secret=${AGENT_API_SECRET}

绑定用户

绑定用于建立代理商用户和 6MM 平台用户之间的关系。推荐在用户第一次进入交易场景或第一次充值到 6MM 前调用。

import com.sixmm.agent.model.BindRequest;
import com.sixmm.agent.model.BindResponse;
BindResponse resp = client.bind(
        BindRequest.of("agent-user-001")
                .withUsername("alice")
                .withExt("{\"source\":\"web\"}"));
System.out.println(resp.platformUserId);
System.out.println(resp.bindStatus);
System.out.println(resp.isSimulatedUser);

请求字段

字段类型必填说明
agentUserIdstring是代理商侧用户唯一标识
usernamestring否代理商侧用户展示名称，用作平台用户昵称
extstring否扩展信息，建议传 JSON 字符串

响应字段

字段类型说明
platformUserIdstring6MM 对外用户 ID
bindStatusstring绑定状态，通常为 BOUND
isSimulatedUserboolean是否模拟用户

推荐业务流程

用户首次进入交易

1. 用户登录代理商站点
2. 代理商后端用 agentUserId 调 bind
3. 保存 agentUserId 与 platformUserId 绑定关系
4. 用户点击进入交易
5. 直接跳转：调用 createEntryUrl，浏览器打开 webUrl
6. 内嵌交易：前端 Trading Widget 触发 tokenProvider，后端调用 createEmbedToken

用户充值到 6MM

1. 代理商生成唯一 agentOrderNo
2. 调 transfer(Direction.IN)
3. 如果返回 SUCCESS，更新订单成功
4. 如果返回 PROCESSING，等待 Webhook 或轮询 queryOrder
5. 如果返回 FAILED 或抛 AgentApiException，按失败处理

用户从 6MM 提回代理商

1. 代理商生成唯一 agentOrderNo
2. 固定金额提回：transfer(Direction.OUT)
3. 全部提回：transferAllOut
4. 按 orderStatus、Webhook、queryOrder 确认最终状态

来源与相关指南

21. 异常处理

SDK 异常分为两类：

异常场景处理建议
AgentApiExceptionHTTP 非 2xx，或 agent 响应 code != 0读取 getHttpStatus()、getCode()、getResponseBody()，按业务失败处理
AgentSdkException网络、序列化、配置、签名计算异常记录日志并按系统异常处理

示例：

import com.sixmm.agent.AgentApiException;
import com.sixmm.agent.AgentSdkException;
try {
    TransferResponse resp = client.transfer(TransferRequest.fixed(
            "AGT-ORDER-1001", "agent-user-001", Direction.IN, "USDT", "10.00"));
    // 根据 resp.orderStatus 更新本地订单
} catch (AgentApiException e) {
    // 业务失败或 HTTP 错误
    log.warn("6mm agent api rejected request, httpStatus={}, code={}, body={}",
            e.getHttpStatus(), e.getCode(), e.getResponseBody());
} catch (AgentSdkException e) {
    // SDK 本地错误或网络错误
    log.error("6mm agent sdk request failed", e);
}

接收 Webhook

四类事件共用商户配置的回调地址，按正文 event 分流。先用收到的原始字节验签，再校验时间窗口、商户和环境。业务与成功去重记录提交完成，或通知已可靠保存到持久任务后，再返回 HTTP 2xx。

事件与强平预警 · 验签、响应与重试