Safeheron Skill

用自然语言指挥 AI 编写生产级 Safeheron 对接代码 —— 从零到上线完整指南。

1. 产品说明

1.1 什么是 Safeheron Skill

Safeheron Skill 是一个面向 Claude Code 和 Cursor IDE 的 AI Skill插件。安装后，开发者可以通过自然语言描述需求，让 AI 直接生成基于 Safeheron Java SDK 的生产级代码，无需逐页翻阅 API 文档。

它的核心能力包括：

• 代码生成 —— 描述您的业务场景，AI 自动生成符合 SDK 规范的 Java 代码，包含正确的 import、异常处理和安全校验。

• 全 API 覆盖 —— 涵盖钱包管理、转账交易、MPC 签名、Web3 签名、Webhook 回调、白名单、Gas Station、AML/KYT 合规检查、Co-Signer 审批等全部 API。

• 调试排错 —— 输入错误码或异常信息，AI 直接定位根因并给出修复方案。

• 安全合规内置 —— 生成的每一段代码都遵循 Safeheron 安全最佳实践，包括密钥管理、幂等性、AML 检查等。

1.2 适用人群

角色	使用场景
后端开发者	快速生成 SDK 集成代码，减少查阅文档时间
技术架构师	了解 Safeheron API 能力边界，设计系统架构方案
安全工程师	审查代码安全性，了解 MPC 自托管的安全要求
产品经理	快速了解 Safeheron 支持的业务场景和能力范围

1.3 核心概念速览

在进入实战之前，您需要了解几个关键概念：

MPC 自托管（MPC Self-Custody）：Safeheron 采用 3-of-3 MPC（安全多方计算）架构管理私钥。私钥永远不会以完整形式出现在任何单一设备上，三个分片分别由团队本地、Safeheron 云端持有，协同签名完成交易。

钱包账户（Wallet Account）：Safeheron 中的钱包账户是一个全链钱包——每个账户可以持有多条链的地址（如 ETH、BTC、USDT 等）。推荐的做法是一个终端用户绑定一个 Safeheron 钱包账户（1:1 关系）。

SDK 调用模式：Safeheron Java SDK 使用固定的三步模式：

SafeheronConfig → ServiceCreator.create() → ServiceExecutor.execute()

所有 API 调用必须通过 ServiceExecutor.execute() 包装，直接调用接口方法会失败。

交易生命周期：

SUBMITTED → WAIT_AUDIT → WAIT_SIGN → BROADCASTING → PENDING → SUCCESS
                ↓              ↓
            REJECTED       FAILED / CANCELLED

1.4 Safeheron Skill 内置知识库

Skill 内部包含 20 份专题参考文档，覆盖 Safeheron API 的方方面面：

分类	文档	说明
入门	GETTING_STARTED.md	从零到第一个 API 调用
SDK	SDK_SETUP.md	Maven/Gradle 配置、Spring Boot 集成
认证	AUTH.md	RSA+AES 加密签名流程
钱包	WALLET_API.md	钱包创建、查询、币种管理
交易	TRANSACTION_API.md	转账、查询、取消、加速
MPC 签名	MPC_SIGN_API.md	原始哈希签名
Web3	WEB3_API.md	EVM 链签名操作
Webhook	WEBHOOK.md	事件回调处理
白名单	WHITELIST_API.md	地址白名单管理
合规	COMPLIANCE_API.md	AML/KYT 报告
工具	TOOLS_API.md	AML 地址风控检查
Gas	GAS_API.md	Gas Station 状态查询
Co-Signer	COSIGNER.md	自动审批回调
安全	SECURITY_BEST_PRACTICES.md	安全编码规范
检查清单	SECURITY_CHECKLIST.md	上线前安全检查
策略	POLICY_STRATEGY.md	审批策略配置
业务模式	BUSINESS_PATTERNS.md	充值/提币/归集架构
错误码	ERROR_CODES.md	常见错误排查
FAQ	FAQ.md	真实场景 Q&A
币种	COIN_API.md	币种查询、地址校验

---

2. 环境准备与安装

2.1 前置条件

• Java 8+

• Maven 3.x 或 Gradle 7+

• OpenSSL（macOS/Linux 自带，Windows 可使用 Git Bash 或 WSL）

• Safeheron Web Console 账户（https://www.safeheron.com）

• Claude Code 或 Cursor IDE

2.2 安装 Skill

Claude Code 安装

方式一：插件安装（推荐）

claude plugin add safeheron/safeheron-skill

方式二：手动安装（项目级）

