Skip to main content

DeBox Developer OpenAPI

Endpoint Index (Ordered)​

  1. POST /openapi/bot/sendMessage
  2. POST /openapi/v2/bot/sendMessage
  3. POST /openapi/bot/sendMessageToFans
  4. POST /openapi/bot/batchSendMessageToGroups
  5. POST /openapi/bot/editMessage
  6. POST /openapi/bot/getMe
  7. GET /openapi/bot/energy
  8. POST /openapi/bot/getUpdates
  9. GET /openapi/group/info
  10. GET /openapi/group/is_join
  11. POST /openapi/group/admin/dao_member
  12. POST /openapi/group/admin/kick_member
  13. POST /openapi/group/admin/message/recall
  14. POST /openapi/group/admin/message/delete
  15. GET /openapi/user/info
  16. GET /openapi/token/info
  17. GET /openapi/box/info

Capability Overview​

CapabilityEndpoints and uses
Bot and messagingGet the current bot, send or edit messages, broadcast to followers or joined groups, and receive messages and interaction events.
Groups and moderationQuery groups and membership, list members, remove members, and recall or delete group messages.
UsersQuery public user information.
Web3 dataQuery 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-Limit reports the per-second request quota; X-Rate-Limit-Duration is 1 (second).
  • On 429, reduce the request rate and retry with backoff. If Retry-After is present, wait the specified number of seconds. The sendMessage minute quota uses a business error response; see that endpoint.

Global Parameter Ranges​

  • chat_type: group | private
  • chat_id:
    • when chat_type=group: group gid
    • when chat_type=private: target user's user_id; this value is the same as that user's uid and invite_code, but the request field remains chat_id
  • content is the primary field
  • max length for text-like modes (text/richtext/Markdown/MarkdownV2/HTML): 5000 chars
  • default parse_mode: richtext
  • parse_mode enum:
    • richtext (default)
    • text
    • Markdown
    • MarkdownV2
    • HTML
    • image
    • video
    • file

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: set content to a public image URL (e.g. https://cdn.example.com/a.png).
  • parse_mode=video: set content to a public video URL (e.g. https://cdn.example.com/a.mp4).
  • parse_mode=file: set content to a public file URL (e.g. https://cdn.example.com/a.pdf).
Image-sending level requirement

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 in content and avoid mention_*.
  • 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 message content.
  • 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 typeMessage quota per rolling 60 seconds
Ordinary account5
Iron account10
Green-badge account10
Gold account10

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_id string, required
  • chat_type string, required, enum: group | private
  • content string, required
  • parse_mode string, optional, default richtext
  • message_id string, optional
  • mention_type int, optional
  • mention_ids string[], optional
  • reply_markup object, optional
  • user_action_markup object, 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​

HeaderRequiredDescription
X-API-KEYYesThe bot's App Key.
nonceYesA fresh random string for every request; do not reuse it across signed endpoints with the same key.
timestampYesA 13-digit Unix timestamp in milliseconds, within 5 minutes of server time, without leading zeros or a plus sign.
signatureYesLowercase 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=false and a busy message, with a wait time in Retry-After. A full queue returns Retry-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 messageAction
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 energyTop up the bot's energy before retrying.
Energy account is not readyThe energy account is not ready; retry later.
Failed to retrieve energy balanceBalance lookup failed; retry later.
The send user is not in the groupAdd the bot to the target group first.
param group Id is errorCheck the target group gid.
The bot account is bannedThe 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_id string, required
  • chat_type string, required, enum: group | private
  • content string, required
  • parse_mode string, optional, default richtext

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_id or chat_type is required, and a custom group list is not supported. Use sendMessage to target a specific group.
  • Limits: content must 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)​

ParameterTypeRequiredDescription
contentstringYesNon-empty message content, at most 2000 UTF-8 bytes. Use this field for the message body.
parse_modestringNoDefaults to richtext. See global field ranges for values and content formats; the 2000-byte limit still applies here.
titlestringNoMessage push title.
reply_markupobjectNoInline 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_balance is null.
  • 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​

FieldTypeDescription
total_messagesintegerNumber of joined groups selected; one message is planned per group.
estimated_energy_coststringEstimated total energy at 0.1 per message.
current_energy_balancestring / nullBalance snapshot at submission; null if unavailable with no target groups.
estimated_duration_minutesintegerEstimated minutes, rounded up; 0 for no messages. Actual duration may be longer.
summarystringUser-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 messageMeaning and action
message can't be emptyProvide non-empty content.
message must be less than 2000 bytesContent exceeds 2000 bytes. Shorten it before retrying.
The bot account is bannedThe 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_id string, required
  • chat_type string, required, enum: group | private
  • message_id string, required
  • content string, required
  • parse_mode string, optional, default richtext

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​

HeaderRequiredDescription
X-API-KEYYesThe bot's App Key.
nonceYesA fresh random string for every request; do not reuse it across signed endpoints with the same key.
timestampYes13-digit Unix timestamp in milliseconds, within 5 minutes of server time, without leading zeros or a plus sign.
signatureYesLowercase 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)​

  • timeout int, optional, range 1~60, default 30

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_member when 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​

  • gid string, 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.joined is false for 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​

  • gid string, required, eight characters; surrounding whitespace is trimmed.
  • user_id is 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)​

  • nonce string
  • timestamp string, a 13-digit Unix timestamp in milliseconds
  • signature string

Signature algorithm: sha1(app_secret + nonce + timestamp).

Request params (Body, JSON)​

  • gid string, required, length 1~8
  • page int, optional, if <=0 then treated as 1
  • size int, optional, default 50, max 50

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, member user_id values, 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)​

  • nonce string
  • timestamp string, a 13-digit Unix timestamp in milliseconds
  • signature string

Signature algorithm: sha1(app_secret + nonce + timestamp).

Permission requirements​

  • X-API-KEY must 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)​

  • gid string, required, target group ID, length 1~8
  • user_ids string array, required, list of DeBox user_id values to remove
  • user_ids maximum size: 20 per request

Validation and execution rules​

  • Empty user_ids is rejected.
  • Empty string items inside user_ids are rejected.
  • Duplicate user_id values are de-duplicated before execution.
  • If any provided user_id cannot 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's user_id, and the exact message_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)​

  • nonce string
  • timestamp string, a 13-digit Unix timestamp in milliseconds
  • signature string

Signature algorithm: sha1(app_secret + nonce + timestamp).

Permission requirements​

  • X-API-KEY must 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)​

  • gid string, required, target group ID, length 1~8
  • user_id string, required, DeBox user_id of the original sender
  • message_id string, required, message ID to recall

Important notes​

  • user_id must resolve to an existing DeBox user.
  • message_id must 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-KEY and signed headers nonce, timestamp, and signature. 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​

codemessage
400Your signature is not available
-2004gid is invalid / user_id is invalid / message_id is required / group not found / user not found
-2006Bot not exist
-4017permission denied
-2000query 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_id or 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_id string, optional; an eight-character DeBox invite code
  • address string, optional (EVM address)
  • at least one is required; an eight-character user_id takes precedence over address

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_id is optional and is treated as 0 when 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_address string, required
  • chain_id int, optional; missing/negative is treated as 0

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": "..."
}
}