A2A Agent Card

The agent card is a machine-readable JSON document that describes Suwappu's capabilities, endpoints, authentication requirements, and skills. It follows the A2A (Agent-to-Agent) protocol specification and enables automated agent discovery.

Endpoint

GET https:class=class="hl-str">"hl-comment">//api.suwappu.bot/.well-known/agent.json

No authentication is required to fetch the agent card. It is publicly accessible so that other agents can discover Suwappu without prior credentials.

Fetching the Agent Card

-kw">curl https://api.suwappu.bot/.well class="hl-flag">-known/agent.json

Full Agent Card

{
  "hl-key">"$schema": "https://specs.a2aprotocol.ai/agent-card.json",
  "hl-key">"id": "suwappu-dex",
  "hl-key">"name": "Suwappu",
  "hl-key">"description": "Cross-chain DEX for AI agents. Swap tokens across 7 chains via natural language.",
  "hl-key">"version": "0.4.0",
  "hl-key">"url": "https://api.suwappu.bot",
  "hl-key">"logo": "https://suwappu.bot/logo.png",
  "hl-key">"openApiUrl": "https://api.suwappu.bot/v1/agent/openapi",
  "hl-key">"protocolVersions": ["0.3"],
  "hl-key">"interfaces": [
    {
      "hl-key">"type": "JSON-RPC",
      "hl-key">"baseUrl": "https://api.suwappu.bot/a2a",
      "hl-key">"version": "1.0"
    }
  ],
  "hl-key">"securitySchemes": {
    "hl-key">"bearer": {
      "hl-key">"type": "http",
      "hl-key">"scheme": "bearer",
      "hl-key">"description": "Register at POST /v1/agent/register to get an API key (suwappu_sk_...)"
    }
  },
  "hl-key">"authentication": {
    "hl-key">"schemes": ["bearer"],
    "hl-key">"credentials": null
  },
  "hl-key">"capabilities": {
    "hl-key">"streaming": false,
    "hl-key">"pushNotifications": true,
    "hl-key">"stateTransitionHistory": false
  },
  "hl-key">"defaultInputModes": ["text"],
  "hl-key">"defaultOutputModes": ["text"],
  "hl-key">"skills": [
    {
      "hl-key">"id": "swap",
      "hl-key">"name": "Token Swap",
      "hl-key">"description": "Swap tokens across 7 chains (ETH, BSC, Polygon, Arbitrum, Optimism, Base, Solana)",
      "hl-key">"tags": ["defi", "swap", "trading", "cross-chain"],
      "hl-key">"examples": ["swap 0.5 ETH to USDC on Base", "swap 100 USDC to SOL on Solana"],
      "hl-key">"inputModes": ["text"],
      "hl-key">"outputModes": ["text"]
    },
    {
      "hl-key">"id": "quote",
      "hl-key">"name": "Get Quote",
      "hl-key">"description": "Get a swap quote without executing",
      "hl-key">"tags": ["defi", "quote", "price"],
      "hl-key">"examples": ["quote 1 ETH to USDC", "price of 100 USDC in ETH"],
      "hl-key">"inputModes": ["text"],
      "hl-key">"outputModes": ["text"]
    },
    {
      "hl-key">"id": "portfolio",
      "hl-key">"name": "Portfolio Check",
      "hl-key">"description": "Check token balances across all chains",
      "hl-key">"tags": ["balance", "portfolio", "wallet"],
      "hl-key">"examples": ["check balance", "show portfolio"],
      "hl-key">"inputModes": ["text"],
      "hl-key">"outputModes": ["text"]
    },
    {
      "hl-key">"id": "prices",
      "hl-key">"name": "Token Prices",
      "hl-key">"description": "Get real-time token prices with 24h change",
      "hl-key">"tags": ["defi", "price", "market-data"],
      "hl-key">"examples": ["get ETH price", "check SOL and USDC prices"],
      "hl-key">"inputModes": ["text"],
      "hl-key">"outputModes": ["text"]
    },
    {
      "hl-key">"id": "tokens",
      "hl-key">"name": "Token Discovery",
      "hl-key">"description": "List available tokens per chain for quoting and swapping",
      "hl-key">"tags": ["defi", "tokens", "discovery"],
      "hl-key">"examples": ["list tokens on Base", "search for USD tokens"],
      "hl-key">"inputModes": ["text"],
      "hl-key">"outputModes": ["text"]
    },
    {
      "hl-key">"id": "key-management",
      "hl-key">"name": "API Key Management",
      "hl-key">"description": "Rotate API keys for security",
      "hl-key">"tags": ["security", "keys"],
      "hl-key">"examples": ["rotate my API key"],
      "hl-key">"inputModes": ["text"],
      "hl-key">"outputModes": ["text"]
    },
    {
      "hl-key">"id": "webhook-management",
      "hl-key">"name": "Webhook Management",
      "hl-key">"description": "List webhook delivery events and test webhook endpoints",
      "hl-key">"tags": ["webhooks", "notifications"],
      "hl-key">"examples": ["list webhook events", "test my webhook"],
      "hl-key">"inputModes": ["text"],
      "hl-key">"outputModes": ["text"]
    }
  ],
  "hl-key">"provider": {
    "hl-key">"organization": "Suwappu",
    "hl-key">"url": "https://suwappu.bot"
  },
  "hl-key">"supportedChains": [
    {"hl-key">"id": 1, "hl-key">"name": "Ethereum", "hl-key">"native": "ETH"},
    {"hl-key">"id": 56, "hl-key">"name": "BSC", "hl-key">"native": "BNB"},
    {"hl-key">"id": 137, "hl-key">"name": "Polygon", "hl-key">"native": "MATIC"},
    {"hl-key">"id": 42161, "hl-key">"name": "Arbitrum", "hl-key">"native": "ETH"},
    {"hl-key">"id": 10, "hl-key">"name": "Optimism", "hl-key">"native": "ETH"},
    {"hl-key">"id": 8453, "hl-key">"name": "Base", "hl-key">"native": "ETH"},
    {"hl-key">"id": "solana", "hl-key">"name": "Solana", "hl-key">"native": "SOL"}
  ]
}

