\n\n## Documentation\n\nFull documentation, API reference, and guides at **[aixyz.sh](https://aixyz.sh)**.\n\n## Quick Start\n\n```bash\nbunx create-aixyz-app my-agent\ncd my-agent\nbun run dev\n```\n\nYour agent is running. It exposes:\n\n| Endpoint | Protocol | What it does |\n| ------------------------------ | -------- | ------------------------------------ |\n| `/.well-known/agent-card.json` | A2A | Agent discovery card |\n| `/agent` | A2A | JSON-RPC endpoint, x402 payment gate |\n| `/mcp` | MCP | Tool sharing with MCP clients |\n\n## How It Works\n\nAn aixyz agent has three parts: a config, an agent, and tools.\n\n### 1. Config\n\n`aixyz.config.ts` declares your agent's identity and payment address:\n\n```ts\nimport type { AixyzConfig } from \"aixyz/config\";\n\nconst config: AixyzConfig = {\n name: \"Weather Agent\",\n description: \"Get current weather for any location worldwide.\",\n version: \"0.1.0\",\n x402: {\n payTo: \"0x...\",\n network: \"eip155:8453\", // Base mainnet\n },\n};\n\nexport default config;\n```\n\n### 2. Agent\n\n`app/agent.ts` defines your agent and its payment price:\n\n```ts\nimport { openai } from \"@ai-sdk/openai\";\nimport { stepCountIs, ToolLoopAgent } from \"ai\";\nimport type { Accepts } from \"aixyz/accepts\";\nimport weather from \"./tools/weather\";\n\nexport const accepts: Accepts = {\n scheme: \"exact\",\n price: \"$0.005\",\n};\n\nexport default new ToolLoopAgent({\n model: openai(\"gpt-4o-mini\"),\n instructions: \"You are a helpful weather assistant.\",\n tools: { weather },\n stopWhen: stepCountIs(10),\n});\n```\n\n### 3. Tools\n\nEach file in `app/tools/` exports a Vercel AI SDK `tool` and an optional `accepts` for MCP payment gating:\n\n```ts\nimport { tool } from \"ai\";\nimport { z } from \"zod\";\nimport type { Accepts } from \"aixyz/accepts\";\n\nexport const accepts: Accepts = {\n scheme: \"exact\",\n price: \"$0.0001\",\n};\n\nexport default tool({\n description: \"Get current weather conditions for a city.\",\n inputSchema: z.object({\n location: z.string().describe(\"City name\"),\n }),\n execute: async ({ location }) => {\n // your logic here\n },\n});\n```\n\nThat's it. Run `bun run dev` and aixyz auto-generates the server, wires up A2A + MCP + x402, and starts serving.\n\n## Examples\n\n| Example | Description |\n| ---------------------------------------------------------------- | ----------------------------------------------- |\n| [`boilerplate`](./examples/boilerplate/) | Minimal starter (auto-generated server) |\n| [`chainlink`](./examples/chainlink/) | Chainlink data feeds with custom server |\n| [`flight-search`](./examples/flight-search/) | Flight search with Stripe payments |\n| [`local-llm`](./examples/local-llm/) | Local LLM via Docker (no external API) |\n| [`with-custom-facilitator`](./examples/with-custom-facilitator/) | Bring-your-own x402 facilitator |\n| [`with-custom-server`](./examples/with-custom-server/) | Custom server setup |\n| [`with-express`](./examples/with-express/) | Express middleware integration |\n| [`sub-agents`](./examples/sub-agents/) | Multiple A2A endpoints from one deployment |\n| [`with-tests`](./examples/with-tests/) | Agent with test examples |\n| [`fake-llm`](./examples/fake-llm/) | Fully deterministic testing with `fake()` model |\n| [`with-vercel-blob`](./examples/with-vercel-blob/) | MCP-only txt storage using Vercel Blob |\n\n## CLI\n\n```bash\nbun add aixyz # CLI included with the aixyz package\nbunx aixyz --help # or run without installing\n```\n\n```bash\naixyz dev # Dev server with hot reload\naixyz build # Bundle for deployment (standalone, Vercel, or executable)\naixyz erc-8004 register # Register on-chain agent identity\naixyz erc-8004 update # Update agent metadata URI\n```\n\nSee the [CLI reference](https://aixyz.sh/packages/aixyz) for all options.\n\n## Protocols\n\n**A2A (Agent-to-Agent)** — Agent discovery card + JSON-RPC endpoint. Other agents find yours and send tasks.\n\n**MCP (Model Context Protocol)** — Expose tools to any MCP client (Claude Desktop, VS Code, Cursor).\n\n**x402** — HTTP 402 micropayments. Per-request payment with cryptographic proof, verified on-chain.\n\n**ERC-8004** — On-chain agent identity on Ethereum, Base, Polygon, Scroll, Monad, BSC, or Gnosis.\n\n## Contributing\n\n\n\n```bash\nbun install # install dependencies\nbun run build # build all packages\nbun run test # run tests\nbun run format # format with Prettier\n```\n\nPRs welcome. Please ensure `bun run build && bun run test && bun run format` pass before submitting.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}
![\"aixyz\"](\"https://raw.githubusercontent.com/AgentlyHQ/aixyz/main/docs/logo/light.svg\"){kind=logo}
\n ![\"Version\"](\"https://img.shields.io/npm/v/aixyz?colorA=21262d&colorB=21262d&style=flat\")
![\"MIT](\"https://img.shields.io/npm/l/aixyz?colorA=21262d&colorB=21262d&style=flat\")