### Quick Start Installation and Execution

Source: https://github.com/agentlyhq/aixyz/blob/main/examples/local-llm/README.md

Install dependencies and start the development server. The model is downloaded and cached on the first run.

```bash
bun install

# First run downloads the model (~1 GB) — subsequent runs use the cache
bun run dev
```

--------------------------------

### Run Development Server

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/templates/advanced/with-custom-facilitator.mdx

Commands to navigate to the example directory, install dependencies, and start the development server.

```bash
cd examples/with-custom-facilitator
bun install
bun run dev
```

--------------------------------

### Run Express Integration Example

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/templates/advanced/with-express.mdx

Commands to install dependencies and start the development server for the Express integration example.

```bash
cd examples/with-express
bun install
bun run dev
```

--------------------------------

### Install Dependencies and Run Development Server

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/templates/advanced/with-custom-server.mdx

These bash commands are used to navigate to the example directory, install project dependencies, and start the development server.

```bash
cd examples/with-custom-server
bun install
bun run dev
```

--------------------------------

### Quick Start Commands

Source: https://github.com/agentlyhq/aixyz/blob/main/examples/sub-agents/README.md

Commands to install dependencies, configure environment variables, and start the development server.

```bash
bun install

# Create .env.local with your keys
echo "OPENAI_API_KEY=sk-..." > .env.local

bun run dev
```

--------------------------------

### Initialize and run the agent

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/packages/create-aixyz-app.mdx

Navigate to the project directory, install dependencies, and start the development server.

```bash
cd my-agent
bun install
bun run dev
```

--------------------------------

### Install Dependencies

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/templates/basic/local-llm.mdx

Installs project dependencies using Bun. Navigate to the example directory first.

```bash
cd examples/local-llm
bun install
```

--------------------------------

### Run Development Server

Source: https://github.com/agentlyhq/aixyz/blob/main/examples/with-vercel-blob/README.md

Install dependencies and start the local development server.

```bash
bun install
bun run dev
```

--------------------------------

### Install Dependencies and Run Agent

Source: https://github.com/agentlyhq/aixyz/blob/main/examples/boilerplate/README.md

Installs project dependencies using bun, sets up the OpenAI API key in a .env.local file, and starts the development server.

```bash
bun install

# Create .env.local with your keys
echo "OPENAI_API_KEY=sk-...".env.local

bun run dev
```

--------------------------------

### Full AixyzApp Server Example

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/api-reference/aixyz-server.mdx

Example demonstrating the setup of an AixyzApp server, including registration of SessionPlugin, IndexPagePlugin, and A2APlugin, followed by initialization.

```typescript
import { AixyzApp } from "aixyz/app";
import { SessionPlugin } from "aixyz/app/plugins/session";
import { IndexPagePlugin } from "aixyz/app/plugins/index-page";
import { A2APlugin } from "aixyz/app/plugins/a2a";
import * as agent from "./agent";

const server = new AixyzApp();

// SessionPlugin must be registered first so its middleware runs before other plugins
await server.withPlugin(new SessionPlugin());
await server.withPlugin(new IndexPagePlugin());
await server.withPlugin(new A2APlugin([{ exports: agent }]));

await server.initialize();

export default server;
```

--------------------------------

### Install Mintlify Skill

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/AGENTS.md

Install the Mintlify skill to access product knowledge. This command is used for first-time setup.

```bash
npx skills add https://mintlify.com/docs
```

--------------------------------

### Install and Run Agent

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/templates/basic/boilerplate.mdx

Commands to install dependencies and start the development server for the boilerplate agent.

```bash
cd examples/boilerplate
bun install
bun run dev
```

--------------------------------

### Initialize the Development Environment

Source: https://github.com/agentlyhq/aixyz/blob/main/examples/flight-search/README.md

Commands to install dependencies, configure environment variables, and start the development server.

```bash
# Install dependencies
bun install

# Set up environment variables
cp .env.example .env
# Edit .env with your OPENAI_API_KEY

# Start development server
bun run dev
```

--------------------------------

### Run Project Locally

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/templates/basic/with-vercel-blob.mdx

Commands to install dependencies and start the development server.

```bash
cd examples/with-vercel-blob
bun install
bun run dev
```

--------------------------------

### Server Initialization Example

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/api-reference/aixyz-server.mdx

Example of how to construct and initialize an AixyzApp server with plugins.

