Skip to main content

DeBox DApp

Developer-facing DApp integration guide (current version).

1. What is a DApp​

A DeBox DApp is an H5 app running inside the DeBox built-in browser.

You can:

  • Reuse existing web pages for fast integration
  • Use injected wallet objects for on-chain interactions
  • Call DeBox OpenAPI from your backend for messaging/user/group features

2. Quick start​

  1. Decide whether the DApp needs DeBox OpenAPI. A wallet-only integration can use injected wallet capabilities without OpenAPI credentials.
  2. If OpenAPI is required, create a bot through BotMother and obtain the bot's App Key (API Key).
  3. Prepare a publicly reachable HTTPS web app. The DeBox in-app browser supports only https:// and blocks http:// URLs.
  4. Implement DeBox environment detection and wallet flows.
  5. Keep the bot's App Key and App Secret on your backend. The H5 frontend calls your backend and never carries these credentials.

3. Runtime detection​

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"

Recommendation:

  • Use hasDeBoxWallet || hasEthereum as your EVM capability check.
  • Add graceful fallback for non-DeBox runtime.

4. Wallet and user-info capabilities​

Primary entry is window.deboxWallet (EVM-compatible).

4.1 Request permissions​

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

4.2 Get public user profile​

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

Example response (fields may vary by client version):

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

uid, the OpenAPI user_id, and that user's invite_code use the same identifier value, but each API keeps its own field name. Use this value as user_id in OpenAPI and as chat_id when an endpoint requires the target user's user_id for a private chat. See DeBox App Deep Links for the complete field comparison.

4.3 Use standard Web3.js for signing and transactions​

An H5/DApp can use the injected provider with standard Web3.js. Use window.deboxWallet first and fall back to window.ethereum when needed:

npm install web3
import { Web3 } from "web3"

const provider = window.deboxWallet ?? window.ethereum

if (!provider) {
  throw new Error("DeBox wallet provider is unavailable")
}

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

Use the same provider for a standard personal_sign request:

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

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

Use Web3.js to send a transaction:

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

console.log(receipt.transactionHash)

Signing and transaction calls open the DeBox wallet confirmation. The action is complete only after the user approves and the call returns successfully; handle rejection and failure states in the H5 page. Before opening the wallet, validate the active chain, destination address, amount, and encoded contract call data. For token transfers and contract calls, use an ABI-encoded data value (or a Web3.js contract method) instead of treating the amount as native-token value.

Use this H5/DApp approach when you need custom forms, quotes, risk notices, calculations, or multi-step business logic. For a single supported wallet action directly in chat, see DeBox Bot Blockchain Buttons.

Security baseline:

  • A DApp that needs OpenAPI must first create a bot through BotMother.
  • The bot's App Key is the API Key carried in X-API-KEY by the backend.
  • Frontend calls your backend only.
  • App Key, App Secret, and signature parameters stay server-side.

Primary API reference:

6. Message sending (current API)​

This example requires a bot created through BotMother. Send the request from your backend with the bot's App Key in X-API-KEY.

Use POST /openapi/bot/sendMessage:

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

Field notes:

  • chat_type: group | private
  • chat_id:
    • group -> gid
    • private -> user user_id
  • content: message body
  • parse_mode: default richtext

7. Production checklist​

  1. The page and every redirect target use HTTPS, and mobile adaptation is complete. The DeBox in-app browser blocks HTTP URLs.
  2. Runtime detection + fallback path are verified.
  3. Wallet permission flow handles reject/cancel/success.
  4. OpenAPI calls are backend-only.
  5. Logs contain request id, user identity, endpoint, and error code.
Third-party link notice

HTTPS is required for access, but it does not remove the third-party website security notice. When a DApp/H5 is opened from a third-party link in a DeBox chat, the notice is shown by default. For the direct-opening assessment process, see Third-party links and HTTPS.

8. FAQ​

  1. OpenAPI fails when called directly in browser:
  • Expected; move calls to backend.
  1. Message send failures:
  • Check chat_type/chat_id mapping.
  • Check non-empty content and valid parse_mode.
  1. Wallet object missing:
  • Not in DeBox runtime or unsupported client version.