Documentation

Full documentation, API reference, and guides at aixyz.sh.

Quick Start

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

Your agent is running. It exposes:

| Endpoint | Protocol | What it does | | ------------------------------ | -------- | ------------------------------------ | | /.well-known/agent-card.json | A2A | Agent discovery card | | /agent | A2A | JSON-RPC endpoint, x402 payment gate | | /mcp | MCP | Tool sharing with MCP clients |

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 and payment address:

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
  },
};

export default config;

2. Agent

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

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

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

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.

Examples

| Example | Description | | ---------------------------------------------------------------- | ----------------------------------------------- | | boilerplate | Minimal starter (auto-generated server) | | chainlink | Chainlink data feeds with custom server | | flight-search | Flight search with Stripe payments | | local-llm | Local LLM via Docker (no external API) | | with-custom-facilitator | Bring-your-own x402 facilitator | | with-custom-server | Custom server setup | | with-express | Express middleware integration | | sub-agents | Multiple A2A endpoints from one deployment | | with-tests | Agent with test examples | | fake-llm | Fully deterministic testing with fake() model |

CLI

bun add aixyz            # CLI included with the aixyz package
bunx aixyz --help        # or run without installing

aixyz dev                # Dev server with hot reload
aixyz build              # Bundle for deployment (standalone, Vercel, or executable)
aixyz erc-8004 register  # Register on-chain agent identity
aixyz erc-8004 update    # Update agent metadata URI

See the CLI reference for all options.

Protocols

A2A (Agent-to-Agent) — Agent discovery card + JSON-RPC endpoint. Other agents find yours and send tasks.

MCP (Model Context Protocol) — Expose tools to any MCP client (Claude Desktop, VS Code, Cursor).

x402 — HTTP 402 micropayments. Per-request payment with cryptographic proof, verified on-chain.

ERC-8004 — On-chain agent identity on Ethereum, Base, Polygon, Scroll, Monad, BSC, or Gnosis.

Contributing

bun install          # install dependencies
bun run build        # build all packages
bun run test         # run tests
bun run format       # format with Prettier

PRs welcome. Please ensure bun run build && bun run test && bun run format pass before submitting.

License

MIT