# DeBox 开发者文档
> DeBox 开发者文档：机器人 OpenAPI、Go / Node.js / Python SDK、开放能力与常见问题。
本文件遵循 llmstxt.org 标准，包含 DeBox 开发者文档的全部正文（Markdown 格式），适合一次性喂给大模型做全量索引或离线参考。只需按章节定位页面时，用更省 token 的索引 https://docs.debox.pro/llms.txt。
## DeBox 使用指南
## DeBox 能为我做什么？
**DeBox 是一站式 Web3 社区管理工具，旨在建立一个可信的数据生态。使用 Web3 钱包登录，可以私聊、小群聊天、Club 聊天、DAO/NFT 聊天（持仓聊天），并发布动态、查看所有人的动态、查看关注人的链上动态。**
:::tip 开始体验
- **官网**
- **Web App**
- **新手社区**
:::
:::info 技术支持
- 欢迎加入DeBox技术讨论群：点击加入
- 问题反馈:【我的】- 右上角【设置】-【问题反馈】提交
:::
## DeBox 官方发行了哪些 NFT?
### DeBox Guardians Penguin(DGP)
> 昵称: 企鹅
> 企鹅是 OG ，在社区中具有重要的治理权限和影响力。
### DeBox Guardians Eagle(DGE)
> 昵称：小鹰
> 小鹰是执法者 ，进行监督和管理社区，确保社区成员遵守规则和准则。
### DeBox Guardians Rabbit(DGR)
> 昵称：小兔
> 小兔是建设者，推动社区发展，通常是开发人员。
### DeBox Guardians Cobra(DGC)
> 昵称：小蛇
> 小蛇是基金会，推动社区的发展和治理，为用户提供更加优质的 Web3 社交体验。
### DeBox Guardians Shark(DGS)
> 昵称：鲨鱼
> 鲨鱼是开拓者，他们勇敢而强大。他们探索着DeBox的边界，并增强了整个DeBox生态系统的稳健性。
## 如何登录 DeBox?
DeBox 有两种钱包登录形式，使用本地钱包登录【推荐】或者连接钱包 App 登录；
### 没有钱包直接创建
App 左上角【Account】-【添加】-【创建钱包】- 设置密码 - 成功创建后 - 备份个人助记词。需要说明的是 DeBox 服务器不会保存个人的私钥。请您务必备份助记词，妥善保管助记词以及私钥，以确保资产安全。
### 已经有钱包去导入
App 左上角【添加钱包】-【导入钱包】- 复制私钥或者助记词 - 设置密码 -【导入】
### 如果不想导入私钥
左上角【添加钱包】- 选择 WalletConnect 或者 TokenPocket - 跳转授权确认，授权过程需要网络服务支持，若无法成功授权并跳转，请检查个人网络或者使用本地钱包登录。
## 如何将自己的 NFT 设置为头像？
### 如何将自己的 NFT 设置为头像？
【个人主页】-【编辑】- 头像 - 选择拥有的 NFT -【保存】。
### 如何将域名设置为昵称？
【个人主页】-【编辑】- 点击【DID】- 选择 DID -【保存】。
## 我如何私信我的好友？
### 我如何私信我的好友？
点一下【对方头像】- 关注按钮旁边的【聊天按钮】。如果无法聊天，表示对方并没有打开对您的私聊权限。另外，更改设置个人私信权限，【我的】-【设置】-【隐私】-【私信权限】。为了避免无效信息过多默认【只允许我关注的人私信我】，可以选择【任何人都可以私信我】或者【不允许任何人私信我】。
## 我如何创建一个群组？
小群是500人以内的多人群聊。您可以邀请多位好友进行小群聊天。在事件板块发现各类热门活动，并加入对应的聊天小群进行实时讨论。
### 如何创建？
底部【聊天】- 右上角的【+】-【创建小群】-【朋友】-【立即创建】。如果人数达到上限，请进入 Web App【社区】-【管理】- 升级成 Club 群聊 - 升级人数。
## 我怎么创建/加入俱乐部？
俱乐部 Club 是超过500人的群聊，Club 中有群主和管理员，有群工具。
### 创建 Club
前往 Web App - 顶部【社区】- 左下角【创建】-【创建 Club】- 选择一个 DeBox Guardians NFT 进行质押 - 设置对应的名称、图标和加入条件 - 创建（该过程需要一定 GAS 费）。
### 加入 Club
底部【社区】- 进入社区 - 选择 Club 加入。加入部分 Club 有一定门槛，由 Club 主设定，有些加入申请需要审核，有些要求您有资产，有些要求您进行付费。
## 持仓聊天指的是什么？
持仓聊天是需持有相应 Token/NFT 的用户才可加入的群组。
### 加入 DAO/NFT
底部【社区】- 选择 DAO/NFT 加入。
### 创建 DAO/NFT
底部【聊天】- 右上角的【+】- 选择【创建DAO】- 选择相应的 Token/NFT - 设置名称、头像进行创建。
## 有哪些好玩的群工具?
### 有哪些好玩的群工具?
进入群聊 - 底部【+】- 【红包】【投票】【抽奖】【Meetup】- 参与/发起；还可以在群组聊天中通过【红包】【投票】【抽奖】【Meetup】消息卡片参与，或者右侧浮窗参与。
## 在发现页有哪些内容可以看?
发现页可以发布动态、浏览动态、评论、以及关注其他用户。
### 看所有人动态
在【发现页】- 【探索】浏览所有人的动态， 平台根据您的喜好算法推荐优质的动态。
### 看关注人动态
切换【探索】到【正在关注】。可以浏览关注人的实时动态和链上动态，发现交易行为，了解交易策略、投资动向和参与的项目。
View More
---
## DeBox 开放能力
DeBox 面向外部开发者提供可落地的能力体系，可用于构建机器人、DApp 与生态协作产品。
## 能力地图
### 1. DeBox 去中心化小程序（DApp）
- 在 DeBox 内承载 Web 应用体验。
- 通过注入钱包对象（`window.deboxWallet`、`window.ethereum`、`window.solana`）完成 Web3 交互。
- 接入说明见：[DeBox DApp 去中心化小程序](/MiniApp)。
### 2. OpenClaw 安装 DeBox 插件
- 将 OpenClaw 工作流接入 DeBox Bot Channel。
- 适合已经使用 OpenClaw 做多渠道自动化的团队。
- 安装配置见：[OpenClaw 安装 DeBox 插件](/APIs/OpenClaw-Plugin-Install)。
### 3. DeBox Shares 无许可自动分佣协议
- 在业务支付链路中集成自动分佣能力。
- 支持链上支付的分佣拆分与结算模式。
- 接入文档见：[DeBox Shares 无许可的自动分佣协议](/Shares)。
### 4. DeBox Grant 扶持计划
- 项目完成 DeBox 能力接入后，可申请生态扶持。
- 计划说明与申请方式见：[DeBox Grant 扶持计划](/OpenPlatformGrant)。
## 推荐接入顺序
1. 明确产品形态：Bot、DApp，或两者结合。
2. 先完成机器人能力接入： [DeBox Bot 聊天机器人](/APIs/BotGuide)。
3. 按接口文档对接： [DeBox 开发者 OpenAPI](/ApiOnePage)。
4. Go 技术栈按接收模式二选一： [Go SDK（Long Polling）](/GO-SDK) 或 [Go SDK Webhook](/GO-SDK-Webhook)。
5. 核心能力稳定后，再扩展 Shares 与 Grant 生态合作。
## 技术支持
- 开发者平台：[developer.debox.pro](https://developer.debox.pro)
- 开发者排障文档：[开发者 FAQ / 排障](/APIQA)
---
## DeBox DApp 去中心化应用
面向开发者的 DApp 接入指南（当前版本）。
## 1. DApp 是什么
DeBox DApp 是运行在 DeBox 内置浏览器中的 H5 应用（HTML/CSS/JS）。
你可以：
- 复用现有 H5 页面快速接入
- 调用注入的钱包对象进行链上交互
- 通过服务端调用 DeBox OpenAPI 完成消息、用户、群组等能力接入
## 2. 快速开始
1. 在 [DeBox 开放平台](https://developer.debox.pro) 创建应用并获取 `API Key`。
2. 准备一个可公网访问的 HTTPS 页面。
3. 按本文完成 DeBox 环境检测与钱包能力接入。
4. 把 OpenAPI 调用放在后端服务，不在前端暴露密钥。
## 3. 运行环境检测
```js
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 请求权限
```js
await window.deboxWallet.request({
method: "wallet_requestPermissions",
params: [{ eth_accounts: { debox_getUserInfo: {} } }],
})
```
### 4.2 获取用户公开信息
```js
const userInfo = await window.deboxWallet.request({
method: "debox_getUserInfo",
params: [],
})
```
返回示例（字段因客户端版本可能有差异）：
```json
{
"uid": "jkdi123",
"address": "0xa56b4f0c7622bd076c2ba48b17d1e8d3fbf5303e",
"name": "张三",
"avatar": "https://...png"
}
```
## 5. 后端调用 OpenAPI（推荐架构）
安全原则：
- 前端只负责采集输入和调用你自己的后端 API。
- `X-API-KEY`、签名参数、App Secret 全部保留在后端。
主文档入口：
- [DeBox 开发者 OpenAPI](/ApiOnePage)
## 6. 消息发送（新版接口示例）
以下示例基于当前公开接口：`POST /openapi/bot/sendMessage`
```bash
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 可访问，移动端适配完成。
2. DeBox 环境检测与非 DeBox 降级逻辑可用。
3. 钱包授权流程可追踪（拒绝/取消/成功）。
4. OpenAPI 调用全部走后端，密钥不下发前端。
5. 错误日志有 request-id、用户标识、接口名。
## 8. 常见问题
1. 前端直接调 OpenAPI 报鉴权或 CORS：
- 属于预期，改为后端代调。
2. 发送消息失败：
- 检查 `chat_type/chat_id` 是否匹配。
- 检查 `content` 非空、`parse_mode` 合法。
3. 钱包对象不存在：
- 当前不在 DeBox 容器或客户端版本不满足。
## 9. 相关文档
- [DeBox 开发者 OpenAPI](/ApiOnePage)
- [DeBox Bot 聊天机器人](/APIs/BotGuide)
- [DeBox 机器人 Go SDK](/GO-SDK)
- [DeBox 机器人 Go SDK Webhook](/GO-SDK-Webhook)
---
## OpenClaw 安装 DeBox 插件
# 在 OpenClaw 安装 DeBox 插件
本教程用于指导 DeBox 用户在 OpenClaw 上安装并启用官方 DeBox 插件。
## 前置条件
- 你已安装 OpenClaw。
- 你已通过 **BotMother** 创建 DeBox Bot。
- `yourDeBoxBotToken` 即该 Bot 在 BotMother 中获取到的 **API Key**。
## 第一步：安装插件
```bash
openclaw plugins install @descartes_1/debox@latest
```
## 第二步：添加 DeBox Channel 并配置 Token
```bash
openclaw channels add --channel debox --token "yourDeBoxBotToken"
```
## 第三步：重启网关
```bash
openclaw gateway restart
```
## 验证是否安装成功
执行：
```bash
openclaw channels list
```
如果配置成功，输出中会看到 DeBox channel/account 已启用。
---
## DeBox Shares 无许可的自动分佣协议
## DeBox Shares 自动分佣协议，无需许可，配置后自动生效
:::tip Shares V2
🎉 DeBox Shares V2 协议已正式上线！
⚡ 若您先前已集成 Shares V1，无需修改代码即可自动升级至 V2，享受更高佣金、更强功能、更优体验！
🚀 立即接入 DeBox Shares 协议，开启全新收益模式！
:::
## DeBox Shares介绍
### 1、DeBox Shares是什么？
- DeBox Shares是基于DeBox产品独创的连接项目方与DeBox群组的底层分佣协议。
- 它基于DeBox的产品与社交关系来运营。
- 项目方接入无需许可，简单、快捷10分钟即可完成接入。
- 群组与邀请人可以获得项目方高达80%的即时返佣。基于DeBox Shares协议和DeBox群组功能，人人都可以开万物上链之后的去中心化交易所。
- DeBox Shares协议为无许可去中心化协议，DeBox平台无法也不会对任何接入DeBox Shares项目进行背书。
### 2、项目方开通DeBox Shares有什么好处？
- 通过DeBox Shares可以触达1000万真实用户与30万个私域群组，在任意群组里面推荐项目可以获得群主的认可与支持。
## Shares 支持哪些参与方式？
1. 支持链上 Token 支付：调用 DeBox-Shares 合约，略微调整 DAPP 的付款处合约代码即可；
2. 支持多种网络：目前已支持 ETH, Arbitrum, Base, BSC, OP, Polygon 网络资产（不断更新中）。
## 如何接入 Shares？
### 1. 支付接入 Shares
- DeBox Shares 协议是一个专为项目方设计的自动分佣工具，旨在简化交易分配流程。
- 开发者只需设置分配金额，无需处理复杂的分享者、邀请码等逻辑，DeBox Shares 协议即可自动完成每笔交易的收益分配。
- 接入过程包含两个主要步骤：连接钱包并获取授权、调用支付完成支付。支付完毕后可以查看支付详细信息。以下是详细步骤和使用方法：
#### 1.1 连接钱包并请求授权
- 通过`window.deboxWallet`调用区块链所有能力,包括用户信息获取，请参考Web3交互。
```jsx
await window.deboxWallet.request({
"method": "wallet_requestPermissions",
"params": [{
eth_accounts: {
"debox_getUserInfo": {}
}
}],
});
```
```jsx
await window.deboxWallet.request({
"method": "debox_getUserInfo",
"params": [],
});
```
### 2. 链上支付接入 Shares
链上 Shares 是一种实时的分佣方式。当用户使用 Token 进行支付时，部分支付金额会被自动捐赠给 DeBox Shares 协议进行分佣，完成收益分配。
开发者只需微调 Dapp 支付部分逻辑，即可快速实现高度定制化的链上支付分佣功能。
#### 2.1 链上支付分佣的调用过程
链上支付的分佣有两类：链上原生代币(ETH)支付分佣；ERC20代币支付分佣：
**2.1.1 链上原生代币(ETH)支付分佣**
链上原生代币(ETH)支付分佣分两步：计算分佣金额；调用合约的捐赠函数以触发分佣。
1. **计算分佣金额**
- Dapp 根据业务设计，计算通过 DeBox Shares 分配的分佣金额额。
2. **调用 `donationToShares`方法，同时传入分佣金额，触发后续分佣逻辑：**
```jsx
// ...
uint256 donatedAmountETH = amountAcquiredETH / 10; // 计算分佣金额
doxShares.donationToShares{ value: donatedAmountETH }(); // 触发后续分佣逻辑
// ...
```
3. **示例合约逻辑**
- Dapp 合约集成 Shares 协议示例：
```solidity
// SPDX-License-Identifier: Apache License 2.0
pragma solidity ^0.8.22;
import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import { IDeBoxShares } from "@debox/deboxdapp/interfaces/facets/IShares.sol";
import { SafeERC20 } from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
contract PlayGameWithShares {
IDeBoxShares public doxShares;
event GamePlayed(address player, IERC20 token, uint256 amount);
constructor(IDeBoxShares _doxShares) {
doxShares = _doxShares;
}
// Dapp中，集成了Shares协议的ETH支付函数
function playGameWithETH() external payable {
uint256 amount = msg.value;
uint256 donatedAmount = amount / 10;
if (donatedAmount > 0) {
doxShares.donationToShares{ value: donatedAmount }();
}
emit GamePlayed(msg.sender, IERC20(address(0)), amount);
}
}
```
**2.1.2 ERC20代币支付分佣**
ERC20代币支付分佣分两步：计算分佣金额并授权 DeBox Shares 合约；调用合约的捐赠函数以触发后续处理。
1. **计算分佣金额，将权限授予 DeBox-Shares 合约**
- 首先，Dapp将用户支付的代币转入Dapp合约，并根据业务设计，计算通过 DeBox Shares 分配的分佣金额。
- 然后，合约调用 `safeIncreaseAllowance` 方法，将分佣金额的使用权限授予 DeBox Shares 合约地址。
...
//将用户支付的代币转入 Dapp 合约
SafeERC20.safeTransferFrom(token, msg.sender, address(this), amount);
//计算通过 DeBox Shares 分配的分佣金额
uint256 donatedAmount = amountAcquired / 10;
//将分佣金额的使用权限授予 DeBox Shares 合约
SafeERC20.safeIncreaseAllowance(token, address(doxShares), donatedAmount);
...
// //触发分佣逻辑
doxShares.donationToShares(token, donatedAmount);
2. **示例合约逻辑**
- Dapp 合约集成 Shares 协议示例：
```solidity
// SPDX-License-Identifier: Apache License 2.0
pragma solidity ^0.8.22;
import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import { IDeBoxShares } from "@debox/deboxdapp/interfaces/facets/IShares.sol";
import { SafeERC20 } from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
contract PlayGameWithShares {
IDeBoxShares public doxShares;
event GamePlayed(address player, IERC20 token, uint256 amount);
constructor(IDeBoxShares _doxShares) {
doxShares = _doxShares;
}
// Dapp中的集成了Shares协议的ERC20代币支付函数
function playGame(IERC20 token, uint256 amount) external {
SafeERC20.safeTransferFrom(token, msg.sender, address(this), amount);
uint256 donatedAmount = amount / 10;
if (donatedAmount > 0) {
SafeERC20.safeIncreaseAllowance(token, address(doxShares), donatedAmount);
doxShares.donationToShares(address(token), donatedAmount);
}
emit GamePlayed(msg.sender, token, amount);
}
```
#### 2.2 Shares 合约接口：
- DeBox-shares 合约接口：
```solidity
// SPDX-License-Identifier: Apache License 2.0
pragma solidity ^0.8.22;
interface IDeBoxShares {
event DonationToShares(address indexed contributor, address indexed token, uint256 amount);
event SharesConfigSet(address vault, address weth);
/**
* @notice Donate tokens to the shares protocol.
* @dev The donated tokens will be transferred to the vault.
* before the donation, the caller must approve me to spend the token.
* @param token The token to donate. must be a valid ERC20 token.
* @param amount The amount of `token` to donate. must be greater than 0.
*/
function donationToShares(address token, uint256 amount) external;
/**
* @notice Donate Native coin (ETH) to the shares protocol.
*/
function donationToShares() external payable;
function getSharesConfig() external view returns (address vault, address weth);
}
```
#### 2.3 DeBox-Shares 合约部署地址：
| Network | Contract Address |
| --- | --- |
| Ethereum | 0x2e6168f9ca3fe204a2110c4613ce18985f3fbf39 |
| Arbitrum One | 0x509Ca4ff42cECAA1FF4988514211b26e72BDa840 |
| Base | 0x2f8Ae1cC4ab784f7b9E07A61F714ecDe18A4A6d2 |
| BSC | 0x32303FFcb9B6564C2b8a373433A043a7f17E4B37 |
| Optimism | 0x18574E5a838B3FE16948653873386DD114ba1D7C |
| Polygon | 0xb8Af0Fa3E38E8Cb95870091b0d4e32CA232b780D |
#### 2.4 简化的链上分佣接口
对于没有复杂业务逻辑的 Dapp，DeBox 提供了简化的链上分佣接口，支持链上原生代币支付和 ERC20 代币支付过程的分佣。
##### 支持方法：
1. **payAndShareWithETH**: 该方法用于 ETH 支付过程的分佣
- 合约方法：
```solidity
/**
* @notice 使用 ETH 支付并分佣，可指定收款地址和分佣金额。
* @param recipient 接收 ETH 支付的目标地址。
* @param shareAmount 在 ETH 支付总额中，用于 Shares 分佣的 ETH 量。
*/
function payAndShareWithETH(address payable recipient, uint256 shareAmount) external payable;
```
- 合约方法调用示例：
```solidity
contract Example {
function examplePayAndShare(address payable recipient) external payable {
// 假设支付 1 ETH，其中分佣 0.2 ETH
payAndShareWithETH{value: 1 ether}(recipient, 0.2 ether);
// 交易后，recipient 收到 0.8 ETH，0.2ETH 通过 Shares 协议完成分佣
}
}
```
- ABI 接口定义:
```json
[
{
"type": "function",
"name": "payAndShareWithETH",
"inputs": [
{
"name": "recipient",
"type": "address",
"internalType": "address payable"
},
{
"name": "shareAmount",
"type": "uint256",
"internalType": "uint256"
}
],
"outputs": [],
"stateMutability": "payable"
}
]
```
- ABI 调用示例（基于 ethers.js）
```JavaScript
const { ethers } = require("ethers");
// 假设合约地址和 ABI
const contractAddress = "SimplifiedSharesContractDeploymentAddress";
const abi = [
{
"type": "function",
"name": "payAndShareWithETH",
"inputs": [
{ "name": "recipient", "type": "address" },
{ "name": "shareAmount", "type": "uint256" }
],
"outputs": [],
"stateMutability": "payable"
}
];
// 设置 Provider 和 Signer
const provider = new ethers.providers.JsonRpcProvider("https://your-rpc-url");
const signer = provider.getSigner();
const contract = new ethers.Contract(contractAddress, abi, signer);
// 调用方法
async function callPayAndShare() {
const recipient = "0xRecipientAddress";
const shareAmount = ethers.utils.parseEther("0.2");
const totalAmount = ethers.utils.parseEther("1.0");
const tx = await contract.payAndShareWithETH(recipient, shareAmount, {
value: totalAmount
});
console.log("Transaction sent:", tx.hash);
// 等待交易完成
const receipt = await tx.wait();
console.log("Transaction mined:", receipt.transactionHash);
}
callPayAndShare();
```
2. **payAndShareWithERC20**：该方法用于 ERC20 代币支付过程的分佣
- 合约方法：
```solidity
/**
* @notice 使用 ERC20 代币执行支付并分佣，可指定收款地址、代币地址及分佣金额。
* @param recipient 接收 ERC20 代币的目标地址。
* @param tokenAddress 用于支付的 ERC20 代币的合约地址。
* @param amount 支付的 ERC20 代币总额。
* @param shareAmount 在 ERC20 代币支付总额中，用于 Shares 分佣的代币量。
*/
function payAndShareWithERC20(address recipient, address tokenAddress, uint256 amount, uint256 shareAmount) external;
```
- 合约方法调用示例：
```solidity
contract Example {
function examplePayAndShareWithERC20( address recipient, address tokenAddress) external {
// 假设支付 1000 个代币，其中分佣 200 个
payAndShareWithERC20(recipient, tokenAddress, 1000, 200);
// 交易后，recipient 收到 800 个代币，200 个代币通过 Shares 协议完成分佣
}
}
```
- ABI 接口定义:
```json
[
{
"type": "function",
"name": "payAndShareWithERC20",
"inputs": [
{
"name": "recipient",
"type": "address",
"internalType": "address"
},
{
"name": "tokenAddress",
"type": "address",
"internalType": "address"
},
{
"name": "amount",
"type": "uint256",
"internalType": "uint256"
},
{
"name": "shareAmount",
"type": "uint256",
"internalType": "uint256"
}
],
"outputs": [],
"stateMutability": "nonpayable"
}
]
```
- ABI 调用示例（基于 ethers.js）
```JavaScript
const { ethers } = require("ethers");
// 合约地址和 ABI
const contractAddress = "SimplifiedSharesContractDeploymentAddress";
const abi = [
{
"type": "function",
"name": "payAndShareWithERC20",
"inputs": [
{ "name": "recipient", "type": "address" },
{ "name": "tokenAddress", "type": "address" },
{ "name": "amount", "type": "uint256" },
{ "name": "shareAmount", "type": "uint256" }
],
"outputs": [],
"stateMutability": "nonpayable"
}
];
// 初始化 Provider 和 Signer
const provider = new ethers.providers.JsonRpcProvider("https://your-rpc-url");
const signer = provider.getSigner();
const contract = new ethers.Contract(contractAddress, abi, signer);
async function callPayAndShareWithERC20() {
const recipient = "0xRecipientAddress";
const tokenAddress = "0xTokenAddress";
const amount = ethers.utils.parseUnits("1000", 18); // 假设代币有 18 位小数
const shareAmount = ethers.utils.parseUnits("200", 18);
const tx = await contract.payAndShareWithERC20(
recipient,
tokenAddress,
amount,
shareAmount
);
console.log("Transaction sent:", tx.hash);
// 等待交易完成
const receipt = await tx.wait();
console.log("Transaction mined:", receipt.transactionHash);
}
callPayAndShareWithERC20();
```
##### 简化的分佣合约部署地址：
| Network | Contract Address |
| --- | --- |
| BSC | 0xf0Cc35840394eD6274e058620FC6eb3aBA27Ba2d |
#### 2.5 链上支付分佣交互示例
这是一个交互式 Demo，演示了如何集成 DeBox Shares 协议以实现链上原生代币（如 ETH）和 ERC20 代币支付的分佣功能。
**示例链接：** [https://shares-test.vercel.app/bsc_new.html](https://shares-test.vercel.app/bsc_new.html) （请在 DeBox App 中打开）
**使用说明：**
1. 在 DeBox App 中打开上述链接。
2. 点击页面上的按钮以调用相应的分佣方法（原生代币支付分佣、ERC20 代币支付分佣）。
3. 在页面右下角的 “vConsole” 中可以观察到详细的调用过程和执行结果。
4. 此 Demo 是一个独立的 HTML 文件，您可以在浏览器中按 F12 打开开发者工具查看其源代码，了解具体的集成方式。
---
## DeBox Grant 扶持计划
DeBox Grant 面向已接入 DeBox 能力并能持续交付价值的生态项目，提供项目扶持与协作支持。
## 计划重点
- 加速基于 DeBox 基础能力的可落地产品。
- 支持长期投入机器人、DApp 与协议集成的开发团队。
- 丰富生态工具供给，提升终端用户体验与活跃度。
## 优先支持方向
### 1. 机器人与社区工具
- 社区运营机器人
- 客服与工单机器人
- 知识库/AI 助手机器人
- 自动化流程机器人
### 2. DApp 与产品工具
- 增长与留存类工具
- 交易与数据分析工具
- 与 DeBox 社交关系链路深度结合的功能产品
### 3. 协议与基础设施集成
- Shares 协议集成项目
- 钱包与账号体系集成
- 具备明确采用目标的 Web3 服务集成
## 基础申请要求
- 产品已完成至少一项 DeBox 能力接入（API/SDK/DApp/Bot）。
- 团队提供清晰的产品路线、里程碑与运营计划。
- 可提供接入证明（Demo、文档、仓库或线上使用数据）。
- 愿意配合 DeBox 生态上线与联合传播安排。
## 入选后可获得支持
- 基于项目复杂度与影响力的潜在代币资助。
- DeBox 生态内的曝光与流量支持。
- DeBox 团队技术与生态协同支持。
## 申请入口
- 工具页上线申请：[提交表单](https://forms.gle/jAxuHUo9bydB69iB8)
- Grant 资助申请：[提交表单](https://forms.gle/9M61P812j6pfN92p9)
## 审核流程
1. 提交完整申请材料。
2. DeBox 团队进行技术与产品评审。
3. 通过初审的项目进入生态决策流程。
4. 审核通过后进入扶持与协作阶段。
---
## DeBox 机器人 开发总览
本文是 DeBox Bot 的总览文档，覆盖从 `BotMother` 找到入口、创建机器人、管理配置，到基于 SDK 二次开发的完整路径。
## 1. 先找到 BotMother
可以通过以下 3 种方式打开 BotMother：
1. 深链接：`https://m.debox.pro/user/chat?id=u7ooqdjt&start=`
2. 地址搜索：`0xda521900ac9dfeff8a8e692bb627ff8cd80a7b28`
3. 从 DeBox Ai 助手入口进入
按实际操作顺序，建议优先从 Ai 助手入口开始：
### 1.1 通过 Ai 助手入口找到 BotMother
### 1.2 进入 BotMother 会话入口
### 1.3 查看 BotMother 指令菜单
## 2. 通过 BotMother 创建 Bot
在 BotMother 中按指令流程完成创建，典型步骤：
1. 输入创建指令（按 BotMother 当前提示）。
2. 设置 Bot 基础信息（名称、头像、简介等）。
3. 创建完成后进入 Bot 管理列表。
## 3. Bot 管理与配置修改
创建后，先在管理页完成基础配置，再选择开发模式。
### 3.1 Bot 管理首页
你可以在这里：
- 查看已有 Bot 列表
- 进入单个 Bot 管理页
- 新增或删除 Bot
### 3.2 单个 Bot 管理页
你可以在这里完成：
- 基础资料修改（名称、描述、头像）
- 凭证管理（`API Key`，必要时 `App Secret`）
- Webhook 配置（`App Domain`、`Webhook URL`）
## 4. 两种开发模式（必须先选）
DeBox Bot 提供两种收消息模式：
- Webhook 模式（平台主动推送到你的服务）
- Long Polling 模式（你的程序主动轮询 `getUpdates`）
两者严格互斥：
- 配置了 Webhook 后，Webhook 优先生效。
- 此时 Long Polling 将收不到或几乎收不到消息。
- 若要改回 Long Polling，先清空 Webhook 配置。
## 5. Webhook 模式怎么用
最小接入步骤：
1. 在 Bot 管理页配置 `App Domain`。
2. 配置 `Webhook URL`（公网 HTTPS 地址）。
3. 服务端实现回调接口，校验请求头 `X-API-KEY == Webhook Key`。
4. 回调处理中按业务逻辑调用 OpenAPI 回消息。
推荐参考：
- [DeBox 机器人 Go SDK Webhook](/GO-SDK-Webhook)
- [DeBox 开发者 OpenAPI](/ApiOnePage)
## 6. Long Polling 模式怎么用
最小接入步骤：
1. 确认平台未配置 Webhook。
2. 使用 SDK 初始化 Bot（`API Key` + `API Secret`）。
3. 开启消息监听并循环处理 `GetUpdates/GetUpdatesChan`。
4. 收到消息后调用发送接口回消息。
## 7. 三个 SDK 选型建议
DeBox 目前提供三套官方 SDK：
1. Go SDK：
- 文档：[DeBox 机器人 Go SDK](/GO-SDK)
- 适合高并发后端与工程化部署。
2. Nodejs SDK：
- 文档：[DeBox 机器人 Nodejs SDK](/NODE-SDK)
- 适合 JS/TS 技术栈与快速迭代场景。
3. Python SDK：
- 文档：[DeBox 机器人 Python SDK](/PYTHON-SDK)
- 适合 AI 工作流、脚本化任务与数据处理场景。
## 8. 接口开发主文档
SDK 负责“怎么调用”，OpenAPI 负责“参数值域和响应结构”。
新开发请同时参考：
- [DeBox 开发者 OpenAPI](/ApiOnePage)
- [开发者 FAQ / 排障](/APIQA)
## 9. 推荐实施路径
1. 先通过 BotMother 创建并完成基础配置。
2. 小流量阶段优先用 Webhook 模式联调。
3. 按团队语言栈选择 Go/Nodejs/Python SDK。
4. 统一以 OpenAPI 参数定义做最终校验。
---
## DeBox 开发者 OpenAPI
## 接口清单（按路由顺序）
1. [`POST /openapi/bot/sendMessage`](#api-bot-sendmessage)
2. [`POST /openapi/bot/sendMessageToFans`](#api-bot-sendmessagetofans)
3. [`POST /openapi/bot/editMessage`](#api-bot-editmessage)
4. [`POST /openapi/bot/getMe`](#api-bot-getme)
5. [`POST /openapi/bot/getUpdates`](#api-bot-getupdates)
6. [`GET /openapi/group/info`](#api-group-info)
7. [`GET /openapi/group/is_join`](#api-group-is-join)
8. [`POST /openapi/group/admin/dao_member`](#api-group-admin-dao-member)
9. [`POST /openapi/group/admin/kick_member`](#api-group-admin-kick-member)
10. [`POST /openapi/group/admin/message/recall`](#api-group-admin-message-recall)
11. [`GET /openapi/user/info`](#api-user-info)
12. [`GET /openapi/user/is_follow`](#api-user-is-follow)
13. [`GET /openapi/token/info`](#api-token-info)
14. [`GET /openapi/box/info`](#api-box-info)
## Base URL
`https://open.debox.pro`
## 鉴权
除 `GET /openapi/box/info` 外，均需请求头：
```http
X-API-KEY:
```
## 返回包裹格式
### 标准包裹（group/user/token/box）
```json
{
"code": 200,
"success": true,
"data": {}
}
```
### Bot 包裹（bot 路由）
```json
{
"ok": true,
"success": true,
"result": {}
}
```
---
## 全局参数值域
- `chat_type`：`group` | `private`
- `chat_id`：
- `chat_type=group` 时：群 `gid`（如 `cc0onr82`）
- `chat_type=private` 时：用户 `user_id`（invite code）
- `content`：主参数
- 文本类长度上限（`text`/`richtext`/`Markdown`/`MarkdownV2`/`HTML`）：5000 字符
- `parse_mode` 默认值：`richtext`
- `parse_mode` 值域：
- `richtext`（默认）
- `text`
- `Markdown`
- `MarkdownV2`
- `HTML`
- `image`
- `video`
- `file`
### `content` 如何填写（关键）
- `parse_mode=richtext`：填普通文本或富文本字符串（默认）。
- `parse_mode=text`：填纯文本（不解析 Markdown/HTML）。
- `parse_mode=Markdown`：填 Markdown 内容。
- `parse_mode=MarkdownV2`：填 MarkdownV2（需要按语法转义）。
- `parse_mode=HTML`：填 HTML 片段（如 `Hello`）。
- `parse_mode=image`：`content` 填可公网访问的图片 URL（如 `https://cdn.example.com/a.png`）。
- `parse_mode=video`：`content` 填可公网访问的视频 URL（如 `https://cdn.example.com/a.mp4`）。
- `parse_mode=file`：`content` 填可公网访问的文件 URL（如 `https://cdn.example.com/a.pdf`）。
### `reply_markup` / `user_action_markup` 最小示例
```json
{
"inline_keyboard": [
[
{ "text": "查看详情", "url": "https://docs.debox.pro/zh/ApiOnePage" },
{ "text": "回调按钮", "callback_data": "detail" }
]
]
}
```
### `mention_type` / `mention_ids` 使用建议
- 仅 `parse_mode=text` 时建议使用 `mention_type` 与 `mention_ids`。
- 富文本模式（`richtext/Markdown/MarkdownV2/HTML`）建议直接在 `content` 中写 `@` 文本，不依赖 `mention_*` 字段。
- 若不需要 @ 功能，`mention_type` 与 `mention_ids` 可省略。
---
## 1. POST `/openapi/bot/sendMessage` {#api-bot-sendmessage}
### Curl 示例
```bash
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","parse_mode":"richtext"}'
```
发送单条消息（群/私聊）。
### 上行参数（Body，JSON）
- `chat_id` string，必填
- `chat_type` string，必填，值域：`group` | `private`
- `content` string，必填
- `parse_mode` string，选填，默认 `richtext`
- `message_id` string，选填
- `mention_type` int，选填
- `mention_ids` string[]，选填
- `reply_markup` object，选填
- `user_action_markup` object，选填
### 成功响应示例
```json
{
"ok": true,
"success": true,
"result": {
"message_id": "01JYXXXX",
"text": "Hello from DeBox",
"parse_mode": "richtext"
}
}
```
### 失败响应示例
```json
{
"ok": false,
"success": false,
"message": "message can't be empty"
}
```
---
## 2. POST `/openapi/bot/sendMessageToFans` {#api-bot-sendmessagetofans}
### Curl 示例
```bash
curl -X POST "https://open.debox.pro/openapi/bot/sendMessageToFans" \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_APP_KEY" \
-d '{"chat_id":"cc0onr82","chat_type":"group","content":"broadcast","parse_mode":"richtext"}'
```
向粉丝批量发送。
### 上行参数（Body，JSON）
- `chat_id` string，必填
- `chat_type` string，必填，值域：`group` | `private`
- `content` string，必填
- `parse_mode` string，选填，默认 `richtext`
约束：`content` 最大 2000 字节。
### 成功响应示例
```json
{
"ok": true,
"success": true,
"result": true
}
```
### 失败响应示例
```json
{
"ok": false,
"success": false,
"message": "message must be less than 2000 bytes"
}
```
---
## 3. POST `/openapi/bot/editMessage` {#api-bot-editmessage}
### Curl 示例
```bash
curl -X POST "https://open.debox.pro/openapi/bot/editMessage" \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_APP_KEY" \
-d '{"chat_id":"cc0onr82","chat_type":"group","message_id":"01JYXXXX","content":"edited","parse_mode":"richtext"}'
```
编辑历史消息文本。
### 上行参数（Body，JSON）
- `chat_id` string，必填
- `chat_type` string，必填，值域：`group` | `private`
- `message_id` string，必填
- `content` string，必填
- `parse_mode` string，选填，默认 `richtext`
### 成功响应示例
```json
{
"ok": true,
"success": true,
"result": true
}
```
### 失败响应示例
```json
{
"ok": false,
"success": false,
"message": "EditMessageText param Group Id is error"
}
```
---
## 4. POST `/openapi/bot/getMe` {#api-bot-getme}
### Curl 示例
```bash
curl -X POST "https://open.debox.pro/openapi/bot/getMe" \
-H "X-API-KEY: YOUR_APP_KEY"
```
获取当前 API Key 绑定账户信息。
### 上行参数
无。
### 成功响应示例
```json
{
"ok": true,
"success": true,
"result": {
"name": "DeBox Bot",
"address": "0x...",
"pic": "https://...",
"user_id": "u1",
"level": 3,
"level_icon": "https://.../icon/level/v3.png"
}
}
```
### 失败响应示例
```json
{
"ok": false,
"success": false,
"message": "invalid param"
}
```
---
## 5. POST `/openapi/bot/getUpdates` {#api-bot-getupdates}
### Curl 示例
```bash
curl -X POST "https://open.debox.pro/openapi/bot/getUpdates" \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_APP_KEY" \
-d '{"timeout":30}'
```
拉取 Bot 更新（长轮询）。
注意：如果你在开放平台配置了 Webhook URL，Webhook 会成为唯一有效收消息链路；此时本接口将拿不到或几乎拿不到消息。
### 上行参数（Body，JSON）
- `timeout` int，选填，值域 `1~60`，默认 `30`
### 成功响应示例（有消息）
```json
{
"ok": true,
"success": true,
"result": [
{
"id": 123,
"message": {
"message_id": "01JYXXXX",
"from": {
"user_id": "u1",
"name": "Alice",
"address": "0x..."
},
"chat": {
"id": "cc0onr82",
"type": "group"
},
"text": "Ping",
"parse_mode": "richtext"
}
}
]
}
```
### 成功响应示例（超时无消息）
```json
{
"ok": true,
"success": true,
"result": []
}
```
### 失败响应示例
```json
{
"ok": false,
"success": false,
"message": "Invalid timeout value"
}
```
---
## 6. GET `/openapi/group/info` {#api-group-info}
### Curl 示例
```bash
curl "https://open.debox.pro/openapi/group/info?gid=cc0onr82" \
-H "X-API-KEY: YOUR_APP_KEY"
```
查询群信息。
### Query 参数
- `gid` string，必填
### 成功响应示例
```json
{
"code": 200,
"success": true,
"data": {
"is_charge": false,
"subchannel_number": 2,
"group_name": "DeBox Dev",
"gid": "cc0onr82",
"group_number": 345,
"group_pic": "https://...",
"create_time": "2026-05-14 14:00:00",
"maximum": "无限制",
"mod": ["Alice", "Bob"],
"mod_info": [
{
"name": "Alice",
"address": "0x...",
"pic": "https://...",
"user_id": "u1"
}
]
}
}
```
### 失败响应示例
```json
{
"code": -3001,
"success": false,
"message": "No such group"
}
```
---
## 7. GET `/openapi/group/is_join` {#api-group-is-join}
### Curl 示例
```bash
curl "https://open.debox.pro/openapi/group/is_join?gid=cc0onr82&walletAddress=0x1234567890abcdef1234567890abcdef12345678" \
-H "X-API-KEY: YOUR_APP_KEY"
```
查询钱包是否已加入群。
### Query 参数
- `gid` string，必填
- `walletAddress` string，必填，EVM 地址
### 成功响应示例
```json
{
"code": 200,
"data": true
}
```
### 失败响应示例
```json
{
"error": "Bad Request",
"code": 401,
"message": "Param error"
}
```
---
## 8. POST `/openapi/group/admin/dao_member` {#api-group-admin-dao-member}
### Curl 示例
```bash
curl -X POST "https://open.debox.pro/openapi/group/admin/dao_member" \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_APP_KEY" \
-H "nonce: RANDOM_NONCE" \
-H "timestamp: 1715500000" \
-H "signature: SHA1(app_secret+nonce+timestamp)" \
-d '{"gid":"cc0onr82","page":1,"size":20}'
```
查询群成员（需签名鉴权 + 管理员权限）。
### 额外请求头（必填）
- `nonce` string
- `timestamp` string
- `signature` string
签名算法：`sha1(app_secret + nonce + timestamp)`。
### 上行参数（Body，JSON）
- `gid` string，必填，长度 `1~8`
- `page` int，选填，`<=0` 时按 `1`
- `size` int，选填，默认 `50`，最大 `50`
### 成功响应示例
```json
{
"code": 1,
"success": true,
"data": [
{
"user_id": "u1",
"name": "Alice",
"pic": "https://...",
"address": "0x...",
"signature": "builder"
}
]
}
```
### 失败响应示例
```json
{
"code": -4017,
"success": false,
"message": "permission denied"
}
```
---
## 9. POST `/openapi/group/admin/kick_member` {#api-group-admin-kick-member}
### 接口说明
将一个或多个成员移出指定 DeBox 群组。
该接口要求当前 `X-API-KEY` 绑定的 Bot 已加入目标群组，且在该群内具备管理员或建群者权限。
### Curl 示例
```bash
curl -X POST "https://open.debox.pro/openapi/group/admin/kick_member" \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_APP_KEY" \
-H "nonce: RANDOM_NONCE" \
-H "timestamp: 1715500000" \
-H "signature: SHA1(app_secret+nonce+timestamp)" \
-d '{
"gid":"cc0onr82",
"user_ids":["u1","u2"]
}'
```
### 额外请求头（必填）
- `nonce` string
- `timestamp` string
- `signature` string
签名算法：`sha1(app_secret + nonce + timestamp)`。
### 权限要求
- `X-API-KEY` 必须合法有效。
- API Key 必须已绑定一个有效的 DeBox Bot 账号。
- 该 Bot 必须在目标群组中具备管理员或建群者权限。
### 上行参数（Body，JSON）
- `gid` string，必填，目标群组 ID，长度 `1~8`
- `user_ids` string[]，必填，待移出成员的 DeBox `user_id` 列表
- `user_ids` 单次最多传入 `20` 个成员
### 参数校验与执行规则
- `user_ids` 不能为空数组。
- `user_ids` 中不允许出现空字符串。
- 重复的 `user_id` 会在服务端自动去重后再执行。
- 只要请求中的任意一个 `user_id` 无法解析为有效用户，接口会直接失败。
### 成功响应示例
```json
{
"code": 1,
"success": true,
"message": "success",
"data": true
}
```
### 失败响应示例
```json
{
"code": -2004,
"success": false,
"message": "uid size must be less than or equal to 20",
"data": null
}
```
```json
{
"code": -4017,
"success": false,
"message": "permission denied",
"data": null
}
```
---
## 10. POST `/openapi/group/admin/message/recall` {#api-group-admin-message-recall}
### 接口说明
管理员撤回群消息接口。
消息撤回后，将展示为如下群通知内容：
`MOD {operator_name} 撤回了 {sender_name}的消息`
### Curl 示例
```bash
curl -X POST "https://open.debox.pro/openapi/group/admin/message/recall" \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_APP_KEY" \
-H "nonce: RANDOM_NONCE" \
-H "timestamp: 1715500000" \
-H "signature: SHA1(app_secret+nonce+timestamp)" \
-d '{
"gid":"cc0onr82",
"user_id":"u1",
"message_id":"01HXYZABCDEF1234567890"
}'
```
### 额外请求头（必填）
- `nonce` string
- `timestamp` string
- `signature` string
签名算法：`sha1(app_secret + nonce + timestamp)`。
### 权限要求
- `X-API-KEY` 必须合法有效。
- API Key 必须已绑定一个有效的 DeBox Bot 账号。
- 该 Bot 必须在目标群组中具备管理员或建群者权限。
### 上行参数（Body，JSON）
- `gid` string，必填，目标群组 ID，长度 `1~8`
- `user_id` string，必填，原消息发送者的 DeBox `user_id`
- `message_id` string，必填，待撤回消息的消息 ID
### 注意事项
- `user_id` 必须能解析到一个真实存在的 DeBox 用户。
- `message_id` 必须对应目标群组内一条可被平台修改的消息。
- 撤回通知中的操作者名称，优先取管理员 Bot 的展示名；若展示名为空，则回退为其 `user_id`。
- 原消息发送者名称同样优先取展示名，缺失时回退为其 `user_id`。
### 成功响应示例
```json
{
"code": 1,
"success": true,
"message": "success",
"data": true
}
```
### 失败响应示例
```json
{
"code": -2004,
"success": false,
"message": "message_id is required",
"data": null
}
```
```json
{
"code": -2000,
"success": false,
"message": "recall message failed",
"data": null
}
```
---
## 11. GET `/openapi/user/info` {#api-user-info}
### Curl 示例
```bash
curl "https://open.debox.pro/openapi/user/info?user_id=u1" \
-H "X-API-KEY: YOUR_APP_KEY"
```
查询用户资料。
### Query 参数
- `user_id` string，选填
- `address` string，选填，EVM 地址
- 至少一个必填
### 成功响应示例
```json
{
"code": 200,
"success": true,
"data": {
"user_id": "u1",
"name": "Alice",
"address": "0x...",
"pic": "https://...",
"signature": "gm builder"
}
}
```
### 失败响应示例
```json
{
"code": -2004,
"success": false,
"message": "invalid param"
}
```
---
## 12. GET `/openapi/user/is_follow` {#api-user-is-follow}
### Curl 示例
```bash
curl "https://open.debox.pro/openapi/user/is_follow?walletAddress=0x1234567890abcdef1234567890abcdef12345678&followAddress=0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" \
-H "X-API-KEY: YOUR_APP_KEY"
```
查询用户关注关系。
### Query 参数
- `walletAddress` string，必填，EVM 地址
- `followAddress` string，必填，EVM 地址
### 成功响应示例
```json
{
"code": 200,
"data": true
}
```
### 失败响应示例
```json
{
"error": "Bad Request",
"code": 401,
"message": "Please input the wallet address correctly"
}
```
---
## 13. GET `/openapi/token/info` {#api-token-info}
### Curl 示例
```bash
curl "https://open.debox.pro/openapi/token/info?contract_address=0x55d398326f99059fF775485246999027B3197955&chain_id=56" \
-H "X-API-KEY: YOUR_APP_KEY"
```
查询 Token 元信息。
### Query 参数
- `contract_address` string，必填
- `chain_id` int，选填；缺失/负值按 `0`
### 成功响应示例
```json
{
"code": 200,
"success": true,
"data": {
"chain_id": 56,
"token": "0x55d398326f99059fF775485246999027B3197955",
"decimal": 18,
"name": "Tether USD",
"symbol": "USDT",
"logo_url": "https://..."
}
}
```
### 失败响应示例
```json
{
"code": -2004,
"success": false,
"message": "参数错误,contract_address must be a valid contract address"
}
```
---
## 14. GET `/openapi/box/info` {#api-box-info}
### Curl 示例
```bash
curl "https://open.debox.pro/openapi/box/info"
```
查询 BOX 基础信息（无需 API Key）。
### Query 参数
无。
### 成功响应示例
```json
{
"code": 200,
"success": true,
"data": {
"max_supply": "1000000000",
"burned": "...",
"supply": "...",
"locked": "...",
"address": "0x...",
"symbol": "BOX",
"chainId": 1,
"icon": "https://...",
"stake": "..."
}
}
```
---
## DeBox 机器人 Go SDK
# DeBox 机器人 Go SDK 使用文档
源码仓库：
- [debox-pro/debox-chat-go-sdk](https://github.com/debox-pro/debox-chat-go-sdk)
## 1. SDK 功能总览
`debox-chat-go-sdk` 主要提供：
- 机器人初始化：`NewBotAPI(apiKey, apiSecret)`
- 发送消息：`bot.Send(...)`
- Long Polling 收消息：`GetUpdates` / `GetUpdatesChan`
- 按钮与回调：`InlineKeyboardMarkup` + `CallbackQuery`
- 编辑消息：`NewEditMessageText` + `bot.Send(...)`
Webhook 已拆分为独立文档：
- [DeBox 机器人 Go SDK Webhook](/GO-SDK-Webhook)
## 2. 收消息模式说明
本文只讲 Long Polling。
如果你已经在开放平台配置 Webhook，Polling 可能收不到消息。Webhook 部署请看：
- [DeBox 机器人 Go SDK Webhook](/GO-SDK-Webhook)
---
## 3. Long Polling（SDK 详细用法）
### 3.1 安装 SDK
```bash
go get github.com/debox-pro/debox-chat-go-sdk
```
### 3.2 准备凭证
从 DeBox 开放平台获取：
- `API_KEY`（必须）
- `API_SECRET`（建议）
### 3.3 初始化 Bot + 发送第一条消息
```go
package main
import (
"log"
boxbotapi "github.com/debox-pro/debox-chat-go-sdk/boxbotapi"
)
func main() {
bot, err := boxbotapi.NewBotAPI("YOUR_APP_KEY", "YOUR_API_SECRET")
if err != nil {
log.Fatalf("init bot failed: %v", err)
}
// group: chatID=gid；private: chatID=user_id(invite code)
msg := boxbotapi.NewMessage("cc0onr82", "group", "Hello from Go SDK")
msg.ParseMode = boxbotapi.ModeRichText
sent, err := bot.Send(msg)
if err != nil {
log.Fatalf("send failed: %v", err)
}
log.Printf("sent message_id=%s", sent.MessageID)
}
```
### 3.4 收消息方式 A：`GetUpdatesChan`（推荐）
```go
package main
import (
"context"
"log"
boxbotapi "github.com/debox-pro/debox-chat-go-sdk/boxbotapi"
)
func main() {
bot, err := boxbotapi.NewBotAPI("YOUR_APP_KEY", "YOUR_API_SECRET")
if err != nil {
log.Fatal(err)
}
// 必须打开监听开关
boxbotapi.MessageListener = true
cfg := boxbotapi.NewUpdate(0)
cfg.Timeout = 30
ctx := context.Background()
updates := bot.GetUpdatesChan(cfg)
for {
select {
case <-ctx.Done():
bot.StopReceivingUpdates()
return
case upd := <-updates:
if upd.Message != nil {
log.Printf("from=%s chat=%s text=%s", upd.Message.From.UserId, upd.Message.Chat.ID, upd.Message.Text)
}
if upd.CallbackQuery != nil {
log.Printf("callback=%s", upd.CallbackQuery.Data)
}
}
}
}
```
### 3.5 收消息方式 B：`GetUpdates`（手动轮询）
```go
cfg := boxbotapi.NewUpdate(0)
cfg.Timeout = 30
updates, err := bot.GetUpdates(cfg)
if err != nil {
log.Printf("get updates failed: %v", err)
return
}
for _, upd := range updates {
if upd.Message != nil {
log.Println(upd.Message.Text)
}
}
```
### 3.6 发送不同类型消息
```go
// MarkdownV2
m1 := boxbotapi.NewMessage(chatID, chatType, "*bold* _italic_")
m1.ParseMode = boxbotapi.ModeMarkdownV2
_, _ = bot.Send(m1)
// HTML
m2 := boxbotapi.NewMessage(chatID, chatType, "Hello docs")
m2.ParseMode = boxbotapi.ModeHTML
_, _ = bot.Send(m2)
// 图片/视频/文件（文本填 URL）
m3 := boxbotapi.NewMessage(chatID, chatType, "https://example.com/a.png")
m3.ParseMode = boxbotapi.ModeImage
_, _ = bot.Send(m3)
```
可用 ParseMode：
- `boxbotapi.ModeRichText`
- `boxbotapi.ModeText`
- `boxbotapi.ModeMarkdown`
- `boxbotapi.ModeMarkdownV2`
- `boxbotapi.ModeHTML`
- `boxbotapi.ModeImage`
- `boxbotapi.ModeVideo`
- `boxbotapi.ModeFile`
`content` 填写规则（按 `parse_mode`）：
- `richtext`（默认）：填写普通文本或富文本语义字符串，例如 `你好，欢迎使用 DeBox Bot`。
- `text`：填写纯文本（不解析 Markdown/HTML），例如 `plain text only`。
- `Markdown`：填写 Markdown 字符串，例如 `**bold**`。
- `MarkdownV2`：填写 MarkdownV2 字符串（注意转义），例如 `\\*bold\\*`。
- `HTML`：填写 HTML 片段字符串，例如 `Hello`。
- `image`：`content` 填可公网访问的图片 URL，例如 `https://cdn.example.com/a.png`。
- `video`：`content` 填可公网访问的视频 URL，例如 `https://cdn.example.com/demo.mp4`。
- `file`：`content` 填可公网访问的文件 URL，例如 `https://cdn.example.com/spec.pdf`。
- 文本类（`richtext/text/Markdown/MarkdownV2/HTML`）最大长度 5000 字符。
### 3.7 按钮与回调
```go
markup := boxbotapi.NewInlineKeyboardMarkup(
boxbotapi.NewInlineKeyboardRow(
boxbotapi.NewInlineKeyboardButtonData("查看详情", "detail"),
boxbotapi.NewInlineKeyboardButtonURL("打开官网", "https://debox.pro"),
),
)
msg := boxbotapi.NewMessage("cc0onr82", "group", "请选择操作")
msg.ParseMode = boxbotapi.ModeRichText
msg.ReplyMarkup = markup
_, _ = bot.Send(msg)
```
处理回调：
```go
if upd.CallbackQuery != nil {
data := upd.CallbackQuery.Data
_ = data
}
```
### 3.8 编辑消息
```go
edit := boxbotapi.NewEditMessageText("cc0onr82", "group", "MESSAGE_ID", "编辑后的文本")
edit.ParseMode = boxbotapi.ModeRichText
_, err := bot.Send(edit)
if err != nil {
log.Printf("edit failed: %v", err)
}
```
---
## DeBox 机器人 Nodejs SDK
# DeBox 机器人 Nodejs SDK 使用文档
源码仓库：
- [debox-pro/debox-chat-nodejs-sdk](https://github.com/debox-pro/debox-chat-nodejs-sdk)
## 1. SDK 功能总览
`debox-chat-nodejs-sdk` 提供：
- Bot 初始化：`NewBotAPI(apiKey, apiSecret)`
- 消息发送：`bot.Send(...)`
- Long Polling 收消息：`GetUpdates` / `GetUpdatesChan`
- 按钮与回调处理
- 编辑消息：`NewEditMessageText(...)` / `NewEditMessageTextAndMarkup(...)`
## 2. 收消息模式说明
本文聚焦 Long Polling 模式。
Webhook 与 Long Polling 严格互斥：
- 开放平台配置了 webhook 后，消息只会进入 webhook。
- 要使用轮询收消息，先清空 webhook 配置。
Webhook 请参考：
- [DeBox 机器人 Go SDK Webhook](/GO-SDK-Webhook)
## 3. 安装与初始化
### 3.1 安装 SDK
```bash
npm install github:debox-pro/debox-chat-nodejs-sdk
```
或本地拉取安装：
```bash
git clone https://github.com/debox-pro/debox-chat-nodejs-sdk.git
cd debox-chat-nodejs-sdk
npm install
```
### 3.2 准备凭证
从 DeBox 开放平台获取：
- `API_KEY`（必填）
- `API_SECRET`（建议）
环境变量示例：
```bash
export DEBOX_BOT_API_KEY="YOUR_APP_KEY"
export DEBOX_BOT_API_SECRET="YOUR_API_SECRET"
```
### 3.3 发送第一条消息
```js
const boxbotapi = require("./boxbotapi");
async function main() {
const bot = await boxbotapi.NewBotAPI(
process.env.DEBOX_BOT_API_KEY,
process.env.DEBOX_BOT_API_SECRET || "",
);
const msg = boxbotapi.NewMessage("cc0onr82", "group", "Hello from Nodejs SDK");
msg.ParseMode = boxbotapi.ModeRichText;
const sent = await bot.Send(msg);
console.log("sent message_id=", sent.MessageID);
}
main().catch(console.error);
```
## 4. Long Polling 收消息
```js
const boxbotapi = require("./boxbotapi");
async function run() {
boxbotapi.Debug = false;
boxbotapi.MessageListener = true;
const bot = await boxbotapi.NewBotAPI(
process.env.DEBOX_BOT_API_KEY,
process.env.DEBOX_BOT_API_SECRET || "",
);
const u = boxbotapi.NewUpdate(0);
u.Timeout = 60;
for await (const update of bot.GetUpdatesChan(u)) {
if (update.Message) {
const text = update.Message.Text || "";
console.log("message:", text);
const reply = boxbotapi.NewMessage(
update.Message.Chat.ID,
update.Message.Chat.Type,
`Received: ${text}`,
);
reply.ParseMode = boxbotapi.ModeRichText;
await bot.Send(reply);
}
if (update.CallbackQuery) {
console.log("callback:", update.CallbackQuery.Data);
}
}
}
run().catch(console.error);
```
## 5. ParseMode 与 content 规则
SDK 常量：
- `boxbotapi.ModeRichText`
- `boxbotapi.ModeMarkdown`
- `boxbotapi.ModeMarkdownV2`
- `boxbotapi.ModeHTML`
- `boxbotapi.ModeImage`
- `boxbotapi.ModeVideo`
- `boxbotapi.ModeFile`
`content` 填写规则：
- `richtext` / `Markdown` / `MarkdownV2` / `HTML`：填写文本内容。
- `image` / `video` / `file`：`content` 必须为公网可访问 URL。
- 文本内容最大长度 5000 字符。
## 6. 按钮与回调
```js
const markup = boxbotapi.NewInlineKeyboardMarkup(
boxbotapi.NewInlineKeyboardRow(
boxbotapi.NewInlineKeyboardButtonData("查看详情", "detail"),
boxbotapi.NewInlineKeyboardButtonURL("打开文档", "https://docs.debox.pro"),
),
);
const msg = boxbotapi.NewMessage("cc0onr82", "group", "请选择");
msg.ParseMode = boxbotapi.ModeRichText;
msg.ReplyMarkup = markup;
await bot.Send(msg);
```
处理回调并编辑消息：
```js
if (update.CallbackQuery) {
const data = update.CallbackQuery.Data;
const chat = update.CallbackQuery.Message.Chat;
const messageId = update.CallbackQuery.Message.MessageID;
const edit = boxbotapi.NewEditMessageText(chat.ID, chat.Type, messageId, `clicked: ${data}`);
edit.ParseMode = boxbotapi.ModeRichText;
await bot.Send(edit);
}
```
## 7. 路由字段说明
发送/编辑消息时：
- `chat_type=group` -> `chat_id` 填群 `gid`
- `chat_type=private` -> `chat_id` 填用户 `user_id`（invite code）
## 8. 常见问题
1. 收不到消息：
- 先检查是否已配置 webhook（与轮询互斥）。
- 确保 `boxbotapi.MessageListener = true`。
2. 鉴权失败：
- 检查 `API_KEY/API_SECRET` 是否正确。
3. 媒体发送失败：
- 检查 URL 是否可公网直接访问。
---
## DeBox 机器人 Python SDK
# DeBox 机器人 Python SDK 使用文档
源码仓库：
- [debox-pro/debox-chat-python-sdk](https://github.com/debox-pro/debox-chat-python-sdk)
## 1. SDK 功能总览
`debox-chat-python-sdk` 提供：
- Bot 初始化：`NewBotAPI(api_key, api_secret)`
- 消息发送：`bot.Send(...)`
- Long Polling 收消息：`GetUpdates` / `GetUpdatesChan`
- 按钮与回调处理
- 编辑消息：`NewEditMessageText(...)` / `NewEditMessageTextAndMarkup(...)`
## 2. 收消息模式说明
本文仅覆盖 Long Polling 模式。
Webhook 与 Long Polling 严格互斥：
- 开放平台配置了 webhook 后，消息优先走 webhook。
- 要使用轮询，先清空 webhook 配置。
Webhook 文档：
- [DeBox 机器人 Go SDK Webhook](/GO-SDK-Webhook)
## 3. 安装与初始化
### 3.1 安装 SDK
```bash
pip install git+https://github.com/debox-pro/debox-chat-python-sdk.git
```
或本地拉取安装：
```bash
git clone https://github.com/debox-pro/debox-chat-python-sdk.git
cd debox-chat-python-sdk
pip install -e .
```
### 3.2 准备凭证
从 DeBox 开放平台获取：
- `API_KEY`（必填）
- `API_SECRET`（建议）
```bash
export DEBOX_BOT_API_KEY="YOUR_APP_KEY"
export DEBOX_BOT_API_SECRET="YOUR_API_SECRET"
```
### 3.3 发送第一条消息
```python
import os
import boxbotapi
bot = boxbotapi.NewBotAPI(
os.getenv("DEBOX_BOT_API_KEY", ""),
os.getenv("DEBOX_BOT_API_SECRET", ""),
)
msg = boxbotapi.NewMessage("cc0onr82", "group", "Hello from Python SDK")
msg.ParseMode = boxbotapi.ModeRichText
sent = bot.Send(msg)
print("sent message_id=", sent.MessageID)
```
## 4. Long Polling 收消息
```python
import os
import boxbotapi
from boxbotapi import configs as cfg
cfg.Debug = False
cfg.MessageListener = True
bot = boxbotapi.NewBotAPI(
os.getenv("DEBOX_BOT_API_KEY", ""),
os.getenv("DEBOX_BOT_API_SECRET", ""),
)
u = boxbotapi.NewUpdate(0)
u.Timeout = 60
for update in bot.GetUpdatesChan(u):
if update.Message is not None:
text = update.Message.Text or ""
print("message:", text)
reply = boxbotapi.NewMessage(
update.Message.Chat.ID,
update.Message.Chat.Type,
f"Received: {text}",
)
reply.ParseMode = boxbotapi.ModeRichText
bot.Send(reply)
if update.CallbackQuery is not None:
print("callback:", update.CallbackQuery.Data)
```
## 5. ParseMode 与 content 规则
SDK 常量：
- `boxbotapi.ModeRichText`
- `boxbotapi.ModeMarkdown`
- `boxbotapi.ModeMarkdownV2`
- `boxbotapi.ModeHTML`
- `boxbotapi.ModeImage`
- `boxbotapi.ModeVideo`
- `boxbotapi.ModeFile`
`content` 填写规则：
- `richtext` / `Markdown` / `MarkdownV2` / `HTML`：填写文本内容。
- `image` / `video` / `file`：`content` 必须是公网可访问 URL。
- 文本内容最大长度 5000 字符。
## 6. 按钮与回调
```python
markup = boxbotapi.NewInlineKeyboardMarkup(
boxbotapi.NewInlineKeyboardRow(
boxbotapi.NewInlineKeyboardButtonData("查看详情", "detail"),
boxbotapi.NewInlineKeyboardButtonURL("打开文档", "https://docs.debox.pro"),
)
)
msg = boxbotapi.NewMessage("cc0onr82", "group", "请选择")
msg.ParseMode = boxbotapi.ModeRichText
msg.ReplyMarkup = markup
bot.Send(msg)
```
处理回调并编辑消息：
```python
if update.CallbackQuery is not None:
data = update.CallbackQuery.Data
chat = update.CallbackQuery.Message.Chat
message_id = update.CallbackQuery.Message.MessageID
edit = boxbotapi.NewEditMessageText(chat.ID, chat.Type, message_id, f"clicked: {data}")
edit.ParseMode = boxbotapi.ModeRichText
bot.Send(edit)
```
## 7. 路由字段说明
发送/编辑消息时：
- `chat_type=group` -> `chat_id` 填群 `gid`
- `chat_type=private` -> `chat_id` 填用户 `user_id`（invite code）
## 8. 常见问题
1. 收不到消息：
- 先检查是否已配置 webhook（与轮询互斥）。
- 确保 `cfg.MessageListener = True`。
2. 鉴权失败：
- 检查 `API_KEY/API_SECRET` 与签名链路。
3. 媒体发送失败：
- 检查 URL 是否可公网直接访问。
---
## DeBox 机器人 Go SDK Webhook
# DeBox 机器人 Go SDK Webhook 使用文档
源码仓库：
- [debox-pro/debox-chat-go-sdk](https://github.com/debox-pro/debox-chat-go-sdk)
本文面向后端开发者，说明如何在 Go 服务中以生产可用的方式接入 DeBox Bot Webhook，包括回调鉴权、消息结构、媒体消息解析、入群事件处理，以及使用 Go SDK 回发消息。
## 1. Webhook 与 Long Polling（严格互斥）
DeBox 机器人收消息有两种方式：
1. Webhook：DeBox 主动 `POST` 回调到你的服务。
2. Long Polling：你的程序调用 `getUpdates` 主动拉取。
严格互斥规则：
- 只要在开放平台配置了 Webhook URL，Webhook 就会成为唯一有效的收消息链路。
- 此时 `GetUpdates/GetUpdatesChan` 作为收消息主链路会失效。
结论：
- 选择 Webhook，就不要再用 Long Polling 收消息。
- 若要切回 Long Polling，必须先清空开放平台上的 Webhook 配置。
## 2. 什么时候使用 Webhook
建议在以下场景使用：
- 服务已部署在公网 HTTP/HTTPS。
- 需要比轮询更低的消息延迟。
- 希望采用事件推送模型。
- 需要处理图片、视频、文件消息或入群事件。
## 3. 开放平台配置
在 DeBox 机器人控制台配置 Webhook URL，例如：
- `https://your-domain.com/bot/webhook`
同时请注意：
- `App Domain` 需正确配置。
- Webhook URL 必须是公网可访问、长期稳定的地址。
- 修改 Webhook URL 后，Webhook Key 会更新。
## 4. 回调协议说明
### 4.1 HTTP 请求规范
DeBox 会发送：
- 方法：`POST`
- Content-Type：`application/json`
- 请求头：`X-API-KEY: `
推荐做法：
- 缺少或校验失败的 `X-API-KEY` 直接拒绝。
- 仅在服务端成功接收事件后返回 `200 OK`。
- 如业务要求幂等，请在你自己的系统中实现事件去重。
### 4.2 顶层回调字段
Webhook 回调使用扁平化 JSON 结构。开发者最常用的字段如下：
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `from_user_id` | `string` | 是 | 当前事件发送者在 Bot 侧暴露的 DeBox 邀请码。私聊场景是对方用户，群聊场景是发言用户；当前入群事件实现中，这里是新入群成员。 |
| `to_user_id` | `string` | 是 | 当前目标 Bot 的邀请码。 |
| `name` | `string` | 否 | `from_user_id` 的显示名。 |
| `pic` | `string` | 否 | `from_user_id` 的头像 URL。 |
| `address` | `string` | 否 | `from_user_id` 的钱包地址。 |
| `language` | `string` | 否 | 用户语言信息，存在则返回。 |
| `group_id` | `string` | 否 | DeBox 群组 ID 或语聊房 ID。私聊时为空字符串。 |
| `parse_mode` | `string` | 是 | 当前回调内容类型，例如 `text`、`image`、`video`、`file`、`link`、`event:joinGroup`。 |
| `message` | `string` | 是 | 归一化后的消息内容。具体语义由 `parse_mode` 决定。 |
| `message_raw` | `string` | 是 | DeBox 解析后的原始内容。具体语义由 `parse_mode` 决定。 |
| `mention_users` | `array