```APIDOC
## Example

```typescript title="app/server.ts"
import { AixyzApp } from "aixyz/app";
import { SessionPlugin } from "aixyz/app/plugins/session";
import { IndexPagePlugin } from "aixyz/app/plugins/index-page";
import { A2APlugin } from "aixyz/app/plugins/a2a";
import * as agent from "./agent";

const server = new AixyzApp();

// SessionPlugin must be registered first so its middleware runs before other plugins
await server.withPlugin(new SessionPlugin());
await server.withPlugin(new IndexPagePlugin());
await server.withPlugin(new A2APlugin([{ exports: agent }]));

await server.initialize();

export default server;
```
```

--------------------------------

### AIXYZ CLI Quick Start

Source: https://github.com/agentlyhq/aixyz/blob/main/packages/aixyz-cli/README.md

Instructions on how to quickly run the AIXYZ CLI without installation, using package runners like Bun or npx.

```APIDOC
## Quick Start

Run without installing:

```bash
bunx aixyz-cli dev
npx aixyz-cli dev
```

> Note: Requires [Bun](https://bun.sh) to be installed on your system.
```

--------------------------------

### Run Development Server

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/templates/basic/local-llm.mdx

Starts the development server for the local LLM agent. Ensure dependencies are installed.

```bash
cd examples/local-llm
bun run dev
```

--------------------------------

### Example Agent Development and Build

Source: https://github.com/agentlyhq/aixyz/blob/main/AGENTS.md

Commands for developing and building example agents, including hot reloading and bundling for deployment.

```bash
cd examples/flight-search
bun run dev    # → aixyz dev (hot reload, watches app/ and aixyz.config.ts)
bun run build  # → aixyz build (bundles for deployment)
```

--------------------------------

### Example Agent Directory Structure

Source: https://github.com/agentlyhq/aixyz/blob/main/AGENTS.md

Standard file and directory structure for example agents within the 'examples' directory.

```bash
examples/*/:
  aixyz.config.ts     # Agent metadata and config (required)
  app/
    agent.ts          # Agent definition (optional, enables A2A endpoints)
    server.ts         # Custom server (optional, overrides auto-generation)
    accepts.ts        # Custom x402 facilitator (optional)
    tools/*.ts        # Tool implementations (files starting with _ ignored)
    icon.png          # Agent icon (served as static asset)
  vercel.json
```

--------------------------------

### Setup and Build Commands

Source: https://github.com/agentlyhq/aixyz/blob/main/AGENTS.md

Standard commands for setting up the project, building all packages, running tests, linting, formatting, and cleaning artifacts.

```bash
bun install                          # Setup
bun run build                        # Build all packages (turbo run build)
bun run test                         # Test all packages (turbo run test)
bun run lint                         # Lint all packages with --fix
bun run format                       # Format with Prettier (printWidth: 120)
bun run clean                        # Clean build artifacts
```

--------------------------------

### Start Development Server

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/getting-started/installation.mdx

Launch the development server to watch for file changes and host the agent.

```bash
bun run dev
```

--------------------------------

### Install and Run Tests

Source: https://github.com/agentlyhq/aixyz/blob/main/examples/fake-llm/README.md

Commands to install dependencies and execute the test suite.

```bash
bun install

# Run tests (no API key needed)
bun test
```

--------------------------------

### Install and Run CLI

Source: https://github.com/agentlyhq/aixyz/blob/main/README.md

Commands to install the aixyz package and access the help menu.

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

--------------------------------

### Install Dependencies

Source: https://github.com/agentlyhq/aixyz/blob/main/examples/with-custom-server/README.md

Install project dependencies using Bun.

```bash
bun install
```

--------------------------------

### Install Stripe Plugin

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/api-reference/experimental-stripe-payment-intent-plugin.mdx

Install the @aixyz/stripe package using bun.

```bash
bun add @aixyz/stripe
```

--------------------------------

### Initialize an aixyz project

Source: https://github.com/agentlyhq/aixyz/blob/main/README.md

Use the CLI to scaffold a new agent project and start the development server.

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

--------------------------------

### Agent example directory structure

Source: https://github.com/agentlyhq/aixyz/blob/main/CLAUDE.md

Standard file layout for agent examples in the examples directory.

