DeBox Developer OpenAPI
Endpoint Index (Ordered)
POST /openapi/bot/sendMessagePOST /openapi/v2/bot/sendMessagePOST /openapi/bot/sendMessageToFansPOST /openapi/bot/batchSendMessageToGroupsPOST /openapi/bot/editMessagePOST /openapi/bot/getMeGET /openapi/bot/energyPOST /openapi/bot/getUpdatesGET /openapi/group/infoGET /openapi/group/is_joinPOST /openapi/group/admin/dao_memberPOST /openapi/group/admin/kick_memberPOST /openapi/group/admin/message/recallPOST /openapi/group/admin/message/deleteGET /openapi/user/infoGET /openapi/token/infoGET /openapi/box/info
Capability Overview
| Capability | Endpoints and uses |
|---|---|
| Bot and messaging | Get the current bot, send or edit messages, broadcast to followers or joined groups, and receive messages and interaction events. |
| Groups and moderation | Query groups and membership, list members, remove members, and recall or delete group messages. |
| Users | Query public user information. |
| Web3 data | Query token metadata and overall BOX information. |
OpenAPI request address (Base URL)
https://open.debox.pro
Authentication
A DApp that needs authenticated DeBox OpenAPI endpoints must first create a bot through BotMother. The bot's App Key is the API Key used in X-API-KEY. Keep it on the backend and never expose it in H5 or browser code.
All endpoints except GET /openapi/box/info require:
X-API-KEY: <your_api_key>
Paid sending v2 and energy queries also require the signed headers nonce, timestamp and signature. Authentication for the free send endpoint is unchanged.
All signed endpoints require a 13-digit Unix timestamp in milliseconds. Replace CURRENT_UNIX_TIMESTAMP_MS below with the current millisecond timestamp. Use exactly the same value when signing and in the request header. Generate it with:
timestamp="$(python3 -c 'import time; print(time.time_ns() // 1_000_000)')"
Response Envelopes
Standard envelope
The wrapped group, user, and token endpoints return code: 1 on success. GET /openapi/box/info uses code: 200 as shown in its example below.
{
"code": 1,
"success": true,
"data": {}
}
Bot envelope
{
"ok": true,
"success": true,
"result": {}
}
Request rate limits
Each endpoint below lists its request rate and bucket dimensions. The unauthenticated GET /openapi/box/info uses source IP + endpoint path. All other listed endpoints use API Key + endpoint path. Requests to the same path with the same API Key share a quota across source IPs; different API Keys and different paths have separate quotas.
- Pace requests evenly and avoid bursts.
- Exceeding an endpoint request limit returns HTTP 429. The body may be plain text rather than the JSON envelopes above.
X-Rate-Limit-Limitreports the per-second request quota;X-Rate-Limit-Durationis1(second).- On 429, reduce the request rate and retry with backoff. If
Retry-Afteris present, wait the specified number of seconds. ThesendMessageminute quota uses a business error response; see that endpoint.
Global Parameter Ranges
chat_type:group|privatechat_id:- when
chat_type=group: groupgid - when
chat_type=private: target user'suser_id; this value is the same as that user'suidandinvite_code, but the request field remainschat_id
- when
contentis the primary field- max length for text-like modes (
text/richtext/Markdown/MarkdownV2/HTML): 5000 chars - default
parse_mode:richtext parse_modeenum:richtext(default)textMarkdownMarkdownV2HTMLimagevideofile
How to fill content (critical)
parse_mode=richtext: normal text/rich text string (default), e.g.Hello, welcome to DeBox Bot.parse_mode=text: plain text only (no Markdown/HTML parsing), e.g.plain text only.parse_mode=Markdown: Markdown content, e.g.**bold**.parse_mode=MarkdownV2: MarkdownV2 content (escape special chars as required), e.g.\\*bold\\*.parse_mode=HTML: HTML fragment (e.g.<b>Hello</b>).parse_mode=image: setcontentto a public image URL (e.g.https://cdn.example.com/a.png).parse_mode=video: setcontentto a public video URL (e.g.https://cdn.example.com/a.mp4).parse_mode=file: setcontentto a public file URL (e.g.https://cdn.example.com/a.pdf).
Image sending is subject to bot-level and target-group administrator rules. See Bot level and image sending for the complete requirements, administrator exception, level check, and upgrade steps.
Minimal reply_markup / user_action_markup sample
{
"inline_keyboard": [
[
{ "text": "View detail", "url": "https://docs.debox.pro/en/ApiOnePage" },
{ "text": "Callback button", "callback_data": "detail" }
]
]
}
mention_type / mention_ids practical guidance
- Recommended mainly when
parse_mode=text. - For rich text modes (
richtext/Markdown/MarkdownV2/HTML), prefer writing@directly incontentand avoidmention_*. - If no mention behavior is needed, omit both fields.
1. POST /openapi/bot/sendMessage
Request rate limit: 10 requests/second per API Key + endpoint path; see rate-limit handling.
At a glance
- Requires: an App Key,
chat_id,chat_type, and messagecontent. - Useful for: replying to a user or sending a notification to a specified private chat or group.
- Limits: each request sends to one specified private chat or group; it is not a fan broadcast.
Message quota per minute
In addition to the per-second request limit, this endpoint shares a rolling 60-second message quota per bot account. Messages to different private chats and groups share this quota; changing API Keys does not reset it.
| Account type | Message quota per rolling 60 seconds |
|---|---|
| Ordinary account | 5 |
| Iron account | 10 |
| Green-badge account | 10 |
| Gold account | 10 |
Account-tier quotas do not stack.
When the minute quota is exceeded, the endpoint returns HTTP 200 with ok: false, success: false, and message: "The system is busy, please try again later!". The Retry-After header specifies how many seconds to wait. A full send queue returns the same error with Retry-After: 10. Check both the HTTP status and business response, and wait before retrying.
Curl Example
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"}'
Request params (Body, JSON)
chat_idstring, requiredchat_typestring, required, enum:group|privatecontentstring, requiredparse_modestring, optional, defaultrichtextmessage_idstring, optionalmention_typeint, optionalmention_idsstring[], optionalreply_markupobject, optionaluser_action_markupobject, optional
Success response example
{
"ok": true,
"success": true,
"result": {
"message_id": "01JYXXXX",
"text": "Hello from DeBox",
"parse_mode": "richtext"
}
}
Error response example
{
"ok": false,
"success": false,
"message": "message can't be empty"
}
For a higher quota, use paid sending v2. A bot outside the group or a nonexistent group returns ok=false, success=false and an explanatory message; HTTP 200 alone does not mean success.
2. POST /openapi/v2/bot/sendMessage
Request rate limit: 10 requests/second per API Key + endpoint path, plus 100 admissions per bot per rolling 60 seconds.
Send a paid message to a specified private chat or group. Each confirmed successful message costs 0.12 energy. The signed headers X-API-KEY, nonce, timestamp and signature are required. The pay_energy, payer and amount parameters are not required.
Signed authentication
| Header | Required | Description |
|---|---|---|
X-API-KEY | Yes | The bot's App Key. |
nonce | Yes | A fresh random string for every request; do not reuse it across signed endpoints with the same key. |
timestamp | Yes | A 13-digit Unix timestamp in milliseconds, within 5 minutes of server time, without leading zeros or a plus sign. |
signature | Yes | Lowercase hexadecimal SHA1(AppSecret + nonce + timestamp), concatenated without separators. |
Store the App Secret and sign requests only on your backend. Authentication failures are rejected before balance lookup or admission: no message is sent, no energy is charged and no minute message quota is consumed. Generate a fresh nonce, timestamp and signature for every retry; a send after an energy query also requires a new nonce.
Request parameters and example
Use the same fields, message types and formats as sendMessage and the global parameter ranges. Required: chat_id, chat_type, content. Optional: parse_mode, reply_markup, etc. For group messages, the bot must have joined the group and have permission to send.
# Set DEBOX_API_KEY and DEBOX_APP_SECRET securely on your backend.
nonce="$(openssl rand -hex 16)"
timestamp="$(python3 -c 'import time; print(time.time_ns() // 1_000_000)')"
signature="$(printf '%s' "${DEBOX_APP_SECRET}${nonce}${timestamp}" | openssl dgst -sha1 | awk '{print $NF}')"
curl -X POST "https://open.debox.pro/openapi/v2/bot/sendMessage" \
-H "Content-Type: application/json" \
-H "X-API-KEY: ${DEBOX_API_KEY}" \
-H "nonce: ${nonce}" \
-H "timestamp: ${timestamp}" \
-H "signature: ${signature}" \
-d '{"chat_id":"cc0onr82","chat_type":"group","content":"hello","parse_mode":"text"}'
Billing, quotas and retries
- The bot bound to the API Key pays. Balance is checked before admission and again before sending; a balance below 0.12 rejects the send.
- Only confirmed successful sends with a valid receipt matching the target are charged. Failed or unknown outcomes are not charged. An accepted message may still be sent and charged after the client disconnects.
- Every bot has 100 admissions per rolling 60 seconds, shared across its API Keys and service instances and counted separately from the free endpoint. Failed sends do not refund admitted quota.
- Up to 300 messages can wait per bot. Messages for the same bot are processed serially. Actual throughput depends on sending time; 100 admissions do not guarantee 100 completions per minute.
- Minute quota exhaustion returns HTTP 200,
ok=falseand a busy message, with a wait time inRetry-After. A full queue returnsRetry-After: 10. Per-second request limits return HTTP 429; see rate limits. - Balance is not reserved. If charging fails after a successful send, the actual send result is retained; the service does not automatically resend or retry the charge.
- Requests are not deduplicated. A timeout or missing message ID does not prove failure; blindly resubmitting may duplicate messages and charges. Queued messages are not guaranteed to survive a service restart, and ordering across instances is not guaranteed.
Success response example
{
"message": "success",
"ok": true,
"success": true,
"result": {
"message_id": "01JYXXXX",
"chat": null,
"text": "hello",
"parse_mode": "text"
}
}
Error response example
HTTP 200 with a business failure:
{
"message": "Insufficient energy: sending a message requires 0.12 energy",
"ok": false,
"result": null,
"success": false
}
Common error message | Action |
|---|---|
Missing required authentication headers: ... | Supply the API Key, nonce, millisecond timestamp and signature. |
Invalid request signature. ... | Check the App Secret and signing inputs, then sign again. |
Request timestamp is outside the allowed 5-minute window. ... | Synchronize your clock and generate a new signature. |
Request rejected: nonce already used. ... | Retry with a fresh nonce, timestamp and signature. |
Insufficient energy: sending a message requires 0.12 energy | Top up the bot's energy before retrying. |
Energy account is not ready | The energy account is not ready; retry later. |
Failed to retrieve energy balance | Balance lookup failed; retry later. |
The send user is not in the group | Add the bot to the target group first. |
param group Id is error | Check the target group gid. |
The bot account is banned | The bot is banned. |
The system is busy, please try again later! | Wait as specified by Retry-After. |
3. POST /openapi/bot/sendMessageToFans
Request rate limit: 2 requests/second per API Key + endpoint path; see rate-limit handling.
At a glance
- Requires: an App Key, approved subscription-account permission, and the message fields listed below.
- Useful for: broadcasting product updates, service notices, or announcements to the bot's followers.
- Limits: content is limited to 2000 bytes; follower scope and delivery rules follow the bot's current platform permissions.
Curl Example
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"}'
Request params (Body, JSON)
chat_idstring, requiredchat_typestring, required, enum:group|privatecontentstring, requiredparse_modestring, optional, defaultrichtext
Constraint: content max 2000 bytes.
Success response example
{
"ok": true,
"success": true,
"result": true
}
Error response example
{
"ok": false,
"success": false,
"message": "message must be less than 2000 bytes"
}
4. POST /openapi/bot/batchSendMessageToGroups
Request rate limit: 2 requests/second per API Key + endpoint path; see rate-limit handling.
At a glance
- Requires: a valid bot App Key, message
content, and sufficient bot energy. Banned bots cannot call this endpoint. - Useful for: broadcasting the same announcement to all groups the bot has joined and has not left.
- Targets: selected by the server. No
chat_idorchat_typeis required, and a custom group list is not supported. UsesendMessageto target a specific group. - Limits:
contentmust not exceed 2000 UTF-8 bytes (not 2000 characters).
Curl Example
curl -X POST "https://open.debox.pro/openapi/bot/batchSendMessageToGroups" \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_APP_KEY" \
-d '{"content":"Announcement: join our event this week","parse_mode":"richtext"}'
Request params (Body, JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
content | string | Yes | Non-empty message content, at most 2000 UTF-8 bytes. Use this field for the message body. |
parse_mode | string | No | Defaults to richtext. See global field ranges for values and content formats; the 2000-byte limit still applies here. |
title | string | No | Message push title. |
reply_markup | object | No | Inline buttons; see global field ranges for the structure. |
chat_id and chat_type do not filter target groups. mention_type, mention_ids, and user_action_markup are not forwarded to this endpoint's batch delivery flow.
Energy and delivery rules
- Each target group costs 0.1 energy. Before sending, the server checks that the balance covers
target group count × 0.1; for example, 10 groups require at least 1 energy. - Insufficient energy, an unavailable energy account, or a query failure rejects the entire request before any group delivery.
- The precheck does not reserve or deduct energy. Each successful group send with a message receipt deducts 0.1 energy. A deduction failure stops delivery to subsequent groups.
- With no target groups, the request succeeds with zero count, cost and duration. This endpoint sends only to joined groups, not the public channel. If the balance cannot be retrieved or the energy account is missing in this zero-target case,
current_energy_balanceisnull. - Delivery is asynchronous. Success means the request passed prechecks and delivery was started; it does not guarantee receipt by every group. No task ID, per-group results, or message IDs are returned.
- Do not resubmit simply because a message has not appeared yet; repeated requests may cause duplicate delivery and energy charges.
Estimate result fields
| Field | Type | Description |
|---|---|---|
total_messages | integer | Number of joined groups selected; one message is planned per group. |
estimated_energy_cost | string | Estimated total energy at 0.1 per message. |
current_energy_balance | string / null | Balance snapshot at submission; null if unavailable with no target groups. |
estimated_duration_minutes | integer | Estimated minutes, rounded up; 0 for no messages. Actual duration may be longer. |
summary | string | User-facing estimate text, currently returned in Chinese. |
The result is an estimate, not a charge receipt or completion notification. Actual energy is charged for successful sends only. The message limit is 200 messages per minute.
Success response example
{
"message": "success",
"ok": true,
"result": {
"total_messages": 16,
"estimated_energy_cost": "1.6",
"current_energy_balance": "1000",
"estimated_duration_minutes": 1,
"summary": "本任务预计发送 16 条群消息,预计消耗 1.6 能量,当前能量余额 1000 能量,预计耗时约 1 分钟。实际能量按成功发送条数结算,失败不扣。"
},
"success": true
}
Error response example
{
"ok": false,
"success": false,
"message": "Insufficient energy: sending to 9 groups requires 0.9 energy; current balance is 0.8. No messages were sent.",
"result": null
}
Business errors may also return HTTP 200. Check ok / success, not just the HTTP status.
Common error message | Meaning and action |
|---|---|
message can't be empty | Provide non-empty content. |
message must be less than 2000 bytes | Content exceeds 2000 bytes. Shorten it before retrying. |
The bot account is banned | The bot account is banned. |
Sender must be a bot. | The sender bound to the App Key is not a bot. |
Insufficient energy: ... No messages were sent. | Insufficient energy. The error includes the group count, required energy, and current balance. Top up before resubmitting. |
Energy account is not ready. No messages were sent. Please try again later. | The energy account is not ready. Retry later. |
Failed to retrieve target groups. No messages were sent. | Target group lookup failed. Retry later. |
Failed to retrieve energy balance. No messages were sent. | Energy balance lookup failed. Retry later. |
5. POST /openapi/bot/editMessage
Request rate limit: 10 requests/second per API Key + endpoint path; see rate-limit handling.
At a glance
- Requires: an App Key, the target chat, the exact
message_id, and the replacement content. - Useful for: correcting or updating a message previously sent by the bot.
- Limits: it does not allow the bot to edit arbitrary messages sent by other users.
Curl Example
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"}'
Request params (Body, JSON)
chat_idstring, requiredchat_typestring, required, enum:group|privatemessage_idstring, requiredcontentstring, requiredparse_modestring, optional, defaultrichtext
Success response example
{
"ok": true,
"success": true,
"result": true
}
Error response example
{
"ok": false,
"success": false,
"message": "EditMessageText param Group Id is error"
}
6. POST /openapi/bot/getMe
Request rate limit: 2 requests/second per API Key + endpoint path; see rate-limit handling.
At a glance
- Requires: an App Key; no request body is required.
- Useful for: checking the current bot's ID, profile, address, and level.
- Limits: it returns the bot bound to the current App Key, not an ordinary user's profile.
Curl Example
curl -X POST "https://open.debox.pro/openapi/bot/getMe" \
-H "X-API-KEY: YOUR_APP_KEY"
Request params
None.
Success response example
{
"ok": true,
"success": true,
"result": {
"name": "DeBox Bot",
"address": "0x...",
"pic": "https://...",
"user_id": "u1",
"level": 3,
"level_icon": "https://.../icon/level/v3.png"
}
}
Error response example
{
"ok": false,
"success": false,
"message": "invalid param"
}
7. GET /openapi/bot/energy
Request rate limit: 2 requests/second per API Key + endpoint path.
Query the energy balance of the account bound to the API Key. No query parameters are needed; parameters such as user_id cannot select another account.
Signed authentication
| Header | Required | Description |
|---|---|---|
X-API-KEY | Yes | The bot's App Key. |
nonce | Yes | A fresh random string for every request; do not reuse it across signed endpoints with the same key. |
timestamp | Yes | 13-digit Unix timestamp in milliseconds, within 5 minutes of server time, without leading zeros or a plus sign. |
signature | Yes | Lowercase hexadecimal SHA1(AppSecret + nonce + timestamp), concatenated without separators. |
AppSecret is the App Secret / API Secret, not the API Key or Webhook Key. Store secrets and sign requests only on your backend. Generate a new nonce, timestamp and signature for each retry.
Curl example
# Run only on your backend. Set DEBOX_API_KEY and DEBOX_APP_SECRET securely.
nonce="$(openssl rand -hex 16)"
timestamp="$(python3 -c 'import time; print(time.time_ns() // 1_000_000)')"
signature="$(printf '%s' "${DEBOX_APP_SECRET}${nonce}${timestamp}" | openssl dgst -sha1 | awk '{print $NF}')"
curl "https://open.debox.pro/openapi/bot/energy" \
-H "X-API-KEY: ${DEBOX_API_KEY}" \
-H "nonce: ${nonce}" \
-H "timestamp: ${timestamp}" \
-H "signature: ${signature}"
Success response example
{
"message": "success",
"ok": true,
"result": {
"energy_balance": "996.8"
},
"success": true
}
energy_balance is a decimal string without fixed decimal places. Zero balance or a missing energy account returns "0"; a missing bound user or balance lookup failure returns an error. Queries do not consume energy.
Error response example
{
"message": "Missing required authentication headers: nonce, timestamp, signature.",
"ok": false,
"result": null,
"success": false
}
Missing or invalid signatures, timestamps outside the 5-minute window, and reused nonces are rejected. Business errors may return HTTP 200; inspect ok / success. Per-second throttling returns HTTP 429.
8. POST /openapi/bot/getUpdates
Request rate limit: 2 requests/second per API Key + endpoint path; see rate-limit handling.
At a glance
- Requires: an App Key and Long Polling as the active receiving mode.
- Useful for: receiving new messages and interaction events sent to the bot.
- Limits: Webhook and Long Polling are mutually exclusive, and this endpoint is not a general chat-history query.
Curl Example
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}'
Request params (Body, JSON)
timeoutint, optional, range1~60, default30
If a Webhook URL is configured in BotMother, Webhook is the only effective receiving path and this endpoint cannot be used to receive messages. Clear the Webhook settings before using getUpdates for Long Polling.
Success response example (with updates)
{
"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"
}
}
]
}
Success response example (timeout, no updates)
{
"ok": true,
"success": true,
"result": []
}
Error response example
{
"ok": false,
"success": false,
"message": "Invalid timeout value"
}
Button interaction events
Button clicks use the selected receiving mode: direct Webhook delivery when configured, otherwise getUpdates. Non-empty callback data appears in callback_query.data; from identifies the clicking user and message contains the original message ID, text, parse_mode, and chat. For groups, chat.id is the group gid; for private chats it is the clicking user’s code. Empty callback data produces a message instead. Both modes use the same event contents, but Webhook omits the polling record id and the result envelope.
See Webhook button events for payloads and failure/discard behavior.
9. GET /openapi/group/info
Request rate limit: 1 request/second per API Key + endpoint path; see rate-limit handling.
At a glance
- Requires: an App Key and the group
gid. - Useful for: validating a group ID and displaying basic group information before sending notifications or performing group operations.
- Limits: it returns group metadata, not the complete member list; use
dao_memberwhen a member list is required.
Curl Example
curl "https://open.debox.pro/openapi/group/info?gid=cc0onr82" \
-H "X-API-KEY: YOUR_APP_KEY"
Query params
gidstring, required
Success response example
{
"code": 1,
"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": "Unlimited",
"mod": ["Alice", "Bob"],
"mod_info": [
{
"name": "Alice",
"address": "0x...",
"pic": "https://...",
"user_id": "u1"
}
]
}
}
Error response example
{
"code": -3001,
"success": false,
"message": "No such group"
}
10. GET /openapi/group/is_join
Request rate limit: 1 request/second per API Key + endpoint path; see rate-limit handling.
At a glance
- Requires: an App Key bound to a bot and the eight-character group
gid. - Useful for: checking whether the bot bound to the current API key is in the target group.
- Limits:
data.joinedisfalsefor a bot that has never joined or has left the group. This endpoint does not join a user or return the member list.
Curl Example
curl "https://open.debox.pro/openapi/group/is_join?gid=cc0onr82" \
-H "X-API-KEY: YOUR_APP_KEY"
Query params
gidstring, required, eight characters; surrounding whitespace is trimmed.user_idis no longer required and is ignored if supplied; it cannot select another user.- The API key must be bound to a valid, existing bot; missing or invalid bindings return an error.
Success response example
{
"code": 1,
"success": true,
"message": "success",
"data": {"joined": true}
}
Error response example
{
"code": -2004,
"success": false,
"message": "API key bound bot is invalid",
"data": null
}
11. POST /openapi/group/admin/dao_member
Request rate limit: 1 request/second per API Key + endpoint path; see rate-limit handling.
At a glance
- Requires: an App Key, signed request headers, the group
gid, and the required management permission in that group. - Useful for: reading the current member list and public member profiles page by page.
- Limits: each page contains at most 50 members; the endpoint does not return historical chat messages or private conversations.
Curl Example
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: CURRENT_UNIX_TIMESTAMP_MS" \
-H "signature: SHA1(app_secret+nonce+timestamp)" \
-d '{"gid":"cc0onr82","page":1,"size":20}'
Extra headers (required)
noncestringtimestampstring, a 13-digit Unix timestamp in millisecondssignaturestring
Signature algorithm: sha1(app_secret + nonce + timestamp).
Request params (Body, JSON)
gidstring, required, length1~8pageint, optional, if<=0then treated as1sizeint, optional, default50, max50
Success response example
{
"code": 1,
"success": true,
"data": [
{
"user_id": "u1",
"name": "Alice",
"pic": "https://...",
"address": "0x...",
"signature": "builder"
}
]
}
Error response example
{
"code": -4017,
"success": false,
"message": "permission denied"
}
12. POST /openapi/group/admin/kick_member
Request rate limit: 1 request/second per API Key + endpoint path; see rate-limit handling.
At a glance
- Requires: an App Key, signed request headers, the target
gid, memberuser_idvalues, and moderator or builder permission. - Useful for: removing specified members from the target group under its moderation rules, such as in cases of spam, policy violations, or failure to meet the group's admission criteria.
- Limits: this operation changes group state and accepts at most 20 users per request; verify it with test accounts first.
Purpose
Remove one or more members from a DeBox group.
The bot account bound to the current X-API-KEY must already be in the target group and must have moderator or builder permission in that group.
Curl Example
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: CURRENT_UNIX_TIMESTAMP_MS" \
-H "signature: SHA1(app_secret+nonce+timestamp)" \
-d '{
"gid":"cc0onr82",
"user_ids":["u1","u2"]
}'
Extra headers (required)
noncestringtimestampstring, a 13-digit Unix timestamp in millisecondssignaturestring
Signature algorithm: sha1(app_secret + nonce + timestamp).
Permission requirements
X-API-KEYmust be valid.- The API key must be bound to an existing DeBox bot account.
- The bound bot must be a moderator or builder of the target group.
Request params (Body, JSON)
gidstring, required, target group ID, length1~8user_idsstring array, required, list of DeBoxuser_idvalues to removeuser_idsmaximum size:20per request
Validation and execution rules
- Empty
user_idsis rejected. - Empty string items inside
user_idsare rejected. - Duplicate
user_idvalues are de-duplicated before execution. - If any provided
user_idcannot be resolved to a valid user, the request fails.
Success response example
{
"code": 1,
"success": true,
"message": "success",
"data": true
}
Error response examples
{
"code": -2004,
"success": false,
"message": "uid size must be less than or equal to 20",
"data": null
}
{
"code": -4017,
"success": false,
"message": "permission denied",
"data": null
}
13. POST /openapi/group/admin/message/recall
Request rate limit: 1 request/second per API Key + endpoint path; see rate-limit handling.
At a glance
- Requires: an App Key, signed request headers, moderator or builder permission, the group
gid, the original sender'suser_id, and the exactmessage_id. - Useful for: recalling a specified message in the target group under its moderation rules, for example to address spam, policy-violating content, or a message sent by mistake.
- Limits: the message and sender must match the target group; this is not a general history search or arbitrary message deletion API.
Purpose
Recall a group message through an administrator action.
After a successful recall, the group displays a system notification similar to:
MOD {operator_name} recalled {sender_name}'s message.
The exact wording follows the language selected in the DeBox App.
Curl Example
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: CURRENT_UNIX_TIMESTAMP_MS" \
-H "signature: SHA1(app_secret+nonce+timestamp)" \
-d '{
"gid":"cc0onr82",
"user_id":"u1",
"message_id":"01HXYZABCDEF1234567890"
}'
Extra headers (required)
noncestringtimestampstring, a 13-digit Unix timestamp in millisecondssignaturestring
Signature algorithm: sha1(app_secret + nonce + timestamp).
Permission requirements
X-API-KEYmust be valid.- The API key must be bound to an existing DeBox bot account.
- The bound bot must be a moderator or builder of the target group.
Request params (Body, JSON)
gidstring, required, target group ID, length1~8user_idstring, required, DeBoxuser_idof the original sendermessage_idstring, required, message ID to recall
Important notes
user_idmust resolve to an existing DeBox user.message_idmust identify a message in the target group that can be modified by the platform.- The operator name in the recall notice prefers the bot display name and falls back to the bot
user_id. - The original sender name follows the same fallback rule.
Success response example
{
"code": 1,
"success": true,
"message": "success",
"data": true
}
Error response examples
{
"code": -2004,
"success": false,
"message": "message_id is required",
"data": null
}
{
"code": -2000,
"success": false,
"message": "recall message failed",
"data": null
}
14. POST /openapi/group/admin/message/delete
Request rate limit: 1 request/second per API Key + endpoint path; see rate-limit handling.
Delete a specific group message for all perspectives through IM. This does not replace the message with a recall notice.
Permissions and parameters
- Requires a valid
X-API-KEYand signed headersnonce,timestamp, andsignature. Algorithm:sha1(app_secret + nonce + timestamp). - The API key must be bound to an existing bot. Active moderators or builders of the target group can delete other users’ messages.
- A non-moderator bot can only delete its own messages in that group. The server verifies sender, group, group conversation type, and non-deleted status against the message record.
gid: required, eight-character group invite code.user_id: required, original sender’s eight-character DeBox user code. Numeric-only values are also treated as user codes, not internal numeric IDs.message_id: required, message ID to delete. Surrounding whitespace is trimmed from all three fields.
Curl example
curl -X POST "https://open.debox.pro/openapi/group/admin/message/delete" \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_APP_KEY" \
-H "nonce: RANDOM_NONCE" \
-H "timestamp: CURRENT_UNIX_TIMESTAMP_MS" \
-H "signature: SHA1(app_secret+nonce+timestamp)" \
-d '{"gid":"cc0onr82","user_id":"uvg2p6ho","message_id":"01HXYZABCDEF1234567890"}'
Success response
{
"code": 1,
"success": true,
"message": "success",
"data": true
}
Errors
| code | message |
|---|---|
| 400 | Your signature is not available |
| -2004 | gid is invalid / user_id is invalid / message_id is required / group not found / user not found |
| -2006 | Bot not exist |
| -4017 | permission denied |
| -2000 | query group failed / query user failed / query bot failed / query permission failed / query message failed / delete message failed |
15. GET /openapi/user/info
Request rate limit: 10 requests/second per API Key + endpoint path; see rate-limit handling.
At a glance
- Requires: an App Key and either a DeBox
user_idor an EVM wallet address. - Useful for: displaying a user's public name and avatar or matching a wallet address to a DeBox profile.
- Limits: it returns public profile fields, not private chats, message history, or private keys.
Curl Example
curl "https://open.debox.pro/openapi/user/info?user_id=uvg2p6ho" \
-H "X-API-KEY: YOUR_APP_KEY"
Query params
user_idstring, optional; an eight-character DeBox invite codeaddressstring, optional (EVM address)- at least one is required; an eight-character
user_idtakes precedence overaddress
Success response example
{
"code": 1,
"success": true,
"data": {
"user_id": "uvg2p6ho",
"name": "Alice",
"address": "0x...",
"pic": "https://...",
"signature": "gm builder"
}
}
Error response example
{
"code": -2004,
"success": false,
"message": "invalid param"
}
16. GET /openapi/token/info
Request rate limit: 5 requests/second per API Key + endpoint path; see rate-limit handling.
At a glance
- Requires: an App Key and
contract_address;chain_idis optional and is treated as0when omitted or negative. - Useful for: displaying a token's name, symbol, decimals, and logo after a contract address is entered.
- Limits: it returns token metadata, not market price or the token balance of a wallet.
Curl Example
curl "https://open.debox.pro/openapi/token/info?contract_address=0x55d398326f99059fF775485246999027B3197955&chain_id=56" \
-H "X-API-KEY: YOUR_APP_KEY"
Query params
contract_addressstring, requiredchain_idint, optional; missing/negative is treated as0
Success response example
{
"code": 1,
"success": true,
"data": {
"chain_id": 56,
"token": "0x55d398326f99059fF775485246999027B3197955",
"decimal": 18,
"name": "Tether USD",
"symbol": "USDT",
"logo_url": "https://..."
}
}
Error response example
{
"code": -2004,
"success": false,
"message": "contract_address must be a valid contract address"
}
17. GET /openapi/box/info
Request rate limit: 5 requests/second per source IP + endpoint path; see rate-limit handling.
At a glance
- Requires: no parameters and no App Key.
- Useful for: retrieving global BOX data, such as its maximum supply, current supply, burned amount, and locked amount.
- Limits: it returns overall BOX data, not the BOX balance held by a specific user.
Curl Example
curl "https://open.debox.pro/openapi/box/info"
Public endpoint, no API key required.
Query params
None.
Success response example
{
"code": 1,
"success": true,
"data": {
"max_supply": "1000000000",
"burned": "...",
"supply": "...",
"locked": "...",
"address": "0x...",
"symbol": "BOX",
"chainId": 1,
"icon": "https://...",
"stake": "..."
}
}