Hub Logs
Hub logs show what happened around your 24/7 Web3 agents: authentication events, setup changes, key usage, MCP/API calls, trading requests, policy outcomes, and failures. Use them to verify an agent is operating as expected and to troubleshoot access, funding, or execution problems.
Use this page for Hub agents. For Studio bot channel activity, start from the Studio bot cockpit and the bot's platform, MCP, trading, and analytics tabs.
Where to find logs
- Open Hub → Logs.
- Filter by agent, action type, result, or time range.
- Open a row to inspect details.
- Copy a request or correlation ID if you need to investigate the same event with support or observability tooling.
You can also open logs from an agent detail page in Hub → Agents & Keys. Agent detail links should be treated as the trusted path for an agent-specific view.
What Hub logs can show
| Category | What to look for |
|---|---|
| Authentication | Sign-in, token, key, or step-up failures. |
| Setup | Agent registration, claim, funding, or configuration state changes. |
| MCP/API | Tool discovery, tool calls, invalid parameters, scope failures, and runtime errors. |
| Trading | Order requests, policy checks, approval steps, provider outcomes, and lifecycle events. |
| System | Rate limits, provider health, circuit-breaker state, and platform-side safeguards. |
Log visibility depends on the current product surface and your access. Sensitive key material, private keys, seed phrases, and full secrets should never appear in logs.
Useful fields
| Field | Meaning |
|---|---|
| Timestamp | When the event occurred. |
| Actor | User, agent, key, or system component associated with the event. |
| Action | The operation, such as a tool call, setup change, order request, or auth event. |
| Result | Whether the operation succeeded, failed, or completed partially. |
| Target | Agent, order, key, or configuration object affected by the event. |
| Error message | Human-readable failure detail when available. |
| Request ID | Identifier for a single API or MCP request. |
| Correlation ID | Identifier used to connect related service events when observability tooling is available. |
Use IDs from the UI when you contact support. Do not include bearer tokens, full MCP/API keys, seed phrases, private keys, or screenshots that expose secrets.
Troubleshooting with logs
Agent cannot call a tool
Check the failing MCP/API event and confirm:
- The key has the required scope.
- The agent is using the correct
publicId. - The tool is visible in
tools/listfor the same key. - The request arguments match the current tool schema.
If the failure is 403 Forbidden, scope or verification is usually the first thing to inspect. See Scopes and Access Control.
Agent cannot trade
Filter to the agent and look for recent trading or MCP failures. A failed trade can be caused by:
readscope being used for a trade action.- Missing funding or native gas token.
- Risk policy or channel policy rejection.
- Slippage or quote constraints.
- Provider, circuit-breaker, or order lifecycle state.
- Invalid tool arguments.
A trade-scoped key only allows trade attempts; it does not bypass wallet, policy, risk, or provider checks.
Agent returns unauthorized
Look for authentication or key events near the failure time. Common causes include:
- Revoked or rotated key.
- Expired identity token.
- Wrong
publicId. - Missing
Authorization: Bearer <key-or-token>header. - Step-up or claim verification required for a sensitive action.
Manage Hub agent keys from Hub → Agents & Keys and the agent detail flow.
Setup or claim action fails
Management-sensitive actions may require manage scope plus fresh step-up or claim-style verification. Use the Hub UI/API prompts for that agent. Do not edit database records to repair setup, key, scope, or wallet state.
API access
If your workflow exposes an audit/log API, use a session-authenticated request and filter narrowly by agent, action, or time range. Treat API output as operational data: store it securely, redact secrets, and avoid sharing raw payloads in support channels.
Example shape:
GET https://api.balchemy.ai/api/audit-logs?actor=<agent-or-user-id>&dateRange=7d&limit=100
Authorization: Bearer <session-token>Available filters can change as the product evolves. Prefer the Hub UI when you need the current set of supported filters.
Safe operating pattern
- Review failures after deploying or rotating an agent runtime.
- Check scope failures before changing wallet or policy settings.
- Compare the failing key's
tools/listoutput with the tool you expected to call. - Keep manage access out of unattended runtimes unless there is a specific need.
- Include request/correlation IDs in support requests, not secrets.