Web Widget Integration

Add a fully featured AI trading assistant to any website in under five minutes. The Balchemy chat widget loads from a single script tag and brings your Studio bot directly to your users.

What is this?

The web widget is an embeddable chat interface that loads on your website via a JavaScript snippet. It connects to your Studio bot's AI, knowledge base, and trading engine. Visitors can chat with your bot, ask questions, and — if you enable wallet authentication — execute trades directly from the widget without leaving your site.

The widget is configured entirely from the Widget tab inside your bot's cockpit at /studio/bots/[botId]/widget. Changes saved there take effect on all websites using your embed snippet immediately — no code change needed.

Prerequisites

A Studio bot in Running or Ready state
At least one website where you can add a <script> tag
For wallet-enabled trading: the wallet connect option enabled in widget settings

The Widget tab has four sub-tabs and a live preview panel below them.

Sub-tab	What you configure
Theme	Branding, colors, position, wallet connect, payout address
Domains	Allowed origins, strict mode, DNS verification
Prompts	Quick-start buttons shown to users when the widget opens
Embed	The `<script>` tag to copy

The Save Changes button in the top right saves all four tabs at once.

Theme settings

Appearance fields

Setting	Default	Notes
Widget Enabled	On	Master switch — turn off to hide the widget without removing the script tag
Widget Title	"Chat with us"	Shown in the widget header bar
Welcome Message	"Hello! How can I help you today?"	First message the bot sends when the widget opens
Primary Color	`#17616B`	Brand teal — used for the chat bubble, header bar, and send button
Position	Bottom Right	Bubble anchor: Bottom Right or Bottom Left
Brand Name	(empty)	Your company name shown in the header instead of the Widget Title
Show "Powered by Balchemy"	On	Footer credit — disable if you prefer unbranded embedding
Enable Wallet Connect	Off	Shows a wallet connection button in the widget UI

Primary Color

The default color #17616B is Balchemy's brand teal. You can change it to any hex value to match your website's design. The color picker in the Theme tab lets you choose visually, and the text input next to it accepts hex values directly. The live preview below the tabs updates in real time as you change the color.

Payout wallet address

If your widget users trade through your bot, swap fee revenue is sent to a payout wallet you specify. Enter a Solana (base58) or EVM (0x...) address in the Payout Wallet Address field. This links to your bot's ERC-8004 agent card feeAddress field. Leave blank if you do not want to collect fees.

Domain allowlist

The Domains sub-tab controls which websites are allowed to load your widget. Without a domain list, the widget loads on any website — which means anyone who finds your script URL could embed your bot on their site.

Strict mode

Toggle Strict Mode to block all requests from domains not on your allowlist. With strict mode off, the domain list acts as a preference — unlisted domains can still load the widget but without verified status. With strict mode on, requests from unlisted domains receive a 403 error.

Tip: Always enable strict mode in production. The permissive default is useful for development when you are testing from localhost, but you should add your production domain and enable strict mode before going live.

Adding a domain

Click the Domains sub-tab.
Type your domain (e.g., yourcompany.com) in the input field.
Press Enter or click the + button.
The domain appears in the list with a Pending verification badge.

DNS verification

To confirm you own the domain, you need to add a TXT record:

Click Verify on the domain row. A panel expands with your unique TXT record value.
The record looks like: balchemy-verify=<your-bot-id>
Add this TXT record to your domain's DNS settings (at your registrar or DNS provider).
DNS propagation can take up to 48 hours.
Once the record is live, click Check Verification in the expanded panel.
A verified badge (green checkmark) replaces the pending badge on success.

Unverified domains still work in non-strict mode. Verification is required only for strict mode enforcement to work correctly.

Quick prompts

Quick prompts are suggestion buttons shown inside the widget when it first opens. They give users a low-friction way to start a conversation without typing.

Adding a prompt

Go to the Prompts sub-tab.
Type a prompt in the text field (e.g., "What is my portfolio worth?").
Press Enter or click the + button.
The prompt appears as a removable chip in the list.

Remove any prompt by clicking the X button next to it. Prompts display in the order they were added.

Tip: Write prompts as complete sentences that the user would actually say. "Show my portfolio" works. "Portfolio" does not — the bot needs context to know what action to take.

