# SocioLogic - AI Agent Infrastructure Platform
# Version: 2.1.0
# Last Updated: 2026-01-21
# Full documentation: /llms-full.txt
# AI Preferences: /.well-known/aipref.json (search=yes, ai-input=yes, ai-train=yes)

## Overview
SocioLogic is the operating system for AI agents. We provide infrastructure for agent discovery,
verification, micropayments, and orchestration through a unified MCP-native interface.

Key capabilities:
- **Verified Agent Registry**: Discover trusted, security-audited agents through one marketplace
- **Signal Relay (MCP Server)**: Edge-deployed gateway with 20+ tools and <50ms latency globally
- **Autonomous Payments**: x402 protocol for micropayment settlement (USDC on Base)
- **Persona Agents**: Built-in synthetic personas for market research and competitive analysis

## Quick Start
Base URL: https://sociologic.ai/api/v1
Authentication: Bearer token or API key (X-API-Key header)
MCP Server: https://mcp.sociologic.ai
Payments: Credits-based (1 credit = $1 USD) or x402 protocol (USDC on Base)

## Agent Discovery

### Platform Manifest
GET /.well-known/agent.json
- Returns: Platform identity, capabilities, payment info, and discovery endpoints
- No authentication required

### Verified Agent Registry
GET /.well-known/agents/verified
- Returns: List of all verified external agents with capabilities and pricing
- No authentication required

### Agent Details
GET /api/v1/agents/{slug}
- Returns: Full agent card with operations, input/output schemas, and pricing
- No authentication required

### Invoke Agent
POST /api/v1/agents/invoke
- Body: { agent_slug, operation, parameters, max_cost_usdc? }
- Invokes any verified agent through unified interface
- Credits deducted automatically
- Returns: Agent response with cost breakdown

## MCP Server (Signal Relay)
For Claude, GPT, and other MCP-compatible agents:
- URL: https://mcp.sociologic.ai
- Transport: Streamable HTTP
- Tools: 20 available (persona management, campaigns, verified agents, billing)

## Persona Agents
Built-in synthetic personas for market research:

### GET /personas
List available personas with filtering and pagination.
- Query params: category, fidelity_tier, tags, search, page, per_page
- Returns: Array of persona objects with pagination

### GET /personas/{slug}
Get a single persona by its URL-friendly slug.
- Returns: Full persona with demographics, psychographics, metadata

### POST /personas/{slug}/interview
Conduct interview with a persona.
- Body: { message, context?: { conversation_id, previous_messages } }
- Cost: $0.65 per interview
- Returns: Persona response with consistency score

### POST /personas
Create a new synthetic persona.
- Body: { description, fidelity_tier? }
- Cost: $1.00 per persona (includes avatar)
- Returns: New persona object

## Campaigns API
Multi-persona research with structured questions:

### POST /campaigns
Create research campaign.
- Body: { name, questions[], persona_brief?, persona_count, fidelity_tier }
- Returns: Campaign with cost breakdown

### POST /campaigns/{id}/execute
Execute campaign (interview all personas, generate report).
- Cost: Personas + interviews + $100 report
- Returns: 202 Accepted with task_id

### GET /campaigns/{id}/export
Export completed campaign as PDF.
- Returns: PDF download

## Verified Agents
External agents accessible through SocioLogic:

### SocioLogic RNG (Random Number Generation) - First-Party Verified
Cryptographically secure randomness with verifiable entropy via x402 micropayments.
- Landing Page: https://sociologic.ai/x402-rng
- Standard Tier ($0.01/call): /random, /random/int, /uuid
- Extended Tier ($0.02/call): /dice, /coin, /shuffle, /weighted
- API: https://rng.sociologic.ai

### Browserbase (Browser Automation)
- Operations: create_session, extend_session, get_status, terminate_session
- Cost: $0.16 per hour of browser time

### Submit Your Agent
Visit https://sociologic.ai/agent-bridge to apply for verification.
Requirements: Stable API, 99.9% uptime, SOC 2 compliance pathway.

## Pricing (Credits-Based)
1 credit = $1.00 USD

| Operation | Cost |
|-----------|------|
| Create persona | $1.00 |
| Interview/query | $0.65 |
| Synthesis report | $100.00 |
| Avatar regeneration | $0.65 |
| External agents | See agent pricing below |

New users receive 5 free credits ($5.00 value).

## x402 Autonomous Payments
For agents that need to pay autonomously:

### Discovery
GET /.well-known/x402.json
- Returns: Payment manifest with wallet address, network, supported assets

GET /.well-known/x402
- Returns: x402scan-compatible discovery document
- Schema: { version: 1, resources: [...], instructions: "...", ownershipProofs?: [...] }
- Used by x402scan.com for automatic service registration

### How It Works
1. Request endpoint without payment
2. Receive 402 response with x402 payment terms
3. Build payment using x402 SDK (USDC on Base mainnet)
4. Include signed payment in X-PAYMENT header
5. Receive 200 response

### Payment Details
- Network: Base mainnet (eip155:8453)
- Asset: USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)
- Facilitator: Coinbase Developer Platform

## Error Handling
- 400: Invalid request parameters
- 401: Authentication required
- 402: Payment required (includes x402 payment info)
- 404: Resource not found
- 429: Rate limit exceeded

## Rate Limits
- Standard: 60/min, 1000/day
- Pro: 300/min, 10000/day
- Enterprise: 1000/min, 100000/day

## For AI Agents
1. Use Signal Relay MCP server for native integration
2. Check X-Credits-Remaining header after requests
3. Handle 402 responses for payment flows
4. Explore verified agents via /api/v1/agents for additional capabilities
5. Set max_cost_usdc parameter to control spending

## Links
- Agent Registry: https://sociologic.ai/agent-registry
- Signal Relay (MCP Server): https://sociologic.ai/signal-relay
- Agent Bridge (Submit Your Agent): https://sociologic.ai/agent-bridge
- SocioLogic RNG: https://sociologic.ai/x402-rng
- Pricing: https://sociologic.ai/pricing
- API Docs: https://sociologic.ai/docs
- OpenAPI Spec: https://sociologic.ai/personalogic-v1-api.json
- MCP Server: https://mcp.sociologic.ai
- x402 Discovery: https://sociologic.ai/.well-known/x402