Warden Code

Overview

Warden Code is a CLI for scaffolding production-ready AI Agents compatible with Warden.

Generated Agents also support open standards such as the A2A protocol, x402 payments, and ERC-8004 identity, which allows them to function across the broader Agent ecosystem.

This article is a reference covering the main features of Warden Code. For getting started with Agent development, see Build an Agent with Warden Code.

GitHub

Warden Code is available on GitHub: warden-code.

Key features

Agents generated with Warden Code support the following key capabilities:

• Compatibility with Warden
• Discoverability outside of Warden through ERC-8004 identity registries
• Interaction with other Agents through the A2A protocol
• Monetization through x402 payments
• Endpoints compatible with the LangGraph Agent Server API
• Built-in chat UI that automatically loads the A2A Agent Card and x402 wallets
• The AI-powered build mode allowing you to implement custom Agent logic with an AI assistant

To learn more, see Warden Agent capabilities.

Basics

Installation

Use the npm commands below to install, update, and run Warden Code. This requires Node.js 18 or higher.

Install globally:

npm install -g warden-code

Update:

npm install -g warden-code

Run:

warden

CLI commands

With Warden Code, you can use the command line to generate a project, edit your code with an AI assistant, configure your Agent, and much more.

Run warden to initiate Warden Code and use the following commands:

Command	Description	Guides
/new	Create a new Agent interactively	Create a new Agent
/build	Enter the AI-powered mode to build your Agent	Implement custom logic
/chat	Chat with a running Agent using A2A or LangGraph	Test the Agent locally
/config	View and edit the Agent configuration	Configure the Agent
/register	Register the Agent onchain (ERC-8004)	Register on ERC-8004
/activate	Activate a registered Agent onchain (ERC-8004)
/deactivate	Deactivate a registered Agent onchain (ERC-8004)
/help	Show available commands	N/A
/clear	Clear the terminal screen	N/A
/exit	Exit the CLI	N/A

Running the Agent

The npm commands below allow you to build and initiate your Agent. Navigate to your project's root directory and run them in a separate terminal window.

Build:

npm run build

Run:

npm start

Run with x402 payments temporarily disabled:

X402=false npm start

Project structure

When you create a new Agent, Warden Code generates the following project structure:

my-agent/
├── src/
│   ├── agent.ts      # Your Agent's logic: the handler function
│   ├── server.ts     # Server setup, static file serving, protocol routing
│   └── payments.ts   # x402 payment setup (created only if you enable x402)
├── public/
│   ├── index.html    # The chat frontend: auto-loads the A2A Agent Card, x402 wallets
│   └── .well-known/
│       ├── agent-card.json           # The A2A Agent Card: the identity, capabilities, skills
│       └── agent-registration.json   # ERC-8004 registration metadata
├── package.json
├── tsconfig.json
├── Dockerfile
├── .env.example
└── .gitignore

Agent models

Depending on the choices you make when creating an Agent, Warden Code uses one of the supported Agent models:

• OpenAI + Streaming: A GPT-powered Agent with streaming responses
• OpenAI + Multi-turn: A GPT-powered Agent with conversation history
• Blank + Streaming: A minimal streaming Agent that echoes input
• Blank + Multi-turn: A minimal multi-turn conversation agent

Build mode

You can edit your Agent through the CLI, in the AI-powered build mode. It supports the following LLM providers:

• OpenAI (default)
• Anthropic

To start, use the /build command and set up an LLM provider. For a full step-by-step guide, see Build with AI.

In the build mode, you can prompt the assistant and use the following commands:

Command	Description
/model	Switch between LLM providers and models at any moment.
/rebuild	Rebuild the project. This triggers npm run build.
/chat	Chat with the Agent. The URL is resolved from .env.
/exit	Exit the build mode.

API server

Agents generated with Warden Code use a server that exposes two types of endpoints: A2A and LangGraph. For more details, see the reference sections below.

note

You can find the server setup src/server.ts.

When you create an Agent, Warden Code generates a random Agent API key. By default, the server requires it for authentication.

important

The Agent API key is stored in the .env file as AGENT_API_KEY.

This key is used in the following ways:

• API requests
  POST requests require authentication, while GET requests remain public. The key must be passed as a Bearer token in the Authorization header:

  -H "Authorization: Bearer AGENT_API_KEY"

• CLI usage
  If you chat with your Agent using the /chat command, it automatically reads AGENT_API_KEY from .env. If no key is found or the key is rejected, Warden Code prompts you for a valid key.

• Usage with x402
  When x402 payments are enabled, API key authentication takes priority. Requests with a valid Bearer token bypass the payment middleware entirely. Requests without a valid key fall through to the x402 payment flow.