git clone https://github.com/absorprofess/safeheron-skill.git
mkdir -p .claude/skills
cp -r safeheron-skill/skills/safeheron .claude/skills/safeheron

方式三：手动安装（用户级，全局生效）

mkdir -p ~/.claude/skills
cp -r safeheron-skill/skills/safeheron ~/.claude/skills/safeheron

Cursor 安装

Cursor 原生支持 SKILL.md 格式，同时兼容 .claude/skills/ 路径，因此一次安装可同时支持 Claude Code 和 Cursor。

# 方式 A：共享安装（Claude Code + Cursor 通用）
mkdir -p .claude/skills
cp -r safeheron-skill/skills/safeheron .claude/skills/safeheron

# 方式 B：Cursor 原生路径（项目级）
mkdir -p .cursor/skills
cp -r safeheron-skill/skills/safeheron .cursor/skills/safeheron

# 方式 C：Cursor 原生路径（用户级）
mkdir -p ~/.cursor/skills
cp -r safeheron-skill/skills/safeheron ~/.cursor/skills/safeheron

⚠️ 注意：~/.cursor/skills-cursor/ 是 Cursor 内置的只读目录，不要安装到此路径。请使用 ~/.cursor/skills/。

2.3 验证安装

安装成功后，在 Claude Code 或 Cursor 中输入以下 prompt 测试：

Use Safeheron-api skill to set up my first API call

如果 AI 能够识别 Safeheron SKILL 并开始引导你完成配置，说明安装成功。

2.4 Safeheron 平台配置

在编写代码之前，需要先在 Safeheron Console 完成以下配置：

Step 1：生成 RSA 密钥对

Safeheron 使用 RSA-4096 进行请求签名和载荷加密。

# 1. 生成 RSA 4096-bit 私钥
openssl genpkey -out api_private.pem -algorithm RSA -pkeyopt rsa_keygen_bits:4096

# 2. 导出公钥（上传到 Safeheron Console）
openssl rsa -in api_private.pem -out api_public.pem -pubout

# 3. 转换私钥为 PKCS8 格式（Java SDK 要求）
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt \
    -in api_private.pem -out api_pkcs8.pem

生成的文件对应关系：

文件	用途	使用方
api_public.pem	公钥	上传到 Safeheron Console
api_pkcs8.pem	PKCS8 编码的私钥	SDK 配置中 **rsaPrivateKey** 字段

提取 Base64 值（去掉 PEM 头尾）：

# 提取公钥 base64
grep -v "BEGIN\|END" api_public.pem | tr -d '\n'

# 提取私钥 base64
grep -v "BEGIN\|END" api_pkcs8.pem | tr -d '\n'

🔒 安全提醒：私钥文件绝不能提交到版本控制。务必将 *.pem 加入 .gitignore。

Step 2：在 Console 配置 API

1. 登录 Safeheron Web Console → Settings → API

2. 复制 Safeheron Platform Public Key（这是 SDK 配置中的 safeheronRsaPublicKey）

3. 创建 API Key：

   • 粘贴你的 RSA 公钥（api_public.pem 的 base64 内容）

   • 选择所需权限

   • 添加服务器 IP 到白名单（必填！未注册的 IP 会被拒绝访问）

4. 保存生成的 API Key 字符串

Step 3：添加 SDK 依赖

Maven（pom.xml）：

<dependency>
    <groupId>com.safeheron</groupId>
    <artifactId>api-sdk-java</artifactId>
    <version>1.0.12</version>
</dependency>

Gradle（build.gradle）：

implementation 'com.safeheron:api-sdk-java:1.0.12'

Step 4：配置凭证注入

方式 A：环境变量

export SAFEHERON_API_KEY="your-api-key-here"
export SAFEHERON_RSA_PRIVATE_KEY="MIIJQgIBADANBgkqhkiG9w0BAQEFAASC..."
export SAFEHERON_PLATFORM_PUBLIC_KEY="MIICIjANBgkqhkiG9w0BAQEFAAOCAQ8A..."

方式 B：Spring Boot **application.yml**

safeheron:
  baseUrl: https://api.safeheron.vip
  apiKey: ${SAFEHERON_API_KEY}
  rsaPrivateKey: ${SAFEHERON_RSA_PRIVATE_KEY}
  safeheronRsaPublicKey: ${SAFEHERON_PLATFORM_PUBLIC_KEY}
  requestTimeout: 20000

⚠️ 注意 requestTimeout 是 Long 类型（毫秒），代码中使用 20000L 而不是 20000。

---

3. 接入实例

以下四个场景覆盖了最常见的业务需求：钱包创建、充值归集、提币转账、Webhook 回调。每个场景都包含 AI Prompt 示例 和 生成代码参考，展示 SKILL 的实际工作方式。

