Web Widget Integration
The Web Widget lets a project or community embed a Studio bot on a website. It connects visitors to the bot's conversation, knowledge, and trading workflow without sending them away from the site.
This page is the legacy integration guide for the widget surface. For the current operator workflow, use Studio Web Widget.
What the widget is for
Use the widget when you want to:
- Add a Balchemy bot to a project website.
- Let visitors ask questions or get market context from the bot.
- Offer wallet-connected trading workflows where enabled.
- Keep domain and embed settings under Studio operator control.
- Attribute widget activity to the project or integration context.
The widget belongs to Studio, not Hub. Hub is for 24/7 Web3 agent operations.
Where to configure it
Open the Studio bot cockpit and use the Widget tab. Typical controls include:
| Control | Purpose |
|---|---|
| Enabled state | Turn the widget on or off without removing the script tag. |
| Theme | Configure title, welcome message, primary color, placement, and branding. |
| Allowed domains | Restrict where the widget can be embedded. |
| Quick prompts | Add starter prompts for visitors. |
| Wallet connect | Decide whether visitors can authenticate a wallet for trading workflows. |
| Embed snippet | Copy the script tag for the website. |
| Analytics | Review widget sessions, activity, and health signals where available. |
Embed snippet
Copy the script tag from the Widget tab and place it before the closing </body> tag on the website.
<script src="https://balchemy.ai/api/widget/YOUR_BOT_ID/script.js" async></script>Use the snippet shown by your own Studio bot. Do not copy a bot ID from another environment or an old screenshot.
Domain controls
Allowed domains protect your bot from being embedded on unrelated sites.
Recommended production setup:
- Add the production domain in the Widget tab.
- Complete any verification prompt shown by the UI.
- Enable strict domain enforcement when available.
- Test the widget from the real domain after deployment.
If the widget appears on one site but not another, check whether strict mode or domain verification is blocking the request.
Wallet-connected trading
When wallet connection is enabled, visitors may be asked to sign a Solana or EVM wallet message before using trading workflows. Trading still depends on product policy, wallet authentication, risk checks, provider state, slippage, and order lifecycle.
If wallet connection is disabled, visitors can still use conversation and analysis features where the bot allows it, but fund-sensitive trading actions should not execute.
Partner attribution and fee-share
A widget can carry project or partner attribution when configured. That attribution can be used to analyze activity associated with an embedded project surface and, where the product flow supports it, connect that activity to channel/widget fee-share metadata.
Do not describe widget attribution as a guaranteed automatic payout. Settlement details depend on the configured product flow and should be verified before making payout promises.
This is separate from referrals:
| Concept | Meaning |
|---|---|
| Widget/channel fee-share | Attribution and configuration tied to activity from a community, server, group, or embedded widget. |
| Referral rewards | Referral-code based tracking and reward/commission records. |
Content Security Policy
If the website uses Content Security Policy headers, allow the widget script and API endpoints used by the embed.
Typical requirements:
script-src https://balchemy.ai;
connect-src https://api.balchemy.ai wss://api.balchemy.ai;Merge those entries with your existing CSP policy rather than replacing it.
Common issues
The widget does not appear.
Confirm the script tag is present, the widget is enabled, and the website can load scripts from https://balchemy.ai.
The widget is blocked on one domain. Check allowed domains, strict mode, and verification state in the Widget tab.
Users can chat but cannot trade. Confirm wallet connect is enabled, the user completed wallet authentication, and the bot's trading policy allows the requested action.
Analytics look empty. Make sure the script is installed on the intended production domain and that the widget has received real traffic after the latest configuration change.