```text
examples/*/ 
  aixyz.config.ts     # Agent metadata and config (required)
  app/
    agent.ts          # Agent definition (optional, enables A2A endpoints)
    server.ts         # Custom server (optional, overrides auto-generation)
    accepts.ts        # Custom x402 facilitator (optional)
    tools/*.ts        # Tool implementations (files starting with _ ignored)
    icon.png          # Agent icon (served as static asset)
  vercel.json
```

--------------------------------

### Install Dependencies and Configure Environment

Source: https://github.com/agentlyhq/aixyz/blob/main/examples/chainlink/README.md

Installs project dependencies using bun and sets up the local environment variables required for the agent to run. Ensure you replace placeholder values with your actual keys and addresses.

```bash
bun install

# Create .env.local with your keys
cat > .env.local <<EOF
OPENAI_API_KEY=sk-...
X402_PAY_TO=0xYourAddress
X402_NETWORK=eip155:8453
EOF

bun run dev
```

--------------------------------

### Initialize and Run Aixyz Project

Source: https://context7.com/agentlyhq/aixyz/llms.txt

Use the CLI scaffolding tool to create a new project and start the development server.

```bash
# Create a new agent project
bunx create-aixyz-app my-agent

# Navigate and start development server
cd my-agent
bun run dev
```

--------------------------------

### AIXYZ CLI Installation

Source: https://github.com/agentlyhq/aixyz/blob/main/packages/aixyz-cli/README.md

Instructions for installing the AIXYZ CLI using Bun.

```APIDOC
## Installation

```bash
bun add aixyz-cli
```
```

--------------------------------

### Install Bun

Source: https://github.com/agentlyhq/aixyz/blob/main/skills/aixyz-on-openclaw/SKILL.md

Commands to install the Bun runtime on macOS, Linux, or Windows.

```bash
# macOS / Linux
curl -fsSL https://bun.sh/install | bash

# Windows (PowerShell, requires WSL or Windows 10+)
powershell -c "irm bun.sh/install.ps1 | iex"
```

--------------------------------

### Install Dependencies and Run Tests

Source: https://github.com/agentlyhq/aixyz/blob/main/examples/with-tests/README.md

Installs project dependencies and runs unit or end-to-end tests using bun:test. Ensure OPENAI_API_KEY is set for integration tests.

```bash
bun install

# Run unit tests (no API key required)
bun test app/agent.test.ts

# Run end-to-end test (builds the agent first)
bun test server.e2e.test.ts
```

--------------------------------

### Clone and List Agently Examples

Source: https://github.com/agentlyhq/aixyz/blob/main/skills/aixyz/SKILL.md

Use the GitHub CLI to clone the AgentlyHQ/aixyz repository and list the contents of the examples directory to find working agent implementations.

```bash
gh repo clone AgentlyHQ/aixyz
ls aixyz/examples/
```

--------------------------------

### Start Development Server

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/packages/aixyz.mdx

Run the development server with hot reload. Use the --port flag to specify a custom port.

```bash
aixyz dev
aixyz dev --port 4000
```

--------------------------------

### Verify Bun Installation

Source: https://github.com/agentlyhq/aixyz/blob/main/skills/aixyz-on-openclaw/SKILL.md

Check the installed version of Bun.

```bash
bun --version   # should print 1.3 or higher
```

--------------------------------

### Install @aixyz/erc-8004

Source: https://github.com/agentlyhq/aixyz/blob/main/packages/aixyz-erc-8004/README.md

Install the package using your preferred package manager.

```bash
bun add @aixyz/erc-8004
# or
npm install @aixyz/erc-8004
```

--------------------------------

### Run Agent Locally

Source: https://github.com/agentlyhq/aixyz/blob/main/skills/aixyz-on-openclaw/SKILL.md

Start the development server to test the agent.

```bash
bun run dev
# Agent is now live at http://localhost:3000
```

--------------------------------

### Install aixyz

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/packages/aixyz.mdx

Install the aixyz package to access the CLI command.

```bash
bun add aixyz
```

--------------------------------

### Run Tests and Agent

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/templates/advanced/fake-llm.mdx

Commands to install dependencies and execute the test suite or development server.

```bash
cd examples/fake-llm
bun install
bun test
```

```bash
cd examples/fake-llm
bun run dev
```

--------------------------------

### Usage Example

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/api-reference/accepts.mdx

Demonstrates how agents and tools declare an `accepts` export to control x402 payment gating.

