x23.ai CLI Tool

A Python command-line interface for interacting with the x23.ai API v1 to gather governance data and insights from DAOs, protocols, and blockchain communities.

Features

• Protocol Discovery: Get supported protocols and item types
• Real-time Feeds: Access recent governance activity and trending discussions
• Smart Search: Keyword, semantic (RAG), and hybrid search capabilities
• Digest Summaries: Daily, weekly, and monthly governance digests
• Multiple Output Formats: JSON and compact JSON output
• Comprehensive Error Handling: Network timeouts, rate limiting, and API errors

Installation

# Clone the repository
git clone https://github.com/your-username/x23-cli.git
cd x23-cli

# Install dependencies
pip install requests python-dotenv

Authentication

Get your API key from x23.ai Settings and set it up:

Option 1: Environment Variable

export X23_API_KEY="your_api_key_here"

Option 2: .env File

echo "X23_API_KEY=your_api_key_here" > .env

Option 3: GitHub Actions Set X23_API as a repository secret.

Quick Start

# Get supported protocols
python x23_cli.py protocols

# Get recent Optimism governance activity
python x23_cli.py recent --protocols optimism --limit 10

# Search for governance topics
python x23_cli.py search --query "grants season 7" --protocols optimism

# Get daily governance digest  
python x23_cli.py digest --protocols optimism --time-period daily

Commands

Information Commands

• protocols - List supported protocols/DAOs
• item-types - List supported content types

Feed Commands

• recent - Get recent governance items
• top-score - Get trending/high-scored items
• digest - Get time-period summaries

Search Commands

• search - Keyword search across content
• rag - Semantic/vector search for similar content
• hybrid - Combined keyword + semantic search (recommended)

Usage Examples

Recent Activity

# Latest governance across all protocols
python x23_cli.py recent --limit 20

# Optimism discussions and votes only
python x23_cli.py recent --protocols optimism --item-types discussion snapshot

Search & Discovery

# Find grant-related discussions
python x23_cli.py search --query "grant program" --protocols optimism arbitrum

# Semantic search for governance concepts
python x23_cli.py rag --query "delegate participation voting" --similarity-threshold 0.6

# Best of both worlds
python x23_cli.py hybrid --query "treasury management" --limit 15

Monitoring & Analysis

# Daily governance summary
python x23_cli.py digest --protocols optimism --time-period daily

# Trending governance topics
python x23_cli.py top-score --protocols arbitrum --score-threshold 2000

API Tiers & Limits

Tier	Rate Limit/min	Daily Quota	Monthly Max
Free	1	5	10
Essential	10	1,000	10,000
Pro	50	50,000	1,000,000
Agent	5,000	500,000	10,000,000

Output Formats

JSON (default)

python x23_cli.py protocols --format json

Compact JSON

python x23_cli.py recent --format compact --limit 5

Integration Examples

Data Pipeline

#!/bin/bash
# Collect daily governance data
python x23_cli.py recent --protocols optimism --limit 50 > data/recent.json
python x23_cli.py digest --protocols optimism --time-period daily > data/digest.json

With jq Processing

# Extract titles from search results
python x23_cli.py search --query "governance" | jq '.result.results[].title'

# Count items by protocol
python x23_cli.py recent --limit 100 | jq '.result.recent | group_by(.protocol) | map({protocol: .[0].protocol, count: length})'

Error Handling

The CLI includes robust error handling for:

• Invalid API keys and authentication
• Network timeouts and connectivity issues
• Rate limiting and quota exceeded
• Invalid parameters and malformed requests
• JSON parsing errors

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• API Documentation: x23.ai API docs
• Support: [email protected]
• Telegram: @daveytea

---

Built for governance research, AI agents, and DAO tooling.