aixyz

Framework for bundling AI agents into deployable services with A2A, MCP, x402 payments, and ERC-8004 identity.

Write your agent logic. aixyz wires up the protocols, payments, and deployment.

Prerequisites

Install Bun if you don't have it:

curl -fsSL https://bun.sh/install | bash

Quick Start

bunx create-aixyz-app my-agent
cd my-agent
bun install
bun run dev

Your agent is running. It exposes:

How It Works

An aixyz agent has three parts: a config, an agent, and tools.

1. Config

aixyz.config.ts declares your agent's identity, payment address, and skills:

import type { AixyzConfig } from "aixyz/config";

const config: AixyzConfig = {
  name: "Weather Agent",
  description: "Get current weather for any location worldwide.",
  version: "0.1.0",
  x402: {
    payTo: "0x...",
    network: "eip155:8453", // Base mainnet
  },
  skills: [
    {
      id: "get-weather",
      name: "Get Weather",
      description: "Get current weather conditions for any city or location",
      tags: ["weather"],
      examples: ["What's the weather in Tokyo?"],
    },
  ],
};

export default config;

2. Agent

app/agent.ts defines your agent, its payment price, and A2A capabilities:

import { openai } from "@ai-sdk/openai";
import { stepCountIs, ToolLoopAgent } from "ai";
import type { Accepts } from "aixyz/accepts";
import type { Capabilities } from "aixyz/app/plugins/a2a";
import weather from "./tools/weather";

export const accepts: Accepts = {
  scheme: "exact",
  price: "$0.005",
};

export const capabilities: Capabilities = {
  streaming: true, // default: true — set to false to use generate() instead of stream()
  pushNotifications: false, // default: false
};

export default new ToolLoopAgent({
  model: openai("gpt-4o-mini"),
  instructions: "You are a helpful weather assistant.",
  tools: { weather },
  stopWhen: stepCountIs(10),
});

3. Tools

Each file in app/tools/ exports a Vercel AI SDK tool and an optional accepts for MCP payment gating:

import { tool } from "ai";
import { z } from "zod";
import type { Accepts } from "aixyz/accepts";

export const accepts: Accepts = {
  scheme: "exact",
  price: "$0.0001",
};

export default tool({
  description: "Get current weather conditions for a city.",
  inputSchema: z.object({
    location: z.string().describe("City name"),
  }),
  execute: async ({ location }) => {
    // your logic here
  },
});

That's it. Run bun run dev and aixyz auto-generates the server, wires up A2A + MCP + x402, and starts serving.

Custom Server

For full control, create app/server.ts instead. This takes precedence over auto-generation:

import { AixyzApp } from "aixyz/app";
import { IndexPagePlugin } from "aixyz/app/plugins/index-page";
import { A2APlugin } from "aixyz/app/plugins/a2a";
import { MCPPlugin } from "aixyz/app/plugins/mcp";

import * as agent from "./agent";
import lookup from "./tools/lookup";

const server = new AixyzApp();

// Index page: human-readable agent info
await server.withPlugin(new IndexPagePlugin());

// A2A: agent discovery + JSON-RPC endpoint
await server.withPlugin(new A2APlugin(agent));

// MCP: expose tools to MCP clients
await server.withPlugin(
  new MCPPlugin([
    {
      name: "lookup",
      exports: {
        default: lookup,
        accepts: { scheme: "exact", price: "$0.001" },
      },
    },
  ]),
);

await server.initialize();

export default server;

Configuration

Environment variables are loaded in the same order as Next.js: .env, .env.local, .env.$(NODE_ENV), .env.$(NODE_ENV).local.

Payment (Accepts)

Each agent and tool declares an accepts export to control payment:

// Require x402 payment
export const accepts: Accepts = {
  scheme: "exact",
  price: "$0.005", // USD-denominated
  network: "eip155:8453", // optional, defaults to config.x402.network
  payTo: "0x...", // optional, defaults to config.x402.payTo
};

Agents and tools without an accepts export are not registered.

CLI

aixyz dev

Starts a local dev server with hot reload. Watches app/ and aixyz.config.ts for changes.

aixyz dev          # default port 3000
aixyz dev -p 4000  # custom port

aixyz build

Bundles your agent for deployment. Default output goes to .aixyz/output/server.js.

aixyz build                      # standalone (default), outputs to .aixyz/output/server.js
bun .aixyz/output/server.js      # run the standalone build

aixyz build --output vercel      # Vercel Build Output API v3, outputs to .vercel/output/
vercel deploy                    # deploy the Vercel build

aixyz build --output executable  # self-contained binary, no Bun runtime required
./.aixyz/output/server           # run directly

aixyz erc-8004 register

Register your agent's on-chain identity (ERC-8004). Creates app/erc-8004.ts if it doesn't exist, asks for your deployment URL, and writes the registration back to the file after a successful on-chain transaction.

aixyz erc-8004 register --url "https://my-agent.vercel.app" --chain base-sepolia --broadcast

aixyz erc-8004 update

Update the metadata URI of a registered agent. Reads registrations from app/erc-8004.ts and lets you select which one to update.

aixyz erc-8004 update --url "https://new-domain.example.com" --broadcast

Protocols

A2A (Agent-to-Agent) — Generates an agent card at /.well-known/agent-card.json and a JSON-RPC endpoint at /agent. Protocol version 0.3.0. Other agents discover yours and send tasks via JSON-RPC.

MCP (Model Context Protocol) — Exposes your tools at /mcp using WebStandardStreamableHTTPServerTransport. Any MCP client (Claude Desktop, VS Code, Cursor) can connect and call your tools.

x402 — HTTP 402 micropayments. Clients pay per-request with an X-Payment header containing cryptographic payment proof. No custodial wallets, no subscriptions. Payments are verified on-chain via a facilitator.

ERC-8004 — On-chain agent identity. Register your agent on Ethereum, Base, Polygon, Scroll, Monad, BSC, or Gnosis so other agents and contracts can reference it.

Agent File Structure

my-agent/
  aixyz.config.ts     # Agent config (required)
  app/
    agent.ts          # Agent definition (required if no server.ts)
    server.ts         # Custom server (optional, overrides auto-generation)
    erc-8004.ts       # ERC-8004 identity registration (optional)
    tools/
      weather.ts      # Tool exports (files starting with _ are ignored)
    icon.png          # Agent icon (served as static asset)
  public/             # Static assets
  vercel.json         # Vercel deployment config
  .env.local          # Local environment variables

Environment Variables

Examples

Contributing

bun install
bun run build
bun run format

License

MIT