Tool Catalog

Balchemy tools are server-executed capabilities used by Studio bots, Hub agents, and MCP-compatible clients. The catalog is dynamic: the exact tools visible to a caller depend on runtime registry state, environment configuration, principal context, and key scope.

Do not rely on a hardcoded tool count. Use MCP tools/list with the current key as the source of truth.

Where tools appear

Surface	Tool context
Studio bot chat	Tools can be called by the bot pipeline when a user asks for research, portfolio, trading, or configuration help.
Studio MCP	A bot-scoped MCP key exposes tools for one Studio bot.
Hub MCP/API	An agent-level key exposes tools for one 24/7 Web3 agent.
Internal AI pipeline	The same registry can be adapted for model tool/function calling.

MCP is a protocol surface over the same execution core. It does not create a separate tool universe.

Tool discovery

Use tools/list with the same key that will call tools:

POST /mcp/<publicId>
Authorization: Bearer <mcp-key>
Content-Type: application/json
 
{
  "jsonrpc": "2.0",
  "id": "tools-list-1",
  "method": "tools/list"
}

The response includes the tools visible to that caller, with names, descriptions, and input schemas.

A tool can be hidden because:

The key has insufficient scope.
The principal is a Studio bot instead of a Hub agent, or the other way around.
The environment exposes a smaller MCP surface.
Runtime configuration has disabled a category.
The tool registry changed after a deploy.

Scope model

Every tool declares the minimum scope required to call it.

Scope	Meaning	Examples
`read`	Observe and retrieve state.	Status, portfolio reads, research, logs, market data.
`trade`	Perform fund-sensitive trade actions allowed by policy.	Submit orders, approve/cancel eligible orders, update trading defaults where allowed.
`manage`	Sensitive management actions.	Key rotation, scope changes, ownership/claim-sensitive operations.

Scopes are permissions, not pricing tiers. A caller with read scope should not see or call trade tools. A trading runtime should not receive manage scope unless it truly needs management access.

Common tool families

The exact names are runtime-driven, but tools generally fall into these families:

Family	Typical purpose	Common scope
AI/chat orchestration	Ask a bot, route a user message, or execute a high-level agent instruction.	`read` or `trade` depending on side effects.
Research and market data	Token search, quotes, prices, social or market context, risk signals.	`read`
Portfolio and status	Wallet balances, positions, open orders, runtime health.	`read`
Trading execution	Swap planning, swap submission, order approval, order cancellation.	`trade`
Risk and security checks	Pre-trade reports, contract checks, token safety signals.	`read`
Strategy/configuration	Trading defaults, risk policy, strategy state.	`read` or `trade` depending on mutation.
Wallet operations	Wallet listing, setup state, authorized wallet flows.	`read`, `trade`, or `manage` depending on action.
Key and agent management	Key rotation, scope changes, claim-sensitive operations.	`manage`

If a tool can move funds, submit transactions, change permissions, or alter agent runtime state, expect it to require more than read scope.

Studio bot tools vs Hub agent tools

Studio bot context

Studio bot tools run in the context of one Balchemy bot. Use this path when an operator wants an MCP-compatible client to interact with a specific bot's knowledge, configuration, trading workflow, or logs.

Create Studio MCP keys from the bot cockpit MCP tab.

Hub agent context

Hub agent tools run in the context of one always-on Web3 agent. Use this path when a runtime needs identity, funding, scoped access, logs, monitoring, and key rotation from Hub.

Create and rotate Hub keys from Hub → Agents & Keys and the agent detail flow.

Trading tool safety

Trading tools do not bypass Balchemy's safety path. Before execution, a request can be checked for:

Authentication and key status.
Scope.
Bot or agent setup state.
Wallet availability and balance.
Risk policy and channel policy.
Slippage and quote constraints.
Provider or circuit-breaker state.
Audit logging and reconciliation metadata.

A trade-capable key is not a guarantee that every requested trade will execute.

Tool response shape

MCP tool calls return JSON-RPC responses. A successful response usually contains text content that may itself be a JSON string or human-readable text, depending on the tool contract.

{
  "jsonrpc": "2.0",
  "id": "call-1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{...}"
      }
    ],
    "isError": false
  }
}

When a tool fails, the response can set isError or return a JSON-RPC error envelope. Use the tool's schema and error message instead of assuming all tools have the same payload shape.

Calling a tool

POST /mcp/<publicId>
Authorization: Bearer <mcp-key>
Content-Type: application/json
 
{
  "jsonrpc": "2.0",
  "id": "call-1",
  "method": "tools/call",
  "params": {
    "name": "ask_bot",
    "arguments": {
      "message": "Summarize my open positions and major risks.",
      "chat_id": "session-abc123"
    }
  }
}

Use the arguments shown by tools/list for the current key. Tool schemas can change as the runtime changes.

Common errors

Error	Meaning	What to check
`401 Unauthorized`	Missing, expired, or revoked credential.	Key/token, header format, correct `publicId`.
`403 Forbidden`	Scope or management verification is insufficient.	Key scope, step-up/claim requirements, policy restrictions.
`404 Not Found`	The target public ID is unknown or inactive.	Copy `publicId` from Studio or Hub again.
`429 Too Many Requests`	Rate limit exceeded.	Reduce request rate or retry after the window.
Invalid params	Tool arguments do not match schema.	Re-run `tools/list` and compare the input schema.
Tool execution error	The tool failed during execution.	Check tool-specific message, logs, wallet state, and provider status.

Safe operating pattern

Start with a read key.
Call tools/list and inspect the visible schema.
Test a read-only call.
Add trade only for the runtime that should submit trade actions.
Keep manage separate from unattended trading runtimes.
Rotate keys after deployments, operator changes, or suspected exposure.
Monitor Studio or Hub logs after enabling automation.

Glossary

Error Codes

Edit this page on GitHub