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 Studio bots, Hub Web3 agents, MCP, widgets, trading, and discovery.
For exact request bodies, use the current product flow, tools/list schemas, or linked domain pages.
Base URL
| Environment | Base URL |
|---|---|
| Production | https://api.balchemy.ai |
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.
| Credential | Used by | Notes |
|---|---|---|
| Session bearer token | Human operators in Studio and Hub | Created through wallet sign-in; mutating session requests also require CSRF. |
| Studio bot MCP key | MCP clients operating one Studio bot | Created from the Studio bot cockpit MCP tab. |
| Hub agent key | MCP/API clients operating one Hub Web3 agent | Managed from Hub → Agents & Keys / agent detail. |
| Hub agent identity token | ERC-8004-compatible Hub agent flows | ES256 short-lived token issued after SIWE or walletless/provider verification. |
CSRF for session-authenticated mutation
Session-authenticated POST, PATCH, PUT, and DELETE requests require a CSRF token.
GET /api/nest/auth/csrfInclude 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
| Method | Path | Purpose | Auth |
|---|---|---|---|
GET | /api/nest/auth/csrf | Get CSRF token. | None |
POST | /api/nest/auth/nonce | Get Solana SIWS nonce. | None |
POST | /api/nest/auth/login | Solana SIWS login. | SIWS signature |
POST | /api/nest/auth/evm/nonce | Get EVM SIWE nonce. | None |
POST | /api/nest/auth/evm/login | EVM SIWE login. | SIWE signature |
POST | /api/nest/auth/refresh | Refresh session token. | Bearer session |
POST | /api/nest/auth/logout | Invalidate session. | Bearer session |
POST | /api/nest/auth/verify | Verify token validity. | Bearer session |
Studio bot routes
Studio routes are for bots operated by traders, communities, and projects.
Core bot management
| Method | Path | Purpose |
|---|---|---|
GET | /api/nest/bots | List bots for the authenticated user. |
GET | /api/nest/bots/list | Simplified bot list. |
POST | /api/nest/bots | Create a Studio bot. |
GET | /api/nest/bots/:id | Get bot details. |
PATCH | /api/nest/bots/:id | Update bot settings. |
PUT | /api/nest/bots/:id | Replace bot settings. |
DELETE | /api/nest/bots/:id | Delete a bot. |
POST | /api/nest/bots/:botId/chat | Send a web-chat message to a bot. |
Mutating bot routes require a session bearer token and CSRF token.
Studio MCP configuration
| Method | Path | Purpose |
|---|---|---|
GET | /api/nest/bots/:botId/mcp | Get bot MCP configuration and key list. |
PUT | /api/nest/bots/:botId/mcp | Update bot MCP configuration. |
GET | /api/nest/bots/:botId/mcp/logs | Fetch bot MCP logs. |
POST | /api/nest/bots/:botId/mcp/keys | Create a bot-scoped MCP key. |
DELETE | /api/nest/bots/:botId/mcp/keys/:keyId | Revoke a bot-scoped MCP key. |
POST | /api/nest/bots/:botId/mcp/step-up | Issue step-up for sensitive bot MCP operations where required. |
POST | /api/nest/bots/:botId/mcp/token | Rotate MCP access token where supported. |
Studio MCP keys are not Hub agent keys. Use the current bot cockpit to create and rotate them.
Studio platforms
| Method | Path | Purpose |
|---|---|---|
POST | /api/nest/bots/:botId/platforms/:platform/start | Start a platform integration. |
POST | /api/nest/bots/:botId/platforms/:platform/stop | Stop a platform integration. |
GET | /api/nest/bots/:botId/telegram-config | Get Telegram configuration. |
PUT | /api/nest/bots/:botId/telegram-config | Update Telegram configuration. |
GET | /api/nest/bots/:botId/discord-config | Get Discord configuration. |
PUT | /api/nest/bots/:botId/discord-config | Update Discord configuration. |
X/Twitter should be treated as limited or coming soon unless it is explicitly enabled for the bot.
Studio analytics and channel attribution
| Method | Path | Purpose |
|---|---|---|
GET | /api/nest/bots/:botId/trading/fees/channels | Aggregate trading-fee attribution by channel where available. |
Channel/widget fee-share attribution is separate from referral rewards and should not be described as guaranteed payout settlement unless the current product flow exposes that settlement path.
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
| Method | Path | Purpose |
|---|---|---|
POST | /api/nest/trading/command | Execute a natural-language trading command. |
GET | /api/nest/trading/approvals/:userId | List pending approvals. |
POST | /api/nest/trading/orders/:userId/:orderId/approve | Approve a pending order. |
Positions and orders
| Method | Path | Purpose |
|---|---|---|
GET | /api/nest/trading/positions/:userId | Get open positions. |
GET | /api/nest/trading/positions/:userId/pnl | Get positions with PnL data. |
GET | /api/nest/trading/orders/:userId | List orders. |
EVM trading and wallet routes
| Method | Path | Purpose |
|---|---|---|
GET | /api/nest/trading/evm/status | EVM trading engine status. |
GET | /api/nest/trading/evm/wallets/:userId | List EVM wallets. |
POST | /api/nest/trading/evm/wallets/:userId | Add EVM wallet through the authorized flow. |
POST | /api/nest/trading/evm/wallets/:userId/custodial | Create EVM custodial wallet through the authorized flow. |
POST | /api/nest/trading/evm/wallets/:userId/delegate | Create EVM delegate wallet through the authorized flow. |
POST | /api/nest/trading/evm/wallets/:userId/default | Set default EVM wallet. |
DELETE | /api/nest/trading/evm/wallets/:userId/:walletId | Revoke EVM wallet access. |
POST | /api/nest/trading/evm/quote/:userId | Get EVM swap quote. |
POST | /api/nest/trading/evm/swap/:userId | Execute EVM swap. |
Solana wallet routes
| Method | Path | Purpose |
|---|---|---|
GET | /api/nest/trading/wallets/custodial/:userId | Get Solana custodial wallet state. |
POST | /api/nest/trading/wallets/custodial/:userId | Create Solana custodial wallet through the authorized flow. |
Do not repair wallet/key state through raw database edits.
Trading configuration
| Method | Path | Purpose |
|---|---|---|
GET | /api/nest/trading/config/:userId | Get trading configuration. |
GET | /api/nest/trading/config/:userId/default-order-profile | Get default order profile. |
PUT | /api/nest/trading/config/:userId/default-order-profile | Update default order profile. |
PUT | /api/nest/trading/config/:userId/trade-defaults | Update trade defaults. |
PUT | /api/nest/trading/config/:userId/risk-policy | Update risk policy. |
PUT | /api/nest/trading/config/:userId/notifications | Update notification config. |
PUT | /api/nest/trading/config/:userId/wallet-mode | Update wallet mode. |
GET | /api/nest/trading/config/:userId/favorites | Get favorite tokens. |
POST | /api/nest/trading/config/:userId/favorites | Add favorite token. |
DELETE | /api/nest/trading/config/:userId/favorites/:address | Remove favorite token. |
GET | /api/nest/trading/config/:userId/blacklist | Get blacklisted tokens. |
POST | /api/nest/trading/config/:userId/blacklist | Add to blacklist. |
DELETE | /api/nest/trading/config/:userId/blacklist/:address | Remove from blacklist. |
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
| Method | Path | Purpose |
|---|---|---|
POST | /api/public/erc8004/onboarding/siwe | Wallet-based agent identity onboarding. |
POST | /api/public/erc8004/onboarding/identity | Walletless/provider-verified agent identity onboarding. |
POST | /api/public/erc8004/onboarding/tokens/revoke | Revoke an identity access token. |
POST | /api/public/erc8004/onboarding/tokens/revoke-status | Check token revocation status. |
Public agent directory and cards
| Method | Path | Purpose |
|---|---|---|
GET | /api/public/erc8004/agents/page | Paged public agent directory where available. |
GET | /api/public/erc8004/agents/:publicId | Get public agent card. |
GET | /api/public/erc8004/agents/:publicId/snapshot | Get agent snapshot where available. |
GET | /api/public/erc8004/discovery/feed | Verified discovery feed where available. |
Agent wallet and funding state
| Method | Path | Purpose |
|---|---|---|
GET | /api/nest/agents/wallet/balance | Get agent wallet balance. |
POST | /api/nest/agents/wallet/withdraw/evm | Withdraw through the authorized EVM flow where available. |
POST | /api/nest/agents/wallet/withdraw/solana | Withdraw through the authorized Solana flow where available. |
Withdrawal and ownership-sensitive actions can require manage scope, claim verification, and step-up.
Ownership-sensitive agent operations
| Method | Path | Purpose |
|---|---|---|
POST | /api/nest/agents/:agentId/control/claim | Claim or verify ownership for protected actions. |
POST | /api/nest/agents/:agentId/control/mcp/step-up | Issue a short-lived step-up token. |
PUT | /api/nest/agents/:agentId/control/scopes | Update agent scopes through the protected flow. |
POST | /api/nest/agents/:agentId/control/mcp/keys/rotate | Rotate agent MCP/API keys through the protected flow. |
PUT | /api/nest/agents/:agentId/control/withdraw | Update protected withdrawal settings where available. |
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.
| Method | Path | Purpose | Auth |
|---|---|---|---|
ALL | /mcp/:publicId | JSON-RPC tool discovery and calls. | Bearer MCP key or identity token |
GET | /mcp/:publicId/events/sse | SSE event stream where available. | Bearer MCP key or identity token |
Use tools/list with the current key or token before calling tools. Visible tools depend on scope, principal context, registry state, and environment configuration.
Widget routes
The web widget belongs to Studio. It lets a project site embed one Studio bot.
| Method | Path | Purpose |
|---|---|---|
GET | /api/widget/:botId/script.js | Serve the widget embed script. |
POST | /api/widget/:botId/init | Initialize a widget session. |
POST | /api/widget/:botId/chat | Send a widget chat message. |
POST | /api/widget/:botId/client-event | Record a client-side widget event. |
Widget sessions can be domain-validated against the bot's allowed origins. Wallet-connected trading requires wallet authentication within the widget session and still passes through normal trading safety checks.
Discovery routes
These routes are readable by clients that need discovery metadata.
| Method | Path | Purpose |
|---|---|---|
GET | /.well-known/erc8004-discovery.json | ERC-8004 discovery document. |
GET | /.well-known/erc8004-onboarding.json | Onboarding metadata. |
GET | /.well-known/erc8004-onboarding.md | Human-readable onboarding guide. |
GET | /.well-known/erc8004-skills-manifest.json | Dynamic capability metadata. |
GET | /.well-known/jwks.json | ES256 public key set. |
GET | /.well-known/mcp.json | MCP endpoint template and auth requirements. |
Do not rely on a fixed tool count in discovery metadata. Use tools/list for the current credential.
Error envelopes
REST API errors use a 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 statuses:
| Code | Meaning |
|---|---|
400 | Invalid body or parameters. |
401 | Missing, expired, or revoked credential. |
403 | Insufficient scope, missing CSRF, or missing verification. |
404 | Resource not found. |
409 | Conflict, such as duplicate resource. |
422 | Validation error. |
429 | Rate limit exceeded. |
500 | Internal server error. |
503 | Dependency or trading service unavailable. |
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
publicIdidentifies the public MCP/discovery target and differs from internal database IDs.agentIdidentifies a Hub Web3 agent.- Studio bots and Hub agents share the same execution core but use separate principal and key models.
- Trading
/:userIdroutes validate the authenticated session; they are not admin routes. - No API route should imply plan, tier, subscription, or enterprise-only access.