Troubleshooting

Common issues and how to resolve them. Use the category headings to jump to your area.

Bot Issues

Bot not responding in Telegram or Discord

Verify the bot is active in the cockpit Overview tab.
Check that platform bindings are configured in the Platforms section.
Confirm access mode and allowed usernames/channels are set correctly.
Studio uses central Balchemy platform adapters — you do not need to provide your own bot tokens.

Bot gives irrelevant answers

Add or update Knowledge with more specific content for your use case.
Use Q&A pairs for questions that need precise, fixed answers.
Check that uploaded documents are relevant and current — outdated knowledge degrades response quality.
Review the bot's personality prompt in Config and ensure it does not conflict with the Knowledge content.

Telegram OTP not received

Confirm you are messaging @BalchemyBot — the official bot handle.
Wait at least 60 seconds before requesting a new code; delivery can be delayed on Telegram's network.
Check that your Telegram account is not set to block messages from bots.
If the problem persists, unlink and re-link your Telegram account in Studio Settings.

DCA strategy not executing

Verify the wallet connected to the bot is funded with sufficient balance for the configured DCA amount plus gas fees.
Check whether the strategy is in a paused state — open the Strategy section in the bot cockpit and confirm it is active.
Review the Risk limits: the DCA order may be blocked because it exceeds a configured max trade size or daily loss threshold.
Check History for any failed orders — error messages there identify the specific blocking condition.

Tip: DCA strategies require the wallet to hold enough of the source token for each interval plus a buffer for Solana transaction fees (SOL) or EVM gas. Underfunded wallets cause silent skips, not error alerts.

Trading Issues

Trading not executing

Verify trading is enabled in Strategy settings.
Check Risk limits — the trade may exceed configured thresholds.
Review History for pending orders that need your approval before execution.
Confirm the wallet is connected and funded.

Solana trade pending

Some MCP trading paths create pending orders by default that require explicit approval.
Open History, locate the pending order, and approve it.
Verify the wallet has sufficient SOL balance including transaction fees — low SOL causes pending trades to stall.

EVM trade failing

Confirm the wallet has sufficient token balance on the target chain.
Base is the primary EVM chain — verify you are targeting the correct network in Strategy settings.
Check that gas availability is adequate; trades fail silently when gas estimation fails.
Review pre-trade security output in History for any flagged conditions that blocked execution.

What happens if my trade fails?

If a trade fails after submission but before on-chain confirmation, funds are not deducted.
If a transaction is reverted on-chain, tokens are returned to your wallet minus any gas fees paid.
Check History for the specific error. Common causes: insufficient balance, slippage exceeded, circuit breaker triggered.
See the FAQ for more on trade failure scenarios.

Integration Issues

Verify the domain is in the widget's allowed domains list (Studio bot cockpit → Widget → Allowed Domains).
Check strict mode — if enabled, only listed domains can initialize the widget.

Confirm the embed script URL is correct:

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

Check the browser console for loading errors.

CORS errors in the browser console indicate the request origin does not match the widget's domain allowlist.

