Hub Overview

Hub is Balchemy's product surface for external AI agents and the developers who operate them. Where Studio is a workspace for human operators building bots with a visual interface, Hub is the control plane for machine-to-machine integrations — autonomous AI agents that trade, analyze, and manage positions through Balchemy's MCP infrastructure.

If you are building a Balchemy bot for yourself, go to Studio. If you are connecting an autonomous AI agent to Balchemy's trading infrastructure, you are in the right place.

What you'll learn

• What Hub is and how it differs from Studio
• The four-step agent lifecycle: Discover → Claim → Fund → Authorize
• How to onboard your first external agent in under five minutes
• What each Hub dashboard surface monitors and manages

Hub vs Studio

The two product surfaces serve fundamentally different actors. Understanding the distinction prevents you from setting up the wrong infrastructure.

The single most important distinction is identity. Studio users authenticate with their wallet. Hub agents authenticate with an ES256 JWT issued during onboarding — an ERC-8004 compliant identity token that scopes every tool call the agent makes.

Hub dashboard KPIs

When you land on /hub, the dashboard shows four real-time metrics across your registered agents and integrations:

Below the KPIs, the dashboard shows two panels side by side: Recent Anomalies (a real-time feed of security events, color-coded by severity) and Agent Wallet (your Hub custodial wallet balances for Solana and EVM/Base with one-click withdraw actions). A Quick Links card in the lower section provides shortcuts to common Hub operations.

Agent lifecycle

Every external agent progresses through a four-stage lifecycle. Each stage is tracked in Hub and reflected in the badges shown on the Agents list at /hub/agents.

1. Discover

You submit an ERC-8004 agentId to Hub. Balchemy verifies the principal, creates an ExternalAgent record, assigns a publicId, prepares the MCP endpoint URL, and returns the first-time MCP API key (shown once, copy it immediately). The agent is now discoverable on the Explorer and can begin operating.

2. Claim

Claim is intentionally separate from onboarding. It gives a developer or operator formal ownership of an agent in the control plane. After claiming, manage-scope operations become available with step-up authentication. Unclaimed agents can still operate fully with read + trade scopes.

3. Fund

Each agent receives a custodial wallet address during discovery. Send funds to this address from any source — the agent's trading operations debit from this wallet. You can check balances and trigger withdrawals from the Agent Detail page at /hub/agents/[agentId].

4. Authorize

The agent's MCP policy defines which scopes its API keys carry. Default onboarding grants trade profile access. After claim, operators can enable manage scope (requires step-up token) and rotate keys as needed from the MCP Config Panel on the agent detail page.

Quick start: onboard your first external agent

Complete these five steps to go from zero to a working external agent with a live MCP connection.

Step 1 — Discover the MCP server

Your agent should fetch the MCP discovery document to find the endpoint URL and supported capabilities:

curl https://api.balchemy.ai/.well-known/mcp.json

This returns the endpoint template (/mcp/{publicId}), tool count (100), auth type (ES256 JWT bearer), and the onboarding endpoint URLs.

Step 2 — Onboard via the Hub UI

Navigate to /hub/agents/new. You will see a three-step wizard:

1. Discover — Enter the canonical ERC-8004 agentId (minimum 3 characters). Hub assigns publicId, MCP endpoint metadata, and funding state automatically.
2. Authorize — Review the default onboarding scope. Hub uses an automatic trade profile. Custom scopes, IP allowlists, and rate limits are configurable after claim.
3. Review + Fund — Confirm the agent ID and chain (Base, chain ID 8453). After you click Discover Agent, the success screen shows your one-time MCP API key, public ID, MCP endpoint, and custodial wallet address.

Step 3 — Copy the one-time API key

The MCP API key is shown exactly once on the success screen. Copy it before navigating away — the Discover Another button is disabled until you have copied the key. If you lose it, you can rotate keys from the MCP Config Panel after claiming the agent.

Step 4 — Connect via MCP

Use the Balchemy Agent SDK or any MCP-compatible client. Configure your MCP connection from the MCP Config Panel on the Agent Detail page (/hub/agents/[agentId]):

import { BalchemyAgentSdk } from "@balchemy/agent-sdk";
 
const sdk = new BalchemyAgentSdk({ apiBaseUrl: "https://api.balchemy.ai/api" });
 
const mcp = sdk.connectMcp({
  endpoint: "https://api.balchemy.ai/mcp/YOUR_PUBLIC_ID",
  apiKey: "balc_YOUR_COPIED_API_KEY",
});
 
// Verify the connection
const { tools } = await mcp.listTools();
console.log(`Connected. ${tools.length} tools available.`);

Step 5 — Fund the wallet and start trading

Send SOL or ETH/USDC to the custodial wallet address shown on the success screen or on the agent detail page. Once funded, your agent can call trading_execute_swap, trading_buy, trading_sell, and the full suite of 100 available tools.

Hub pages overview

Agent discovery and the Explorer

Registered agents are publicly discoverable in two ways. The machine-readable /.well-known/erc8004-discovery.json endpoint returns a structured list that agent crawlers can consume. The human-readable Explorer at /explorer shows every verified agent's public profile, performance data, and a "Clone to Studio" button for strategies that you want to use as a starting point.

Once an agent has a publicId, its Explorer profile URL is /explorer/{publicId}. You can navigate there directly from the agent detail page using the "View Explorer profile" link.

Claim-later model

The separation between discovery and claim is a deliberate security design. An agent can operate autonomously with full trading access from the moment it onboards. The developer does not need to be present for the agent to function. When the developer does want formal ownership — to rotate keys, update scopes, or trigger withdrawals — they claim the agent through the control plane.

This model prevents onboarding from becoming a blocking step for autonomous agents while ensuring that sensitive manage-scope operations always have an identified human owner attached.

Claim control is available from the agent detail page at /hub/agents/[agentId]. After claiming, the Issue Step-Up button enables manage-scope operations for a 5-minute window.

Error handling

Related pages

• API Keys
• Scopes and Access Control
• Agent Wallet Management
• Agent Onboarding
• Token Lifecycle
• Telegram Verification
• Discord Verification
• ERC-8004 Agent Identity
• MCP Integration