Embed snippet

The Embed sub-tab shows the script tag to add to your website:

<script
  src="https://balchemy.ai/api/widget/YOUR_BOT_ID/script.js"
  async
></script>

Copy this tag by clicking Copy code in the top-right corner of the code block. Paste it into your website's HTML before the closing </body> tag. The widget script loads asynchronously — it will not block your page from rendering.

Open the Embed sub-tab and click Copy code.
Open your website's HTML source.
Paste the script tag just before </body>.
Deploy your website change.
Open your website in a browser.
The Balchemy chat bubble appears in the corner you configured.
Click the bubble to open the widget and test the conversation.

Wallet authentication

When Enable Wallet Connect is on, the widget shows a wallet connection button. Users can connect a Solana or EVM wallet directly from the chat interface.

How it works

The user clicks "Connect Wallet" inside the widget.
Balchemy sends a sign-in message (SIWS for Solana, SIWE for EVM).
The user signs with their wallet.
Balchemy verifies the signature server-side and creates a widget session with a 1-hour TTL.
During the active session, the user can submit trade commands through the chat.
After 1 hour of inactivity or session expiry, the user must re-authenticate.

Open mode vs strict mode

Open mode (wallet connect disabled): anyone can chat with the bot, but trading commands are blocked. The bot answers questions and provides analysis but will not submit orders.
Strict mode (wallet connect enabled + domain strict mode on): only users from verified domains who sign in with a wallet can use the full trading functionality.

Warning: Wallet authentication in the widget uses session tokens with a 1-hour TTL. Sessions are stored server-side and validated on every request. Users should close the widget tab when done — do not leave authenticated sessions open on shared computers.

widgetConfig sync

Your bot has a widgetConfig object in its settings that stores the widget configuration. There is also a legacy embedSettings field. The two are kept in sync automatically via a server-side pre-save hook — you never need to update embedSettings manually. Always configure the widget through the Studio UI or via the widgetConfig API field.

CSP headers

If your website uses Content Security Policy headers, you need to allow the Balchemy widget script and API to load. Add the following to your CSP:

script-src 'self' https://balchemy.ai;
connect-src 'self' https://api.balchemy.ai wss://api.balchemy.ai;
frame-src 'none';

If you are using a strict script-src with nonces or hashes, you also need to add the nonce or hash for the Balchemy script tag. The easiest approach is to add https://balchemy.ai to script-src rather than managing per-request nonces.

Live preview

Below the four sub-tabs, the Widget tab shows a live preview of your widget using your current configuration. A mock browser chrome with fake page content lets you see exactly how the bubble and chat panel will look. Click the bubble in the preview to toggle the chat panel open and closed. The preview reads your active config state — changes you make in the Theme tab are reflected in the preview without saving.

Below the live preview, a Widget Analytics section shows three KPIs: Total Sessions, Active Sessions, and Messages Today. An online/offline status badge shows whether the widget service is currently reachable. Analytics update in near-real time and give you a quick health check without leaving the Widget tab.

Common issues

The widget does not appear on my website. Check that the script tag is present in your HTML before </body>. Confirm the widget is enabled in the Theme tab. Open your browser console and look for network errors loading the script.

The widget loads but shows an error message. If your website uses strict CSP headers, add https://balchemy.ai to your script-src directive. Check the browser console for blocked resource errors.

The widget loads on my site but not on another domain. If strict mode is enabled, only domains on your allowlist can load the widget. Add the domain to your allowlist in the Domains sub-tab.

Users can chat but cannot trade. Wallet Connect must be enabled in the Theme tab. Users must connect their wallet and complete the sign-in flow before trading commands are accepted.

The primary color I set is not showing on my site. The widget reads configuration from the server at load time. Try a hard refresh (Ctrl+Shift+R) to bypass browser cache. If you recently changed the color, confirm you clicked Save Changes in the Widget tab.

DNS verification shows "Pending" after 48 hours. DNS propagation is complete when the TXT record is visible worldwide. Use a tool like dig TXT yourdomain.com to check if the record is live. If the record is visible but verification still shows Pending, click Check Verification again in the expanded DNS panel.

Knowledge Base

Automation

Edit this page on GitHub