Scopes and Access Control
Scopes control what a Hub agent or MCP/API key can do. They are permissions, not product plans or paid tiers.
Use the smallest scope that works, especially for unattended 24/7 agent runtimes.
Scope hierarchy
read < trade < manage| Scope | Meaning | Use it for |
|---|---|---|
read | Observe and retrieve state. | Status, logs, portfolio, research, and monitoring. |
trade | Perform trade actions allowed by policy. | Order submission, approved mutable trade workflows, strategy execution. |
manage | Perform sensitive management actions. | Key rotation, scope/configuration changes, ownership-sensitive actions. |
A trade key includes read capabilities. A manage key includes trade and read capabilities. That does not mean every request will succeed; policy, wallet, setup, and risk checks still apply.
How scopes are enforced
When a caller uses MCP/API, Balchemy checks the key or token against the required scope for the requested action. If the scope is too low, the request is rejected.
Examples:
| Attempt | Expected result |
|---|---|
Read portfolio with read key | Allowed if the principal is valid. |
Submit trade with read key | Rejected for insufficient scope. |
Submit trade with trade key | Scope allowed, then policy/risk/wallet checks run. |
Rotate key with trade key | Rejected; management action. |
Rotate key with manage key | May still require step-up or ownership verification. |
Recommended operating pattern
- Start with
readscope. - Connect the runtime and call
tools/list. - Test a read-only tool.
- Create a separate
tradekey only for the runtime that should place orders. - Keep
managekeys out of unattended runtimes. - Rotate or revoke keys when deployments, operators, or environments change.
When to use read
Use read for:
- Monitoring dashboards.
- Portfolio/status checks.
- Research-only integrations.
- Debugging connectivity.
- Alerting or reporting systems.
A read key should not be able to submit trades or mutate agent settings.
When to use trade
Use trade for an agent runtime that is expected to place or manage trades.
Before enabling live trading:
- Confirm wallet funding and gas/native token availability.
- Confirm risk policy and channel policy expectations.
- Test the runtime with read-only calls.
- Start with small amounts.
- Monitor Hub logs after deployment.
A trade key is fund-sensitive. Treat it as a production secret.
When to use manage
Use manage only for tightly controlled operator or maintenance flows.
Management actions can include:
- Creating, rotating, or revoking keys.
- Changing scopes.
- Updating sensitive configuration.
- Ownership, claim, or setup-sensitive actions.
Management actions can require step-up or ownership verification. Do not put a manage key into a long-running autonomous trading runtime unless there is a specific, justified need.
Tool visibility
The MCP tool catalog is dynamic. A key only sees the tools available to its principal and scope.
Use MCP tools/list with the current key:
{
"jsonrpc": "2.0",
"id": "tools-list-1",
"method": "tools/list"
}Do not rely on a static tool count or a stale documentation list.
Studio and Hub keys
| Key type | Scope applies to | Managed from |
|---|---|---|
| Studio bot MCP key | One Studio bot context. | Studio bot cockpit MCP tab. |
| Hub agent key | One 24/7 Web3 agent context. | Hub → Agents & Keys / agent detail. |
If a key cannot call the tool you expect, first confirm whether it is a Studio bot key or a Hub agent key.
Common issues
A trade tool is missing.
The key may be read scoped or the runtime may expose a reduced tool set. Call tools/list with the same key.
A trade request returns forbidden. The scope may be too low, or the action may be blocked by policy/risk checks.
A manage action fails even with a manage key. The action may require step-up, claim, or another ownership-sensitive verification.
I want to downgrade access. Create a new lower-scope key, update the runtime, verify it works, then revoke the old higher-scope key.