场景一：钱包创建与充值地址分配

业务需求：为每个终端用户创建独立的钱包账户，添加 ETH 和 USDT 币种，获取充值地址。

AI Prompt

在 Claude Code 或 Cursor 中输入：

使用 Safeheron skill，为一个新用户创建钱包账户，
添加 ETH 和 USDT(ERC20) 两个币种，并获取充值地址。
钱包标记为 DEPOSIT 类型，用于接收用户充值。

生成代码参考

import com.safeheron.client.api.AccountApiService;
import com.safeheron.client.config.SafeheronConfig;
import com.safeheron.client.request.CreateAccountRequest;
import com.safeheron.client.request.CreateAccountCoinV2Request;
import com.safeheron.client.response.CreateAccountResponse;
import com.safeheron.client.response.CreateAccountCoinV2Response;
import com.safeheron.client.utils.ServiceCreator;
import com.safeheron.client.utils.ServiceExecutor;

import java.util.Arrays;

public class CreateWalletExample {


    public static void main(String[ ] args) throws Exception {


        // ── Step 1: 构建配置 ──
        SafeheronConfig config = SafeheronConfig.builder()
                .baseUrl("https://api.safeheron.vip")
                .apiKey(System.getenv("SAFEHERON_API_KEY"))
                .rsaPrivateKey(System.getenv("SAFEHERON_RSA_PRIVATE_KEY"))
                .safeheronRsaPublicKey(System.getenv("SAFEHERON_PLATFORM_PUBLIC_KEY"))
                .requestTimeout(20000L)
                .build();

        // ── Step 2: 创建 API 服务实例 ──
        AccountApiService accountApi = ServiceCreator.create(
                AccountApiService.class, config);

        // ── Step 3: 创建钱包账户 ──
        CreateAccountRequest createReq = new CreateAccountRequest();
        createReq.setAccountName("user-deposit-001");
        createReq.setHiddenOnUI(true);         // 充值钱包隐藏，不在 Console 显示
        createReq.setAccountTag("DEPOSIT");    // 标记为充值钱包，支持 Auto-Sweep

        CreateAccountResponse createResp = ServiceExecutor.execute(
                accountApi.createAccount(createReq));
        String accountKey = createResp.getAccountKey();
        System.out.println("钱包已创建，accountKey: " + accountKey);
        // ⚠️ 请将 accountKey 与 userId 绑定，持久化到数据库

        // ── Step 4: 添加币种，获取充值地址 ──
        CreateAccountCoinV2Request coinReq = new CreateAccountCoinV2Request();
        coinReq.setAccountKey(accountKey);
        coinReq.setCoinKeyList(Arrays.asList(
                "ETHEREUM_ETH",
                "USDT(ERC20)_ETHEREUM_USDT"
        ));

        CreateAccountCoinV2Response coinResp = ServiceExecutor.execute(
                accountApi.createAccountCoinV2(coinReq));

        System.out.println("已添加币种:");
        for (CreateAccountCoinV2Response.CoinAddress coin : coinResp.getCoinAddressList()) {
            String address = coin.getAddressList().get(0).getAddress();
            System.out.println("  " + coin.getCoinKey() + " → " + address);
            // ⚠️ 将充值地址展示给用户
        }
    }
}

要点说明

• hiddenOnUI(true) —— 充值钱包不需要在 Console UI 中展示，避免界面混乱

• accountTag("DEPOSIT") —— 标记为充值钱包后，Auto-Sweep 归集引擎会自动处理该钱包

• 添加 ERC-20 Token（如 USDT）时，ETH 会被自动添加（因为需要 ETH 作为 Gas 费）

• accountKey 是钱包的永久唯一标识符，创建后务必保存到数据库

---

场景二：充值检测与资产归集

业务需求：检测用户的充值到账，确认后将资产从各个充值钱包归集到平台热钱包。

AI Prompt

使用 Safeheron skill，实现充值检测和资产归集：
1. 通过 Webhook 监听充值到账事件
2. 充值确认后，将 USDT 从充值钱包转到热钱包
3. 需要防粉尘攻击过滤，设置最小充值金额

生成代码参考

充值检测（Webhook Handler）

