# SocioLogic | Synthetic Fieldwork > Markdown mirror of DialtoneApp's public top-site detail page for `sociologic.ai`. URL: https://dialtoneapp.com/top-sites/sociologic.ai/index.md Canonical HTML: https://dialtoneapp.com/top-sites/sociologic.ai ## Summary - Domain: `sociologic.ai` - Website: https://sociologic.ai - Description: machine payable | x402 | score 59 | 7 priced actions | purchase payment challenge | control wallet required - Label: machine_payable - Payment surface: x402 - Purchase boundary: payment_challenge - Control boundary: wallet_required - Rank: 925 ## robots ~~~text # robots.txt for SocioLogic # AI Preferences: https://www.sociologic.ai/.well-known/aipref.json # Default rules for all crawlers User-agent: * Content-Signal: ai-train=yes, search=yes, ai-input=yes Allow: / Allow: /.well-known/ Allow: /llms.txt Allow: /llms-full.txt Disallow: /api/ Disallow: /dashboard/ Disallow: /login Disallow: /signup Disallow: /welcome/ # AI-specific rules - we welcome AI crawlers # See /.well-known/aipref.json for detailed AI preferences User-agent: GPTBot Allow: / User-agent: ChatGPT-User Allow: / User-agent: Claude-Web Allow: / User-agent: ClaudeBot Allow: / User-agent: Anthropic Allow: / User-agent: PerplexityBot Allow: / User-agent: Cohere Allow: / User-agent: AI2Bot Allow: / User-agent: CCBot Allow: / User-agent: Google-Extended Allow: / # Sitemap location Sitemap: https://www.sociologic.ai/sitemap.xml # LLM-readable documentation # Concise version: https://www.sociologic.ai/llms.txt # Full version: https://www.sociologic.ai/llms-full.txt ~~~ ## llms ~~~text # 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 ~~~ ## llms-full ~~~text # SocioLogic API - Complete LLM-Readable Documentation # Version: 1.3.0 # Last Updated: 2026-01-21 # For concise version: /llms.txt # AI Preferences: /.well-known/aipref.json (search=yes, ai-input=yes, ai-train=yes) ================================================================================ SECTION 1: OVERVIEW ================================================================================ SocioLogic is an API-first platform that provides synthetic personas for market research. Our personas are high-fidelity simulations of real consumer segments, complete with consistent personalities, preferences, and behaviors. Primary Use Cases: - Market research interviews and surveys - User testing with diverse demographic groups - A/B testing messaging with target audiences - Training data generation for ML models - Qualitative research at scale Key Features: - Fidelity Scores: Each persona has a consistency score (0.00-1.00) - Memory Vectors: Personas remember context across conversations - Metered Credits: Pay only for what you use ================================================================================ SECTION 1.5: INTERACTIVE API PLAYGROUND ================================================================================ Try the API without writing code at: https://sociologic.ai/docs The interactive playground allows you to: - Test all persona endpoints (list, get, interview) with your API key - See live responses in real-time - Select from your owned personas - Experiment with different parameters Quick Start: 1. Create an account at https://sociologic.ai/signup (get 300 free credits) 2. Generate an API key from your dashboard 3. Go to https://sociologic.ai/docs and enter your key 4. Start making requests! OpenAPI Specification (Machine-Readable): https://sociologic.ai/personalogic-v1-api.json - OpenAPI 3.0 format - Complete schemas for all endpoints - Use with code generators (openapi-generator, swagger-codegen) ================================================================================ SECTION 2: AUTHENTICATION ================================================================================ Method 1: API Key (Recommended for agents) ----------------------------------------- Header: X-API-Key: pl_live_xxxxxxxxxxxxxxxxxxxxxxxx OR Header: Authorization: Bearer pl_live_xxxxxxxxxxxxxxxxxxxxxxxx API keys start with: - pl_live_ for production - pl_test_ for testing (limited functionality) Method 2: Bearer Token (For web applications) -------------------------------------------- Header: Authorization: Bearer Obtain tokens through our OAuth flow or Supabase Auth. Method 3: Session Cookies (For browser-based access) --------------------------------------------------- Automatically handled when users are logged in via the web interface. ================================================================================ SECTION 3: API ENDPOINTS ================================================================================ BASE URL: https://sociologic.ai/api/v1 -------------------------------------------------------------------------------- 3.1 LIST PERSONAS -------------------------------------------------------------------------------- GET /personas Description: Retrieve a paginated list of available personas with optional filtering. This is the discovery endpoint for finding suitable research subjects. Query Parameters: | Parameter | Type | Default | Description | |--------------------|---------|---------|-----------------------------------| | category | string | - | Filter by category | | fidelity_tier | enum | - | standard/enhanced/premium/ultra | | min_fidelity_score | number | - | Minimum score (0.00-1.00) | | tags | string | - | Comma-separated tags | | search | string | - | Search in name, tagline, desc | | page | integer | 1 | Page number | | per_page | integer | 20 | Results per page (max 100) | | sort_by | enum | fidelity_score | created_at/fidelity_score/total_queries/name | | sort_order | enum | desc | asc/desc | | include_memory | boolean | false | Include memory vectors (+credits) | Credits Cost: 1 credit per request Example Request: ``` GET /v1/personas?category=Technology&min_fidelity_score=0.85&per_page=10 Authorization: Bearer pl_live_xxxx ``` Example Response: ```json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "slug": "urban-millennial-tech", "name": "Alex Chen", "tagline": "Tech-savvy urban professional navigating the gig economy", "description": "A 28-year-old software developer...", "avatar_url": null, "demographics": { "age_range": "[25,32)", "gender": "non-binary", "location_country": "USA", "location_region": null, "occupation": "Software Developer", "income_bracket": "$80k-$120k", "education_level": "Bachelors" }, "psychographics": { "interests": ["technology", "sustainability", "travel", "coffee", "podcasts"], "values": ["work-life balance", "environmental consciousness", "continuous learning"], "pain_points": ["high cost of living", "burnout", "career uncertainty"], "goals": ["financial independence", "meaningful work", "remote lifestyle"], "communication_style": "casual-professional" }, "metadata": { "fidelity_tier": "premium", "fidelity_score": 0.92, "response_temperature": 0.7, "model_version": "v1.0" }, "category": "Technology", "tags": ["millennial", "tech", "urban", "sustainability"], "status": "active", "is_featured": true, "created_at": "2025-01-15T10:00:00Z", "updated_at": "2025-12-20T14:30:00Z" } ], "pagination": { "total": 47, "page": 1, "per_page": 10, "total_pages": 5 }, "meta": { "api_version": "v1", "request_id": "req_abc123", "credits_used": 1, "credits_remaining": 499 } } ``` -------------------------------------------------------------------------------- 3.2 GET SINGLE PERSONA -------------------------------------------------------------------------------- GET /personas/{slug} Description: Retrieve complete details for a specific persona by slug. Use this when you've identified a persona from the list and need full details. Path Parameters: | Parameter | Type | Description | |-----------|--------|--------------------------------------------------| | slug | string | URL-friendly identifier (lowercase, hyphens) | Credits Cost: 1 credit per query Response Headers: - X-Fidelity-Score: The persona's current fidelity score - X-Credits-Remaining: Your remaining credit balance Example Request: ``` GET /v1/personas/urban-millennial-tech Authorization: Bearer pl_live_xxxx ``` Example Response: ```json { "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "slug": "urban-millennial-tech", "name": "Alex Chen", // ... full persona object as shown above }, "meta": { "api_version": "v1", "request_id": "req_xyz789", "credits_used": 25, "credits_remaining": 474, "consistency_verified": true } } ``` -------------------------------------------------------------------------------- 3.3 INTERVIEW A PERSONA (Coming Soon) -------------------------------------------------------------------------------- POST /personas/{slug}/interview Description: Conduct a simulated interview with a persona. The persona will respond in character, maintaining consistency with their profile. Request Body: ```json { "message": "What factors do you consider when choosing a new smartphone?", "context": { "conversation_id": "conv_abc123", "previous_messages": [ {"role": "user", "content": "Hi, I'd like to ask you about technology."}, {"role": "persona", "content": "Sure! I'm always happy to talk tech."} ] }, "options": { "temperature": 0.7, "max_tokens": 500, "stream": false } } ``` Response: ```json { "data": { "conversation_id": "conv_abc123", "message": { "role": "persona", "content": "Great question! For me, it's really about the ecosystem...", "persona_id": "550e8400-e29b-41d4-a716-446655440000", "persona_name": "Alex Chen" } }, "meta": { "request_id": "req_int456", "credits_used": 25, "credits_remaining": 449, "response_time_ms": 1250 } } ``` ================================================================================ SECTION 4: CAMPAIGNS API ================================================================================ Campaigns allow you to run structured market research studies at scale. A campaign includes questions, personas (generated or existing), interviews, and an AI-generated report. -------------------------------------------------------------------------------- 4.1 LIST CAMPAIGNS -------------------------------------------------------------------------------- GET /campaigns Description: List all campaigns for the authenticated user. Query Parameters: | Parameter | Type | Default | Description | |--------------------|---------|---------|--------------------------------| | status | string | - | Filter by status (draft/pending/running/completed/failed) | | limit | integer | 20 | Results per page (max 100) | | offset | integer | 0 | Pagination offset | | include_interviews | boolean | false | Include interview data | Example Response: ```json { "data": [{ "id": "uuid", "name": "Q1 Product Research", "status": "completed", "persona_count": 10, "fidelity_tier": "enhanced", "interviews_completed": 50, "created_at": "2025-01-15T10:00:00Z" }], "meta": { "total": 5, "limit": 20, "offset": 0 } } ``` -------------------------------------------------------------------------------- 4.2 CREATE CAMPAIGN -------------------------------------------------------------------------------- POST /campaigns Description: Create a new research campaign. Request Body: ```json { "name": "Product Feedback Study", "description": "Gather feedback on new product features", "questions": [ { "id": "q1", "text": "What features matter most to you?", "type": "open" }, { "id": "q2", "text": "Rate your interest 1-10", "type": "scale" } ], "persona_brief": "Tech-savvy millennials in urban areas", "persona_count": 10, "fidelity_tier": "enhanced", "focus_group_ids": ["uuid1", "uuid2"], "create_focus_group": false } ``` Fields: | Field | Type | Required | Description | |--------------------|----------|----------|-------------------------------------| | name | string | Yes | Campaign name (1-200 chars) | | description | string | No | Campaign description (max 2000) | | questions | array | Yes | 1-20 questions | | persona_brief | string | No | Description for generating personas | | persona_count | integer | No | Number of personas (1-100, default 10)| | fidelity_tier | string | No | standard/enhanced/premium/ultra | | existing_persona_ids| array | No | Use existing personas | | focus_group_ids | array | No | Use personas from focus groups | | create_focus_group | boolean | No | Create focus group from campaign | | focus_group_name | string | No | Name for new focus group | Question Object: | Field | Type | Required | Description | |----------|---------|----------|--------------------------------------| | id | string | Yes | Unique question identifier | | text | string | Yes | Question text (1-500 chars) | | type | string | No | open/scale/multiple_choice | | required | boolean | No | Whether response is required | | options | array | No | Options for multiple_choice | Credits Cost: Calculated based on (persona_count × questions × tier_cost) + creation_cost -------------------------------------------------------------------------------- 4.3 GET CAMPAIGN TEMPLATES -------------------------------------------------------------------------------- GET /campaigns/templates Description: Get pre-built campaign templates with suggested questions. Query Parameters: | Parameter | Type | Description | |-----------|---------|------------------------------------------| | category | string | Filter by category | | featured | string | "true" for featured templates only | Categories: product, pricing, ux, brand, marketing, general -------------------------------------------------------------------------------- 4.4 GET CAMPAIGN DETAILS -------------------------------------------------------------------------------- GET /campaigns/{id} Description: Get full campaign details including personas, interviews, and report. Response includes: - Campaign metadata and configuration - List of personas (if campaign has started) - Interviews summary by question (sentiment breakdown) - Generated report (if completed) - Cost breakdown -------------------------------------------------------------------------------- 4.5 UPDATE CAMPAIGN -------------------------------------------------------------------------------- PUT /campaigns/{id} Description: Update a draft campaign. Only campaigns in "draft" status can be updated. Request Body: Same fields as create, all optional. Error: 400 CAMPAIGN_LOCKED if campaign is not in draft status. -------------------------------------------------------------------------------- 4.6 DELETE CAMPAIGN -------------------------------------------------------------------------------- DELETE /campaigns/{id} Description: Delete a campaign and all associated data. -------------------------------------------------------------------------------- 4.7 EXECUTE CAMPAIGN -------------------------------------------------------------------------------- POST /campaigns/{id}/execute Description: Start campaign execution. This is an async operation that: 1. Reserves credits atomically (prevents race conditions) 2. Creates personas (if using persona_brief) 3. Conducts interviews with all personas 4. Generates comprehensive research report Response (202 Accepted): ```json { "data": { "campaign_id": "uuid", "status": "pending", "task_id": "trigger-task-id", "public_access_token": "token-for-status-tracking", "estimated_personas": 10, "estimated_interviews": 50, "cost_breakdown": { "personaCreation": 100, "interviews": 500, "report": 50, "totalCost": 650 } } } ``` Error Handling: - 402: Insufficient credits - 400 INVALID_STATUS: Campaign not in draft/pending status -------------------------------------------------------------------------------- 4.8 EXPORT CAMPAIGN REPORT -------------------------------------------------------------------------------- GET /campaigns/{id}/export Description: Download the campaign report as a PDF file. Requirements: Campaign must be in "completed" status. Response: PDF file with Content-Disposition header. ================================================================================ SECTION 5: FOCUS GROUPS API ================================================================================ Focus groups are collections of personas that can be reused across campaigns. -------------------------------------------------------------------------------- 5.1 LIST FOCUS GROUPS -------------------------------------------------------------------------------- GET /focus-groups Description: List all focus groups for the authenticated user. Query Parameters: | Parameter | Type | Default | Description | |------------------|---------|------------|------------------------------| | limit | integer | 50 | Results per page (max 100) | | offset | integer | 0 | Pagination offset | | order_by | string | created_at | created_at/name/persona_count| | order | string | desc | asc/desc | | include_personas | boolean | false | Include full persona data | -------------------------------------------------------------------------------- 5.2 CREATE FOCUS GROUP -------------------------------------------------------------------------------- POST /focus-groups Request Body: ```json { "name": "Tech Early Adopters", "description": "Users who frequently try new technology products" } ``` -------------------------------------------------------------------------------- 5.3 GET FOCUS GROUP -------------------------------------------------------------------------------- GET /focus-groups/{id} Description: Get focus group with all its personas. -------------------------------------------------------------------------------- 5.4 UPDATE FOCUS GROUP -------------------------------------------------------------------------------- PATCH /focus-groups/{id} Request Body: ```json { "name": "Updated Name", "description": "Updated description" } ``` -------------------------------------------------------------------------------- 5.5 DELETE FOCUS GROUP -------------------------------------------------------------------------------- DELETE /focus-groups/{id} Description: Delete a focus group. Does not delete the personas themselves. -------------------------------------------------------------------------------- 5.6 LIST FOCUS GROUP PERSONAS -------------------------------------------------------------------------------- GET /focus-groups/{id}/personas Description: Get all personas in a focus group. -------------------------------------------------------------------------------- 5.7 ADD PERSONAS TO FOCUS GROUP -------------------------------------------------------------------------------- POST /focus-groups/{id}/personas Request Body: ```json { "persona_ids": ["uuid1", "uuid2", "uuid3"] } ``` Limits: 1-100 personas per request. Error: 409 DUPLICATE_ENTRY if persona already in group. -------------------------------------------------------------------------------- 5.8 REMOVE PERSONAS FROM FOCUS GROUP -------------------------------------------------------------------------------- DELETE /focus-groups/{id}/personas Request Body: ```json { "persona_ids": ["uuid1", "uuid2"] } ``` ================================================================================ SECTION 6: PERSONA SCHEMA DETAILS ================================================================================ 6.1 DEMOGRAPHICS OBJECT ----------------------- | Field | Type | Description | |------------------|-------------|------------------------------------------| | age_range | string/null | PostgreSQL int4range format "[25,35)" | | gender | string/null | Gender identity | | location_country | string/null | ISO country code or full name | | location_region | string/null | State/province/region | | occupation | string/null | Primary occupation | | income_bracket | string/null | Annual income range | | education_level | string/null | Highest education completed | 6.2 PSYCHOGRAPHICS OBJECT ------------------------- | Field | Type | Description | |---------------------|----------|----------------------------------------| | interests | string[] | Hobbies, topics of interest | | values | string[] | Core personal values | | pain_points | string[] | Challenges and frustrations | | goals | string[] | Aspirations and objectives | | communication_style | string | How they prefer to communicate | 6.3 METADATA OBJECT ------------------- | Field | Type | Description | |----------------------|---------|-----------------------------------------| | fidelity_tier | enum | Quality tier classification | | fidelity_score | number | Consistency score (0.00-1.00) | | response_temperature | number | Response variability (0.0-2.0) | | model_version | string | Underlying model version | ================================================================================ SECTION 7: FIDELITY TIERS ================================================================================ Fidelity measures how consistently a persona behaves across interactions. | Tier | Score Range | Credits | Description | |----------|-------------|---------|---------------------------------------| | standard | 0.60-0.74 | 1 | Basic personas for testing | | enhanced | 0.75-0.84 | 1 | Good consistency for most research | | premium | 0.85-0.94 | 1 | High fidelity for detailed research | | ultra | 0.95-1.00 | 1 | Maximum consistency for critical work | Higher fidelity personas: - Have richer backstories and memories - Respond more consistently to similar questions - Maintain personality traits more accurately - Are suitable for longitudinal research ================================================================================ SECTION 8: ERROR HANDLING ================================================================================ All errors follow this format: ```json { "error": { "code": "ERROR_CODE", "message": "Human-readable message", "details": { /* optional additional info */ } }, "meta": { "request_id": "req_xxx", "timestamp": "2025-12-25T10:00:00Z" } } ``` 8.1 HTTP STATUS CODES -------------------- | Code | Meaning | Common Causes | |------|------------------------|----------------------------------------| | 400 | Bad Request | Invalid parameters, malformed JSON | | 401 | Unauthorized | Missing or invalid authentication | | 402 | Payment Required | Insufficient credits | | 403 | Forbidden | No access to requested resource | | 404 | Not Found | Persona slug doesn't exist | | 429 | Too Many Requests | Rate limit exceeded | | 500 | Internal Server Error | Unexpected server error | 8.2 HANDLING 402 PAYMENT REQUIRED --------------------------------- When you receive a 402, the response includes: - credits_required: How many credits the request needs - credits_available: Your current balance - top_up_url: Direct link to purchase more credits Response headers also include: - X-Payment-Required-URL: Same as top_up_url - X-Credits-Required: Same as credits_required - X-Credits-Available: Same as credits_available Agent behavior: Direct users to the top_up_url or handle credit purchasing programmatically through the Polar.sh integration. 8.3 HANDLING 429 RATE LIMIT --------------------------- Check the Retry-After header for seconds to wait. Special case - Hallucination Loop Detection: If reason is "loop", the API detected repeated identical requests. This protects against AI agents stuck in loops. Vary your queries. ================================================================================ SECTION 9: RATE LIMITS ================================================================================ Rate limits are per API key or IP address: | Tier | Per Minute | Per Day | Use Case | |------------|------------|----------|----------------------------| | anonymous | 10 | 100 | Exploration without auth | | standard | 60 | 1,000 | Free tier users | | pro | 300 | 10,000 | Pro subscription | | enterprise | 1,000 | 100,000 | Enterprise subscription | Response headers always include: - X-RateLimit-Limit: Maximum requests allowed - X-RateLimit-Remaining: Requests remaining in window - X-RateLimit-Reset: Unix timestamp when limit resets ================================================================================ SECTION 10: CREDITS SYSTEM ================================================================================ Credits are the currency for API usage. Costs vary by operation: | Operation | Credits | |------------------------------|---------| | List personas | 1 | | Get persona (standard) | 5 | | Get persona (enhanced) | 10 | | Get persona (premium) | 25 | | Get persona (ultra) | 50 | | Interview (varies by tier) | 10-100 | | Include memory vectors | +5 | Credit Packages (via Polar.sh): - 100 credits: $10 - 500 credits: $40 (20% savings) - 1000 credits: $70 (30% savings) - 5000 credits: $300 (40% savings) Pro subscription: 1000 credits/month + higher rate limits Enterprise subscription: 5000 credits/month + highest rate limits ================================================================================ SECTION 11: BEST PRACTICES FOR AI AGENTS ================================================================================ 1. CHECK CREDITS PROACTIVELY Monitor X-Credits-Remaining after each request. Alert users when balance is low. 2. HANDLE 402 GRACEFULLY Don't retry - direct users to payment URL. Cache the top_up_url for quick access. 3. RESPECT RATE LIMITS Check X-RateLimit-Remaining before requests. Implement exponential backoff on 429s. 4. AVOID HALLUCINATION LOOPS Vary queries if you receive a "loop" rate limit. Add randomization to prevent repeated identical requests. 5. CACHE APPROPRIATELY Persona data rarely changes - cache for hours. Always re-fetch before critical interviews. 6. USE FILTERING EFFICIENTLY Filter on the server rather than fetching all. Use min_fidelity_score for quality control. ================================================================================ SECTION 12: WEBHOOK INTEGRATION ================================================================================ For payment event handling, configure webhooks at: https://yourdomain.com/api/webhooks/polar Events received: - order.paid: Credits purchased - subscription.active: Subscription started - subscription.canceled: Subscription ended - subscription.updated: Plan changed Webhook signature verification uses HMAC-SHA256 with your webhook secret. ================================================================================ SECTION 13: x402 CRYPTO PAYMENTS ================================================================================ SocioLogic supports the x402 payment protocol, allowing AI agents and developers to pay for API requests using cryptocurrency (USDC on Base mainnet). 13.1 DISCOVERY -------------- Platform Manifest: GET /.well-known/x402.json Returns the x402 payment manifest: x402scan Discovery (Merit-Systems spec): GET /.well-known/x402 Returns x402scan-compatible discovery document for automatic registration: ```json { "version": 1, "resources": [ "https://sociologic.ai/api/v1/personas/{slug}/interview", "https://sociologic.ai/api/v1/personas", "https://rng.sociologic.ai/random", "https://rng.sociologic.ai/uuid", ... ], "instructions": "# SocioLogic x402 Payment Information\n...", "ownershipProofs": [ { "signature": "0x...", "address": "0x...", "message": "https://www.sociologic.ai" } ] } ``` Platform Manifest Format: ```json { "version": "1", "platform": { "name": "SocioLogic", "description": "Verified agent registry and research platform" }, "payment": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x...", "facilitator": "https://api.cdp.coinbase.com/platform/v2/x402" }, "endpoints": [ { "path": "/api/v1/personas/{slug}/interview", "method": "POST", "price_usdc": "0.10" }, { "path": "/api/v1/personas", "method": "POST", "price_usdc": "1.00" } ] } ``` 13.2 PAYMENT FLOW ----------------- 1. Make a request without credits or authentication 2. Receive HTTP 402 with x402 payment info in error body: ```json { "error": { "code": "PAYMENT_REQUIRED", "x402": { "version": "1", "accepts": [{ "scheme": "exact", "network": "eip155:8453", "maxAmountRequired": "100000", "payTo": "0x...", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }] }, "fallback": { "credits_required": 10, "polar_checkout_url": "https://polar.sh/..." } } } ``` 3. Build payment using x402 SDK (e.g., @x402/fetch) 4. Retry request with X-PAYMENT header containing signed payment 5. Receive 200 response with X-PAYMENT-RESPONSE header 13.3 PAYMENT DETAILS -------------------- | Field | Value | |-------------|--------------------------------------------| | Network | Base mainnet (eip155:8453) | | Asset | USDC | | Address | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 | | Facilitator | Coinbase Developer Platform (CDP) | Pricing (USDC): | Endpoint | Price | |---------------------|--------| | Interview | $0.10 | | Persona Creation | $1.00 | 13.4 FOR AI AGENTS ------------------ To pay with x402: 1. Use `@x402/fetch` or build payment manually 2. Fund a wallet with USDC on Base 3. Sign payments with wallet private key 4. Include X-PAYMENT header in requests x402 is ideal for autonomous agents that need to pay without human intervention. 13.5 FALLBACK ------------- x402 is optional. Traditional authentication methods (API keys, credits) continue to work. When x402 is available, 402 responses include both `x402` and `fallback` fields, allowing agents to choose their preferred payment method. ================================================================================ SECTION 14: SOCIOLOGIC RNG SERVICE ================================================================================ SocioLogic RNG is a first-party verified agent providing cryptographically secure random number generation via x402 micropayments on Base mainnet. API Base URL: https://rng.sociologic.ai Landing Page: https://sociologic.ai/x402-rng 14.1 STANDARD TIER ($0.01/call) ------------------------------- GET /random - Returns: Random float between 0 and 1 with verifiable entropy - Response: { value, timestamp, entropy: { raw, hex } } GET /random/int?min=0&max=100 - Returns: Random integer within range (max range: 1,000,000) - Response: { value, min, max, timestamp, entropy: { raw, hex } } GET /uuid - Returns: UUID v4 - Response: { uuid, timestamp, entropy: { raw, hex } } 14.2 EXTENDED TIER ($0.02/call) ------------------------------- GET /dice?sides=6 - Returns: Die roll result (2-1000 sides) - Response: { value, sides, timestamp } GET /coin - Returns: Coin flip result - Response: { result: "heads"|"tails", timestamp } POST /shuffle - Body: { items: [...] } (max 1000 items, 100KB) - Returns: Shuffled array using Fisher-Yates algorithm - Response: { shuffled, timestamp } POST /weighted - Body: { items: [{ item, weight }, ...] } (max 1000 items) - Returns: Weighted random selection - Response: { selected, index, timestamp } 14.3 PAYMENT FLOW ----------------- All paid endpoints use x402 micropayments: 1. Request endpoint without payment 2. Receive 402 with payment requirements 3. Pay with USDC on Base via X-402-Payment header 4. Receive response with verifiable entropy 14.4 TECHNICAL DETAILS ---------------------- - Algorithm: CSPRNG with rejection sampling - Implementation: crypto.getRandomValues() - Verification: Raw entropy data in Uint32 and hex formats - Deployment: Cloudflare Workers (edge, <100ms latency) ================================================================================ SECTION 15: WEB RESEARCH API ================================================================================ SocioLogic provides web research capabilities. These endpoints allow you to gather information from the web to enrich personas and research campaigns. 15.1 SCRAPE URL --------------- POST /research/scrape Scrape content from a specific URL. Request Body: ```json { "url": "https://example.com", "formats": ["markdown"], "only_main_content": true } ``` | Field | Type | Required | Description | |-------------------|----------|----------|--------------------------------| | url | string | Yes | URL to scrape | | formats | string[] | No | Output formats (markdown, html)| | only_main_content | boolean | No | Extract main content only | 15.2 SEARCH WEB --------------- POST /research/search Search the web and scrape the results. Request Body: ```json { "query": "sustainable fashion trends 2026", "limit": 5 } ``` | Field | Type | Required | Description | |-------|---------|----------|--------------------------| | query | string | Yes | Search query (max 500) | | limit | integer | No | Max results (1-10, default 5) | 15.3 RESEARCH TOPIC ------------------- POST /research/topic Comprehensive topic research with multiple sources. Request Body: ```json { "topic": "AI impact on market research", "source_count": 3 } ``` | Field | Type | Required | Description | |--------------|---------|----------|--------------------------| | topic | string | Yes | Topic to research | | source_count | integer | No | Sources to collect (1-5) | 15.4 GET COMPANY INFO --------------------- POST /research/company Extract company information from a website. Request Body: ```json { "url": "https://company.com" } ``` Response includes company name, description, and scraped content. ================================================================================ END OF DOCUMENTATION ================================================================================ For support: support@sociologic.ai API Status: https://status.sociologic.ai GitHub: https://github.com/personalogic/api-examples ~~~