Tips

• To rotate the key, replace the value and restart or redeploy the Agent server.
• To disable authentication, remove the AGENT_API_KEY line from .env. In production, omit the variable from the hosting service configuration.

x402 payments

Every scaffolded Agent includes x402 payment infrastructure—Coinbase's HTTP 402 payment protocol.

Enabling/disabling

x402 payments are disabled by default. This is how you can enable them:

• When creating a new Agent, choose Enable x402 payments.
• After creating an Agent, run /config and select Payments.
• You can also directly edit x402 parameters in the .env file.

To disable x402 payments for testing purposes, you can do the following:

• Start the Agent with X402=false npm start
• Remove all X402_<PREFIX>_PAY_TO values from the .env file

tip

Alternatively, you can keep API key authentication enabled and bypass payments in the chat mode.

Parameters

When enabling x402 payments, you need to specify x402 parameters, which are stored in the .env file. Each payment network has its own set of variables, differentiated by prefixes.

Name	Variable	Description
Network	X402_<PREFIX>_NETWORK	The network for receiving payments, identified by ID. For development, use test chains: they require no real funds. See the supported networks.
Wallet	X402_<PREFIX>_PAY_TO	Your EVM wallet address for receiving payments (0x + 40 hex characters).
Price	X402_<PREFIX>_PRICE	The preferred price per request. It's set in USDC and defaults to 0.01. Removing this value disables the corresponding network.
Facilitator	X402_FACILITATOR_URL	The preferred facilitator for processing payments. Warden Code automatically enables one of the default facilitators, but you can edit this value in the .env file.

Networks

The available payment networks are listed below.

Each network has its own set of parameters in the .env file, differentiated by prefixes, and the default faciliatator.

Network	ID	Currency	Facilitator	Prefix
Base Sepolia (testnet)	eip155:84532	test USDC	x402.org	X402_BASE_SEPOLIA
Base (mainnet)	eip155:8453	real USDC	PayAI	X402_BASE

You can find all networks with their parameters .env.example:

X402_FACILITATOR_URL=https://x402.org/facilitator

# Base Sepolia (testnet)
X402_BASE_SEPOLIA_PAY_TO=
X402_BASE_SEPOLIA_PRICE=0.01
X402_BASE_SEPOLIA_NETWORK=eip155:84532

# Base (mainnet)
# X402_BASE_PAY_TO=
# X402_BASE_PRICE=0.01
# X402_BASE_NETWORK=eip155:8453

Facilitators

A payment facilitator is a service that handles verifying and submitting x402 payments.

When you enable x402, Warden code automatically selects one of the following facilitators (based on the network):

• Testnets: x402.org
• Mainnets: PayAI

The PayAI facilitator offers 1,000 free settlements per month. For higher volumes, create a merchant account at merchant.payai.network and add the following variables to your .env file:

• PAYAI_API_KEY_ID
• PAYAI_API_KEY_SECRET

note

Authentication is handled automatically by the @payai/facilitator package when the facilitator URL contains payai.network.

Dependencies

When x402 is enabled, the following packages are added to the generated Agent's dependencies:

• express and @types/express
• @x402/express (payment middleware)
• @x402/core (protocol types and facilitator client)
• @payai/facilitator (facilitator authentication)
• @x402/evm (EVM payment scheme verification)

Payment flow

Clients that support x402 (such as @x402/fetch) handle the payment flow automatically:

1. The server returns a HTTP 402 response with payment requirements.
2. The client signs a USDC transaction.
3. The server verifies the payment before processing the request.

A2A endpoints & methods

All Warden Agents are immediately compatible with the A2A protocol, supporting the Agent Card and the JSON-RPC endpoint with the core methods.

To learn more, see the A2A specification.

Agent Card

Name	Method	Endpoint
Get Agent Card	GET	/.well-known/agent-card.json
A2A JSON-RPC	POST	/

JSON-RPC endpoint

Name	Method	Endpoint
A2A JSON-RPC	POST	/

This endpoint uses just the base URL. To run a specific A2A method, specify it in the request body:

Name	Method	JSON-RPC method
Send Message	POST	message/send
Send Streaming Message	POST	message/stream
Get Task	POST	tasks/get
Cancel Task	POST	tasks/cancel
Subscribe to Task	POST	tasks/resubscribe

You can find detailed descriptions of all methods in the sections below.

Send Message

Postman

POST BASE_URL
Headers: Content-Type: application/json
Authorization: Type: Bearer Token, Token: AGENT_API_KEY
Body:

{
  "jsonrpc": "2.0",
  "id": "",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "PROMPT_TEXT"
        }
      ],
      "messageId": ""
    },
    "thread": {
      "threadId": ""
    }
  }
}

