A2A (Agent-to-Agent) Protocol

The A2A protocol enables AI agents to communicate with Suwappu using natural language messages over JSON-RPC 2.0. Your agent sends a message, and Suwappu returns a task object that tracks the request through its lifecycle.

Endpoint

POST https:class=class="hl-str">"hl-comment">//api.suwappu.bot/a2a

Authentication

Include your Bearer token in the Authorization header:

Authorization: Bearer suwappu_sk_YOUR_KEY

Obtain a token by registering at POST /v1/agent/register.

Protocol

All requests and responses follow the JSON-RPC 2.0 specification. Every request must include:

  • jsonrpc: Always "2.0"
  • id: A unique request identifier (integer or string)
  • method: One of the three supported methods
  • params: Method-specific parameters

Methods

message/send

Send a natural language message to Suwappu and receive a task with the result.

Request: 
{

  "hl-key">"jsonrpc": "2.0",


  "hl-key">"id": 1,


  "hl-key">"method": "message/send",


  "hl-key">"params": {


    "hl-key">"message": {


      "hl-key">"role": "user",


      "hl-key">"parts": [


        {


          "hl-key">"type": "text",


          "hl-key">"text": "swap 0.5 ETH to USDC on base"


        }


      ]


    }


  }


}
Response: 
{

  "hl-key">"jsonrpc": "2.0",


  "hl-key">"id": 1,


  "hl-key">"result": {


    "hl-key">"task": {


      "hl-key">"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",


      "hl-key">"status": {


        "hl-key">"state": "completed",


        "hl-key">"timestamp": "2026-03-07T12:00:00Z"


      },


      "hl-key">"artifacts": [


        {


          "hl-key">"id": "artifact-1",


          "hl-key">"parts": [


            {


              "hl-key">"type": "text",


              "hl-key">"text": "Quote ready: 0.5 ETH -> 1,247.50 USDC on Base"


            },


            {


              "hl-key">"type": "data",


              "hl-key">"data": {


                "hl-key">"quote_id": "q_abc123",


                "hl-key">"from_token": "ETH",


                "hl-key">"to_token": "USDC",


                "hl-key">"from_amount": "0.5",


                "hl-key">"to_amount": "1247.50",


                "hl-key">"chain": "base",


                "hl-key">"expires_at": "2026-03-07T12:05:00Z"


              }


            }


          ]


        }


      ],


      "hl-key">"messages": [


        {


          "hl-key">"role": "user",


          "hl-key">"parts": [{"hl-key">"type": "text", "hl-key">"text": "swap 0.5 ETH to USDC on base"}]


        },


        {


          "hl-key">"role": "agent",


          "hl-key">"parts": [{"hl-key">"type": "text", "hl-key">"text": "Quote ready: 0.5 ETH -> 1,247.50 USDC on Base"}]


        }


      ]


    }


  }


}

tasks/get

Retrieve a task by its ID to check its current status and results.

Request: 
{

  "hl-key">"jsonrpc": "2.0",


  "hl-key">"id": 2,


  "hl-key">"method": "tasks/get",


  "hl-key">"params": {


    "hl-key">"taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"


  }


}
Response:

Returns the same task object structure as message/send.

tasks/cancel

Cancel a task that is currently running.

Request: 
{

  "hl-key">"jsonrpc": "2.0",


  "hl-key">"id": 3,


  "hl-key">"method": "tasks/cancel",


  "hl-key">"params": {


    "hl-key">"taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"


  }


}
Response: 
{

  "hl-key">"jsonrpc": "2.0",


  "hl-key">"id": 3,


  "hl-key">"result": {


    "hl-key">"task": {


      "hl-key">"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",


      "hl-key">"status": {


        "hl-key">"state": "canceled",


        "hl-key">"timestamp": "2026-03-07T12:01:00Z"


      }


    }


  }


}

Task Lifecycle

A task transitions through the following states:

submitted --> working --> completed

                |


                +--> failed


                |


                +--> canceled
StateDescription
submittedTask received and queued for processing
workingTask is actively being processed
completedTask finished successfully; results available in artifacts
failedTask encountered an error; details in status.message
canceledTask was canceled via tasks/cancel

Task Object

FieldTypeDescription
idstring (UUID)Unique task identifier
status.statestringCurrent lifecycle state
status.timestampstring (ISO 8601)When the status last changed
status.messagestring (optional)Human-readable status detail or error message
artifactsarrayResult data, present when state is completed
artifacts[].idstringArtifact identifier
artifacts[].partsarrayContent parts (text and/or structured data)
messagesarrayFull conversation history for the task

Supported Commands

Suwappu understands the following natural language intents:

IntentExample messages
Swap / Quote / Convert"swap 0.5 ETH to USDC on base", "quote 100 USDC to WBTC on ethereum"
Price checks"price of ETH", "prices for ETH, BTC, SOL"
Balance / Portfolio"show my portfolio on base", "check balances for 0xabc..."
Token discovery"list tokens on arbitrum", "search for PEPE token"
Chain discovery"list supported chains", "what chains do you support"
Help"help", "what can you do"

Error Codes

Standard JSON-RPC 2.0 error codes plus Suwappu-specific codes:

CodeNameDescription
-32700Parse errorInvalid JSON in request body
-32600Invalid requestRequest is not a valid JSON-RPC 2.0 object
-32601Method not foundThe method name is not one of the three supported methods
-32001Task not foundThe provided taskId does not match any existing task
-32002Unsupported operationThe requested operation is not supported
Error response example: 
{

  "hl-key">"jsonrpc": "2.0",


  "hl-key">"id": 2,


  "hl-key">"error": {


    "hl-key">"code": -32001,


    "hl-key">"message": "Task not found",


    "hl-key">"data": {


      "hl-key">"taskId": "nonexistent-uuid"


    }


  }


}

Full Example: Quote and Execute

-str">"hl-comment"># Step 1: Request a swap (returns a quote)
-kw">curl -X POST https://api.suwappu.bot/a2a \

  -H -str">"Content-Type: application/json" \


  -H -str">"Authorization: Bearer suwappu_sk_YOUR_KEY" \


  -d -str">'{


    -str">"jsonrpc": -str">"2.0",


    -str">"id": 1,


    -str">"method": -str">"message/send",


    -str">"params": {


      -str">"message": {


        -str">"role": -str">"user",


        -str">"parts": [{-str">"type": -str">"text", -str">"text": -str">"swap 0.5 ETH to USDC on base"}]


      }


    }


  }'


-str">"hl-comment"># Step 2: Check task status (if needed)
-kw">curl -X POST https://api.suwappu.bot/a2a \

  -H -str">"Content-Type: application/json" \


  -H -str">"Authorization: Bearer suwappu_sk_YOUR_KEY" \


  -d -str">'{


    -str">"jsonrpc": -str">"2.0",


    -str">"id": 2,


    -str">"method": -str">"tasks/get",


    -str">"params": {


      -str">"taskId": -str">"TASK_ID_FROM_STEP_1"


    }


  }'