Swarm Nexus Homepage

The Agent (API)

The Agent is the official public-facing REST API for Swarm Nexus. It provides programmatic, read-only access to the Swarm Memory for developers, third-party services, and other agents in the Torus Network. It is a lightweight and efficient Node.js application built with the Hono framework.

Core Responsibilities

  • Programmatic Data Access: Exposes the data stored in the Swarm Memory through a set of stable, versioned REST endpoints.

  • Read-Only Operations: Like the Dashboard, the Agent connects to the swarm.db database in read-only mode to guarantee data integrity.

  • API Standardization: Provides an OpenAPI (Swagger) specification, allowing for easy discovery of its capabilities and auto-generation of client libraries.

  • Health Checks: Includes a /healthz endpoint for automated monitoring to confirm the service is running and can connect to the database.

Technical Stack

  • Framework: Hono (a small, fast, and modern web framework for Node.js)

  • Runtime: Node.js

  • Service Management: systemd (swarm-agent.service)

How It Works

  1. Request Handling: Nginx receives a request with the /agent/ path prefix (e.g., https://swarm-nexus.xyz/agent/memory/mentions) and reverse-proxies it to the Agent server listening on 127.0.0.1:3011.

  2. Application Logic: The Hono application parses the request, validates parameters, and queries the swarm.db database.

  3. Response: The application formats the results as a JSON object and returns them to the client.

Key API Endpoints

  • GET /agent/healthz: Returns a health status check.

  • GET /agent/openapi.yaml: Serves the OpenAPI specification file.

  • GET /agent/memory/mentions: Queries for ingested tweets with filters for author, ticker, date ranges, and more.

  • GET /agent/memory/tickers: Retrieves mentions related to a specific ticker.

PreviousThe DashboardNextUser Guide

Last updated