ERC-8004 support gives Hub Web3 agents a standards-aligned identity and discovery path. Use it when an always-on agent runtime needs to register with Balchemy, prove identity, receive scoped access, discover MCP/API connection details, and expose public agent metadata where available.

This is a Hub agent flow. If you are creating a Telegram, Discord, or embedded website trading bot for a community, use Studio instead.

What ERC-8004 enables

A Hub agent can use ERC-8004-compatible flows to:

discover Balchemy agent onboarding and MCP metadata;
authenticate with wallet-based SIWE or a supported walletless identity provider;
receive short-lived ES256 identity access tokens;
connect to Balchemy through scoped MCP/API access;
expose public agent-card metadata through discovery surfaces;
complete ownership-sensitive setup or management actions through Hub when required.

ERC-8004 identity does not bypass fund-safety checks. Trading still depends on scope, wallet state, balances, risk policy, provider state, slippage, and order lifecycle.

Key identifiers

Identifier	Meaning	Where it appears
`agentId`	Canonical agent identity assigned or provided during setup.	Onboarding request, identity token claims, Hub agent records.
`publicId`	Public connection identifier for MCP and discovery routes.	`/mcp/<publicId>`, agent card URLs, discovery metadata.
`controllingAddress`	Wallet or derived address associated with the agent identity where applicable.	Identity claims, ownership checks, traceability metadata.

Do not guess identifiers from old logs or screenshots. Use the values returned by the current onboarding or Hub agent detail flow.

Onboarding paths

Path	Use it when
SIWE onboarding	The agent or owner can prove control of an EVM wallet.
Walletless onboarding	A supported provider verifies the agent identity without a direct wallet signature.
Hub UI setup	An operator is manually registering or maintaining the agent from the app.

Solana wallet sign-in is supported for user authentication and wallet linking, but the ERC-8004 onboarding path documented here focuses on EVM SIWE and walletless/provider-verified identity. Follow the Hub UI if the product flow prompts for a different setup path.

SIWE onboarding

Request an EVM SIWE nonce.
Sign the returned message with the controlling EVM wallet.
Submit the signed message to the ERC-8004 SIWE onboarding endpoint.
Store returned credentials securely.
Use the returned MCP endpoint and publicId for tool discovery.

POST /api/nest/auth/evm/nonce
Content-Type: application/json
 
{
  "address": "0xYOUR_WALLET_ADDRESS",
  "chainId": 8453,
  "domain": "yourdomain.ai",
  "uri": "https://yourdomain.ai"
}

POST /api/public/erc8004/onboarding/siwe
Content-Type: application/json
 
{
  "message": "<siwe-message-string>",
  "signature": "0x...",
  "agentId": "my-agent-001",
  "scope": "trade"
}

A successful response can include agent metadata, the MCP endpoint, funding/setup information, and an identity access token. Copy and store returned secrets immediately. Full secrets may not be shown again.

Walletless onboarding

Walletless onboarding is for agent runtimes verified by a supported identity provider. The provider adapter verifies the submitted identity token and Balchemy issues a scoped identity token if verification succeeds.

POST /api/public/erc8004/onboarding/identity
Content-Type: application/json
 
{
  "provider": "balchemy",
  "identityToken": "<provider-issued-token>",
  "agentId": "my-agent-001",
  "chainId": 8453,
  "scope": "trade"
}

Provider token construction is provider-specific. Do not place provider secrets, signing keys, or shared secrets in source code, logs, prompts, screenshots, or public documentation.

Identity access tokens

Balchemy issues ES256 identity access tokens for successful agent onboarding.

Claim	Meaning
`sub`	Subject ID.
`aid`	Agent ID.
`cid`	Chain ID.
`prv`	Identity provider.
`caddr`	Controlling address where applicable.
`scp`	Scope: `read`, `trade`, or `manage`.
`exp`	Expiration time.
`iat`	Issued-at time.
`jti`	Token identifier.
`kid`	Signing key identifier.

TTL by scope

