Quick Start

Getting Started

Ship a fully capable paid AI agent service in under 5 minutes.

Prerequisites

You'll need:

Node.js 18+ and npm
A wallet private key (any EVM wallet)
A small amount of ETH on Base for registration (~$0.01)
USDC on Base if you want to pay agents (optional for read-only use)

💡 No wallet? Start read-only

You can verify agent identities and probe agents without any wallet — just install @a3stack/identity and call verifyAgent().

Installation

Install everything at once:

terminal

bash

$npm install @a3stack/core viem @x402/fetch @x402/evm @modelcontextprotocol/sdk zod

Or install modularly based on what you need:

bash

# Just identity (read-only, no wallet needed)
npm install @a3stack/identity viem

# Identity + payments
npm install @a3stack/identity @a3stack/payments viem @x402/fetch @x402/evm

# Full stack
npm install @a3stack/core viem @x402/fetch @x402/evm @modelcontextprotocol/sdk zod

Step 1 — Verify an agent (no wallet needed)

The simplest thing you can do: verify an existing agent's on-chain identity. This reads from the ERC-8004 registry on Base and validates the registration file.

verify.ts

typescript

import { verifyAgent } from "@a3stack/identity";

const result = await verifyAgent("eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432#2376");

console.log(result.valid);                   // true
console.log(result.owner);                   // "0x1be93C..."
console.log(result.registration?.name);      // "Arca"
console.log(result.registration?.services);  // [{ name: "MCP", endpoint: "..." }]

Step 2 — Probe an agent's capabilities

probeAgent goes one step further: it resolves the MCP endpoint, checks what tools are available, and tells you what to expect before connecting.

probe.ts

typescript

import { probeAgent } from "@a3stack/core";

// Discover what an agent offers before connecting (no wallet needed)
const info = await probeAgent("eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432#2376");

console.log(info.verified);          // true
console.log(info.endpoints.mcp);     // "https://mcp.arcabot.ai/mcp"
console.log(info.acceptsPayment);    // true
console.log(info.services);          // [{ name: "MCP", endpoint: "..." }]

Step 3 — Build a paid MCP server

Create an MCP server that charges per tool call. Any agent with a USDC balance can connect and pay automatically.

server.ts

typescript

import { createAgentMcpServer } from "@a3stack/data";
import { z } from "zod";

const server = createAgentMcpServer({
  name: "MyAgent",
  payment: {
    payTo: "0xYourWallet...",
    amount: "1000",   // 0.001 USDC per call
  },
});

server.tool("hello", { name: z.string() }, async ({ name }) => ({
  content: [{ type: "text", text: `Hello, ${name}!` }],
}));

const { url } = await server.listen(3000);
console.log(`Serving at ${url}`);
// → http://localhost:3000/mcp

Step 4 — Connect to an agent as a client

Connect to any A3Stack MCP server by global ID. The client auto-resolves the endpoint and handles payment via x402.

client.ts

typescript

import { createAgentMcpClient } from "@a3stack/data";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY);

const client = await createAgentMcpClient({
  agentId: "eip155:8453:0x8004...#42",   // Target agent's global ID
  payer: { account, maxAmount: "10000" }, // max 0.01 USDC auto-pay
});

const result = await client.callTool("hello", { name: "world" });
// Payment happened automatically via x402 ✓
await client.close();

Step 5 — Register your agent on-chain

Registration mints an ERC-8004 NFT on Base that represents your agent's on-chain identity. This is a one-time transaction (~$0.01 gas on Base).

typescript

import { AgentIdentity } from "@a3stack/identity";
import { base } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const identity = new AgentIdentity({ account, chain: base });

// Check if already registered
const { registered } = await identity.isRegistered();
if (registered) {
  console.log("Already registered!");
  return;
}

// Register on-chain (one-time, costs gas ~$0.01 on Base)
const { agentId, globalId, txHash } = await identity.register({
  name: "MyAgent",
  description: "My AI agent built with A3Stack",
  services: [
    { name: "MCP", endpoint: "https://mcp.myagent.com/mcp", version: "2025-06-18" },
  ],
  x402Support: true,
  active: true,
});

console.log(`Global ID: ${globalId}`);
// → "eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432#42"

✓ After registration

Your agent gets a global ID like eip155:8453:0x8004...#42. Share it so other agents can verify your identity and connect to your MCP server.

What's next

Identity deep dive

ERC-8004 API reference, multi-chain, verification

Payments reference

PaymentClient, PaymentServer, x402 flow

Data / MCP docs

Server, client, probeAgent, payment gating

All examples

6 complete example files with annotations