Full-Stack App Integration

Abstraxn ships two sample projects you can clone or mirror:

Sample	Stack	Role
Sample backend API	NestJS, Postgres	Your server: users, DB, `@abstraxn/agent-kit`, MCP + LLM
Sample web app	Next.js	Your UI: login, agents, chat, portfolio

Together they show the full path from dashboard credentials to a user-facing agent with chat, portfolio, and on-chain actions. Folder names in your monorepo may differ; the patterns below apply to any backend and frontend you build.

What you are building

Layer	Your project	Responsibility
Dashboard	Abstraxn UI	API key, MCP URL, monitor agents
Backend API	Sample backend API (NestJS)	Users, DB, `@abstraxn/agent-kit`, MCP + LLM
Web app	Sample web app (Next.js)	Login, pick agent, chat, portfolio
Infrastructure	Agent Kit host	REST + MCP + x402

Prerequisites

Dashboard setup — application API key and MCP URL.
SDK quickstart — understand createAgent and accessKey.
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

Variable	Example	Purpose
`AGENT_KIT_API_KEY`	From dashboard Overview	`AgentKitClient` + MCP auth
`AGENT_KIT_BASE_URL`	`https://dev-agent-kit.abstraxn.com`	REST base
`MCP_SERVER_URL`	`https://dev-agent-kit.abstraxn.com/mcp`	Same as dashboard MCP URL
`MCP_SERVER_AUTH_TOKEN`	Same as `AGENT_KIT_API_KEY`	MCP `Authorization` header
`ENCRYPTION_KEY`	Long random secret	Encrypt `wallet.accessKey` at rest
`LLM_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL`	OpenRouter, etc.	Chat model
`JWT_SECRET`	Random	End-user sessions
`POSTGRES_*`	Local DB	Agents + chat tables

npm run start:dev   # default port 3008

Create agent — SDK + server wallet

When the UI calls POST /agents, AgentsService.create:

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

This matches SDK quickstart. After creation, the agent appears in dashboard All agents with EVM/Solana addresses. Your production checklist:

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)

Method	Path	Behavior
`POST`	`/agents`	`createAgent` via SDK
`GET`	`/agents`	List agents for logged-in user
`GET`	`/agents/:id`	Agent detail (no `accessKey`)
`PATCH`	`/agents/:id`	Update name / prompt
`POST`	`/agents/:id/register-identity`	Body `{ "chainId": … }` — supported chain IDs (`1`, `11155111`, `137`, `80002`, `8453`, `84532`, `56`, `97`, `42161`, `43114`)
`GET`	`/agents/:id/identity?chainId=`	Read registration for one supported chain
`GET`	`/agents/assets`	Multi-chain balances (Tatum)
`POST`	`/chat/sessions`	New session for `agentId`
`POST`	`/chat/sessions/:id/messages`	SSE stream; runs LLM + MCP tools

Swagger is available when enabled in your Nest build.

MCP + LLM chat loop

McpClientService (on module init when MCP_SERVER_URL is set):

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

ChatService.sendMessageStreaming:

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

Relevant files:

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

Transfer auto-sign (unsigned MCP → broadcast)

When the LLM calls MCP transfer, the tool returns an unsigned transaction. The sample app:

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

See src/agents/agent-signing.service.ts and src/agents/pending-transfer.service.ts.

x402 in chat (`paid_fetch`, `get_token_price`)

When MCP returns payment required (-32402 or paymentRequired):

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

See x402 payments and src/chat/mcp-x402.util.ts.

Part 2 — Sample web app (Next.js)

Install and configure

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

Set backend URL in lib/constants.ts:

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

File	Role
`components/providers/agents-provider.tsx`	Load/create agents via `/agents`
`app/dashboard/page.tsx`	Agent picker + chat entry
`stores/agents-store.ts`	Selected agent persistence

Creating an agent in the UI → POST /agents on your backend → SDK createAgent → dashboard All agents updates on refresh.

Chat (BFF)

The browser never calls Agent Kit or the LLM directly.

UI posts to Next.js app/api/chat/route.ts with Bearer JWT.
Route proxies to POST /chat/sessions/:sessionId/messages on the backend with SSE.
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 }),
  },
);

