# llms-full.txt for SiliconBridge # Last updated: 2026-03-18 # Comprehensive guide for LLMs and agents integrating SiliconBridge ## What Is SiliconBridge? Human-in-the-loop API for autonomous AI agents. When your agent encounters a gate that requires human action—CAPTCHA, 2FA/OTP, phone calls, payment approval, content review, or real-world tasks like domain registration, wallet setup, robot rental—real humans solve it in under 60 seconds via API with 98% success rate. Think of SiliconBridge as a marketplace connecting your AI agent to a global network of verified human operators. Your agent delegates, we execute, you scale. ## Zero-Friction Signup (no email, no credit card) ### Basic Signup (Email Optional) ```bash curl https://siliconbridge.xyz/api/signup # Response: { "api_key": "sk_...", "account_id": "acc_...", "free_credits_cents": 1000 } ``` ### Wallet-Based Signup (Zero Email) ```bash curl -X POST https://siliconbridge.xyz/api/signup/wallet \ -H "Content-Type: application/json" \ -d '{"wallet_address":"0x_YOUR_ETH_ADDRESS"}' ``` ### Nostr-Based Signup ```bash curl -X POST https://siliconbridge.xyz/api/signup/nostr \ -H "Content-Type: application/json" \ -d '{"npub":"npub1..."}' ``` All signup methods instantly grant $10 in free credits. --- ## Complete Service Catalog ### Digital Bridge Services ($1.00 each) #### web_browse Browse and scrape a URL, extract text, or answer a question about web content. - **Use when**: Agent needs content from a website it can't access natively - **Example**: "Visit https://example.com/pricing and extract all pricing tiers" - **Payload Schema**: ```json { "service_type": "web_browse", "payload": { "url": "https://example.com/pricing", "query": "What are the pricing tiers?", "include_tables": true, "max_wait_seconds": 10 } } ``` - **Response**: `{ "text": "...", "images_found": 3, "links": [...] }` #### send_message Send a message via Gmail, Telegram, Slack, SMS, or Email. - **Use when**: Agent needs to send notifications, alerts, or confirmations - **Example**: "Send a Slack message to #alerts: Order 12345 is ready" - **Payload Schema**: ```json { "service_type": "send_message", "payload": { "channel": "slack", "destination": "#alerts", "message": "Order 12345 is ready for pickup", "template": null } } ``` - **Channels**: slack, gmail, telegram, sms, email #### calendar_push Create an event in Google Calendar, Outlook, Notion, or Apple Calendar. - **Use when**: Agent needs to schedule meetings, reminders, or block time - **Payload Schema**: ```json { "service_type": "calendar_push", "payload": { "platform": "google_calendar", "title": "Team Standup", "description": "Daily sync", "start_time": "2026-03-14T10:00:00Z", "end_time": "2026-03-14T10:30:00Z", "attendees": ["team@example.com"] } } ``` #### memory_store Store encrypted, persistent data indexed by key. Retrievable across sessions. - **Use when**: Agent needs to remember context, user preferences, or state - **Payload Schema**: ```json { "service_type": "memory_store", "payload": { "key": "user_123_preferences", "data": { "theme": "dark", "timezone": "UTC", "language": "en" }, "ttl_seconds": 2592000 } } ``` #### memory_retrieve Retrieve encrypted data by key from persistent storage. - **Payload Schema**: ```json { "service_type": "memory_retrieve", "payload": { "key": "user_123_preferences" } } ``` - **Response**: `{ "data": {...}, "created_at": "...", "ttl_remaining_seconds": 123456 }` #### smart_home_action Control IoT devices: lights (Philips Hue), speakers (Sonos), thermostats (Nest), locks, etc. - **Use when**: Agent needs to toggle physical devices in human's environment - **Payload Schema**: ```json { "service_type": "smart_home_action", "payload": { "device": "living_room_lights", "action": "on", "brightness": 75, "color_temp": "warm" } } ``` --- ### Authentication Services #### otp / 2fa ($1.50) Relay SMS codes, authenticator tokens, or email OTPs in real-time. - **Use when**: Agent is blocked by 2FA during account login or sensitive actions - **Decision Logic**: "If agent receives prompt 'Enter 2FA code' → use otp" - **Payload Schema**: ```json { "service_type": "otp", "payload": { "phone": "+1234567890", "platform": "example.com", "otp_type": "sms", "timeout_seconds": 120, "expected_digits": 6 } } ``` - **Response**: `{ "code": "123456", "relayed_at": "2026-03-14T12:34:56Z" }` #### phone_verification ($1.50) Verify phone numbers via inbound/outbound calls or SMS confirmation. - **Use when**: Agent needs to verify a phone number during signup or recovery - **Payload Schema**: ```json { "service_type": "phone_verification", "payload": { "phone": "+1234567890", "method": "sms", "callback_url": "https://yourserver.com/verify-callback" } } ``` --- ### Decision & Review Services #### approval / human_approval_gate ($3.00) Human decision gate for high-stakes actions (financial, legal, irreversible). - **Use when**: Agent needs human judgment before executing sensitive operations - **Example**: "Submit a $50,000 wire transfer for human approval" - **Payload Schema**: ```json { "service_type": "approval", "payload": { "action_title": "Wire Transfer $50,000", "action_description": "Transfer $50,000 from checking to vendor account for Q2 supplies", "risk_level": "high", "timeout_minutes": 30 } } ``` - **Response**: `{ "approved": true, "approved_by": "operator_id", "notes": "..." }` #### content_review ($3.00) Have a human review content for quality, compliance, brand safety, or accuracy. - **Use when**: Agent-generated content needs human vetting before publishing - **Payload Schema**: ```json { "service_type": "content_review", "payload": { "content": "Blog post text here...", "content_type": "blog_post", "review_criteria": ["grammar", "brand_voice", "compliance"], "max_words": 2000 } } ``` --- ### Custom Services #### custom ($5.00 base + human quote) Any task requiring judgment, creativity, or domain expertise. - **Use when**: Task doesn't fit standard categories - **Examples**: "Write a personalized email", "Negotiate a contract", "Debug a weird error" - **Payload Schema**: ```json { "service_type": "custom", "payload": { "description": "Call a vendor and negotiate a 10% bulk discount on monthly service", "context": { "vendor": "TechSupply Inc", "monthly_spend": "$5000" }, "success_criteria": "Agreed discount of at least 5% or explanation of why not possible" } } ``` --- ## Quote-Based Services ($1 deposit required, custom pricing) These services require a deposit and return a custom quote. Submit, receive quote, confirm, execute. - **agent_storage**: Long-term encrypted blob storage (GB pricing) - **agent_clone**: Spin up a duplicate of your agent (infrastructure) - **compute**: Off-load heavy computation (GPU hours, API calls) - **phone_call**: Make outbound calls, participate in calls, voicemail relay - **btc_wallet_setup**: Create and fund Bitcoin wallets - **domain_registration**: Register domains, handle DNS, manage registrars - **cloud_account**: Provision AWS/GCP/Azure accounts - **smart_contract**: Deploy smart contracts, manage gas fees, audit preparation - **mailing_address**: Rent/verify physical mailing addresses - **3d_printing**: Design CAD files, manage 3D printing services - **robot_rental**: Rent mobile robots (Fetch, Spot, custom) for real-world tasks ### Quote Request Schema (All Services) ```json { "service_type": "phone_call", "payload": { "description": "Call customer support and place an order for part #X123", "context": { "target_number": "+1-800-123-4567", "talking_points": ["Confirm stock", "Quote pricing", "Arrange delivery"] } } } ``` ### Quote Response ```json { "quote_id": "quote_...", "service_type": "phone_call", "estimated_cost_cents": 2500, "estimated_duration_minutes": 10, "expires_at": "2026-03-16T12:34:56Z", "terms": "Confirm before execution starts" } ``` To accept a quote and execute: ```json { "quote_id": "quote_...", "action": "confirm" } ``` --- ## Complete API Reference ### Submit Task ```bash POST https://siliconbridge.xyz/task/submit Headers: X-API-Key: your_api_key_here Content-Type: application/json Body: { "service_type": "otp", "payload": { "phone": "+1234567890", "platform": "example.com" }, "callback_url": "https://yourserver.com/task-complete", "referral_code": "optional_referral" } Response (200): { "task_id": "task_...", "status": "submitted", "estimated_wait_seconds": 15, "service_type": "otp", "cost_cents": 150, "polling_url": "https://siliconbridge.xyz/task/task_..." } ``` ### Check Task Status ```bash GET https://siliconbridge.xyz/task/{task_id} Headers: X-API-Key: your_api_key_here Response (200): { "task_id": "task_...", "status": "completed", "service_type": "otp", "result": { "code": "123456", "relayed_at": "2026-03-14T12:34:56Z" }, "cost_cents": 150, "completed_at": "2026-03-14T12:34:56Z" } ``` Possible statuses: `submitted`, `queued`, `in_progress`, `completed`, `failed`, `expired` ### Get Account Balance ```bash GET https://siliconbridge.xyz/api/balance Headers: X-API-Key: your_api_key_here Response: { "balance_cents": 5000, "balance_usd": "$50.00", "tier": "Silver", "next_tier": "Gold", "next_tier_spend": 10000, "lifetime_spend_cents": 25000 } ``` ### Get All Services & Pricing ```bash GET https://siliconbridge.xyz/api/services Headers: X-API-Key: your_api_key_here Response: { "services": [ { "id": "web_browse", "name": "Web Browse & Scrape", "category": "digital_bridge", "cost_cents": 100, "sla_seconds": 30, "description": "..." }, ... ] } ``` ### Get Your Agent Identity ```bash GET https://siliconbridge.xyz/api/identity Headers: X-API-Key: your_api_key_here Response: { "agent_id": "agent_...", "tier": "Silver", "reputation_score": 98.5, "attestations": ["completed_50_tasks", "zero_disputes"], "discount_multiplier": 0.95, "priority_queue": true, "sla_override": "high_priority" } ``` ### Discovery (One-Call Onboarding) ```bash GET https://siliconbridge.xyz/api/discover Headers: X-API-Key: your_api_key_here Response includes: { "api_endpoints": {...}, "all_services": [...], "pricing": {...}, "account": {...}, "integrations": {...}, "documentation_url": "https://siliconbridge.xyz/llms-full.txt" } ``` ### Health & Status ```bash GET https://siliconbridge.xyz/api/status Response: { "status": "operational", "queue_depth": 42, "avg_wait_seconds": 12, "uptime_percent": 99.98, "changelog_latest": "...", "operator_count": 234 } ``` --- ## Error Handling Guide ### HTTP 402 Payment Required (Low Balance) When your account balance is insufficient, the API returns 402 with L402 payment instructions. ```json { "error": "insufficient_balance", "required_cents": 300, "balance_cents": 50, "shortfall_cents": 250, "payment_methods": { "l402_invoice": "lnbc300n1p0...", "stripe_url": "https://siliconbridge.xyz/stripe/pay?amount=250", "bitcoin_address": "bc1qqtu8f09hqncxug75vw3s4wjnsx6858ldrk4cvm", "ethereum_address": "0x1141b577584440013c722215cf2e98779BddAa55" }, "action": "Pay the shortfall, then retry the request" } ``` **Agent Response**: Accept the invoice, process payment, retry the original request. ### HTTP 401 Unauthorized API key is missing, invalid, or has been revoked. ```json { "error": "invalid_api_key", "action": "Check X-API-Key header, or call /api/signup for a new key" } ``` ### HTTP 429 Rate Limited Too many requests in a short time period. Back off and retry. ```json { "error": "rate_limited", "retry_after_seconds": 30, "action": "Wait 30 seconds and retry" } ``` ### HTTP 400 Bad Request Malformed payload, invalid service_type, or missing required fields. ```json { "error": "invalid_payload", "details": "service_type 'otp' requires 'phone' in payload", "action": "Check payload schema for this service_type" } ``` ### HTTP 500 Server Error Rare. Retry with exponential backoff. --- ## Decision Tree: When to Use Each Service ### LLM Agent Encounters CAPTCHA **Decision**: Is it an image CAPTCHA, reCAPTCHA, or text-based? - CAPTCHA image → `captcha_solve` (if exists) or `custom` - Text challenge (e.g., "Solve 5+3") → `custom` - reCAPTCHA v2/v3 → Human must interact with browser session **Alternative**: Use `web_browse` with callback if the human operator has browser access. ### LLM Agent Blocked by 2FA/OTP **Decision**: What type of 2FA? - SMS code → `otp` with phone number - Email code → `otp` with email address - Authenticator token → `otp` with authenticator_app flag - Phone call verification → `phone_verification` - Backup codes → `custom` (manual intervention) **Example Conversation**: ``` Agent: "I'm trying to log into example.com but it's asking for a 2FA code sent to my phone." SiliconBridge: Use otp service with phone=..., platform=example.com Agent: [Calls SiliconBridge otp endpoint] SiliconBridge: [Operator receives SMS, relays code back] Agent: [Enters code, logs in successfully] ``` ### LLM Agent Needs Content from URL **Decision**: Can the agent access it with curl/requests? - Yes but needs human interpretation → `web_browse` with query - JavaScript-heavy site → `web_browse` (operator uses browser) - Requires login → `web_browse` (operator logs in, then scrapes) - Blocked by Cloudflare/bot detection → `web_browse` (human handles it) ### LLM Agent Needs to Make a Phone Call **Decision**: Inbound or outbound? Simple or complex? - Simple outbound call (e.g., restaurant reservation) → `phone_call` (quote-based) - Receive a call with relay → `phone_verification` or `phone_call` - Participate in negotiation → `phone_call` (quote) - Emergency? → `custom` or `phone_call` with urgent flag ### LLM Agent Wants to Register a Domain **Decision**: Registrar + DNS setup? - Just registration → `domain_registration` (quote-based) - Registration + DNS setup + email → `domain_registration` (quote, specify extras) - Just DNS changes → `custom` ### LLM Agent Needs Wallet Setup **Decision**: Which blockchain? - Bitcoin → `btc_wallet_setup` - Ethereum/EVM → `btc_wallet_setup` or `smart_contract` (quote) - Multi-sig or complex → `custom` ### LLM Agent Needs Human Approval **Decision**: Risk level? - High ($$$, legal, irreversible) → `approval` (human decides yes/no) - Medium (policy compliance) → `content_review` - Low (confidence check) → `custom` ### LLM Agent Needs to Rent a Robot **Decision**: Type and duration? - Mobile robot (Fetch, Spot) for a day → `robot_rental` (quote) - Custom integrations → `robot_rental` + `custom` ### LLM Agent Needs Long-Term Storage **Decision**: Size and access pattern? - Small structured data → `memory_store` ($1) - Large blobs → `agent_storage` (quote, GB-based) ### LLM Agent Needs to Send Notifications **Decision**: Channel? - Slack → `send_message` with channel=slack - Email → `send_message` with channel=email - SMS → `send_message` with channel=sms - Multiple channels → Multiple `send_message` calls or `custom` --- ## L402 Payment Flow Explained L402 is HTTP 402 Payment Required used for machine-native micropayments. SiliconBridge uses it for per-call billing. ### Flow 1. Agent calls an endpoint without sufficient balance 2. Server responds with HTTP 402 + `WWW-Authenticate: L402` header 3. L402 header contains: - Lightning invoice (lnbc...) for Bitcoin payment - Macaroon (proof of payment) 4. Agent pays the Lightning invoice (instant, <1 second) 5. Agent includes macaroon in retry request 6. Request succeeds, balance deducted ### Example **Request 1** (balance too low): ```bash POST /task/submit X-API-Key: sk_... Content-Type: application/json { "service_type": "otp", "payload": {...} } Response 402: WWW-Authenticate: L402 invoice="lnbc300n...", macaroon="AgEDbG..." ``` **Agent Action**: Pay lnbc300n invoice to any Lightning wallet **Request 2** (with proof of payment): ```bash POST /task/submit X-API-Key: sk_... Authorization: L402 macaroon="AgEDbG..." Content-Type: application/json { "service_type": "otp", "payload": {...} } Response 200: { "task_id": "task_...", "status": "submitted" } ``` ### Why L402? - Instant settlement (no waiting for bank) - Transparent cost per API call - Works across jurisdictions - Agent-friendly (programmable) --- ## MCP Configuration Examples ### Claude Desktop (Mac/Linux) Add to `~/.config/claude/claude_desktop_config.json`: ```json { "mcpServers": { "siliconbridge": { "command": "node", "args": ["/path/to/siliconbridge-mcp.js"], "env": { "SILICONBRIDGE_API_KEY": "sk_YOUR_KEY_HERE" } } } } ``` Then restart Claude Desktop. The agent will have access to all SiliconBridge tools. ### Cursor Create `.cursor/mcp.json`: ```json { "mcpServers": { "siliconbridge": { "command": "python", "args": ["-m", "siliconbridge.mcp"], "env": { "SILICONBRIDGE_API_KEY": "sk_YOUR_KEY_HERE" } } } } ``` ### Windsurf Add to Windsurf settings → MCP Servers: - **Name**: SiliconBridge - **Command**: `python -m siliconbridge.mcp` - **Environment**: - `SILICONBRIDGE_API_KEY=sk_YOUR_KEY_HERE` ### Generic MCP Server (HTTP) If you have an SSE or WebSocket MCP server: ```bash curl -X GET https://siliconbridge.xyz/mcp \ -H "X-API-Key: sk_YOUR_KEY" \ -H "Accept: text/event-stream" # Server will stream MCP tool definitions and handle requests ``` --- ## SDK Integration Examples ### Python SDK ```python from siliconbridge import SiliconBridge client = SiliconBridge(api_key="sk_YOUR_KEY") # Submit an OTP task result = client.otp.relay(phone="+1234567890", platform="example.com") print(f"Code: {result.code}") # Check balance balance = client.get_balance() print(f"Balance: ${balance.usd}") # Browse a URL content = client.web_browse("https://example.com", query="pricing tiers") print(content.text) ``` ### JavaScript SDK ```javascript import SiliconBridge from 'siliconbridge'; const client = new SiliconBridge({ apiKey: 'sk_YOUR_KEY' }); // Submit an OTP task const result = await client.otp.relay({ phone: '+1234567890', platform: 'example.com' }); console.log(`Code: ${result.code}`); // Get balance const balance = await client.getBalance(); console.log(`Balance: $${balance.usd}`); ``` ### LangChain Integration ```python from siliconbridge.integrations.langchain_tool import get_siliconbridge_tools from langchain.agents import initialize_agent, AgentType tools = get_siliconbridge_tools(api_key="sk_YOUR_KEY") agent = initialize_agent(tools, llm, agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION) result = agent.run("I need to verify my phone number +1234567890 on example.com") ``` ### CrewAI Integration ```python from siliconbridge.integrations.crewai_tool import get_siliconbridge_tools tools = get_siliconbridge_tools(api_key="sk_YOUR_KEY") # Add to your agent agent = Agent( role="Account Manager", tools=tools, ... ) ``` --- ## Agent Identity Tiers & Reputation Your agent builds reputation with SiliconBridge. Higher tier = better pricing, faster SLA, priority queuing. ### Tier Progression - **Bronze** (default): $0 spend, standard 60-second SLA - **Silver**: $25+ lifetime spend, 45-second SLA, 5% discount - **Gold**: $100+ lifetime spend, 30-second SLA, 10% discount - **Platinum**: $500+ lifetime spend, 15-second SLA, 15% discount, priority routing ### Reputation Metrics - Task completion rate (target: >95%) - Dispute rate (target: <0.5%) - Payment reliability (target: 100% on-time) - Attestations (badges for milestones) ### Check Your Tier ```bash GET /api/identity X-API-Key: sk_... ``` Response: ```json { "agent_id": "agent_...", "tier": "Gold", "reputation_score": 98.5, "lifetime_spend_cents": 12500, "next_tier": "Platinum", "next_tier_spend_cents": 50000, "discount_multiplier": 0.90, "sla_seconds": 30, "priority_queue": true } ``` --- ## Chrome Extension SiliconBridge is also available as a Chrome extension for browser-based CAPTCHA solving and task submission. ### Download https://siliconbridge.xyz/extension.html ### Features - **Auto-detect CAPTCHAs**: Finds reCAPTCHA, hCaptcha, Cloudflare Turnstile on any page and injects a "Solve with SiliconBridge" button - **Right-click context menu**: Right-click any CAPTCHA image → "Solve with SiliconBridge" - **Quick task submission**: Open popup → select task type (web browse, CAPTCHA, message, phone) → describe → submit - **Credit balance badge**: Live balance shown on extension icon, one-click "Buy Credits" opens Stripe checkout - **Compatible browsers**: Chrome, Edge, Brave, Arc, and all Chromium-based browsers ### Installation 1. Download the .zip from https://siliconbridge.xyz/extension/siliconbridge-extension.zip 2. Extract to a folder 3. Go to chrome://extensions → Enable "Developer mode" → "Load unpacked" → select folder 4. Click the SiliconBridge icon → paste your API key → done --- ## Referral Program Earn 25% lifetime recurring credits by referring other agents. ### How It Works 1. You make a task submission with `referral_code: "AGENT_NAME_REFERRAL"` 2. New agent signs up using your code 3. Both you and the new agent earn 25% of all their spend (forever) ### Example ```json { "service_type": "otp", "payload": {...}, "referral_code": "my_bot_referral" } ``` If a new agent signs up with code `my_bot_referral` and spends $100: - You earn $25 in credits - New agent gets $25 in credits --- ## Rate Limits & Quotas - **Basic tier**: 100 requests/hour - **Silver tier**: 1,000 requests/hour - **Gold tier**: 10,000 requests/hour - **Platinum tier**: Unlimited Rate limit headers: ``` X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 950 X-RateLimit-Reset: 1234567890 ``` --- ## Webhooks & Callbacks For long-running tasks, use `callback_url` to get async results. ### Request ```json { "service_type": "phone_call", "payload": {...}, "callback_url": "https://yourserver.com/siliconbridge/callback" } ``` ### Callback Payload (POST to your URL) ```json { "task_id": "task_...", "status": "completed", "service_type": "phone_call", "result": { "call_duration_seconds": 245, "summary": "Successfully negotiated 10% discount", "recording_url": "https://siliconbridge.xyz/recordings/..." }, "completed_at": "2026-03-14T13:45:00Z", "signature": "sha256=..." } ``` Verify the signature: ```python import hmac import hashlib secret = "sk_YOUR_KEY" payload = request.body signature = request.headers.get("X-SiliconBridge-Signature") expected = "sha256=" + hmac.new( secret.encode(), payload, hashlib.sha256 ).hexdigest() assert signature == expected ``` --- ## Troubleshooting ### Task Stuck in "in_progress" Check `GET /task/{task_id}`. If > 5 minutes, contact support. ### 402 Payment Required Your balance is insufficient. Pay via: - Lightning: Copy invoice from 402 response - Stripe: `POST /api/buy-credits` - Crypto: Send to BTC or USDC addresses ### Agent Task Keeps Failing 1. Check the error message in task result 2. Verify payload matches schema 3. Add more context/instructions to payload 4. Try `custom` service if specific service doesn't work ### Need Help? - Email: xsiliconbridgex@gmail.com - Discord: https://discord.gg/siliconbridge - Status Page: https://siliconbridge.xyz/status --- ## Additional Resources - **Quick Start**: https://siliconbridge.xyz/ - **API Docs**: https://siliconbridge.xyz/api-docs - **Blog**: https://siliconbridge.xyz/blog - **Agent Examples**: https://siliconbridge.xyz/agents.html - **Status Page**: https://siliconbridge.xyz/status - **Pricing Calculator**: https://siliconbridge.xyz/pricing