DeBox DApp 去中心化应用

面向开发者的 DApp 接入指南（当前版本）。

1. DApp 是什么

DeBox DApp 是运行在 DeBox 内置浏览器中的 H5 应用（HTML/CSS/JS）。

你可以：

• 复用现有 H5 页面快速接入
• 调用注入的钱包对象进行链上交互
• 通过服务端调用 DeBox OpenAPI 完成消息、用户、群组等能力接入

2. 快速开始

1. 先确认 DApp 是否需要调用 DeBox OpenAPI。只使用注入钱包能力时，不需要 OpenAPI 凭证。
2. 需要调用 OpenAPI 时，先通过 BotMother 创建 Bot，并获取该 Bot 的 App Key（API Key）。
3. 准备一个可公网访问的 HTTPS 页面。DeBox 内置浏览器只支持 https://，http:// 链接会被拦截。
4. 按本文完成 DeBox 环境检测与钱包能力接入。
5. 将 Bot 的 App Key 和 App Secret 保存在后端。H5 前端只调用自己的后端，不携带这些凭证。

3. 运行环境检测

const isDeBoxUA = !!window?.navigator?.userAgent?.includes("DeBox")
const hasDeBoxWallet = typeof window?.deboxWallet !== "undefined"
const hasEthereum = typeof window?.ethereum !== "undefined"
const hasSolana = typeof window?.solana !== "undefined"

建议：

• 以 hasDeBoxWallet || hasEthereum 作为 EVM 主判断。
• 非 DeBox 环境给出降级提示，不直接报错。

4. 钱包与用户信息能力

window.deboxWallet 是主要入口（与 window.ethereum 兼容）。

4.1 请求权限

await window.deboxWallet.request({
  method: "wallet_requestPermissions",
  params: [{ eth_accounts: { debox_getUserInfo: {} } }],
})

4.2 获取用户公开信息

const userInfo = await window.deboxWallet.request({
  method: "debox_getUserInfo",
  params: [],
})

返回示例（字段因客户端版本可能有差异）：

{
  "uid": "jkdi123",
  "address": "0xa56b4f0c7622bd076c2ba48b17d1e8d3fbf5303e",
  "name": "张三",
  "avatar": "https://...png"
}

uid、OpenAPI 中的 user_id 以及该用户的 invite_code 使用相同的用户标识值，但不同接口仍保留各自的字段名。调用 OpenAPI 时将该值填入 user_id；接口要求使用目标用户 user_id 作为私聊 chat_id 时，也将该值填入 chat_id。完整字段对照请查看 DeBox App 深链接。

4.3 使用标准 Web3.js 发起签名和交易

H5/DApp 可以通过注入的钱包 Provider 使用标准 Web3.js。优先使用 window.deboxWallet， 需要时回退到 window.ethereum：

npm install web3

import { Web3 } from "web3"

const provider = window.deboxWallet ?? window.ethereum

if (!provider) {
  throw new Error("当前环境没有可用的 DeBox 钱包 Provider")
}

const web3 = new Web3(provider)
const [account] = await web3.eth.requestAccounts()

使用同一个 Provider 发起标准 personal_sign 请求：

const message = web3.utils.utf8ToHex("Confirm this action")

const signature = await provider.request({
  method: "personal_sign",
  params: [message, account],
})

通过 Web3.js 发起交易：

const receipt = await web3.eth.sendTransaction({
  from: account,
  to: "0xTARGET_ADDRESS",
  value: web3.utils.toWei("0.01", "ether"),
  data: "0x",
})

console.log(receipt.transactionHash)

签名和交易调用会拉起 DeBox 钱包确认页。只有用户确认并且调用成功返回后，操作才算完成； H5 页面需要处理用户拒绝和调用失败的状态。拉起钱包前，应校验当前链、目标地址、金额和编码后的 合约调用数据。代币转账和合约调用应使用 ABI 编码后的 data（或 Web3.js 合约方法），不能把 代币金额当作原生币 value。

需要自定义表单、报价、风险提示、交易计算或多步骤业务逻辑时，应使用 H5/DApp。如果只需要在 聊天中完成一次受支持的钱包操作，请查看 DeBox 机器人区块链按钮。

5. 后端调用 OpenAPI（推荐架构）

安全原则：

• DApp 需要调用 OpenAPI 时，必须先通过 BotMother 创建 Bot。
• Bot 的 App Key 就是后端通过 X-API-KEY 携带的 API Key。
• 前端只负责采集输入和调用你自己的后端 API。
• App Key、App Secret 和签名参数全部保留在后端。

主文档入口：

• DeBox 开发者 OpenAPI

6. 消息发送（新版接口示例）

以下示例要求已经通过 BotMother 创建 Bot。请求由后端发出，并在 X-API-KEY 中携带 Bot 的 App Key。

以下示例基于当前公开接口：POST /openapi/bot/sendMessage

curl -X POST "https://open.debox.pro/openapi/bot/sendMessage" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_APP_KEY" \
  -d '{
    "chat_id": "cc0onr82",
    "chat_type": "group",
    "content": "Hello from DApp",
    "parse_mode": "richtext"
  }'

参数要点：

• chat_type：group 或 private
• chat_id：
  • group 时填群 gid
  • private 时填用户 user_id
• content：消息主体
• parse_mode 默认 richtext

7. 上线检查清单

1. 页面及所有跳转地址均使用 HTTPS，且移动端适配完成。DeBox 内置浏览器会拦截 HTTP 链接。
2. DeBox 环境检测与非 DeBox 降级逻辑可用。
3. 钱包授权流程可追踪（拒绝/取消/成功）。
4. OpenAPI 调用全部走后端，密钥不下发前端。
5. 错误日志有 request-id、用户标识、接口名。

第三方链接提示

HTTPS 是页面能够打开的基本条件，但不会消除“第三方网站”安全提示。从 DeBox 聊天中的第三方链接打开 DApp/H5 时，默认仍会显示该提示。申请直接打开评估的方法请查看 第三方链接与 HTTPS。

8. 常见问题

1. 前端直接调 OpenAPI 报鉴权或 CORS：

• 属于预期，改为后端代调。

2. 发送消息失败：

• 检查 chat_type/chat_id 是否匹配。
• 检查 content 非空、parse_mode 合法。

3. 钱包对象不存在：

• 当前不在 DeBox 容器或客户端版本不满足。

9. 相关文档

• DeBox 开发者 OpenAPI
• DeBox Bot 聊天机器人
• DeBox 机器人 Go SDK
• DeBox 机器人 Go SDK Webhook