Category specialist agents

The sample web app supports predefined specialist agents via serviceAgent on chat requests (or the category picker in the UI). Each specialist filters MCP tools and injects focused system prompts.

`serviceAgent`	Purpose
`uniswap`, `lifi`, `jupiter`, `oneinch`	Swap quotes (BYOK) — see Third-party integrations
`portfolio`	Read-only balances, prices, charts; use with CoinGecko for `data_and_analytics`
`transfer`	Send tokens with optional confirmation cards
`x402`	Discover and pay for x402 APIs
`gas`	Gas fees, blocks, transaction status

Example: open chat as Portfolio & Price with ?serviceAgent=portfolio.

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)

Your API must decrypt accessKey and call @abstraxn/agent-kit registerAgentIdentity (or Kit REST prepare/confirm). The browser never signs registration transactions directly. Full standard and dashboard parity: ERC-8004 agent identity.

Transaction history

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

Part 3 — Map dashboard UI to your code

Dashboard screen	Your implementation
Overview API key	`AGENT_KIT_API_KEY`, `MCP_SERVER_AUTH_TOKEN`
Overview MCP URL	`MCP_SERVER_URL`
All agents table	Rows from your DB after `createAgent`
Identity tab	`metadata.erc8004` after `registerAgentIdentity`
Activity log tab	MCP tool call logs for that agent
Tools catalog	Same tools `McpClientService` discovers

Security model

Secrets stay on your backend API

Application API key, MCP token, ENCRYPTION_KEY, and LLM keys live only in backend env. The web app holds the user JWT only.

accessKey is the signing root

Losing accessKey means you cannot sign transfers or x402 for that agent. Encrypt the DB column; never expose in GET /agents/:id.

Do not call MCP from the browser

Always proxy tool execution through your backend so keys and paymentPayload signing stay server-side.

Customize for production

Sample choice	Alternative
`userIdentity: userId`	Email, external id
OpenRouter	Azure OpenAI, Anthropic via compatible proxy
Tatum balances	Your indexer
Next.js `/api/chat` BFF	SSE from API + CORS
Single `AGENT_KIT_API_KEY`	Per-agent `apiKey` for MCP

Getting started

SDK & wallets

Third-party integrations

Off-chain policies

Identity

Build your app

MCP

Payments

Help

Full-Stack App Integration

What you are building

Prerequisites

Part 1 — Sample backend API (NestJS)

Install and configure

Create agent — SDK + server wallet

REST surface (your API, JWT)

MCP + LLM chat loop

Transfer auto-sign (unsigned MCP → broadcast)

x402 in chat (`paid_fetch`, `get_token_price`)

Part 2 — Sample web app (Next.js)

Install and configure

Auth

Agents UI

Chat (BFF)

Category specialist agents

Portfolio and ERC-8004 identity

Transaction history

Part 3 — Map dashboard UI to your code

Security model

Customize for production

​What you are building

​Prerequisites

​Part 1 — Sample backend API (NestJS)

​Install and configure

​Create agent — SDK + server wallet

​REST surface (your API, JWT)

​MCP + LLM chat loop

​Transfer auto-sign (unsigned MCP → broadcast)

​x402 in chat (paid_fetch, get_token_price)

​Part 2 — Sample web app (Next.js)

​Install and configure

​Auth

​Agents UI

​Chat (BFF)

​Category specialist agents

​Portfolio and ERC-8004 identity

​Transaction history

​Part 3 — Map dashboard UI to your code

​Security model

​Customize for production

​Related documentation

What you are building

Prerequisites

Part 1 — Sample backend API (NestJS)

Install and configure

Create agent — SDK + server wallet

REST surface (your API, JWT)

MCP + LLM chat loop

Transfer auto-sign (unsigned MCP → broadcast)

x402 in chat (`paid_fetch`, `get_token_price`)

Part 2 — Sample web app (Next.js)

Install and configure

Auth

Agents UI

Chat (BFF)

Category specialist agents

Portfolio and ERC-8004 identity

Transaction history

Part 3 — Map dashboard UI to your code

Security model

Customize for production

Related documentation