Errors & Tiers
How failures surface to an agent, and which tier each tool needs.
MCP tool errors
A failed tools/call returns a CallToolResult with isError: true, a text reason, and a structured error body. The two an agent should handle explicitly:
Tier too low — the call resolved to a tier above your key’s:
{ "error": "tier_insufficient", "tool": "query_token_bundles", "requiredTier": "Layer 3", "yourTier": "Layer 2" }Missing / invalid key — no resolvable Authorization: Bearer <key> on the HTTP transport:
missing or invalid API key; send Authorization: Bearer <key>A tool that can’t find its subject (unknown mint/wallet, or no data) returns a successful result with an empty or null body — not an error. Check the payload, not just isError.
Tool tiers
| Tier | Tools |
|---|---|
| Free | query_buyer_quality, query_token_bundle_summary, search_tokens, resolve_token_identifier |
| Layer 2 | Wallet intelligence — query_wallet_quality, query_wallet_performance, query_wallet_trades, query_wallet_positions, query_wallet_xray(_lite), query_wallet_provenance, query_similar_wallets, query_leaderboard, query_holder_breakdown, query_token_holder_pnl — plus wallet_overview |
| Layer 3 | Everything else — bundles, wash trades, funding abuse, the full coordination/detection surface, and the token_deep_dive / token_coordination_report / wallet_network_report composites |
On the local stdio transport, tier gating is bypassed (it’s trusted, self-hosted). Tiers apply on the hosted HTTP endpoint. See the Tool Catalog for the per-tool tier and Tiers & Rate Limits for what each plan includes.
REST status codes
If you call the REST API directly instead of through MCP, errors use the standard envelope {"error": "...", "code": <int>} with HTTP 400 / 401 / 403 / 404 / 429 / 500 / 503. Full table on Errors & Status Codes.