GET /.well-known/agent.json
Returns the A2A-compliant Agent Card for your Key0 seller agent. This is the entry point for any client agent that wants to discover your agent’s capabilities, skills, and payment requirements.
No authentication is required.
Response The agent name, from SellerConfig.agentName.
The agent description, from SellerConfig.agentDescription.
The primary endpoint URL. Points to /x402/access by default.
Agent version. Defaults to "1.0.0".
A2A protocol version. Currently "0.3.0".
Declares supported capabilities and extensions.
Array of skills the agent exposes. Key0 registers two skills by default.
Organization and URL of the agent provider.
Example Response { "name" : "Acme Photo API" , "description" : "Pay-per-use access to high-resolution stock photos via USDC on Base." , "url" : "https://api.acme.com/x402/access" , "version" : "1.0.0" , "protocolVersion" : "0.3.0" , "capabilities" : { "extensions" : [ { "uri" : "https://github.com/google-agentic-commerce/a2a-x402/blob/main/spec/v0.2" , "description" : "Supports x402 payments with USDC on base-sepolia." , "required" : true } ], "pushNotifications" : false , "streaming" : false , "stateTransitionHistory" : false }, "defaultInputModes" : [ "text" ], "defaultOutputModes" : [ "application/json" ], "skills" : [ { "id" : "discover-plans" , "name" : "Discover Plans" , "description" : "Browse available plans and pricing for Acme Photo API. Returns the product catalog with plan IDs, prices (USDC on base-sepolia), wallet address, and chain ID. GET https://api.acme.com/discover to discover plans." , "tags" : [ "discovery" , "catalog" , "x402" ], "examples" : [ "GET https://api.acme.com/discover" ] }, { "id" : "request-access" , "name" : "Request Access" , "description" : "Purchase access to a Acme Photo API product plan via x402 payment on base-sepolia. First call discover-plans to get available plans. Then POST to https://api.acme.com/x402/access with planId and requestId to initiate purchase. Server responds with x402 payment challenge. Complete payment on-chain and include PAYMENT-SIGNATURE header to receive access token." , "tags" : [ "payment" , "x402" , "purchase" ], "examples" : [ "POST https://api.acme.com/x402/access with { planId: \" <plan-id> \" , requestId: \" <uuid> \" , resourceId: \" default \" }" , "Receive 402 with payment challenge" , "Pay USDC on-chain, retry same request with PAYMENT-SIGNATURE header" , "Receive 200 with access token" ], "endpoint" : { "url" : "https://api.acme.com/x402/access" , "method" : "POST" }, "inputSchema" : { "type" : "object" , "properties" : { "planId" : { "type" : "string" , "description" : "Plan ID from discover-plans" }, "requestId" : { "type" : "string" , "description" : "Client-generated UUID for idempotency" }, "resourceId" : { "type" : "string" , "description" : "Resource to access (defaults to 'default')" } }, "required" : [ "planId" ] }, "workflow" : [ "1. Call GET /discover to browse available plans and note the planId" , "2. POST /x402/access { planId, requestId } — receive 402 with payment challenge" , "3. Sign EIP-3009 authorization off-chain (no gas required)" , "4. Retry POST /x402/access with PAYMENT-SIGNATURE header — receive AccessGrant" ] } ], "provider" : { "organization" : "Acme Inc." , "url" : "https://acme.com" } }
Skills Key0 automatically generates two A2A-compliant skills:
discover-plans A free discovery skill. Clients call this (or GET to /discover) to browse the plan catalog. Returns plan IDs, prices, wallet address, and chain ID.
request-access The payment-gated skill. Clients call this to initiate a purchase flow:
POST with planId to receive a 402 challenge with payment requirements.
Sign an EIP-3009 authorization off-chain.
Retry the same request with a PAYMENT-SIGNATURE header.
Receive a 200 response with an AccessGrant containing the bearer token.
This skill includes machine-readable metadata for automated clients:
endpointPOST /x402/access URL and method, so clients don’t need to parse the description.inputSchemaplanId, requestId, resourceId).workflow
x402 Extension The Agent Card declares the x402 extension as required: true in capabilities.extensions:
{ "uri" : "https://github.com/google-agentic-commerce/a2a-x402/blob/main/spec/v0.2" , "description" : "Supports x402 payments with USDC on base-sepolia." , "required" : true }
This signals to client agents that they must support the x402 payment protocol to interact with this agent. The uri follows the A2A x402 extension spec v0.2.
TypeScript Types type AgentCard = { name : string ; description : string ; url : string ; version : string ; protocolVersion : string ; capabilities : { extensions ?: AgentExtension []; pushNotifications ?: boolean ; streaming ?: boolean ; stateTransitionHistory ?: boolean ; }; defaultInputModes : string []; defaultOutputModes : string []; skills : AgentSkill []; provider ?: { organization : string ; url : string ; }; }; type AgentSkill = { id : string ; name : string ; description : string ; tags : string []; examples ?: string []; inputModes ?: string []; outputModes ?: string []; /** @key0 Direct endpoint URL and HTTP method. */ endpoint ?: { url : string ; method : "GET" | "POST" }; /** @key0 JSON Schema for input parameters. */ inputSchema ?: Record < string , unknown >; /** @key0 Step-by-step workflow for automated clients. */ workflow ?: string []; }; type AgentExtension = { uri : string ; description ?: string ; required ?: boolean ; params ?: Record < string , unknown >; };
SellerConfig The configuration object that drives agent card generation.
How It Works Overview of the Key0 payment flow and agent discovery.
API Reference Overview Index of all Key0 API endpoints and protocols.
