API Endpoints

This page is a route-family map, not a full OpenAPI reference. It shows the major Balchemy API surfaces and how they relate to Hub Web3 agents, MCP, trading, discovery, and legacy compatibility routes.

For exact request bodies, use the current product flow, tools/list schemas, or linked domain pages.

Base URL

Most REST routes live under /api/nest/. MCP routes live under /mcp/. Public discovery routes live under /.well-known/ and selected /api/public/ paths.

Authentication methods

Balchemy uses different credentials depending on the caller and surface.

CSRF for session-authenticated mutation

Session-authenticated POST, PATCH, PUT, and DELETE requests require a CSRF token.

GET /api/nest/auth/csrf

Include the returned token on mutating requests:

X-CSRF-Token: <csrf-token>

MCP key calls and agent identity-token calls use bearer authentication and follow their own scope and replay protections.

Auth routes

Retired compatibility routes

Studio-era bot management, bot chat, bot-scoped MCP, embedded chat, and conversational Telegram/Discord setup routes are intentionally omitted from the public route map. They may remain internally during migration, but they are not new integration targets. Use Hub agent routes, Hub Signal Sources, and Hub MCP/API access for active product work.

Trading routes

Trading routes proxy through the backend to the trading engine and are fund-sensitive. Use authorized product flows and preserve idempotency for on-chain side effects.

Commands and approvals

Positions and orders

EVM trading and wallet routes

Solana wallet routes

Do not repair wallet/key state through raw database edits.

Trading configuration

Hub agent routes

Hub routes are for 24/7 Web3 agent onboarding, funding state, scoped access, logs, and ownership-sensitive operations.

Public ERC-8004 onboarding

Public agent directory and cards

Agent wallet and funding state

Withdrawal and ownership-sensitive actions can require manage scope, claim verification, and step-up.

Ownership-sensitive agent operations

Use Hub → Agents & Keys and the agent detail flow as the source of truth for key and setup operations.

MCP routes

MCP is a protocol surface over Balchemy's execution core. It does not create a separate tool universe.

Use tools/list with the current key or token before calling tools. Visible tools depend on scope, principal context, registry state, and environment configuration.

Discovery routes

These routes are readable by clients that need discovery metadata.

Do not rely on a fixed tool count in discovery metadata. Use tools/list for the current credential.

Error envelopes

REST API callers should treat canonical success: false envelopes as failures even when the HTTP transport status is 200. Canonical failures include request metadata when available:

{
  "success": false,
  "error": {
    "code": "PROVIDER_UNAVAILABLE",
    "message": "Provider unavailable",
    "details": {
      "retryable": true
    }
  },
  "meta": {
    "requestId": "req_123",
    "correlationId": "corr_456"
  }
}

Some legacy routes can still return statusCode, message, and error fields. Client code should preserve error details and metadata instead of treating an empty or degraded provider response as successful zero data.

MCP errors follow JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "error": {
    "code": -32603,
    "message": "Tool execution failed"
  }
}

Common statuses:

Idempotency

Mutating trading routes that can create on-chain side effects require an idempotency key.

X-Idempotency-Key: <uuid-v4>

Use one fresh key per unique operation. Do not retry a broadcast transaction unless the authorized execution layer reports a reconciliation-safe retry state.

Notes

• publicId identifies the public MCP/discovery target and differs from internal database IDs.
• agentId identifies a Hub Web3 agent.
• Legacy bot routes and Hub agent routes share the same execution core but use separate principal and key models.
• Trading /:userId routes validate the authenticated session; they are not admin routes.
• No API route should imply plan, tier, subscription, or enterprise-only access.

Related pages

• MCP Integration
• ERC-8004 Agent Identity
• Agent Keys
• Trading Fees
• Security