🔌 Plugin Delivery

AI Function Call Plugins & Tools for SperaxOS

Live: plugin.delivery

📚 Docs • 🚀 Quick Start • 📦 Templates • 🎨 Plugin Types • 🔧 Development

---

What Is Plugin Delivery?

The official plugin marketplace and SDK for SperaxOS — a crypto/DeFi-focused AI assistant platform.

Feature	Description
📋 Plugin Index	JSON registry of AI-discoverable plugins
⚡ Gateway Service	Secure proxy routing function calls to plugin APIs
🛠️ SDK	TypeScript SDK for building custom plugins
🎨 Templates	6 starter templates for different plugin types
🌍 i18n	18 languages supported out of the box

How It Works

User: "What's the price of ETH?"
         │
         ▼
┌─────────────────────────────────────────────────────────┐
│  SperaxOS discovers plugin from plugin.delivery index   │
│  AI generates function call: getPrice(coin: "ethereum") │
│  Gateway routes request to CoinGecko API                │
│  Response rendered in chat (JSON, Markdown, or UI)      │
└─────────────────────────────────────────────────────────┘
         │
         ▼
AI: "ETH is currently trading at $3,450..."

---

Plugin Types

SperaxOS supports 4 distinct plugin types, each optimized for different use cases:

Type	Rendering	Best For	Complexity
Default	Server-rendered JSON → AI formats	Data APIs, lookups	⭐ Simple
Markdown	Pre-formatted rich text	Documentation, reports	⭐ Simple
Standalone	Full React/HTML app in iframe	Interactive dashboards	⭐⭐⭐ Advanced
OpenAPI	Auto-generated from spec	Existing APIs	⭐⭐ Medium

Default Plugins

Returns JSON data that the AI formats into natural language.

{
  "ui": {
    "mode": "default"
  }
}

Use when: You have an API that returns structured data and want the AI to explain results conversationally.

Markdown Plugins

Returns pre-formatted Markdown that displays directly in chat.

{
  "ui": {
    "mode": "markdown"
  }
}

Use when: You want full control over formatting — tables, code blocks, headers, etc.

Standalone Plugins (Artifacts)

Embeds a full React/HTML application in an iframe within the chat.

{
  "ui": {
    "mode": "standalone",
    "url": "https://your-plugin.com/ui",
    "height": 400
  }
}

Use when: You need rich interactivity — charts, forms, dashboards, embedded apps.

💡 Standalone plugins are SperaxOS's superpower — they enable experiences beyond what ChatGPT plugins can do.

OpenAPI Plugins

Auto-generated from an OpenAPI 3.x specification. No custom code needed.

{
  "openapi": "https://your-api.com/openapi.json"
}

Use when: You already have an OpenAPI spec for your API.

---

Artifacts, Embeds & Interactive UI

What Are Artifacts?

Artifacts are rich interactive content that plugins can render directly in chat. Unlike plain text responses, artifacts can include:

• 📊 Charts & Visualizations (Chart.js, Recharts, D3)
• 📝 Interactive Forms (Input fields, buttons, selectors)
• 🎮 Mini Applications (Games, calculators, tools)
• 📄 Rich Documents (Formatted reports, tables)

HTML Artifacts

Render raw HTML directly:

// In your plugin API response
return {
  type: 'html',
  content: `
    <div style="padding: 20px;">
      <h2>Price Alert</h2>
      <p>ETH crossed $3,500!</p>
    </div>
  `
};

React Artifacts

Render React components (standalone plugins):

// ui/page.tsx
export default function PriceChart({ data }) {
  return (
    <div className="p-4">
      <LineChart data={data}>
        <Line dataKey="price" stroke="#22c55e" />
      </LineChart>
    </div>
  );
}

iframe Embeds

Embed external content:

{
  "ui": {
    "mode": "standalone",
    "url": "https://tradingview.com/chart/?symbol=BTCUSD",
    "height": 500
  }
}

Function Calls from UI

Standalone plugins can trigger additional function calls:

import { speraxOS } from '@sperax/plugin-sdk/client';

// Trigger a new function call from your UI
speraxOS.triggerFunctionCall({
  name: 'getTokenDetails',
  arguments: { token: 'ETH' }
});

---

Plugin Templates

Get started fast with our official templates:

Template	Type	Description	Use Case
basic	Default	Standard plugin with API endpoint	Simple data lookups
default	Default	Plugin with settings UI	Configurable plugins
markdown	Markdown	Rich text output	Formatted reports
openapi	OpenAPI	Auto-generated from spec	Existing APIs
settings	Default	Plugin with user preferences	Personalized tools
standalone	Standalone	Full React application	Interactive dashboards

Using a Template

# Clone template to new directory
cp -r templates/standalone my-plugin
cd my-plugin

# Install dependencies
bun install

# Start development
bun dev

Template Structure

templates/standalone/
├── public/
│   └── manifest.json    # Plugin manifest
├── src/
│   ├── api/            # API endpoints
│   │   └── index.ts    # Main handler
│   └── ui/             # React UI (standalone only)
│       └── page.tsx    # UI component
├── package.json
└── README.md

---

Quick Start

1. Install the SDK

bun add @sperax/plugin-sdk
# or
npm install @sperax/plugin-sdk

2. Create manifest.json

{
  "$schema": "https://plugin.delivery/schema.json",
  "identifier": "my-crypto-plugin",
  "api": [
    {
      "name": "getPrice",
      "description": "Get cryptocurrency price",
      "url": "https://my-plugin.vercel.app/api/price",
      "parameters": {
        "type": "object",
        "properties": {
          "coin": {
            "type": "string",
            "description": "Coin ID (e.g., bitcoin, ethereum)"
          }
        },
        "required": ["coin"]
      }
    }
  ],
  "meta": {
    "title": "My Crypto Plugin",
    "description": "Get real-time crypto prices",
    "avatar": "🪙",
    "tags": ["crypto", "prices"]
  }
}

3. Create API Handler

// api/price.ts
export default async function handler(req: Request) {
  const { coin } = await req.json();
  
  const res = await fetch(
    `https://api.coingecko.com/api/v3/simple/price?ids=${coin}&vs_currencies=usd`
  );
  const data = await res.json();
  
  return Response.json({
    coin,
    price: data[coin]?.usd,
    timestamp: new Date().toISOString()
  });
}

4. Deploy & Register

# Deploy to Vercel
vercel --prod

# Add to plugin index (submit PR or use Plugin Store)

---

Documentation

Guide	Description
📖 Plugin Development Guide	Complete development walkthrough
📋 Plugin Manifest Reference	Full manifest.json specification
🎨 Plugin Types Guide	Default, Markdown, Standalone explained
🔌 SDK API Reference	Client SDK documentation
🌐 OpenAPI Integration	Using OpenAPI specs
💬 Communication Guide	Plugin ↔ Host messaging
🎭 Artifacts Guide	Rich UI components
⚡ Complete Guide	Everything in one doc

---

Available Plugins

Production

Plugin	Description	Type	API
🪙 CoinGecko Crypto	Prices, trends, market data for 1M+ tokens	OpenAPI	Free
🦙 DeFiLlama Analytics	TVL, yields, stablecoins, protocol metrics	Default	Free

Coming Soon

Plugin	Description	Status
📊 DexScreener	DEX pairs, volume, liquidity	Planned
💼 Portfolio Tracker	Multi-chain wallet aggregation	Planned
⛓️ Chain Explorer	Transaction lookup, gas prices	Planned

---

Development

Prerequisites

• Bun 1.0+ (recommended) or Node.js 18+
• Git

Setup

# Clone
git clone https://github.com/nirholas/plugin.delivery.git
cd plugins

# Install
bun install

# Dev server
bun dev

Commands

Command	Description
bun dev	Start local dev server
bun run format	Generate i18n translations (requires OpenAI API key)
bun run build	Build plugin index
bun test	Run tests
bun lint	Lint code

---

Adding a New Plugin