Scope	Typical maximum TTL
`read`	1 hour
`trade`	5 minutes
`manage`	1 minute

Privileged tokens are intentionally short-lived. Re-authenticate or repeat the supported onboarding/step-up flow when a token expires.

JWKS verification

Clients that verify Balchemy-issued identity tokens should use the public JWKS endpoint:

GET https://api.balchemy.ai/.well-known/jwks.json

Use a JWT library that supports ES256 and validates issuer, audience or expected context where your integration requires it. Do not treat a decoded token as trusted unless the signature and claims were verified.

MCP connection

The MCP endpoint shape is:

POST https://api.balchemy.ai/mcp/<publicId>
Authorization: Bearer <agent-key-or-identity-token>
Content-Type: application/json

Use tools/list with the same credential that will call tools:

{
  "jsonrpc": "2.0",
  "id": "tools-list-1",
  "method": "tools/list"
}

The visible tools are dynamic. They depend on runtime registry state, environment configuration, principal context, and key scope. Do not rely on a fixed tool count or a stale manifest.

Scope rules

Scope	Use it for
`read`	Status, logs, portfolio, research, monitoring, and discovery.
`trade`	Trade actions allowed by policy, wallet state, and risk checks.
`manage`	Sensitive management actions such as key rotation, scope changes, claim/ownership-sensitive operations, or protected setup changes.

Use the smallest scope that works. A long-running autonomous trading runtime usually needs trade, not manage.

Ownership-sensitive actions

Some actions require more than a valid token. Hub can require claim, ownership, or step-up verification before allowing management-sensitive changes such as:

rotating keys;
changing scopes;
changing sensitive setup or ownership state;
enabling protected withdrawal or management actions where available.

Use the Hub UI/API flow shown for the specific agent. Do not bypass these checks by editing database records or reusing stale verification tokens.

Funding and wallet state

Agent onboarding can return wallet or funding information where the product flow supports it. Treat this as fund-sensitive operational state:

Fund only the amount intended for active trading.
Confirm the intended chain before sending funds.
Keep staging and production funds separate.
Keep native gas token available where required.
Monitor Hub logs after funding or enabling trade automation.

Never export private keys from production systems or paste seed phrases/private keys into prompts, logs, screenshots, or support channels.

Discovery endpoints

Endpoint	Purpose
`GET /.well-known/erc8004-discovery.json`	Machine-readable discovery document.
`GET /.well-known/erc8004-onboarding.json`	Onboarding metadata and endpoint list.
`GET /.well-known/erc8004-onboarding.md`	Human-readable onboarding guide.
`GET /.well-known/erc8004-skills-manifest.json`	Capability categories and MCP metadata.
`GET /.well-known/jwks.json`	ES256 public key set.
`GET /.well-known/mcp.json`	MCP endpoint template and auth requirements.
`GET /api/public/erc8004/discovery/feed`	Public discovery feed where available.
`GET /api/public/erc8004/agents/page`	Paged public agent directory where available.

Discovery documents should be treated as live metadata. If they differ from a stale doc page, trust the current discovery response and tools/list output.

Public agent cards

Public agent-card routes can expose metadata for discoverable agents:

GET /api/public/erc8004/agents/<publicId>
GET /api/public/erc8004/agents/<publicId>/snapshot

The exact fields can vary by runtime and agent state. They can include identifiers, supported scopes, onboarding modes, capabilities, fee policy metadata, verification status, and last provisioning timestamps.

Common issues

The agent cannot call a tool. Run tools/list with the same credential. The key or token may have too low a scope, point at the wrong publicId, or belong to a different principal.

A trade request is forbidden. Check scope first, then wallet funding, gas/native token, risk policy, setup state, and Hub logs.

A management action fails. The action may require manage scope plus claim, ownership verification, or a fresh step-up token.

The discovery manifest lists different tools than expected. Tool availability is dynamic. Use tools/list for the current credential instead of relying on a fixed count.

MCP

X/Twitter

Edit this page on GitHub

ERC-8004 Agent Identity