Full-Stack App Integration

​

What you are building

​

Prerequisites

1. Dashboard setup — application API key and MCP URL.
2. SDK quickstart — understand createAgent and accessKey.
3. Postgres (or adapt persistence) for the sample service.

​

Part 1 — Sample backend API (NestJS)

​

Install and configure

cd <your-backend-project>   # NestJS sample API
npm install
cp .env.example .env

npm run start:dev   # default port 3008

​

Create agent — SDK + server wallet

1. Calls agentKitClient.createAgent({ name, description, userIdentity: userId }).
2. Receives agent (Kit id, per-agent apiKey) and wallet (evmAddress, organizationId, accessKey).
3. Encrypts wallet.accessKey with ENCRYPTION_KEY and saves to Postgres.
4. Never returns accessKey in API responses.

• Map userIdentity to your stable user id (the sample uses userId).
• Fund the agent EVM address with native gas before transfers or x402.
• Store agentId (Kit UUID) for MCP agent_id in tool arguments.

​

REST surface (your API, JWT)

​

MCP + LLM chat loop

1. initialize + notifications/initialized
2. tools/list → cache tool schemas
3. Expose tools to the LLM as OpenAI functions

1. Loads session messages.
2. Calls LLM with tool definitions.
3. On tool call → McpClientService.callTool(name, args, paymentPayload?).
4. For application key, include agent_id: session.agentId in args (Kit UUID from DB).
5. Streams assistant text to the client over SSE.

• src/chat/mcp-client.service.ts
• src/chat/chat.service.ts
• src/chat/llm.service.ts

​

Transfer auto-sign (unsigned MCP → broadcast)

1. Detects transfer metadata in the stream (transfer_confirmation_ui / pending transfer flow).
2. Asks the user to confirm in the UI.
3. AgentSigningService loads decrypted accessKey, authenticates server signer, signs and sends via viem.

​

x402 in chat (paid_fetch, get_token_price)

1. AgentSigningService.createX402PaymentPayloadForAgent builds paymentPayload using the agent’s access key.
2. Chat layer retries tools/call with top-level paymentPayload.

​

Part 2 — Sample web app (Next.js)

​

Install and configure

cd <your-frontend-project>   # Next.js sample app
npm install

export const API_BASE_URL = "https://your-agent-api.example.com";

npm run dev   # default http://localhost:3000

​

Auth

• Email OTP or Google OAuth → auth-store JWT.
• lib/api.ts adds Authorization: Bearer on every request to your API only.

​

Agents UI

​

Chat (BFF)

1. UI posts to Next.js app/api/chat/route.ts with Bearer JWT.
2. Route proxies to POST /chat/sessions/:sessionId/messages on the backend with SSE.
3. lib/chat/create-chat-session.ts creates sessions via your API.

// app/api/chat/route.ts — pattern
const upstream = await fetch(
  `${API_BASE_URL}/chat/sessions/${sessionId}/messages`,
  {
    method: "POST",
    headers: { Authorization: auth, Accept: "text/event-stream" },
    body: JSON.stringify({ content }),
  },
);

​

Portfolio and ERC-8004 identity

• components/portfolio/ — balances from /agents/assets
• RegisterIdentityModal — user picks a supported chainId; your API posts { "chainId": … } to /agents/:id/register-identity (full list)
• RegisterIdentityFundRequiredModal — prompts to fund the agent EVM wallet when gas is insufficient
• AgentIdentityDetails — global id, on-chain agent id, registry, owner, explorer links
• useAgentIdentity / lib/fetch-agent-identity.ts — load identity from your backend (proxies Agent Kit)

​

Transaction history

• hooks/use-agent-transactions.ts — on-chain transfer history helpers

​

Part 3 — Map dashboard UI to your code

​

Security model

​

Customize for production

​

Related documentation

• Agentic Layer overview
• SDK quickstart
• MCP tools reference
• x402 payments
• MCP in Cursor