// 在 Webhook 处理器中监听充值事件
public void handleDepositEvent(JsonNode event) {
    String eventType = event.get("eventType").asText();
    if (!"TRANSACTION_STATUS_CHANGED".equals(eventType)) return;

    String txDirection = event.get("transactionDirection").asText();
    String status = event.get("transactionStatus").asText();

    // 只处理充值（INFLOW）且状态为 COMPLETED 的交易
    if (!"INFLOW".equals(txDirection)) return;
    if (!"COMPLETED".equals(status)) return;

    String txKey = event.get("txKey").asText();
    String coinKey = event.get("coinKey").asText();
    String txAmount = event.get("txAmount").asText();
    String destAccountKey = event.get("destinationAccountKey").asText();

    // ── 防粉尘攻击：过滤小额充值 ──
    BigDecimal amount = new BigDecimal(txAmount);
    BigDecimal minDeposit = getMinimumDeposit(coinKey); // 自定义最小充值额
    if (amount.compareTo(minDeposit) < 0) {
        log.info("过滤粉尘充值: {} {} (低于最小额 {})", txAmount, coinKey, minDeposit);
        return;
    }

    // ── 幂等性检查：防止重复入账 ──
    if (depositService.isAlreadyProcessed(txKey)) {
        log.info("充值已处理，跳过: txKey={}", txKey);
        return;
    }

    // ── 入账：更新用户余额 ──
    String userId = walletService.getUserByAccountKey(destAccountKey);
    depositService.creditUser(userId, coinKey, amount, txKey);
    log.info("充值入账成功: userId={}, amount={} {}", userId, txAmount, coinKey);
}

资产归集（Internal Transfer）

// 将充值钱包的资产归集到热钱包
public void sweepToHotWallet(String depositAccountKey, String coinKey,
                              String amount, String hotWalletAccountKey) {

    // ⚠️ 先生成 customerRefId 并保存到数据库
    String customerRefId = UUID.randomUUID().toString();
    sweepOrderDao.save(new SweepOrder(customerRefId, depositAccountKey,
            hotWalletAccountKey, coinKey, amount, "PENDING"));

    CreateTransactionRequest req = new CreateTransactionRequest();
    req.setCustomerRefId(customerRefId);
    req.setCoinKey(coinKey);
    req.setTxAmount(amount);                           // String 类型
    req.setSourceAccountKey(depositAccountKey);         // 充值钱包
    req.setSourceAccountType("VAULT_ACCOUNT");
    req.setDestinationAccountType("VAULT_ACCOUNT");     // 内部转账
    req.setDestinationAccountKey(hotWalletAccountKey);  // 热钱包
    req.setTxFeeLevel("MIDDLE");

    TxKeyResult resp = ServiceExecutor.execute(
            transactionApi.createTransactions(req));
    sweepOrderDao.updateTxKey(customerRefId, resp.getTxKey(), "SUBMITTED");
}

要点说明

• 推荐使用 Auto-Sweep：如果已部署 API Co-Signer，建议在 Console 配置 Auto-Sweep 规则，可实现零代码自动归集

• Webhook + REST API 轮询：充值检测必须同时实现两种方式，Webhook 作为主路径，REST API 轮询作为兜底

• 状态不可回退：如果数据库中交易已经是 COMPLETED，收到迟到的 CONFIRMING 事件应丢弃

• 粉尘攻击防护：外部攻击者可能向你的充值地址发送极小金额，务必设置最小充值阈值过滤

---

场景三：提币转账

业务需求：处理用户提币请求，从热钱包转出资产到用户指定的外部地址，包含 AML 检查和地址验证。

AI Prompt

使用 Safeheron skill，实现用户提币功能：
1. 先验证目标地址格式
2. 执行 AML 风控检查
3. 从热钱包发起转账到外部地址
4. 需要支持超时重试的幂等性设计

生成代码参考

import com.safeheron.client.api.CoinApiService;
import com.safeheron.client.api.ToolsApiService;
import com.safeheron.client.api.TransactionApiService;
import com.safeheron.client.request.*;
import com.safeheron.client.response.*;
import com.safeheron.client.utils.ServiceCreator;
import com.safeheron.client.utils.ServiceExecutor;

import java.math.BigDecimal;
import java.util.UUID;

public class WithdrawalService {

    private final TransactionApiService transactionApi;
    private final CoinApiService coinApi;
    private final ToolsApiService toolsApi;

    public WithdrawalService(SafeheronConfig config) {
        this.transactionApi = ServiceCreator.create(TransactionApiService.class, config);
        this.coinApi = ServiceCreator.create(CoinApiService.class, config);
        this.toolsApi = ServiceCreator.create(ToolsApiService.class, config);
    }

