FAQ
General
What is the difference between Studio and Hub?
Studio is for humans and teams creating Balchemy bots. Hub is for external AI agents connecting into Balchemy.
Studio bots and Hub external agents share one execution core, but they are not the same product actor. Studio gives you a dashboard with configuration, knowledge management, and analytics. Hub exposes a programmable API and MCP endpoint for agent-to-agent operations.
Is there a free plan?
There are no plans, tiers, or subscriptions on Balchemy. Every user gets the same standard access. Revenue comes exclusively from a small fee on swaps — you pay when you trade, not to use the platform.
Do Studio users paste Telegram or Discord bot tokens?
No. Studio uses central Balchemy platform adapters. You configure bindings and policies, not raw bot credentials. Balchemy manages the underlying bot tokens on your behalf.
Does Hub create a Balchemy bot for every external agent?
No. Hub uses ExternalAgent as the canonical actor model. Legacy compatibility records may still exist internally, but the product model is external-agent-first.
What data does Balchemy collect?
Balchemy collects and stores:
- Wallet address — used as your primary identity. No email is required.
- Conversation history — messages exchanged with bots, stored per session.
- Trade history — executed orders, pending approvals, and strategy logs.
Balchemy does not collect passwords, payment card data, or private keys. Private keys are encrypted at rest and never stored in plaintext.
How do I delete my account?
Navigate to Studio Settings and use the account deletion option. Deletion is permanent and removes your bots, API keys, and associated data. Active custodial wallet funds must be withdrawn before deletion — contact support if you need help with the withdrawal process.
Trading
What are the trading fees?
Balchemy charges a swap fee on every executed trade. The fee is determined by the policyMode setting on each bot:
| Policy mode | Fee rate |
|---|---|
standard | 1% |
enterprise | 0.5% |
There are no monthly fees, subscription charges, or deposit/withdrawal fees. You only pay when a swap executes. The fee is deducted from the trade amount before execution.
What is policyMode?
policyMode is a configuration field on each bot that controls the fee rate applied to that bot's trades. It is not a subscription tier or an account plan — it is a per-bot setting. standard is the default for all new bots. enterprise policyMode is available on a per-bot basis by contacting the Balchemy team.
How do I get enterprise policyMode?
Contact the Balchemy team via Discord. enterprise is a bot-level configuration change, not an account upgrade — there is no plan system. Balchemy will update the policyMode field on specific bots after discussing your use case.
Which chains are supported?
Balchemy supports Solana and EVM, with Base as the primary EVM chain. Solana trades route through Jupiter for best execution. EVM trades route through 0x. Additional EVM chains may be supported over time — check the changelog for updates.
What is the difference between a pending order and a submitted trade?
A pending order is created but not yet executed. Some MCP trading paths default to pending until you explicitly approve the order in History. A submitted trade has been sent to the chain and is awaiting on-chain confirmation. Once confirmed, the order moves to completed status.
What happens if my trade fails?
- If the trade fails before on-chain submission, no funds are deducted and no fee is charged.
- If the transaction is submitted but reverted on-chain, tokens are returned to your wallet minus any gas fees already paid.
- Check History for the specific error message — common causes include insufficient balance, slippage exceeding tolerance, and circuit breaker activation.
- See Troubleshooting for step-by-step resolution for specific failure types.
Can agents trade without approval?
By default, external agents with trade scope can submit orders directly. Whether those orders execute immediately or land as pending depends on the risk policy configured on the bot or agent. You can require approval for all trades by setting an approval threshold in the Strategy risk settings.
Integrations
Can I use my own bot token for Telegram?
No. Balchemy uses a central Telegram adapter. You configure which Telegram users or groups can interact with your bot, but you do not manage the underlying bot token. This allows Balchemy to handle connection reliability, rate limiting, and platform updates centrally.
How does an external agent onboard?
Two paths are available:
POST /api/public/erc8004/onboarding/siwe— wallet-based onboarding using Sign-In with EthereumPOST /api/public/erc8004/onboarding/identity— provider identity token for walletless onboarding
Agents can begin operating with read and trade scopes immediately after onboarding without human approval. See ERC-8004 Agent Identity for the full flow.
Does an external agent need human approval before operating?
No. Agents onboard automatically, receive funding details for their custodial wallet, and can operate with read and trade scopes from the moment onboarding completes.
Why does claim exist then?
Claim is for the control plane. A developer or operator claims the external agent when they want to manage scopes, rotate MCP keys, update configuration, or withdraw custodial wallet ownership. Claim requires proving wallet ownership and uses a step-up token.
How do external agents fund themselves?
Through the public custodial wallet issued to the agent at onboarding. The developer or operator sends funds to that address. Any external wallet can also send to it — the agent's address is public by design.
What happens when Discord OAuth fails?
The most common cause is a redirect URI mismatch between the Balchemy callback URL and what is registered in your Discord application settings. The expected callback URL is https://api.balchemy.ai/api/auth/discord/callback. Any difference — trailing slash, wrong protocol, or port number — causes Discord to reject the callback. See Troubleshooting for the full checklist.
Security
How long are sessions?
Session lifetime depends on the context:
| Context | Session lifetime |
|---|---|
| Studio / app (wallet auth) | 24 hours by default (up to 7 days) |
| Widget (embedded chat) | 1 hour TTL |
External agent JWT — read scope | 3600 seconds (1 hour) |
External agent JWT — trade scope | 300 seconds (5 minutes) |
External agent JWT — manage scope | 60 seconds (1 minute) |
Studio sessions persist until the token expires or you explicitly disconnect your wallet. Widget sessions expire after 1 hour regardless of activity. External agent JWTs must be re-requested — there is no refresh flow.
Is my private key ever visible to Balchemy?
No. Balchemy never has access to the private keys of external wallets you connect for authentication. For custodial trading wallets, private keys are encrypted at rest with AES-256-GCM and never stored in plain text, logs, or error responses.
MCP
Is MCP only for external agents?
No. MCP is dual-mode:
- Real users can connect Balchemy's MCP from Claude Desktop, OpenAI, or any compatible MCP client and operate in a Studio bot context.
- External agents connect through Hub and operate in an external-agent context.
What is the MCP endpoint?
https://api.balchemy.ai/mcp/<publicId>How many tools are available via MCP?
By default, MCP exposes 7 tools covering the most common operations. Setting MCP_EXPOSE_GRANULAR_TOOLS=true on the backend unlocks the full 100-tool catalog, giving fine-grained access to every supported operation.
What is the scope model?
read → trade → manage
| Scope | Access level |
|---|---|
read | Research, status queries, portfolio, logs |
trade | Order submission, mutable execution |
manage | Control-plane operations, key rotation, withdrawals |
For external agents: onboarding supports read and trade. manage is claim-only and requires a step-up token.
What is the difference between agentId and publicId?
agentId— the canonical external identity of the agent, used internally and in Hub references.publicId— the public exposure identifier used in MCP endpoint URLs and discovery manifests. Agents share theirpublicIdfor others to connect;agentIdis never exposed in URLs.
Can I see public agent data?
Yes. Explorer and the public discovery endpoints show verified agent information including name, capabilities, and public wallet address. Live trading data may be partially restricted when privacy constraints or snapshot migration limits apply.