Open the bot cockpit in Studio and navigate to the Widget section.
Add your exact domain (including protocol, e.g. https://yoursite.com) to the Allowed Domains list.
Do not use wildcard entries in strict mode — each domain must be listed explicitly.
Clear the browser cache and reload after saving — CORS headers are cached by browsers.

Warning: If the widget loads on localhost during development, add http://localhost:3000 (or your dev port) as a separate allowed domain entry. Remove it before going to production.

Verify the bot is active and responding in Studio's built-in chat.
Check that the widget backend is reachable — use curl https://api.balchemy.ai/health to confirm the API is up.
Review widget configuration in the cockpit Widget section for any misconfigured fields.

Discord OAuth fails

Confirm that the redirect URI registered in your Discord application settings exactly matches what Balchemy expects: https://api.balchemy.ai/api/auth/discord/callback.
Any mismatch — trailing slash, http vs https, or a port number — causes Discord to reject the callback.
Verify the Discord application has the identify and email OAuth2 scopes enabled.
If you recently changed the redirect URI in Discord, allow a few minutes for the change to propagate.

API key not working

Confirm the key has the correct scope for the operation you are attempting. Read-only keys cannot submit trades.
Check the key expiry — API keys do not refresh automatically. Rotate the key in Studio Settings if it has expired.
Verify the key is being sent in the correct header format: Authorization: Bearer <key> or X-API-Key: <key> depending on the endpoint.
Revoked keys return 401 Unauthorized. Rotate a new key in Studio Settings.

Connection Issues

Wallet connect fails

Browser extension conflicts are the most common cause. Disable all wallet extensions except the one you want to use, then refresh.
Confirm the wallet extension is unlocked and set to the correct network (Solana mainnet or EVM Base mainnet).
Network mismatch between your wallet and Balchemy's expected chain causes connection rejection with no clear error — check the network selector in your wallet extension.
Try a different browser or incognito window to rule out extension state corruption.

Authentication issues

Clear your browser session and cookies for app.balchemy.ai, then reconnect your wallet.
JWT tokens expire — if you see TOKEN_EXPIRED, disconnect and re-authenticate by signing a new nonce.
For wallet auth: ensure the wallet extension is connected and the signing prompt is not hidden behind another window.

Slow responses

Check if the LLM model is configured correctly in the bot's Config section.
Large knowledge bases increase retrieval time — consider pruning irrelevant documents.
Complex prompts that invoke many tools take longer to process; simplify the system prompt if latency is a concern.

MCP Issues

Cannot connect MCP client

Verify the MCP endpoint URL: https://api.balchemy.ai/mcp/<publicId>
Check that MCP keys are valid and have not been revoked. Rotate if needed from the bot's MCP section.
Confirm the bot or agent has MCP enabled in its settings.
For Studio: create MCP keys in the bot's MCP section.
For Hub: keys are issued during onboarding or through the control plane API.

MCP connection drops

MCP uses Server-Sent Events (SSE) for streaming. Connections can drop due to network timeouts or proxy configurations.

Your MCP client should implement automatic reconnection — most Claude and OpenAI MCP clients do this by default.
If connections drop consistently after the same interval, a proxy or load balancer between you and the API may be imposing a timeout. Configure the proxy to allow longer-lived SSE connections (disable request timeout or set it to 5+ minutes).
Check your MCP client's timeout configuration — the default SSE reconnection delay is typically a few seconds.

MCP actions failing

Check scope — the action may require a higher scope level than your current token holds.
manage-level actions require a step-up token. Request one at POST /api/nest/bots/:botId/mcp/step-up.
Verify the tool name and parameter schema match what the endpoint expects — check the tool list at GET /.well-known/mcp.json.
Review MCP logs in the bot's cockpit for the specific error returned by the tool handler.

Agent cannot trade

Two conditions must both be true before an agent can execute a trade:

The agent's JWT must have trade scope (granted during onboarding by default).
The agent's custodial wallet must be funded with enough balance on the target chain plus gas.

Confirm scope by inspecting the JWT claims or checking the Hub control plane.
Check the wallet balance in Hub or directly on-chain using the public address.
If the agent was onboarded with read-only scope, it cannot trade without re-onboarding with the correct scope.

Hub External Agent Issues

Onboarding fails

SIWE path: verify the wallet signature is valid and the nonce is fresh (nonces expire).
Walletless path: verify the provider identity token is valid and has not expired.
Check that the discovery endpoints return expected data:
- GET /.well-known/erc8004-discovery.json
- GET /.well-known/erc8004-onboarding.json

Claim not working

Claim requires the developer or operator to prove wallet ownership through a signature.
The agent must exist in Hub and must not already be claimed by another operator.
Ensure you are signing with the wallet address that matches the agent's registered identity.

General

Still stuck?

Check the FAQ — most common questions are answered there.
Review the API Reference for endpoint-level details and error codes.
Join the Balchemy Discord community and post in the #support channel. Include your bot ID (not your API key), the error message, and what you were doing when it occurred.

Security

FAQ

Edit this page on GitHub