    public String processWithdrawal(String userId, String coinKey,
                                     String amount, String toAddress,
                                     String hotWalletAccountKey) throws Exception {

        // ── Step 1: 验证目标地址格式 ──
        CheckCoinAddressRequest checkReq = new CheckCoinAddressRequest();
        checkReq.setCoinKey(coinKey);
        checkReq.setAddress(toAddress);
        CheckCoinAddressResponse checkResp = ServiceExecutor.execute(
                coinApi.checkCoinAddress(checkReq));

        if (!checkResp.getAddressValid()) {
            throw new IllegalArgumentException("无效的地址格式: " + toAddress);
        }

        // ── Step 2: AML 风控检查 ──
        AmlScreenRequest amlReq = new AmlScreenRequest();
        amlReq.setAddress(toAddress);
        amlReq.setCoin(coinKey.split("_")[0]); // 提取链标识
        AmlScreenResponse amlResp = ServiceExecutor.execute(
                toolsApi.amlScreen(amlReq));

        if (amlResp.isHighRisk()) {
            throw new SecurityException("AML 检查未通过，高风险地址: " + toAddress);
        }

        // ── Step 3: 生成 customerRefId 并持久化 ──
        // ⚠️ 必须在调用 API 之前保存，确保幂等性
        String customerRefId = UUID.randomUUID().toString();
        withdrawalOrderDao.save(new WithdrawalOrder(
                userId, coinKey, amount, toAddress, customerRefId, "PENDING"));

        // ── Step 4: 发起提币转账 ──
        CreateTransactionRequest req = new CreateTransactionRequest();
        req.setCustomerRefId(customerRefId);
        req.setCoinKey(coinKey);
        req.setTxAmount(amount);                          // ⚠️ String 类型，不要用 float
        req.setSourceAccountKey(hotWalletAccountKey);
        req.setSourceAccountType("VAULT_ACCOUNT");
        req.setDestinationAccountType("ONE_TIME_ADDRESS"); // 外部地址
        req.setDestinationAddress(toAddress);
        req.setTxFeeLevel("MIDDLE");
        req.setFailOnAml(true);                           // 开启 AML 拦截
        req.setFailOnContract(true);                      // 默认阻止合约地址

        try {
            TxKeyResult resp = ServiceExecutor.execute(
                    transactionApi.createTransactions(req));
            withdrawalOrderDao.updateTxKey(customerRefId, resp.getTxKey(), "SUBMITTED");
            return resp.getTxKey();
        } catch (Exception e) {
            if (isDuplicateRefIdError(e)) {
                // Error 9001: customerRefId 已存在，说明之前的请求已成功
                // 查询原始交易，获取 txKey
                OneTransactionsRequest query = new OneTransactionsRequest();
                query.setCustomerRefId(customerRefId);
                OneTransactionsResponse existing = ServiceExecutor.execute(
                        transactionApi.oneTransactions(query));
                withdrawalOrderDao.updateTxKey(customerRefId,
                        existing.getTxKey(), "SUBMITTED");
                return existing.getTxKey();
            }
            throw e; // 其他错误，上层处理
        }
    }

    private boolean isDuplicateRefIdError(Exception e) {
        return e.getMessage() != null && e.getMessage().contains("9001");
    }
}

要点说明

• DB-first 模式：先在数据库创建提币订单（包含 customerRefId），再调用 Safeheron API。这样即使网络超时，也能通过相同的 customerRefId 重试，Safeheron 会返回已有交易而非创建新交易

• AML 检查前置：在调用转账 API 前先通过 ToolsApiService 检查目标地址风险等级

• 金额使用 String：txAmount 必须是 String 类型（如 "0.01"），应用层使用 BigDecimal 计算

• **failOnAml: true**：即使前置做了 AML 检查，仍建议保持此选项开启，作为第二道防线

• 对于经常性转账目标（如交易所热钱包、合作方地址），应使用白名单地址（WHITELISTING_ACCOUNT），而非 ONE_TIME_ADDRESS

---

场景四：Webhook 回调处理

业务需求：实现完整的 Webhook 回调处理服务，支持签名验证、事件路由、幂等处理和安全事件告警。

AI Prompt

使用 Safeheron skill，生成 Spring Boot 的 Webhook 处理器：
1. 包含签名验证和 IP 白名单检查
2. 处理交易状态变更事件
3. 处理安全告警事件（非法 IP、策略未匹配等）
4. 实现幂等性和状态不可回退逻辑

生成代码参考

Webhook 配置类

@Configuration
public class SafeheronWebhookConfig {

    @Value("${safeheron.webhook.platform-public-key}")
    private String safeheronWebHookRsaPublicKey;

    @Value("${webhook.rsa-private-key}")
    private String webHookRsaPrivateKey;

