Troubleshooting

Common issues and how to resolve them. Start with the product surface you are using: Studio for bots and channels, Hub for 24/7 Web3 agent operations.

Studio bot issues

Bot not responding in Telegram or Discord

Verify the bot is active in the Studio cockpit.
Check that the platform binding is configured in the Platforms tab.
Confirm access mode, allowed usernames, allowed channels, or role rules are set correctly.
If the bot is in a group/server, check whether it only responds to mentions.
Studio uses Balchemy-managed platform adapters; you do not need to provide your own Telegram or Discord bot token.

Bot gives irrelevant answers

Add or update Knowledge with more specific content for your use case.
Use Q&A pairs for answers that must be precise.
Remove stale or conflicting documents from the bot knowledge base.
Review the bot persona/configuration and make sure it does not conflict with knowledge content.
Test with a narrow prompt before enabling the bot in a busy group or server.

Telegram OTP not received

Confirm you are messaging the official Balchemy Telegram bot handle shown in the app.
Send /start before requesting a code.
Wait at least 60 seconds before requesting a new code.
Check that your Telegram account allows bot messages.
If the problem is for Hub operator verification, restart the verification flow from Hub instead of reusing an old link.

DCA strategy not executing

Verify the relevant trading strategy is active.
Confirm the wallet has enough source token and enough gas/native token for fees.
Check risk limits; the DCA order may exceed a configured threshold.
Review History for failed or pending orders.

Trading issues

Trading not executing

Verify trading is enabled for the bot or agent context.
Check the key scope; a read key cannot submit trade actions.
Check risk/policy settings; the trade may be blocked before execution.
Review pending orders that may require approval.
Confirm the wallet is funded on the target chain.

Solana trade pending

Some flows create pending orders until approval or execution conditions are met.
Open History, locate the order, and inspect the status.
Verify the wallet has enough SOL for transaction fees.
Check provider or circuit-breaker status if many Solana trades are failing.

EVM trade failing

Confirm the wallet has enough token balance on the target EVM chain.
Confirm the wallet has enough native gas token.
Check whether token approval is required for the sell token.
Review pre-trade security output and order error details.
Confirm you are using the intended chain, especially for Base/EVM flows.

What happens if my trade fails?

If a trade fails before submission, it should not execute. If a submitted transaction fails on-chain, chain-specific gas or fee behavior may still apply. Check the order detail for the exact failure reason: insufficient balance, slippage exceeded, provider error, circuit breaker, or policy rejection.

Verify the domain is in the widget allowed-domains list in Studio.
Check strict mode; if enabled, only listed domains can initialize the widget.
Confirm the embed script URL and botId are copied from the Studio widget page.
Check browser console network errors for blocked script, CORS, or domain mismatch messages.

CORS errors usually mean the request origin does not match the widget domain allowlist.

Open the bot cockpit in Studio.
Go to the Widget page.
Add the exact production domain.
Save and reload the website.
Remove temporary localhost domains before production launch.

Verify the Studio bot responds in the built-in chat.
Check whether the widget is enabled.
Check wallet-connect settings if the visitor flow expects wallet-aware actions.
Review widget settings and logs in the bot cockpit.

Telegram and Discord issues

Telegram group messages are ignored

Check access mode: private responds only to the owner in DMs.
Check whitelist usernames if whitelist mode is enabled.
Check channel policies for that group.
If Only Respond to Mentions is enabled, mention the bot directly.

Discord bot is in the server but not responding

Confirm the Guild ID matches the Discord server ID.
Confirm the test channel is allowed or the allowed-channel list is empty.
Check required role IDs and blocked role IDs.
Make sure the Balchemy Discord application has permission to read and post in the channel.

Discord OAuth fails

Start a fresh Hub Discord verification flow instead of reusing an old link.
Confirm the callback URL and OAuth app settings match the current app flow.
Check that the Discord account you authorize is the one you intend to link.

MCP issues

Cannot connect MCP client

Verify the MCP endpoint format: https://api.balchemy.ai/mcp/<publicId>.
Use the publicId from the relevant Studio or Hub flow.
Confirm the key has not been revoked or rotated.
For Studio, create keys in the bot cockpit MCP tab.
For Hub, manage keys from Hub → Agents & Keys / agent detail.

Tool is missing from `tools/list`

Confirm the key scope is high enough.
Confirm you are using the correct Studio bot or Hub agent publicId.
Remember that the visible tool catalog is dynamic; do not rely on a static count.
If a runtime exposes a reduced tool set, use the tools returned by tools/list as the source of truth.

MCP action returns forbidden

The action may require trade or manage scope.
Manage-sensitive actions may require owner/claim or step-up style verification.
Trading actions can still be blocked by risk policy, wallet state, or execution checks.

Hub agent cannot trade

Both conditions must be true before a Hub agent can trade:

The agent has a key or token with trade scope.
The agent wallet has enough balance on the target chain, including gas/native token where required.

Also check policy/risk settings, setup state, and Hub logs for the specific rejection reason.

Hub agent issues

Agent onboarding fails

For wallet-based onboarding, verify the wallet signature is fresh and matches the expected address.
For walletless/provider onboarding, verify the provider token is valid and not expired.
Confirm you are using the correct onboarding flow for the agent type.
Check Hub logs or setup state for the exact failure.

Claim or ownership-sensitive action fails

Confirm you are signed in with the wallet or identity expected by the flow.
Start a fresh verification or step-up flow if the token expired.
Check whether the agent is already claimed or managed by another operator.
Use the Hub UI/API flow; do not edit database records to force ownership or wallet state.

Hub key cannot call a tool

Call tools/list with the same key to see visible tools.
Confirm the key belongs to the correct agent.
Confirm the key scope is high enough.
Rotate the key if it may be expired, revoked, or exposed.

Wallet and authentication issues

Wallet connect fails

Disable conflicting browser wallet extensions and try again.
Confirm the wallet extension is unlocked.
Confirm the wallet is on the intended chain/network.
If you reject a signature request, reconnect and sign a fresh nonce.
Try a clean browser profile if extension state appears corrupted.

Authentication issues

Disconnect and reconnect the wallet to sign a fresh nonce.
Clear stale site session data if the browser keeps an expired token.
Make sure the signing prompt is not hidden behind another wallet window.
Do not paste seed phrases or private keys into Balchemy or support channels.

Slow responses

Large knowledge bases can increase retrieval time.
Complex prompts that trigger many tools can take longer.
Network or provider issues can affect trading and research calls.
If only one bot is slow, review that bot's knowledge and configuration first.

Still stuck?

Check FAQ.
Review MCP Integration if the issue involves keys or tools.
Review Hub Overview for agent operations issues.
Review Studio Bot Cockpit for bot/channel issues.
Contact support with the bot or agent ID, the timestamp, and the visible error message. Do not include secrets, private keys, seed phrases, bearer tokens, or full API keys.

Security

FAQ

Edit this page on GitHub