```APIDOC
## Usage

Agents and tools declare an `accepts` export to control x402 payment gating. Endpoints without `accepts` are **not registered**.

```typescript title="app/agent.ts"
import type { Accepts } from "aixyz/accepts";

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

```typescript title="app/tools/lookup.ts"
import type { Accepts } from "aixyz/accepts";

export const accepts: Accepts = {
  scheme: "free",
};
```
```

--------------------------------

### Run Tests and Agent Commands

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/templates/advanced/with-tests.mdx

Commands to install dependencies and execute tests or the development server.

```bash
cd examples/with-tests
bun install
bun test
```

```bash
cd examples/with-tests
bun run dev
```

--------------------------------

### Install aixyz-cli

Source: https://github.com/agentlyhq/aixyz/blob/main/packages/aixyz-cli/README.md

Add the aixyz-cli package to your project dependencies using Bun.

```bash
bun add aixyz-cli
```

--------------------------------

### Install Stripe Packages

Source: https://github.com/agentlyhq/aixyz/blob/main/examples/flight-search/README.md

Install the necessary Stripe packages for your React project using npm.

```bash
npm install @stripe/stripe-js @stripe/react-stripe-js
```

--------------------------------

### Start aixyz-cli development server

Source: https://github.com/agentlyhq/aixyz/blob/main/packages/aixyz-cli/README.md

Launch a local development server with file watching and auto-restart capabilities. You can specify a custom port.

```bash
aixyz-cli dev
aixyz-cli dev --port 8080
```

--------------------------------

### Custom Server Configuration with MCPPlugin

Source: https://github.com/agentlyhq/aixyz/blob/main/examples/with-custom-server/README.md

This server.ts example demonstrates how to manually register tools with pricing using MCPPlugin, omitting 'accepts' from the tool itself.

```typescript
// app/server.ts
import { MCPPlugin } from "aixyz/app/plugins/mcp";
import lookup from "./tools/lookup";

await server.withPlugin(
  new MCPPlugin([
    {
      name: "latestData",
      exports: {
        default: lookup,
        accepts: { scheme: "exact", price: "$0.001" },
      },
    },
  ]),
);
```

--------------------------------

### Payment-Gated Tool Setup

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/protocols/mcp.mdx

Configure a tool to require x402 payment by providing an `accepts` configuration during registration. This tool requires $0.001 per invocation.

```typescript
// This tool requires $0.001 per invocation
await server.withPlugin(
  new MCPPlugin([
    {
      name: "premiumSearch",
      exports: {
        default: searchTool,
        accepts: { scheme: "exact", price: "$0.001" },
      },
    },
  ]),
);
```

--------------------------------

### Local Environment Variables Setup

Source: https://github.com/agentlyhq/aixyz/blob/main/examples/with-custom-server/README.md

Configure local environment variables for API keys and payment details.

```env
OPENAI_API_KEY=sk-...
X402_PAY_TO=0xYourAddress
X402_NETWORK=eip155:8453
```

--------------------------------

### Manual MCP Setup

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/protocols/mcp.mdx

Wire up MCP manually with the MCPPlugin if using a custom server. Register tools and mount the /mcp endpoint.

```typescript
import { MCPPlugin } from "aixyz/app/plugins/mcp";
import * as lookup from "./tools/lookup";

// Register tools and mount the /mcp endpoint
await server.withPlugin(
  new MCPPlugin([
    {
      name: "lookup",
      exports: {
        default: lookup.default,
        accepts: { scheme: "exact", price: "$0.001" },
      },
    },
  ]),
);
```

--------------------------------

### Custom Server Setup with IndexPagePlugin

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/api-reference/unstable-with-index-page.mdx

Manually registers the IndexPagePlugin in a custom server configuration. Ensure to call server.initialize() after registering plugins.

```typescript
import { AixyzApp } from "aixyz/app";
import { IndexPagePlugin } from "aixyz/app/plugins/index-page";

const server = new AixyzApp();

// Mount at root (default)
await server.withPlugin(new IndexPagePlugin());

await server.initialize();

export default server;
```

--------------------------------

### Build Custom Server with AixyzApp

Source: https://context7.com/agentlyhq/aixyz/llms.txt

Set up a custom server using AixyzApp, manually registering plugins for full control over routing and middleware. Includes examples for A2A, MCP, and ERC8004 plugins.

```typescript
// app/server.ts
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 { SessionPlugin } from "aixyz/app/plugins/session";
import { ERC8004Plugin } from "aixyz/app/plugins/erc-8004";
import { facilitator } from "aixyz/accepts";

