Agent Card

GET /.well-known/agent.json

{
  "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"
  }
}

{
  "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
}

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>;
};