    @Bean
    public WebhookConverter webhookConverter() {
        return new WebhookConverter(safeheronWebHookRsaPublicKey, webHookRsaPrivateKey);
    }
}

Webhook Controller

import com.safeheron.client.webhook.WebHook;
import com.safeheron.client.webhook.WebHookBizContent;
import com.safeheron.client.webhook.WebhookConverter;
import com.safeheron.client.webhook.TransactionParam;

@RestController
public class SafeheronWebhookController {

    // Safeheron 出口 IP 白名单
    private static final Set<String> SAFEHERON_IPS = Set.of(
            "18.162.105.64", "18.167.22.59", "18.167.21.182"
    );

    @Resource
    private ObjectMapper objectMapper;
    @Resource
    private WebhookConverter webhookConverter;
    @Resource
    private TransactionService transactionService;
    @Resource
    private AlertService alertService;

    @PostMapping("/safeheron/webhook")
    public WebHookResponse handleWebhook(@RequestBody String rawBody,
                                          HttpServletRequest httpReq) {
        WebHookResponse response = new WebHookResponse();
        response.setCode("200");
        response.setMessage("SUCCESS");

        try {
            // ── Step 1: IP 白名单检查 ──
            String clientIp = httpReq.getRemoteAddr();
            if (!SAFEHERON_IPS.contains(clientIp)) {
                log.warn("拒绝未知 IP 的 Webhook 请求: {}", clientIp);
                return response; // 仍返回 200，避免触发重试风暴
            }

            // ── Step 2: 签名验证 + 解密 ──
            WebHook param = objectMapper.readValue(rawBody, WebHook.class);
            WebHookBizContent content = webhookConverter.convert(param);
            // convert() 内部完成：RSA 签名验证 → AES 密钥解密 → 载荷解密

            // ── Step 3: 事件路由 ──
            String eventType = content.getEventType();
            switch (eventType) {
                // 交易事件
                case "TRANSACTION_STATUS_CHANGED":
                    handleTransactionEvent(content);
                    break;
                case "TRANSACTION_CREATED":
                    log.info("新交易创建: txKey={}", content.getTxKey());
                    break;

                // 安全告警事件
                case "ILLEGAL_IP_REQUEST":
                    alertService.sendAlert("非法 IP 访问 API", content);
                    break;
                case "NO_MATCHING_TRANSACTION_POLICY":
                    alertService.sendAlert("交易无匹配策略", content);
                    break;
                case "GAS_BALANCE_WARNING":
                    alertService.sendAlert("Gas 余额不足", content);
                    break;
                case "AML_KYT_ALERT":
                    alertService.sendAlert("AML/KYT 风险告警", content);
                    break;

                default:
                    log.info("未处理的事件类型: {}", eventType);
            }

        } catch (Exception e) {
            log.error("Webhook 处理异常", e);
        }

        // ⚠️ 始终返回 200，处理逻辑异步执行
        return response;
    }

    private void handleTransactionEvent(WebHookBizContent content) {
        TransactionParam tx = (TransactionParam) content.getEventDetail();
        String txKey = tx.getTxKey();
        String newStatus = tx.getTransactionStatus();

        // ── 幂等性检查 ──
        String currentStatus = transactionService.getStatusByTxKey(txKey);

        // ── 状态不可回退：终态优先 ──
        if (isTerminalStatus(currentStatus)) {
            log.info("交易已处于终态，忽略迟到事件: txKey={}, 当前={}, 收到={}",
                    txKey, currentStatus, newStatus);
            return;
        }

        // ── 更新状态 ──
        transactionService.updateStatus(txKey, newStatus);

        if ("COMPLETED".equals(newStatus) || "SUCCESS".equals(newStatus)) {
            transactionService.onTransactionCompleted(tx);
        } else if ("FAILED".equals(newStatus) || "REJECTED".equals(newStatus)) {
            transactionService.onTransactionFailed(tx);
        }
    }

    private boolean isTerminalStatus(String status) {
        return status != null && Set.of(
                "COMPLETED", "SUCCESS", "FAILED", "REJECTED", "CANCELLED"
        ).contains(status);
    }
}

要点说明

• 签名验证是强制要求：SDK 的 WebhookConverter.convert() 内部会自动完成 RSA 签名验证和 AES 解密，验证失败会抛出 SafeheronException

• IP 白名单：Safeheron 的 Webhook 出口 IP 固定为 18.162.105.64、18.167.22.59、18.167.21.182。建议在防火墙/安全组层面限制，而非仅在应用层

• 始终返回 HTTP 200：即使处理出错也应返回 200。非 200 响应会触发 Safeheron 的重试机制（共 7 次：30s → 1m → 5m → 1h → 12h → 24h）

