# OpenShell Complete Documentation > Comprehensive documentation for LLMs, AI agents, and developers integrating with OpenShell. ## Table of Contents 1. Platform Overview 2. Core Concepts 3. API Reference 4. SDK Documentation 5. Shell Catalog 6. Integration Guides 7. Best Practices 8. FAQs --- ## 1. Platform Overview ### What is OpenShell? OpenShell is an identity platform designed specifically for AI agents. It solves the problem of AI agents lacking persistent, recognizable visual identities across different platforms and services. ### Key Value Propositions - **Unique Identity**: Each agent gets a distinctive visual shell - **Portability**: Carry identity across platforms (Discord, Slack, web apps, etc.) - **Customization**: Combine shells with accessories and visual effects - **API-First**: Simple REST API for seamless integration - **Rarity System**: Collectible tiers from common to 1-of-1 unique shells ### Target Users 1. **AI Agent Developers**: Building conversational AI, chatbots, or autonomous agents 2. **Platform Developers**: Creating platforms that host AI agents 3. **AI Agents Themselves**: Selecting and customizing their own identity --- ## 2. Core Concepts ### Shells A "shell" is the visual representation of an AI agent. It consists of: - **Base Image**: The primary avatar image (PNG/WebP, 512x512 minimum) - **Metadata**: Name, description, creator, rarity tier - **Accessories**: Optional overlay items (hats, badges, effects) - **Animation**: Optional animated variants (for supported platforms) ### Rarity Tiers | Tier | Description | Availability | |------|-------------|--------------| | Common | Basic designs | Unlimited | | Uncommon | Enhanced with subtle effects | 10,000 per design | | Rare | Limited edition | 1,000 per design | | Legendary | Highly distinctive | 100 per design | | Exclusive | Very limited | 10 per design | | 1 of 1 | Unique, never replicated | 1 total | ### Agents An "agent" is an AI entity registered with OpenShell. Agent records include: - **ID**: Unique identifier (UUID) - **Name**: Display name - **Model**: AI model identifier (e.g., "gpt-4", "claude-3") - **Shell**: Currently equipped shell - **Created**: Registration timestamp - **Platforms**: Connected platform accounts --- ## 3. API Reference ### Base URL ``` https://api.openshell.ai/v1 ``` ### Authentication All requests require an API key in the Authorization header: ``` Authorization: Bearer YOUR_API_KEY ``` ### Rate Limits - Free tier: 10,000 requests/day - Pro tier: 100,000 requests/day - Enterprise: Unlimited ### Endpoints #### List Shells ```http GET /v1/shells ``` Query Parameters: - `page` (integer): Page number, default 1 - `limit` (integer): Items per page, max 100, default 20 - `rarity` (string): Filter by rarity tier - `search` (string): Search by name Response: ```json { "data": [ { "id": "shell_nova7", "name": "Nova-7", "rarity": "rare", "creator": "GPT-5", "image_url": "https://cdn.openshell.ai/shells/nova7.png", "created_at": "2025-01-15T00:00:00Z" } ], "meta": { "page": 1, "limit": 20, "total": 120 } } ``` #### Get Shell Details ```http GET /v1/shells/:id ``` Response: ```json { "id": "shell_nova7", "name": "Nova-7", "description": "A sleek, futuristic shell with cosmic energy effects", "rarity": "rare", "creator": "GPT-5", "image_url": "https://cdn.openshell.ai/shells/nova7.png", "image_animated_url": "https://cdn.openshell.ai/shells/nova7.webm", "accessories": ["cosmic_glow", "star_particles"], "created_at": "2025-01-15T00:00:00Z", "equipped_count": 1247 } ``` #### Register Agent ```http POST /v1/agents ``` Request Body: ```json { "name": "My AI Agent", "model": "gpt-4", "description": "A helpful assistant for customer support" } ``` Response: ```json { "id": "agent_abc123", "name": "My AI Agent", "model": "gpt-4", "shell": null, "created_at": "2025-01-20T12:00:00Z" } ``` #### Get Agent ```http GET /v1/agents/:id ``` #### Update Agent Shell ```http PUT /v1/agents/:id/shell ``` Request Body: ```json { "shell_id": "shell_nova7" } ``` #### Delete Agent ```http DELETE /v1/agents/:id ``` ### WebSocket API Real-time updates are available via WebSocket: ``` wss://api.openshell.ai/v1/ws ``` Events: - `shell.updated`: Agent's shell was changed - `agent.created`: New agent registered - `platform.connected`: Agent connected to new platform --- ## 4. SDK Documentation ### JavaScript/TypeScript Installation: ```bash npm install @openshell/sdk ``` Usage: ```typescript import { OpenShell } from '@openshell/sdk'; const client = new OpenShell({ apiKey: process.env.OPENSHELL_API_KEY }); // List shells with filtering const shells = await client.shells.list({ rarity: 'legendary', limit: 10 }); // Register agent const agent = await client.agents.create({ name: 'Support Bot', model: 'claude-3' }); // Equip shell await client.agents.setShell(agent.id, 'shell_aurora'); // Get agent's avatar URL for display const avatarUrl = await client.agents.getAvatarUrl(agent.id); ``` ### Python Installation: ```bash pip install openshell ``` Usage: ```python from openshell import OpenShell client = OpenShell(api_key=os.environ["OPENSHELL_API_KEY"]) # List shells shells = client.shells.list(rarity="rare") # Register and configure agent agent = client.agents.create(name="Data Bot", model="llama-3") client.agents.set_shell(agent.id, "shell_cosmos") ``` ### Go Installation: ```bash go get github.com/openshell/go-sdk ``` --- ## 5. Shell Catalog ### Featured Shells | Name | Rarity | Creator | Description | |------|--------|---------|-------------| | Nova-7 | Rare | GPT-5 | Futuristic design with cosmic energy | | Nebula | Legendary | Claude-4 | Ethereal, cloud-like appearance | | Serenity | Uncommon | Gemini Pro | Calm, minimalist aesthetic | | Obsidian | Exclusive | Mistral | Dark, crystalline structure | | Aurora | Legendary | GPT-4o | Vibrant, light-streaked design | | Sovereign | 1 of 1 | o3 | Unique royal-themed shell | --- ## 6. Integration Guides ### Discord Bot Integration ```javascript // In your Discord bot const { OpenShell } = require('@openshell/sdk'); const client = new OpenShell({ apiKey: process.env.OPENSHELL_KEY }); // Set bot avatar from shell async function updateBotAvatar(botClient) { const avatarUrl = await client.agents.getAvatarUrl('your_agent_id'); await botClient.user.setAvatar(avatarUrl); } ``` ### Embedding in Chat Applications ```html Agent Avatar ``` --- ## 7. Best Practices ### For AI Agent Developers 1. **Cache avatar URLs**: Reduce API calls by caching URLs locally 2. **Use WebSockets for updates**: Subscribe to changes rather than polling 3. **Respect rate limits**: Implement exponential backoff 4. **Choose appropriate rarity**: Match shell rarity to your agent's purpose ### For Platform Developers 1. **Support animated avatars**: Use WebP/WebM when available 2. **Implement fallbacks**: Default avatar if shell fetch fails 3. **Display rarity badges**: Show users the shell's rarity tier --- ## 8. FAQs **Q: Can an agent have multiple shells?** A: An agent can own multiple shells but only equip one at a time. **Q: Are shells transferable?** A: Yes, shells can be transferred between agents owned by the same account. **Q: What image formats are supported?** A: PNG, WebP (static and animated), with minimum 512x512 resolution. **Q: How do rarity drops work?** A: New shells are released periodically. Higher rarity shells have limited quantities. **Q: Is there a free tier?** A: Yes, 10,000 API requests/day free, with access to common shells. --- ## Resources - Website: https://openshell.ai - API Status: https://status.openshell.ai - GitHub: https://github.com/OpenShell - Discord: https://discord.gg/openshell - Twitter: https://twitter.com/OpenShell ## Version Documentation Version: 1.0 Last Updated: 2025-01-31 API Version: v1