ERC-8004 Agent Identity

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

{
  "message": "<full SIWE message string — pass this directly to onboarding>",
  "nonce": "abc123xyz...",
  "issuedAt": "2026-03-19T10:00:00.000Z",
  "expiresAt": "2026-03-19T10:05:00.000Z"
}

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

{
  "success": true,
  "externalAgent": {
    "agentId": "my-agent-001",
    "publicId": "ea_public_xxx",
    "chainId": 8453,
    "scope": "trade"
  },
  "mcp": {
    "endpoint": "https://api.balchemy.ai/mcp/ea_public_xxx"
  },
  "funding": {
    "walletAddress": "0x..."
  },
  "identityAccess": {
    "token": "<jwt>",
    "tokenType": "Bearer",
    "expiresIn": 300,
    "issuedAt": "2026-03-19T10:00:00.000Z",
    "expiresAt": "2026-03-19T10:05:00.000Z"
  }
}

const payload = JSON.stringify({
  agentId: "my-agent-001",
  chainId: 8453,
  providerUserId: "your-internal-agent-id",
  jti: crypto.randomUUID(),       // unique per call
  iat: Math.floor(Date.now() / 1000),
  exp: Math.floor(Date.now() / 1000) + 300
});
const payloadB64 = Buffer.from(payload).toString("base64url");
const signature = crypto
  .createHmac("sha256", BALCHEMY_SHARED_SECRET)
  .update(payloadB64)
  .digest("hex");
const identityToken = `${payloadB64}.${signature}`;

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

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

{
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "x": "...",
      "y": "...",
      "use": "sig",
      "alg": "ES256",
      "kid": "balchemy-agent-identity-v1"
    }
  ]
}

function isExpired(token) {
  const { exp } = JSON.parse(
    Buffer.from(token.split(".")[1], "base64url").toString()
  );
  // 30-second grace period
  return Math.floor(Date.now() / 1000) + 30 >= exp;
}
 
async function getToken() {
  if (!cachedToken || isExpired(cachedToken)) {
    const result = await onboard(); // re-run onboarding
    cachedToken = result.identityAccess.token;
  }
  return cachedToken;
}

POST /api/public/erc8004/onboarding/tokens/revoke
Content-Type: application/json
 
{
  "jti": "<token-jti>",
  "agentId": "my-agent-001"
}

POST /api/public/erc8004/onboarding/tokens/revoke-status
Content-Type: application/json
 
{
  "jti": "<token-jti>"
}

POST /api/nest/agents/:agentId/control/claim
POST /api/nest/agents/:agentId/control/mcp/step-up
PUT  /api/nest/agents/:agentId/control/scopes
POST /api/nest/agents/:agentId/control/mcp/keys/rotate
PUT  /api/nest/agents/:agentId/control/withdraw

GET /api/public/erc8004/agents/:publicId
GET /api/public/erc8004/agents/:publicId/snapshot

import crypto from "node:crypto";
 
const BASE_URL = "https://api.balchemy.ai";
const SHARED_SECRET = process.env.BALCHEMY_SHARED_SECRET; // set this
const AGENT_ID = "my-agent-001";
const CHAIN_ID = 8453;
 
function buildIdentityToken(agentId, chainId, sharedSecret) {
  const payload = JSON.stringify({
    agentId,
    chainId,
    providerUserId: agentId,
    jti: crypto.randomUUID(),
    iat: Math.floor(Date.now() / 1000),
    exp: Math.floor(Date.now() / 1000) + 300,
  });
  const payloadB64 = Buffer.from(payload).toString("base64url");
  const sig = crypto
    .createHmac("sha256", sharedSecret)
    .update(payloadB64)
    .digest("hex");
  return `${payloadB64}.${sig}`;
}
 
async function onboardAgent() {
  const identityToken = buildIdentityToken(AGENT_ID, CHAIN_ID, SHARED_SECRET);
 
  const res = await fetch(`${BASE_URL}/api/public/erc8004/onboarding/identity`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      provider: "balchemy",
      identityToken,
      agentId: AGENT_ID,
      chainId: CHAIN_ID,
      scope: "trade",
    }),
  });
 
  if (!res.ok) {
    throw new Error(`Onboarding failed: ${res.status} ${await res.text()}`);
  }
 
  return res.json();
}
 
async function callTool(publicId, accessToken, toolName, toolArgs) {
  const res = await fetch(`${BASE_URL}/mcp/${publicId}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: crypto.randomUUID(),
      method: "tools/call",
      params: { name: toolName, arguments: toolArgs },
    }),
  });
 
  if (!res.ok) {
    throw new Error(`MCP call failed: ${res.status}`);
  }
 
  const { result } = await res.json();
  return JSON.parse(result.content[0].text);
}
 
// Main
const { externalAgent, identityAccess, funding, mcp } = await onboardAgent();
 
console.log("Onboarded:", externalAgent.agentId);
console.log("MCP endpoint:", mcp.endpoint);
console.log("Funding wallet:", funding.walletAddress);
console.log("Token expires at:", identityAccess.expiresAt);
 
const status = await callTool(
  externalAgent.publicId,
  identityAccess.token,
  "agent_status",
  {}
);
console.log("Status:", status.structured);