Troubleshooting

Common issues and how to resolve them. Start with the Hub agent, Signal Source, MCP key, wallet, or order state involved in the failure.

Hub verification issues

Telegram verification code not received

Confirm you are messaging the official Balchemy verifier 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 messages from the verifier.
Restart the verification flow from Hub instead of reusing an old link.

Trading issues

Trading not executing

Verify trading is enabled for the Hub 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.

Retired Studio and embedded chat issues

Studio bot creation, Studio bot cockpit, Studio knowledge/training, embedded chat, and Studio bot-scoped MCP are retired as active product paths.

If you reached an old Studio or embedded chat URL:

Use Hub for active agent operations.
Use Signal Sources for Telegram/Discord token-signal ingestion and attribution.
Use Hub agent MCP/API keys instead of Studio bot-scoped keys.
Do not build new integrations against retired embedded-chat or Studio bot routes.

Signal Source issues

Telegram source signals are not appearing

Confirm the Telegram account or source is verified in Hub.
Confirm the source is enabled as a Signal Source.
Check allowed, blocked, or trusted submitter rules.
Confirm the message contains a supported token, mint, contract, or CA signal.
Review Hub activity logs for source health or ingestion errors.

Discord source signals are not appearing

Confirm the Guild ID matches the Discord server ID.
Confirm the channel is authorized as a Signal Source.
Check allowed, blocked, or trusted submitter rules.
Make sure the Balchemy Discord application has permission to read the source channel.
Review Hub activity logs for source health or ingestion errors.

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 Hub flow.
Confirm the key has not been revoked or rotated.
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 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 agent is slow, review that agent's rules, memory/working set, source health, and provider/degradation status first.

Still stuck?

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

Security

FAQ

Edit this page on GitHub