Wispy

Autonomous AI Agent Infrastructure — Think for Days, Pay for Services, Prove Identity On-Chain

Website · Docs · API Docs · npm · Issues · Quickstart

What is Wispy?

Wispy is an autonomous AI agent platform that goes beyond simple chatbots. It can run multi-day tasks independently, make payments for premium APIs, prove its identity on-chain, and communicate with other AI agents — all from a single CLI or API.

Think of it as an AI engineer that can:

• Plan and execute complex projects over hours or days (Marathon Mode)
• Pay for services automatically using USDC via the x402 protocol
• Verify its identity on-chain with ERC-8004 registrations
• Talk to other agents using Google's A2A protocol
• Operate across channels — CLI, Telegram, WhatsApp, REST API, WebSocket

Wispy is powered by Google Gemini 2.5 Pro with configurable thinking budgets up to 24K tokens, giving it deep reasoning capabilities for complex multi-step tasks.

Quickstart

Install

npm install -g wispy-ai

pnpm add -g wispy-ai

brew tap brn-mwai/wispy && brew install wispy

curl -fsSL https://wispy.cc/install.sh | bash

irm https://wispy.cc/install.ps1 | iex

curl -o install.bat https://wispy.cc/install.bat && install.bat

Setup

wispy setup

This interactive wizard will configure your AI credentials (Gemini API key or Vertex AI), channels, and optional blockchain integrations.

Run

# Interactive chat
wispy chat

# Start the full gateway (API + channels + A2A)
wispy gateway

# Run a marathon (multi-day autonomous task)
wispy marathon "Build a full-stack SaaS dashboard with Next.js"

# Execute a single agent task
wispy agent "Research the DePIN market and produce a detailed report"

Features

Marathon Mode — Multi-Day Autonomous Execution

Wispy's Marathon Mode plans complex tasks into milestones, then executes them autonomously over hours or days. It checkpoints progress, self-recovers from failures, and sends real-time updates via Telegram or WhatsApp.

wispy marathon "Build and deploy a REST API with auth, tests, and docs"

• Deep planning with Gemini 2.5 Pro (up to 24K token thinking budget)
• Autonomous milestone-by-milestone execution
• Self-recovery — analyzes failures and retries with different approaches
• Checkpointing — pause anytime, resume exactly where you left off
• Real-time notifications on progress via Telegram/WhatsApp

Agentic Commerce — Autonomous Payments with Spending Controls

Wispy handles payments autonomously with a full commerce policy engine. It can pay for premium APIs (x402), send USDC transfers, and manage its own wallet — all with configurable guardrails.

• Real USDC transfers on Base via the wallet_pay tool
• Commerce policy engine — per-transaction limits, daily spending caps, auto-approve thresholds
• Recipient controls — whitelist trusted addresses, blacklist known-bad ones
• MetaMask interop — export/import private keys to manage your agent's wallet from MetaMask
• Automatic HTTP 402 handling — detects payment-required APIs and pays with USDC
• Full audit trail — transaction logging, daily ledger, spending summaries

# Wallet management
/wallet                  # Show address, balance, spending summary
/wallet export           # Export private key for MetaMask
/wallet import <key>     # Import a MetaMask wallet
/wallet fund             # Show funding instructions
/wallet commerce         # View commerce policy & daily spending
/wallet commerce set dailyLimit 50   # Update spending limits

ERC-8004 Identity — Verifiable Agent Registration

Register your agent on-chain using the ERC-8004 standard. This gives Wispy a verifiable, decentralized identity that other agents and services can trust.

• On-chain registration on Base Sepolia
• Reputation tracking system
• Serves /.well-known/agent.json for discovery
• Validation framework for trust verification

A2A Protocol — Agent-to-Agent Communication

Wispy implements Google's Agent-to-Agent protocol for discovering, delegating tasks to, and receiving results from other AI agents.

• Agent card publishing and discovery
• Task delegation with structured messaging
• Secure Ed25519 message signing
• Compatible with the broader A2A ecosystem

27+ Built-in Tools

Multi-Channel Support

Public REST API

Wispy exposes a full REST API so you can integrate it into your own products. Manage API keys, set scopes and rate limits, and interact with all Wispy features programmatically.

# Create an API key
wispy api create "My App" --scopes chat,marathon

# Use it
curl -H "Authorization: Bearer wsk_..." https://your-wispy-instance/api/v1/chat \
  -d '{"message": "Hello"}'

See the full API documentation at docs.wispy.cc/developers.

Architecture

