## Documentation
Full documentation, API reference, and guides at **[aixyz.sh](https://aixyz.sh)**.
## Quick Start
```bash
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:
```ts
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:
```ts
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:
```ts
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`](https://github.com/agentlyhq/aixyz/tree/HEAD/examples/boilerplate/) | Minimal starter (auto-generated server) |
| [`chainlink`](https://github.com/agentlyhq/aixyz/tree/HEAD/examples/chainlink/) | Chainlink data feeds with custom server |
| [`flight-search`](https://github.com/agentlyhq/aixyz/tree/HEAD/examples/flight-search/) | Flight search with Stripe payments |
| [`local-llm`](https://github.com/agentlyhq/aixyz/tree/HEAD/examples/local-llm/) | Local LLM via Docker (no external API) |
| [`with-custom-facilitator`](https://github.com/agentlyhq/aixyz/tree/HEAD/examples/with-custom-facilitator/) | Bring-your-own x402 facilitator |
| [`with-custom-server`](https://github.com/agentlyhq/aixyz/tree/HEAD/examples/with-custom-server/) | Custom server setup |
| [`with-express`](https://github.com/agentlyhq/aixyz/tree/HEAD/examples/with-express/) | Express middleware integration |
| [`sub-agents`](https://github.com/agentlyhq/aixyz/tree/HEAD/examples/sub-agents/) | Multiple A2A endpoints from one deployment |
| [`with-tests`](https://github.com/agentlyhq/aixyz/tree/HEAD/examples/with-tests/) | Agent with test examples |
| [`fake-llm`](https://github.com/agentlyhq/aixyz/tree/HEAD/examples/fake-llm/) | Fully deterministic testing with `fake()` model |
| [`with-vercel-blob`](https://github.com/agentlyhq/aixyz/tree/HEAD/examples/with-vercel-blob/) | MCP-only txt storage using Vercel Blob |
## CLI
```bash
bun add aixyz # CLI included with the aixyz package
bunx aixyz --help # or run without installing
```
```bash
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](https://aixyz.sh/packages/aixyz) 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
```bash
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
