API Endpoints

This page is a route-family map, not a full OpenAPI dump. It covers every major surface of the Balchemy REST API organized by domain. For detailed parameter schemas, see the linked domain pages.

Base URLs

Most routes live under /api/nest/. MCP routes are under /mcp/ — intentionally outside the /api namespace.

Authentication methods

Balchemy uses three authentication mechanisms depending on the caller type.

SIWE / SIWS session (Studio users)

Human operators authenticate with a wallet signature. Solana uses SIWS (Sign In With Solana), EVM uses SIWE (EIP-4361).

The session token is returned on login and sent as a Bearer token on all subsequent requests. Session tokens expire and can be refreshed.

CSRF flow

All mutating session-authenticated requests require a CSRF token. Fetch one before your first POST:

GET /api/nest/auth/csrf

Response:

{
  "csrfToken": "abc123..."
}

Include it on every POST, PATCH, PUT, DELETE:

X-CSRF-Token: abc123...

If the CSRF token is missing or invalid, the server returns 403 Forbidden.

API key (MCP and external integrations)

MCP API keys are created per-bot and sent as a Bearer token:

Authorization: Bearer <mcp-api-key>

Agent JWT (external agents)

External agents receive an ES256 identity access token during ERC-8004 onboarding. Use it as a Bearer token:

Authorization: Bearer <identity-access-token>

See ERC-8004 Agent Identity for token format and TTLs.

Auth routes

Session management endpoints for Studio operators.

Login example (Solana SIWS)

POST /api/nest/auth/nonce
Content-Type: application/json
 
{
  "walletAddress": "8zFgn..."
}

POST /api/nest/auth/login
X-CSRF-Token: <csrf-token>
Content-Type: application/json
 
{
  "message": "<siws-message>",
  "signature": "<base58-signature>",
  "walletAddress": "8zFgn..."
}

Response:

{
  "accessToken": "<jwt>",
  "refreshToken": "<jwt>",
  "user": { "id": "...", "walletAddress": "8zFgn..." }
}

Bot routes (Studio)

CRUD and configuration for Studio bots.

Core bot management

Bot MCP configuration

Bot platforms

Bot agent card

Bot analytics

Trading routes

Trading operations proxied through the backend to the Rust trading engine over gRPC.

All trading routes are under /api/nest/trading/ and require Bearer session authentication unless noted.

Commands and approvals

Positions and orders

EVM trading

Token approvals (EVM)

Custodial wallets (Solana)

Trading config

DCA strategies

Research

External agent routes (Hub)

Public onboarding (no auth required)

Public agent directory (no auth required)

Authenticated agent wallet

Requires a valid trade-scoped identity token.

Control-plane (claim + manage scope + step-up required)

MCP routes

The MCP surface is outside the /api prefix.

The publicId is the public exposure identifier. See MCP Integration for the full request format.

Widget routes

The chat widget is served from the backend. Widget routes are public (no user session), but require a valid bot ID.

Widget sessions are domain-validated against the bot's allowed origins. Sessions have a 1-hour TTL. Trading requires wallet authentication within the widget session.

Discovery routes (well-known, no auth)

These endpoints follow the /.well-known/ convention and are readable by any client — including AI agents performing cold-start discovery.

Error envelope

All API errors return a consistent JSON envelope:

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}

MCP errors follow JSON-RPC 2.0:

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

Common HTTP status codes

Idempotency

Mutating trading routes that involve on-chain side effects require an idempotency key:

X-Idempotency-Key: <uuid-v4>

Generate a fresh UUID per unique operation. Replaying the same key within the TTL window returns the cached result without re-executing. Missing idempotency keys on guarded routes return 400 Bad Request.

Notes

• publicId identifies an external agent or bot for MCP and public routes. It is different from the internal _id.
• agentId is the canonical developer-assigned identity of an external agent.
• Studio bots and external agents share the same execution core but have separate principal models.
• Trading /:userId paths validate that the :userId matches the authenticated session — this is not an admin route.
• The X-CSRF-Token header is required on all mutating session-authenticated requests.

Related pages

• MCP Integration
• ERC-8004 Agent Identity
• Fees and Limits
• Security