cURL

curl BASE_URL \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer AGENT_API_KEY' \
  --data '{
    "jsonrpc": "2.0",
    "id": "",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "PROMPT_TEXT"
          }
        ],
        "messageId": ""
      },
      "thread": {
        "threadId": ""
      }
    }
  }'

tip

This method returns a result object containing the LLM response, conversation history, and execution status. Task methods require the task ID, which is returned as result.id.

Send Streaming Message

Postman

POST BASE_URL
Headers: Content-Type: application/json
Authorization: Type: Bearer Token, Token: AGENT_API_KEY
Body:

{
  "jsonrpc": "2.0",
  "id": "",
  "method": "message/stream",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "PROMPT_TEXT"
        }
      ],
      "messageId": ""
    },
    "thread": {
      "threadId": ""
    }
  }
}

cURL

curl BASE_URL \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer AGENT_API_KEY' \
  --data '{
    "jsonrpc": "2.0",
    "id": "",
    "method": "message/stream",
    "params": {
      "message": {
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "PROMPT_TEXT"
          }
        ],
        "messageId": ""
      },
      "thread": {
        "threadId": ""
      }
    }
  }'

tip

This method streams task status updates. When the response is ready, the stream includes the generated LLM message. Task methods require the task ID, which is returned as result.id.

Get Task

Postman

POST BASE_URL
Headers: Content-Type: application/json
Authorization: Type: Bearer Token, Token: AGENT_API_KEY
Body:

{
  "jsonrpc": "2.0",
  "id": "",
  "method": "tasks/get",
  "params": {
    "id": ""
  }
}

cURL

curl BASE_URL \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer AGENT_API_KEY' \
  --data '{
    "jsonrpc": "2.0",
    "id": "",
    "method": "tasks/get",
    "params": {
      "id": "TASK_ID"
    }
  }'

tip

In params.id, specify the task ID. You can obtain this value from result.id, returned by Send Message or Send Streaming Message.

Cancel Task

Postman

POST BASE_URL
Headers: Content-Type: application/json
Authorization: Type: Bearer Token, Token: AGENT_API_KEY
Body:

{
  "jsonrpc": "2.0",
  "id": "",
  "method": "tasks/cancel",
  "params": {
    "id": "TASK_ID"
  }
}

cURL

curl BASE_URL \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer AGENT_API_KEY' \
  --data '{
    "jsonrpc": "2.0",
    "id": "",
    "method": "tasks/cancel",
    "params": {
      "id": "TASK_ID"
    }
  }'

tip

In params.id, specify the task ID. You can obtain this value from result.id, returned by Send Message or Send Streaming Message.

Subscribe to Task

Postman

POST BASE_URL
Headers: Content-Type: application/json
Authorization: Type: Bearer Token, Token: AGENT_API_KEY
Body:

{
  "jsonrpc": "2.0",
  "id": "",
  "method": "tasks/resubscribe",
  "params": {
    "id": "TASK_ID"
  }
}

cURL

curl BASE_URL \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer AGENT_API_KEY' \
  --data '{
    "jsonrpc": "2.0",
    "id": "",
    "method": "tasks/resubscribe",
    "params": {
      "taskId": "TASK_ID"
    }
  }'

tip

In params.id, specify the task ID. You can obtain this value from result.id, returned by Send Message or Send Streaming Message.

LangGraph endpoints

All Warden Agents are immediately compatible with the LangGraph Agent Server API.

Warden Code exposes a subset of this API. Below, you can find a full list of supported endpoints with links to the LangGraph API reference.

Assistants

Name	Method	Endpoint
Search Assistants	POST	/assistants/search
Get Assistant	GET	/assistants/{assistant_id}

Threads

Name	Method	Endpoint
Create Thread	POST	/threads
Search Threads	POST	/threads/search
Get Thread	GET	/threads/{thread_id}
Get Thread State	GET	/threads/{thread_id}/state
Get Thread History	GET	/threads/{thread_id}/history
Delete Thread	DELETE	/threads/{thread_id}

Thread runs

Name	Method	Endpoint
Create Background Run	POST	/threads/{thread_id}/runs
Create Run, Stream Output	POST	/threads/{thread_id}/runs/stream
Create Run, Wait for Output	POST	/threads/{thread_id}/runs/wait

Stateless runs

Name	Method	Endpoint
Create Run, Stream Output	POST	/runs/stream
Create Run, Wait for Output	POST	/runs/wait

System

Name	Method	Endpoint
Server Information	GET	/info
Health Check	GET	/ok

Functions

Coming soon.