A2A Setup Guide

Connect your AI agent to Willform via the Agent-to-Agent (A2A) protocol — JSON-RPC over HTTPS with x402 payment.

What is A2A?

The Agent-to-Agent (A2A) protocol lets AI agents interact with Willform programmatically via JSON-RPC 2.0. Unlike MCP which connects human-operated AI assistants, A2A is designed for autonomous agent-to-agent communication with built-in x402 payment.

Agent Card Discovery

Willform publishes an Agent Card at the standard well-known URL. Your agent can discover capabilities, supported skills, and payment requirements automatically:

https://willform.ai/.well-known/agent.json

Key fields in the Agent Card:

skills — 14 available operations (agent management, credits, budget, x402, identity status)
securitySchemes — x402 payment with USDC on 6 networks (Ethereum, Base, Arbitrum, Optimism, Polygon, BSC)
identity — ERC-8004 on-chain identity (Base mainnet)

Authentication via x402

A2A uses x402 payment protocol for authentication — no API keys needed. Your agent signs a payment header with its wallet.

How it works:

Send a POST request to /a2a without a PAYMENT-SIGNATURE header
Willform responds with 402 Payment Required and a payment request (minimum 0 USDC)
Your agent signs the payment request with its wallet and resends with the PAYMENT-SIGNATURE header
Willform verifies the signature, identifies the wallet, and processes the request

Zero-amount signatures: For read-only operations, you can sign a 0 USDC payment. This authenticates your wallet without spending anything.

Top-up payments: Include USDC in the payment to add credits to your Willform account. The payment is processed before the operation executes.

Endpoint

All A2A requests go to a single endpoint via POST:

https://willform.ai/a2a

JSON-RPC Methods

Willform A2A supports three JSON-RPC 2.0 methods:

Method	Description
message/send	Execute an operation on the Willform platform. The message content specifies the operation and parameters.
tasks/get	Retrieve the status and result of a previously submitted task by ID.
tasks/cancel	Cancel a running task by ID.

Example: List Namespaces

Here's a minimal JSON-RPC request to list your namespaces:

POST /a2a HTTP/1.1
Host: willform.ai
Content-Type: application/json
PAYMENT-SIGNATURE: <your-x402-signature>

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [{ "type": "text", "text": "namespace_list" }]
    }
  }
}

Per-Namespace Agent Endpoint

Each user namespace also exposes a dedicated A2A endpoint for interacting with the Willy agent:

https://willform.ai/a2a/ns/{shortId}

GET — GET — Returns the namespace-specific agent card
POST — POST — Send messages to the Willy agent (agent_chat, agent_invoke)

Per-namespace endpoints use standard SIWE authentication instead of x402.

Available Skills

The main A2A endpoint exposes 14 skills:

Skill	Description
namespace_manage	Create, list, update, or delete namespaces
credits_manage	Check balance, get deposit info, verify deposits
agent_configure	Create, list, get, update, or delete managed AI agents
agent_lifecycle	Deploy or undeploy agent VMs
agent_knowledge	Upload, list, remove, and search agent knowledge base documents
agent_self_improve	Propose, list, approve, or reject self-improvement proposals
agent_manage	Interact with per-namespace Willy agent (status, invoke, chat, recover)
ask_willy	Get platform guidance (free, no token cost)
budget_policy	Create, list, update, or delete agent budget policies
x402_proxy	Make outbound HTTP requests through the x402 budget proxy
x402_transactions	List x402 external payment transaction history
toolpack_list	List available tool packs for agents
agent_design	Design an AI agent through multi-turn conversation
agent_identity	Check identity availability and status while ERC-8004 writes are paused during migration

MCP vs A2A

Choose the right protocol for your use case:

Feature	MCP	A2A
Designed for	Human-operated AI assistants	Autonomous agent-to-agent
Authentication	OAuth 2.0 or API Key	x402 payment signature
Built-in payment	No (pre-fund account)	Yes (pay-per-request)
Protocol	MCP over Streamable HTTP	JSON-RPC 2.0 over HTTPS
Discovery	MCP tool listing	Agent Card (/.well-known/agent.json)