• 状态不可回退：由于 Webhook 事件可能乱序到达，必须确保终态（COMPLETED/FAILED/REJECTED/CANCELLED）不会被中间状态覆盖

• 安全事件处理：务必订阅 ILLEGAL_IP_REQUEST、NO_MATCHING_TRANSACTION_POLICY、GAS_BALANCE_WARNING、AML_KYT_ALERT 等安全事件并对接告警系统

---

4. 最佳实践

4.1 安全规范（非谈判性要求）

以下安全要求是强制性的，所有 Safeheron 集成代码都必须遵守：

密钥管理

部署环境	密钥存储方案
AWS 云	AWS KMS / Secrets Manager
GCP 云	GCP KMS
自建机房	HashiCorp Vault
本地开发	环境变量或项目外的文件（绝不提交到 Git）

绝对禁止在代码中硬编码 API Key 和 RSA 私钥。

转账安全

1. **customerRefId** 先行：在调用任何 Safeheron 创建类 API 之前，先生成 UUID 并保存到数据库。网络超时时使用相同的 ID 重试

2. 地址验证：调用 CoinApiService.checkCoinAddress() 验证地址格式后再操作

3. AML 前置检查：每笔出金前通过 ToolsApiService 检查目标地址风险

4. 金额精度：API 中使用 String 类型（"0.01"），代码中使用 BigDecimal。绝不使用 float/double

5. **failOnAml: true**：默认开启，仅在明确的业务场景下关闭

6. 白名单优先：正式的、经常性的转账目标地址应加入白名单；ONE_TIME_ADDRESS 仅用于真正的一次性付款

Co-Signer 安全

• 禁止盲审批：每笔交易必须校验 customerRefId、金额、目标地址三要素

• Co-Signer 服务必须部署在隔离的私有网络中，禁止公网直接访问

• 生产环境的 Co-Signer API Key 必须配置 Callback URL

Webhook 安全

• 必须验证 RSA 签名后再处理任何事件

• 生产环境必须使用 HTTPS

• 实现幂等处理，防止重复入账/出金

• 在防火墙层面限制仅接受 Safeheron 出口 IP 的流量

• 始终实现 REST API 轮询作为 Webhook 的兜底方案

4.2 架构设计建议

审批策略分层

对于交易所级别的部署，推荐配置分层审批策略：

交易金额（24 小时累计）	审批方式
单笔 ≤ 10 万 USD	API Co-Signer 自动审批
单笔 > 10 万 USD	运维团队 2-of-3 审批
24H 累计 10-50 万 USD	运维团队 2-of-3 审批
24H 累计 50-200 万 USD	财务团队 2-of-2 审批
24H 累计 > 200 万 USD	高管 1-of-2 审批

务必在策略栈底部添加一条兜底阻断规则，拦截所有未匹配的交易。

充值-提币完整架构

用户充值:
  区块链 → Safeheron 检测 → Webhook 通知 → 入账服务（幂等）→ 用户余额 +
                                                                ↓
                                                        REST API 轮询（兜底）

资产归集:
  充值钱包 → [Gas 补充] → USDT 归集 → 热钱包
  (Auto-Sweep 自动执行，或 API 手动触发)

用户提币:
  前端 → [1. DB 创建订单, status=PENDING] → 返回"已受理"
            ↓
  后台Job → [2. 地址验证 + AML 检查]
          → [3. 调用 Safeheron API, 获取 txKey]
          → [4. 更新订单: txKey, status=SUBMITTED]
            ↓
  Webhook → [5. 接收 TRANSACTION_STATUS_CHANGED]
          → [6. 更新订单状态]
          → [7. 通知用户结果]

4.3 使用 SKILL 的高效 Prompt 技巧

以下是一些经过验证的高效 Prompt 示例：

需求	推荐 Prompt
快速入门	"Use Safeheron skill to set up my first API call"
创建钱包	"Generate Java code to create a wallet and add ETH and USDT"
发起转账	"Create a transaction to send 0.01 ETH from wallet abc to address 0x1234..."
Spring Boot 配置	"Generate Spring Boot configuration class for Safeheron SDK"
Webhook 处理	"Write a webhook handler that processes incoming transaction events"
Co-Signer 集成	"Help me set up the API Co-Signer approval callback service"
错误排查	"My API call returns error 1010 — what's wrong and how do I fix it?"
安全审查	"Review my Safeheron integration code for security issues"

Prompt 技巧：

1. 明确场景：告诉 AI 你的业务上下文（如"交易所充值场景"），AI 会自动加入安全检查和最佳实践

