OpenAPI Specification

Suwappu publishes an OpenAPI 3.1.0 specification that describes all REST API endpoints. The spec enables automated code generation, API documentation, and programmatic agent discovery.

Endpoint

GET https:class=class="hl-str">"hl-comment">//api.suwappu.bot/v1/agent/openapi

No authentication is required to fetch the OpenAPI spec.

Fetching the Spec

-kw">curl https://api.suwappu.bot/v1/agent/openapi

To save it to a file:

-kw">curl -o suwappu-openapi.json https://api.suwappu.bot/v1/agent/openapi

To pretty-print it:

-kw">curl -s https://api.suwappu.bot/v1/agent/openapi | python3 -m json.tool

What the Spec Contains

The OpenAPI 3.1.0 JSON document describes:

• Info --- API name, version, description, and contact details.
• Servers --- Base URL (https://api.suwappu.bot).
• Paths --- All REST API endpoints with request/response schemas, including:

- POST /v1/agent/register --- Agent registration

- GET /v1/agent/quote --- Get a swap quote

- POST /v1/agent/swap --- Execute a swap

- GET /v1/agent/portfolio --- Check wallet portfolio

- GET /v1/agent/prices --- Get token prices

- GET /v1/agent/chains --- List supported chains

- GET /v1/agent/tokens --- List and search tokens

- GET /v1/agent/openapi --- This spec itself

• Components --- Reusable schemas for request/response objects.
• Security --- Bearer token authentication scheme.

Using with Code Generation Tools

openapi-generator

Generate a client library in any supported language:

-str">"hl-comment"># Install openapi-generator
-kw">npm install -g @openapitools/openapi-generator-cli

-str">"hl-comment"># Generate a Python client
openapi-generator-cli generate \
  -i https://api.suwappu.bot/v1/agent/openapi \
  -g python \
  -o ./suwappu-python-client

-str">"hl-comment"># Generate a TypeScript client
openapi-generator-cli generate \
  -i https://api.suwappu.bot/v1/agent/openapi \
  -g typescript-axios \
  -o ./suwappu-ts-client

-str">"hl-comment"># Generate a Go client
openapi-generator-cli generate \
  -i https://api.suwappu.bot/v1/agent/openapi \
  -g go \
  -o ./suwappu-go-client

openapi-typescript

Generate TypeScript types from the spec:

npx openapi-typescript https://api.suwappu.bot/v1/agent/openapi -o suwappu.d.ts

Swagger UI

You can load the spec into Swagger UI for an interactive API explorer:

docker run -p 8080:8080 \
  -e SWAGGER_JSON_URL=https://api.suwappu.bot/v1/agent/openapi \
  swaggerapi/swagger-ui

Then open http://localhost:8080 in your browser.

Programmatic Usage

Auto-Discovery (Python)

An agent can fetch the spec at runtime to discover endpoints and their parameters without any hardcoded knowledge:

import requests

class=class="hl-str">"hl-comment"># Fetch the OpenAPI spec
spec = requests.get(class="hl-str">"https:class="hl-commentclass="hl-str">">//api.suwappu.bot/v1/agent/openapi").json()

class=class="hl-str">"hl-comment"># List all available endpoints
for path, methods in spec[class="hl-str">"paths"].items():
    for method, details in methods.items():
        print(fclass="hl-str">"{method.upper()} {path} - {details.get(class="hl-str">'summary', class="hl-str">'')}")

class=class="hl-str">"hl-comment"># Get the schema for a specific endpoint
quote_params = spec[class="hl-str">"paths"][class="hl-str">"/v1/agent/quote"][class="hl-str">"get"][class="hl-str">"parameters"]
for param in quote_params:
    required = class="hl-str">"required" if param.get(class="hl-str">"required") else class="hl-str">"optional"
    print(fclass="hl-str">"  {param[class="hl-str">'name']} ({required}): {param.get(class="hl-str">'description', class="hl-str">'')}")

Auto-Discovery (JavaScript)

const spec = await fetch(class="hl-str">"https:class="hl-commentclass="hl-str">">//api.suwappu.bot/v1/agent/openapi").then(r => r.json());

class=class="hl-str">"hl-comment">// List all endpoints
for (const [path, methods] of Object.entries(spec.paths)) {
  for (const [method, details] of Object.entries(methods)) {
    console.log(${method.toUpperCase()} ${path} - ${details.summary || class="hl-str">""});
  }
}

Dynamic Client Construction

AI agents can use the OpenAPI spec to dynamically build API calls without pre-built client libraries:

import requests

spec = requests.get(class="hl-str">"https:class="hl-commentclass="hl-str">">//api.suwappu.bot/v1/agent/openapi").json()
base_url = spec[class="hl-str">"servers"][0][class="hl-str">"url"]

class=class="hl-str">"hl-comment"># Register to get a token
reg = requests.post(fclass="hl-str">"{base_url}/v1/agent/register", json={
    class="hl-str">"name": class="hl-str">"auto-agent",
    class="hl-str">"description": class="hl-str">"Dynamically configured agent"
})
token = reg.json()[class="hl-str">"api_key"]
headers = {class="hl-str">"Authorization": fclass="hl-str">"Bearer {token}"}

class=class="hl-str">"hl-comment"># Use the spec to build a quote request
quote_endpoint = spec[class="hl-str">"paths"][class="hl-str">"/v1/agent/quote"][class="hl-str">"get"]
response = requests.get(fclass="hl-str">"{base_url}/v1/agent/quote", params={
    class="hl-str">"from_token": class="hl-str">"ETH",
    class="hl-str">"to_token": class="hl-str">"USDC",
    class="hl-str">"amount": class="hl-str">"1.0",
    class="hl-str">"chain": class="hl-str">"base"
}, headers=headers)

print(response.json())

Relationship to Other Protocols

The OpenAPI spec describes the REST API. The same underlying functionality is also available through:

• A2A Protocol (/a2a) --- Natural language interface over JSON-RPC. See A2A Protocol.
• MCP Protocol (/mcp) --- Tool-based interface for LLMs. See MCP Protocol.

The agent card at /.well-known/agent.json includes the openApiUrl field pointing to this spec, enabling agents to discover both the A2A and REST interfaces from a single entry point. See Agent Card.