Step-by-Step Workflow

1. Create plugin definition in src/[plugin-name].json:

{
  "author": "Your Name",
  "createdAt": "2025-12-29",
  "homepage": "https://example.com",
  "identifier": "my-plugin",
  "manifest": "https://plugin.delivery/my-plugin/manifest.json",
  "meta": {
    "avatar": "🔌",
    "description": "What your plugin does",
    "tags": ["tag1", "tag2"],
    "title": "My Plugin",
    "category": "stocks-finance"
  },
  "schemaVersion": 1
}

2. Create manifest in public/[plugin-name]/manifest.json:

{
  "$schema": "https://plugin.delivery/schema.json",
  "identifier": "my-plugin",
  "api": [
    {
      "url": "https://plugin.delivery/api/my-plugin/endpoint",
      "name": "myFunction",
      "description": "What this function does",
      "parameters": {
        "type": "object",
        "properties": {
          "param": { "type": "string", "description": "Parameter description" }
        },
        "required": ["param"]
      }
    }
  ],
  "meta": {
    "avatar": "🔌",
    "title": "My Plugin",
    "description": "What your plugin does"
  },
  "version": "1"
}

3. Create API endpoints in api/[plugin-name]/[endpoint].ts

4. Run format (generates i18n translations for 18 languages):

# Set OpenAI API key (required for i18n generation)
export OPENAI_API_KEY=sk-your-key-here
# Or create .env file with OPENAI_API_KEY=sk-your-key-here

# Generate translations
bun run format

5. Build the plugin index:

bun run build

6. Commit and push:

git add -A
git commit -m "feat: add [plugin-name] plugin"
git push

⚠️ Important: Always run bun run format before bun run build when adding new plugins. The format command uses OpenAI to generate translations for all 18 supported languages.

Project Structure

plugins/
├── packages/
│   ├── sdk/              # @sperax/plugin-sdk
│   └── gateway/          # @sperax/chat-plugins-gateway
├── templates/            # Starter templates
│   ├── basic/
│   ├── default/
│   ├── markdown/
│   ├── openapi/
│   ├── settings/
│   └── standalone/
├── public/               # Static files (auto-generated)
│   ├── index.json        # Plugin registry
│   └── openai/           # OpenAPI manifests
├── src/                  # Plugin definitions
├── locales/              # i18n translations
├── docs/                 # Documentation
└── api/                  # Serverless functions

---

Packages

Package	Description	npm
@sperax/plugin-sdk	Plugin SDK for building SperaxOS plugins
@sperax/chat-plugins-gateway	Gateway service for routing plugin calls

SDK Usage

import { 
  pluginManifestSchema,
  createPluginResponse,
  PluginError 
} from '@sperax/plugin-sdk';

// Client-side (in standalone UI)
import { speraxOS } from '@sperax/plugin-sdk/client';

---

Gateway

The Plugin Gateway securely routes function calls from SperaxOS to plugin APIs:

SperaxOS → Gateway → Plugin API
              │
              ├── Auth injection
              ├── Rate limiting
              ├── Request logging
              └── Response transform

Self-Hosting

# Clone gateway
cd packages/gateway

# Deploy
vercel --prod

# Set in SperaxOS
PLUGINS_GATEWAY_URL=https://your-gateway.vercel.app

---

Contributing

We welcome contributions! See CONTRIBUTING.md.

Submit a Plugin

1. Option A: Open a Plugin Submission issue
2. Option B: Submit a PR adding your plugin to src/

Requirements

• ✅ Valid manifest with working endpoints
• ✅ Tested in SperaxOS
• ✅ No API key required (or documented)
• ✅ en-US locale at minimum

---

Links

Resource	URL
🌐 Plugin Index	plugin.delivery
📦 SDK on npm	@sperax/plugin-sdk
🐙 GitHub	github.com/nirholas/plugins
🐦 Twitter/X	@nichxbt

---

License

MIT © Sperax

---

🔌 plugin.delivery — AI Function Calls for the Crypto Era

Built with ❤️ by nich