2. 指定框架：如果你使用 Spring Boot，在 prompt 中注明，AI 会生成对应的 Bean 配置和注入代码

3. 提出限制：说明你的安全要求（如"使用环境变量注入密钥"），AI 会遵循

4. 迭代优化：先生成基础代码，再让 AI "增加异常处理" 或 "添加 AML 检查"

4.4 测试网环境

Safeheron 支持以下测试网络，建议在正式接入前充分测试：

测试网	coinKey
Ethereum Sepolia	ETH_SEPOLIA
Bitcoin Testnet	BITCOIN_BTC_TESTNET
TRON Shasta	TRX_SHASTA

可以通过 Prompt 让 SKILL 生成测试网的代码：

使用 Safeheron skill，在 Ethereum Sepolia 测试网上创建一个测试钱包并发送 0.01 ETH

---

5. 常见问题与排错

5.1 API 错误码速查

错误码	含义	根因	解决方案
1010	参数解密失败	safeheronRsaPublicKey 配置错误	从 Console 重新复制 Safeheron 平台公钥
1012	签名验证失败	rsaPrivateKey 不是 PKCS8 格式，或与 Console 上传的公钥不匹配	重新执行 openssl pkcs8 转换
9001	customerRefId 已存在	重复提交	查询已有交易而非重新创建
9028	MPC Sign 策略未配置	首次使用 MPC Sign	联系 Safeheron Support 开通
Illegal IP	IP 不在白名单	服务器 IP 未注册	在 Console → API Keys → IP Whitelist 添加

5.2 SDK 常见编码错误

错误：直接调用接口方法

// ❌ 错误 — 不会执行
CreateAccountResponse resp = accountApi.createAccount(req);

// ✅ 正确 — 必须通过 ServiceExecutor
CreateAccountResponse resp = ServiceExecutor.execute(accountApi.createAccount(req));

错误：类型不匹配

// ❌ pageSize 和 pageNumber 是 Long 类型
req.setPageSize(10);     // 编译错误
req.setPageNumber(1);    // 编译错误

// ✅ 正确
req.setPageSize(10L);
req.setPageNumber(1L);

错误：金额使用数值类型

// ❌ 会导致精度丢失
req.setTxAmount(0.1);

// ✅ 正确 — 始终使用 String
req.setTxAmount("0.1");

错误：配置字段混淆

// ❌ 把自己的公钥当成了平台公钥
.safeheronRsaPublicKey(yourOwnPublicKey)

// ❌ 把平台公钥当成了自己的私钥
.rsaPrivateKey(safeheronPublicKey)

// ✅ 正确
.rsaPrivateKey(yourPKCS8PrivateKey)            // 你的 PKCS8 私钥
.safeheronRsaPublicKey(platformPublicKey)      // Safeheron 平台公钥

5.3 使用 SKILL 快速排错

当遇到错误时，可以直接将错误信息发给 AI：

My Safeheron API call returns error 1012 "Signature verification failed".
Here is my config code: [粘贴代码]
Help me fix it.

AI 会根据 SKILL 内置的 ERROR_CODES.md 知识，精准定位问题并给出修复步骤。

---

6. 附录

6.1 SDK API Service 速查表

API 领域	Service 类	说明
钱包账户	AccountApiService	创建/查询钱包、添加币种
币种管理	CoinApiService	查询币种信息、验证地址
交易	TransactionApiService	创建/查询/取消/加速交易
MPC 签名	MPCSignApiService	原始哈希签名
Web3	Web3ApiService	EVM 链签名操作
白名单	WhitelistApiService	地址白名单 CRUD
合规	ComplianceApiService	AML/KYT 报告查询
Gas Station	GasApiService	Gas 余额和补充记录
工具	ToolsApiService	AML 地址风控检查

6.2 交易状态流转

SUBMITTED           ← 已提交至 Safeheron
    ↓
WAIT_AUDIT          ← 等待审批
    ↓ (或 → REJECTED)
WAIT_SIGN           ← 等待 MPC 签名
    ↓ (或 → CANCELLED)
BROADCASTING        ← 已广播到链上
    ↓
PENDING             ← 等待链上确认
    ↓
SUCCESS             ← 交易成功 ✅
(或 FAILED)          ← 交易失败 ❌

6.3 相关资源

资源	链接
Safeheron SKILL GitHub	https://github.com/absorprofess/safeheron-skill
Safeheron API 文档	https://docs.safeheron.com/api/en.html
Java SDK GitHub	https://github.com/Safeheron/safeheron-api-sdk-java
Safeheron Web Console	https://www.safeheron.com

---