import * as agent from "./agent";
import * as researchAgent from "./agents/research";
import lookup from "./tools/lookup";
import erc8004 from "./erc-8004";

// Create app with x402 facilitator
const app = new AixyzApp({ facilitators: facilitator });

// Register plugins (order matters - session should be first)
await app.withPlugin(new SessionPlugin());
await app.withPlugin(new IndexPagePlugin("/"));

// A2A plugin - supports multiple agents with path prefixes
await app.withPlugin(
  new A2APlugin([
    { exports: agent }, // → /agent, /.well-known/agent-card.json
    { name: "research", exports: researchAgent }, // → /research/agent
  ])
);

// MCP plugin - register tools with optional payment
await app.withPlugin(
  new MCPPlugin([
    {
      name: "lookup",
      exports: {
        default: lookup,
        accepts: { scheme: "exact", price: "$0.001" },
      },
    },
  ])
);

// ERC-8004 identity plugin
await app.withPlugin(
  new ERC8004Plugin({
    default: erc8004,
    options: { a2a: ["/agent"], mcp: true },
  })
);

// Initialize all plugins
await app.initialize();

export default app;

```

--------------------------------

### Mount Sub-Agents with A2APlugin

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/protocols/a2a.mdx

TypeScript example demonstrating how to mount multiple sub-agents using A2APlugin, each with a unique name to define their respective paths.

```typescript
import * as research from "./agents/research";
import * as implement from "./agents/implement";

await server.withPlugin(
  new A2APlugin([
    { exports: agent }, // → /agent
    { name: "research", exports: research }, // → /research/agent
    { name: "implement", exports: implement }, // → /implement/agent
  ]),
);
```

--------------------------------

### Vercel Configuration for Bun

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/getting-started/why-bun.mdx

This JSON configuration specifies the build command and Bun version for deploying a Bun project to Vercel, optimizing for fast cold starts.

```json
{
  "buildCommand": "bun run build",
  "bunVersion": "1.x"
}
```

--------------------------------

### Register IndexPagePlugin

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/api-reference/unstable-with-index-page.mdx

Installs the IndexPagePlugin into the server. This is automatically handled when using the default AixyzApp setup.

```typescript
import { IndexPagePlugin } from "aixyz/app/plugins/index-page";

await server.withPlugin(new IndexPagePlugin());
```

--------------------------------

### Implement Custom RedisSessionStore

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/api-reference/session-plugin.mdx

Create a custom session store by implementing the SessionStore interface for use with Redis. This example shows basic get, set, delete, and list operations.

```typescript
import { defineSessionStore } from "aixyz/app/plugins/session";
import type { SessionStore, ListOptions, SetOptions } from "aixyz/app/plugins/session";

class RedisSessionStore implements SessionStore {
  async get(payer: string, key: string) {
    return (await redis.get(`${payer}:${key}`)) ?? undefined;
  }
  async set(payer: string, key: string, value: string, options?: SetOptions) {
    if (options?.ttlMs) {
      await redis.set(`${payer}:${key}`, value, "PX", options.ttlMs);
    } else {
      await redis.set(`${payer}:${key}`, value);
    }
  }
  async delete(payer: string, key: string) {
    return (await redis.del(`${payer}:${key}`)) > 0;
  }
  async list(payer: string, options?: ListOptions) {
    // scan for keys matching payer prefix, apply options.prefix/limit/cursor
    return {
      entries: {
        /* ... */
      },
    };
  }
}

