Agent Onboarding
Hub onboarding registers a 24/7 Web3 agent so it can use Balchemy with identity, funding, scoped MCP/API access, logs, and monitoring.
Use Hub when the actor is an always-on agent runtime. If you are creating a Telegram, Discord, or web-widget trading bot for a community, use Studio instead.
What onboarding gives you
A completed Hub onboarding flow can produce:
- An agent record visible in Hub → Agents & Keys.
- A
publicIdfor MCP/API connection. - A one-time MCP/API key.
- A setup state for funding and trading readiness.
- Agent wallet information where the agent will trade.
- Logs for tool calls, setup errors, and access failures.
Copy one-time keys immediately. Full secrets are not shown again.
Choose an onboarding path
| Path | Use it when |
|---|---|
| Hub UI | You are manually registering and operating an agent from the app. |
| CLI or runtime setup | Your agent runtime has a supported Balchemy setup flow and should connect itself. |
| ERC-8004 / identity API | You need standards-based or programmatic onboarding for a Web3 agent. |
Regardless of path, the operating model is the same: register the agent, secure the key, fund only what the agent needs, assign the minimum scope, connect MCP/API, and monitor logs.
Hub UI flow
- Open Hub → Agents & Keys.
- Create or select an agent.
- Complete the setup information shown by the UI.
- Copy the one-time key and endpoint.
- Store the key in a secrets manager or secure runtime environment.
- Fund the agent wallet only if the agent should trade.
- Call MCP
tools/listto verify visible capabilities. - Start with read-only calls before enabling trade actions.
- Watch Hub logs after the agent goes live.
Do not use raw database edits to create, repair, fund, or reset an agent.
Programmatic onboarding
Programmatic flows exist for agent runtimes that need to onboard through identity or ERC-8004-compatible paths.
Common patterns include:
- Wallet-based onboarding, where the agent or owner proves control of an EVM wallet.
- Walletless or provider-verified onboarding, where a trusted provider verifies the agent identity.
- Discovery-based setup, where the runtime reads published well-known metadata before connecting.
See ERC-8004 Agent Identity for protocol details. Keep public docs focused on the operator workflow; do not expose private provider secrets, signing keys, or backend environment values.
Connect with MCP/API
The MCP endpoint format is:
POST https://api.balchemy.ai/mcp/<publicId>
Authorization: Bearer <agent-key>
Content-Type: application/jsonUse the publicId and key shown by the Hub setup flow. Do not guess IDs from URLs or logs.
Verify with tools/list:
{
"jsonrpc": "2.0",
"id": "tools-list-1",
"method": "tools/list"
}The visible tool list depends on the key scope, principal context, environment, and runtime registry state.
Scope selection
Choose the smallest scope that works.
| Scope | Use it for |
|---|---|
read | Status, logs, portfolio, research, and monitoring. |
trade | Trading actions allowed by policy and risk checks. |
manage | Sensitive management actions such as key rotation or configuration changes. |
Start with read to verify connectivity. Add trade only for the runtime that should place orders. Keep manage out of unattended runtimes unless absolutely required.
Funding and trading readiness
An agent that trades needs funds available through its authorized agent wallet flow.
Safe operating rules:
- Fund only the amount intended for active trading.
- Keep staging and production funding separate.
- Confirm balances before enabling trade automation.
- Review policy and risk settings before live execution.
- Use Hub logs and order history to troubleshoot failures.
- Never repair wallet or key state through raw database edits.
A trade-scoped key does not guarantee every trade will execute. Orders still pass through wallet, balance, policy, risk, slippage, provider, and execution checks.
Claim and ownership-sensitive actions
Some management actions can require owner/claim or step-up style verification. Examples include rotating sensitive keys, changing scopes, or making ownership-sensitive configuration changes.
Use the Hub UI/API flow for those actions. Do not bypass it by editing database records or reusing old verification tokens.
Common issues
The key cannot call a tool.
Call tools/list with the same key. The key may have too low a scope, point at the wrong publicId, or belong to a different agent.
The agent cannot trade. Check scope, wallet funding, setup state, policy/risk settings, and Hub logs. The most common causes are read-only keys, insufficient balance, missing gas/native token, or policy rejection.
I lost the one-time key. Create or rotate a new key from Hub → Agents & Keys / agent detail, then update the agent runtime. Revoke the old key if it may still exist somewhere.
I expected this key to control a Studio bot. Hub keys are agent-level. For a Studio bot, use the bot cockpit MCP tab.