Skip to main content

aixyz.config.ts

Every aixyz project requires an aixyz.config.ts at the project root. This file defines your agent’s identity, payment settings, and skills. It is validated at build time using Zod schemas from @aixyz/config.
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",
  },
  skills: [
    {
      id: "get-weather",
      name: "Get Weather",
      description: "Get current weather conditions for any city",
      tags: ["weather"],
      examples: ["What's the weather in Tokyo?"],
    },
  ],
};

export default config;

Config Fields

FieldTypeRequiredDescription
namestringYesAgent display name
descriptionstringYesWhat the agent does
versionstringYesSemver version
urlstringNoAgent base URL (auto-detected on Vercel)
x402.payTostringYesEVM address to receive payments
x402.networkstringYesCAIP-2 chain ID (e.g. eip155:8453)
skillsAgentSkill[]YesSkills exposed in the A2A agent card

AgentSkill

FieldTypeRequiredDescription
idstringYesUnique skill identifier
namestringYesSkill display name
descriptionstringYesWhat the skill does
tagsstring[]YesCategorization tags
examplesstring[]NoExample prompts
inputModesstring[]NoInput MIME types
outputModesstring[]NoOutput MIME types

URL Resolution

If url is omitted, it is auto-detected in the following order:
  1. https://${VERCEL_PROJECT_PRODUCTION_URL} (Vercel production)
  2. https://${VERCEL_URL} (Vercel preview)
  3. http://localhost:3000 (fallback)

Payment Networks

NetworkCAIP-2 ID
Baseeip155:8453
Base Sepoliaeip155:84532
Ethereumeip155:1
Switch networks per environment:
x402: {
  payTo: "0x...",
  network: process.env.NODE_ENV === "production" ? "eip155:8453" : "eip155:84532",
},

Accepts

The accepts named export on agents and tools controls x402 payment gating:
import type { Accepts } from "aixyz/accepts";

// x402 payment
export const accepts: Accepts = {
  scheme: "exact",
  price: "$0.005",
};
With optional overrides:
export const accepts: Accepts = {
  scheme: "exact",
  price: "$0.005",
  network: "eip155:8453", // overrides config
  payTo: "0x...", // overrides config
};
Prices are USD strings: "$0.005", "$0.01", "$0.0001".

Environment Variables

Environment files are loaded in Next.js order: process.env.env.$(NODE_ENV).local.env.local.env.$(NODE_ENV).env
VariableDescription
OPENAI_API_KEYOpenAI API key
X402_PAY_TODefault payment recipient address
X402_NETWORKDefault payment network
X402_FACILITATOR_URLCustom x402 facilitator URL
CDP_API_KEY_IDCoinbase CDP key ID (switches to Coinbase facilitator)
CDP_API_KEY_SECRETCoinbase CDP key secret
STRIPE_SECRET_KEYExperimental Stripe adapter
STRIPE_PRICE_CENTSStripe price in cents (default: 100)

Build-Time vs Runtime Config

@aixyz/config exposes two functions:
FunctionUsageDescription
getAixyzConfig()Build-timeFull config including all fields for the build pipeline
getAixyzConfigRuntime()RuntimeSubset safe for inclusion in runtime bundles
The AixyzConfigPlugin build plugin materializes the resolved config into the bundle, replacing aixyz/config imports so the runtime bundle does not need the config file.