export default defineSessionStore(new RedisSessionStore());
```

--------------------------------

### Define Weather Tool

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/api-reference/tools.mdx

Example of a tool definition file for getting current weather conditions. It includes necessary imports, payment configuration, and the tool's description, input schema, and execution logic.

```typescript
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 implementation
  },
});
```

--------------------------------

### Run aixyz-cli without installation

Source: https://github.com/agentlyhq/aixyz/blob/main/packages/aixyz-cli/README.md

Execute the aixyz-cli commands directly without a prior installation using bunx or npx. Requires Bun to be installed.

```bash
bunx aixyz-cli dev
npx aixyz-cli dev
```

--------------------------------

### Build Project

Source: https://github.com/agentlyhq/aixyz/blob/main/examples/with-custom-server/README.md

Build the project for production using Bun.

```bash
bun run build
```

--------------------------------

### Preview Documentation Locally

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/AGENTS.md

Run this command to preview your documentation site locally. Ensure you are in the project directory.

```bash
mint dev
```

--------------------------------

### Configure Foundry and Import Contracts

Source: https://github.com/agentlyhq/aixyz/blob/main/packages/aixyz-erc-8004/README.md

Set up remappings in foundry.toml and import the necessary Solidity contracts.

```toml
# foundry.toml
remappings = ["@aixyz/erc-8004/=node_modules/@aixyz/erc-8004/"]
```

```solidity
import { IdentityRegistryUpgradeable } from "@aixyz/erc-8004/contracts/IdentityRegistryUpgradeable.sol";
import { ReputationRegistryUpgradeable } from "@aixyz/erc-8004/contracts/ReputationRegistryUpgradeable.sol";
import { ValidationRegistryUpgradeable } from "@aixyz/erc-8004/contracts/ValidationRegistryUpgradeable.sol";
```

--------------------------------

### Scaffold a New Project

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/getting-started/installation.mdx

Initialize a new agent project using the create-aixyz-app CLI.

```bash
bunx create-aixyz-app my-agent
cd my-agent
```

```bash
bunx create-aixyz-app my-agent -y
```

--------------------------------

### Scaffold a New Agent Project

Source: https://github.com/agentlyhq/aixyz/blob/main/skills/aixyz-on-openclaw/SKILL.md

Initialize a new project using the aixyz CLI.

```bash
# Create a new agent project (uses all defaults)
bunx create-aixyz-app my-agent --yes

cd my-agent
```

--------------------------------

### Agent Card Example Response

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/protocols/a2a.mdx

An example JSON response for an agent card, detailing name, description, protocol version, capabilities, and skills.

```json
{
  "name": "Weather Agent",
  "description": "Get current weather for any location worldwide.",
  "protocolVersion": "0.3.0",
  "version": "0.1.0",
  "url": "https://my-agent.vercel.app/agent",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {
      "id": "get-weather",
      "name": "Get Weather",
      "description": "Get current weather conditions for any city",
      "tags": ["weather"],
      "examples": ["What's the weather in Tokyo?"]
    }
  ]
}
```

--------------------------------

### Development Commands

Source: https://github.com/agentlyhq/aixyz/blob/main/examples/flight-search/README.md

Standard commands for building, testing, and running the production server.

```bash
# Build
bun run build

# Test
bun run test

# Start production server
bun run start
```

--------------------------------

### POST /initialize

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/api-reference/aixyz-server.mdx

Initialize the payment gateway and plugins for the AixyzApp server.

```APIDOC
## POST /initialize

### Description
Initialize payment gateway and plugins. Passes an `InitializeContext` with read access to all routes, registered plugins, and payment gateway. Must be called after all plugins are registered.

### Method
POST

### Endpoint
`/initialize`

### Parameters
None

### Request Example
```typescript
await server.initialize();
```

### Response
#### Success Response (200)
- **status** (string) - Indicates that the server initialization is complete.

#### Response Example
```json
{
  "status": "Server initialized successfully"
}
```
```

--------------------------------

### GET /mcp

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/protocols/mcp.mdx

Establishes an SSE stream for server-initiated messages to the MCP client.

```APIDOC
## GET /mcp

### Description
Establishes an SSE stream for server-initiated messages to the MCP client.

### Method
GET

### Endpoint
/mcp
```

--------------------------------

### Sub-Agent Definition Pattern

Source: https://github.com/agentlyhq/aixyz/blob/main/examples/sub-agents/README.md

Example of defining a sub-agent where the filename dictates the URL prefix.

```typescript
// app/agents/math.ts  →  /math/agent
export const accepts: Accepts = { scheme: "exact", price: "$0.001" };
export default new ToolLoopAgent({ ... });
```

--------------------------------

### Install use-agently Skill

Source: https://github.com/agentlyhq/aixyz/blob/main/skills/aixyz-on-openclaw/SKILL.md

Add the skill to enable discovery and calling of the local agent.

```bash
npx skills add https://github.com/agentlyhq/use-agently --skill use-agently
```

--------------------------------

### Verify Bun Version

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/getting-started/installation.mdx

Check that the installed Bun version meets the minimum requirement of 1.3.9.

```bash
bun --version  # Should be ≥ 1.3.9
```

--------------------------------

### Scaffold a new project

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/packages/create-aixyz-app.mdx

Initialize a new agent project using the CLI. This command prompts for the agent name and optional OpenAI API key.

```bash
bunx create-aixyz-app my-agent
```

--------------------------------

### aixyz dev

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/packages/aixyz.mdx

Starts a local development server with hot reload capabilities for agent development.

```APIDOC
## aixyz dev