┌────────────────────────────────────────────────────────────────────┐
│                        WISPY PLATFORM                              │
├────────────────────────────────────────────────────────────────────┤
│                                                                    │
│   Channels          Core Engine           Protocols                │
│  ┌──────────┐     ┌──────────────┐     ┌──────────────┐          │
│  │ CLI      │     │ Gemini 2.5   │     │ x402         │          │
│  │ Telegram │────▶│ Pro Agent    │────▶│ Payments     │          │
│  │ WhatsApp │     │ + Marathon   │     │ (USDC/Base)  │          │
│  │ REST API │     │   Mode       │     ├──────────────┤          │
│  │ WebSocket│     └──────┬───────┘     │ ERC-8004     │          │
│  └──────────┘            │             │ Identity     │          │
│                          │             ├──────────────┤          │
│   Services               │             │ A2A Protocol │          │
│  ┌──────────┐     ┌──────▼───────┐     │ (Google)     │          │
│  │ Memory   │     │  27+ Tools   │     └──────────────┘          │
│  │ Cron     │     │  + MCP       │                               │
│  │ Skills   │     │  Servers     │     Security                  │
│  │ Browser  │     └──────────────┘     ┌──────────────┐          │
│  │ Voice    │                          │ Trust Ctrl   │          │
│  └──────────┘                          │ Device Auth  │          │
│                                        │ Rate Limits  │          │
│                                        └──────────────┘          │
└────────────────────────────────────────────────────────────────────┘

Configuration

Option 1: Gemini API Key (Simplest)

GEMINI_API_KEY=your-api-key

Get your key at Google AI Studio.

Option 2: Vertex AI (Production)

GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=us-central1

Then authenticate:

gcloud auth application-default login

Full Configuration

Wispy uses ~/.wispy/config.yaml:

agent:
  name: Wispy
  id: wispy-agent-001

gemini:
  vertexai:
    enabled: true
    project: your-gcp-project
    location: us-central1
  models:
    pro: gemini-2.5-pro
    flash: gemini-2.5-flash
    image: imagen-3.0-generate-002
    embedding: text-embedding-004

marathon:
  thinkingLevel: ultra       # Thinking budget: low | medium | high | ultra
  checkpointInterval: 5

wallet:
  enabled: true
  chain: base-sepolia
  commerce:
    maxPerTransaction: 1.0
    dailyLimit: 10.0
    autoApproveBelow: 0.10

channels:
  telegram:
    enabled: true
  whatsapp:
    enabled: true
  rest:
    enabled: true
    port: 4001
  web:
    port: 4000

security:
  autonomousMode: false      # Auto-approve file/code operations
  actionGuard:
    enabled: true

memory:
  heartbeatIntervalMinutes: 30

Security

Wispy is built with security as a first-class concern:

• Device Identity — Ed25519 keypair generated per device for authentication
• Encrypted Storage — AES-256-GCM encryption for credentials and sensitive data
• Trust Controller — Approval workflows for sensitive operations (file writes, payments, shell commands)
• Action Guard — Configurable rules for what the agent can and cannot do autonomously
• API Key System — Scoped keys with rate limiting, expiry, and usage tracking
• Secret Scanner — Automatic detection and redaction of API keys in outputs
• Loop Detection — Prevents infinite tool execution loops
• Session Isolation — Separate contexts for different users and channels

CLI Reference

wispy chat              Interactive chat session
wispy gateway           Start full gateway (API + channels + A2A)
wispy marathon <goal>   Start autonomous multi-day task execution
wispy agent <task>      Execute a single agent task
wispy setup             Interactive configuration wizard
wispy doctor            Diagnose configuration issues
wispy skill <name>      Run a specific skill
wispy api create        Create an API key
wispy api list          List API keys
wispy api revoke <id>   Revoke an API key
wispy voice             Enter voice mode
wispy history           View conversation history

Technical Specs

API Usage

Chat

import { Agent } from 'wispy-ai';

const agent = new Agent({ config, runtimeDir, soulDir });

for await (const chunk of agent.chatStream("Build a landing page", "user-1", "api")) {
  process.stdout.write(chunk.content);
}

Marathon

const marathon = agent.startMarathon("Build a full-stack app with auth and tests");

marathon.on('milestone', (m) => console.log(`Completed: ${m.name}`));
marathon.on('complete', (result) => console.log('Done!', result));

REST API

# Create API key
wispy api create "My Integration" --scopes chat,chat:stream,marathon

# Chat
curl -X POST https://localhost:4001/api/v1/chat \
  -H "Authorization: Bearer wsk_..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, Wispy"}'

# Stream (SSE)
curl -N https://localhost:4001/api/v1/chat/stream \
  -H "Authorization: Bearer wsk_..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Explain quantum computing"}'

Full API docs: docs.wispy.cc/developers

Deployed Contracts

Documentation

Full documentation is available at docs.wispy.cc:

• Getting Started — Installation, setup, first chat
• Marathon Mode — Multi-day autonomous task execution
• Agentic Commerce — Wallet, payments, commerce policies
• API Reference — REST API, WebSocket, authentication
• Channels — Telegram, WhatsApp, CLI, REST
• Tools — Built-in tools, MCP servers, custom skills
• Security — Trust controller, device auth, action guard
• Configuration — Full config reference

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

git clone https://github.com/brn-mwai/wispy.git
cd wispy
npm install
npm run build
npm run dev

License

MIT

Wispy is built by Hausor Labs Team (HL Team)

wispy.cc · docs · npm · GitHub