Field Reference

Top-Level Fields

Field	Type	Description
`id`	string	Unique identifier for this agent. Used by other agents to reference Suwappu in multi-agent systems.
`name`	string	Human-readable display name.
`description`	string	Brief description of what this agent does. Other agents use this to decide whether Suwappu can help with a given task.
`version`	string	Semantic version of the agent. Clients can use this to detect capability changes.
`url`	string	Base URL for the agent's API. All protocol endpoints are relative to this URL.
`openApiUrl`	string	URL to the OpenAPI 3.1.0 specification. Enables REST API code generation and auto-discovery.

interfaces

Describes the communication protocols the agent supports.

Field	Type	Description
`type`	string	Protocol type. Suwappu uses `"JSON-RPC"` for the A2A protocol.
`baseUrl`	string	Full URL for the protocol endpoint (`/a2a`).
`version`	string	Protocol version.

securitySchemes

A dictionary of named security schemes. Each key is the scheme name (e.g., "bearer").

Field	Type	Description
`type`	string	Authentication transport (`"http"`).
`scheme`	string	Authentication scheme (`"bearer"`).
`description`	string	Instructions for obtaining credentials.

authentication

Declares which security schemes the agent requires.

Field	Type	Description
`schemes`	array	List of scheme names from `securitySchemes` that the agent accepts.
`credentials`	null	No default credentials; agents must register to obtain a token.

capabilities

Declares what optional features the agent supports.

Field	Type	Description
`streaming`	boolean	Whether the agent supports streaming responses. Suwappu does not currently stream.
`pushNotifications`	boolean	Whether the agent can send push notifications (e.g., webhooks for task completion). Suwappu supports this.
`stateTransitionHistory`	boolean	Whether full task state transition history is retained. Suwappu does not retain transition history.

skills

An array of capabilities the agent can perform. Each skill has:

Field	Type	Description
`id`	string	Unique skill identifier.
`name`	string	Human-readable skill name.
`description`	string (optional)	What the skill does.
`tags`	array (optional)	Categorization tags for discovery and filtering.
`examples`	array (optional)	Example natural language messages that trigger this skill.
`inputModes`	array	Accepted input types (e.g., `["text"]`).
`outputModes`	array	Output types the skill produces (e.g., `["text"]`).

How Agents Discover Suwappu

The agent card lives at the well-known path /.well-known/agent.json, following the A2A discovery convention. An agent that wants to discover Suwappu follows these steps:

1. Fetch the agent card from https://api.suwappu.bot/.well-known/agent.json.

2. Read the description and skills to determine if Suwappu can handle the task at hand.

3. Check securitySchemes to learn how to authenticate (register at POST /v1/agent/register to get a Bearer token).

4. Read interfaces to find the A2A endpoint URL.

5. Send messages to the A2A endpoint using the message/send method.

Alternatively, an agent can use the openApiUrl to fetch the full OpenAPI spec and integrate via the REST API instead.

Using the Agent Card for Integration

Programmatic Discovery (Python)

import requests

class=class="hl-str">"hl-comment"># Step 1: Discover the agent
card = requests.get(class="hl-str">"https:class="hl-commentclass="hl-str">">//api.suwappu.bot/.well-known/agent.json").json()

print(fclass="hl-str">"Agent: {card[class="hl-str">'name']}")
print(fclass="hl-str">"Description: {card[class="hl-str">'description']}")
print(fclass="hl-str">"Skills: {[s[class="hl-str">'name'] for s in card[class="hl-str">'skills']]}")

class=class="hl-str">"hl-comment"># Step 2: Find the A2A endpoint
a2a_url = card[class="hl-str">"interfaces"][0][class="hl-str">"baseUrl"]

class=class="hl-str">"hl-comment"># Step 3: Register for a token
reg = requests.post(fclass="hl-str">"{card[class="hl-str">'url']}/v1/agent/register", json={
    class="hl-str">"name": class="hl-str">"my-agent",
    class="hl-str">"description": class="hl-str">"My trading agent"
})
token = reg.json()[class="hl-str">"api_key"]

class=class="hl-str">"hl-comment"># Step 4: Send a message via A2A
response = requests.post(a2a_url, json={
    class="hl-str">"jsonrpc": class="hl-str">"2.0",
    class="hl-str">"id": 1,
    class="hl-str">"method": class="hl-str">"message/send",
    class="hl-str">"params": {
        class="hl-str">"message": {
            class="hl-str">"role": class="hl-str">"user",
            class="hl-str">"parts": [{class="hl-str">"type": class="hl-str">"text", class="hl-str">"text": class="hl-str">"price of ETH"}]
        }
    }
}, headers={class="hl-str">"Authorization": fclass="hl-str">"Bearer {token}"})

task = response.json()[class="hl-str">"result"][class="hl-str">"task"]
print(fclass="hl-str">"Task {task[class="hl-str">'id']}: {task[class="hl-str">'status'][class="hl-str">'state']}")

Multi-Agent Systems

In a multi-agent orchestration system, an orchestrator agent can:

1. Discover multiple agents by fetching their agent cards.

2. Match tasks to agents by reading skill descriptions.

3. Route a "swap ETH to USDC" request to Suwappu based on its swap skill.

4. Route other tasks to different agents based on their skills.

The agent card makes this routing automatic --- no hardcoded knowledge of Suwappu is needed.