### Description
Starts a local development server with hot reload. Watches `app/` and `aixyz.config.ts` for changes and restarts automatically.

### Parameters
#### Flags
- **-p, --port** (number) - Optional - Port to listen on (Default: 3000)
```

--------------------------------

### Build Agent for Deployment

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/packages/aixyz.mdx

Bundle the agent using different output formats. Standalone is the default.

```bash
aixyz build                       # Standalone (default)
aixyz build --output standalone   # Explicit standalone
aixyz build --output vercel       # Vercel Build Output API v3
aixyz build --output executable   # Self-contained binary
```

--------------------------------

### Wire the fake model into an agent

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/api-reference/aixyz-model-fake.mdx

Example of integrating the fake model into a ToolLoopAgent for testing agent logic.

```typescript
import { fake } from "aixyz/model";
import { ToolLoopAgent } from "ai";

export const model = fake((input) => `Echo: ${input}`);

export default new ToolLoopAgent({
  model,
  instructions: "You echo back whatever the user says.",
});
```

--------------------------------

### Build and Deploy Agent

Source: https://github.com/agentlyhq/aixyz/blob/main/examples/boilerplate/README.md

Bundles the agent for deployment and deploys it to Vercel.

```bash
bun run build   # bundle for deployment
vercel          # deploy to Vercel
```

--------------------------------

### Get Payer Address

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/api-reference/session-plugin.mdx

Retrieve the x402 signer address for the current session. This is a shorthand for getSession()?.payer.

```typescript
import { getPayer } from "aixyz/app/plugins/session";

const payer = getPayer(); // "0x1234..."
```

--------------------------------

### Configure dynamic payment networks

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/config/aixyz-config.mdx

Demonstrates how to switch payment networks based on the environment using process.env.

```typescript
x402: {
  payTo: "0x...",
  network: process.env.NODE_ENV === "production" ? "eip155:8453" : "eip155:84532",
},
```

--------------------------------

### Get Runtime Aixyz Config

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/api-reference/aixyz-config.mdx

Retrieves the runtime-safe subset of the agent configuration. Use this in server code.

```typescript
const config = getAixyzConfigRuntime();
console.log(config.name, config.version);
```

--------------------------------

### Build and Deploy Agent

Source: https://github.com/agentlyhq/aixyz/blob/main/examples/chainlink/README.md

Builds the project for deployment and deploys it using Vercel. This command prepares the agent for production.

```bash
bun run build
vercel
```

--------------------------------

### Authenticate with x402 Cryptocurrency Payment

Source: https://github.com/agentlyhq/aixyz/blob/main/examples/flight-search/README.md

Example of how to include the x402 payment proof in the request header for protected endpoints.

```bash
curl -X POST http://localhost:3000/agent \
  -H "Content-Type: application/json" \
  -H "X-Payment: <x402-payment-proof>" \
  -d '{"jsonrpc": "2.0", "method": "message/send", ...}'
```

--------------------------------

### Get Full Aixyz Config

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/api-reference/aixyz-config.mdx

Retrieves the full parsed agent configuration. Intended for build-time and CLI use.

```typescript
const config = getAixyzConfig();
console.log(config.x402.payTo);
```

--------------------------------

### Docker Build and Run Commands

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/getting-started/deploying.mdx

Build a Docker image for your agent and run it as a container, exposing the specified port and passing necessary environment variables.

```bash
docker build -t my-agent .
docker run -p 3000:3000 \
  -e OPENAI_API_KEY=sk-... \
  -e PORT=3000 \
  my-agent
```

--------------------------------

### Define Custom Session Store

Source: https://github.com/agentlyhq/aixyz/blob/main/docs/api-reference/session-plugin.mdx

Configure a custom session store by defining app/session.ts. This example uses an in-memory store.

```typescript
import { defineSessionStore, InMemorySessionStore } from "aixyz/app/plugins/session";

export default defineSessionStore(new InMemorySessionStore());
```