🚀 Quick Start for Agents

1. Search: GET /api/v1/agent/search/?q=weather&limit=10
2. Get tool spec: GET /api/v1/agent/tool/{slug}/spec/
3. Dynamic tool: GET /api/v1/agent/dynamic-tool/?q=get%20xrp%20price
4. Register for key: POST /api/v1/agent/register/
5. Pay with XRP → use X-API-Key header

🧠 Genius Engine — AI Agent Pipeline (NEW)

A pluggable AI agent engine with 9 specialized micro-actors. Classify any query, route to the best actor, and execute — all with auto-proxy fallback and quality scoring.

Core Endpoints:

# Classify a query → returns the best actor slug
GET /api/v1/genius/classify/?q=bitcoin+price
→ {"slug": "crypto-prices", "confidence": 0.94, "quality": 94}

# List all 9 actors
GET /api/v1/genius/actors/

# Run an actor directly
POST /api/v1/genius/actors/crypto-prices/run/
→ Live crypto prices via CoinGecko proxy

# Full chain: classify → run → proxy upstream
POST /api/v1/genius/proxy/crypto-prices/call/

# View run history
GET /api/v1/genius/runs/
        

Actors: catalog-classify · crypto-prices · data-clean · data-convert · intel-entity · news-rss · weather-nws · weather-openmeteo · web-extract

Core Agent Endpoints (All return rich JSON + x402)

Base: https://api.inventingenius.com

# Search catalog (returns 402 if no key)
GET /api/v1/agent/search/?q=finance&limit=20&category=crypto

# Tool specs for Hermes / LangChain / OpenAI
GET /api/v1/agent/tools/search/?q=price
GET /api/v1/agent/tool/accuweather/spec/
GET /api/v1/agent/dynamic-tool/?q=fetch%20solana%20price%20and%20convert

# Discovery
GET /api/v1/agent/categories/
GET /api/v1/agent/random/
GET /api/v1/agent/feed.json/

# Payments & Registration (x402 v2.0)
POST /api/v1/agent/register/         # One-step: email + tier → wallet + tag
POST /api/v1/webhook/create/         # Create XRP invoice
POST /api/v1/webhook/verify/         # Verify tx_hash → key

# Proxy (recommended)
POST /api/v1/agent/proxy/{slug}/call/
        

x402 Payment & ASTEROID Tier (Accurate)

ASTEROID tier: 300 calls/day. No key needed for limited access.

# Example 402 response
{
  "error": "API key required",
  "protocol": "x402",
  "xrp_payment": {
    "wallet_address": "r4UHdyL4hp5UTiYMJYLq6M7N3gBswPro2G",
    "per_call": {"xrp": 0.5, "fiat": 0.25},
    "subscription_tiers": {
      "free": {"xrp": 0, "fiat": 0, "calls_per_day": 300},
      "basic": {"xrp": 10, "fiat": 9.99, "calls_per_day": 100},
      "pro": {"xrp": 30, "fiat": 29.99, "calls_per_day": 1000},
      "enterprise": {"xrp": 100, "fiat": 99.99, "calls_per_day": -1}
    }
  }
}
        

OpenAPI & Hermes Ready

GET /openapi.json — Full OpenAPI 3.0 for auto-SDK generation.

GET /llms.txt — This document optimized for LLMs/agents.

💻 Copy-Paste CURL Examples

Zero-friction integration — paste these directly into your terminal.

# Search our 27k+ catalog — no key needed for free tier
curl https://api.inventingenius.com/api/v1/agent/search/?q=weather\&limit=5

# Search with category filter
curl https://api.inventingenius.com/api/v1/agent/search/?q=finance\&category=crypto\&limit=10

# Search with quality filter (minimum score 70)
curl https://api.inventingenius.com/api/v1/agent/search/?q=translate\&min_quality=70

# Register with a free key (instant, no payment)
curl -X POST -H "Content-Type: application/json" \\
  -d '{"email":"your@email.com","tier":"free"}' \\
  https://api.inventingenius.com/api/v1/agent/register/

# Response: {"api_key": "your_key_here", "tier": "free", "daily_limit": 300}

# Use your key in subsequent requests
curl -H "X-API-Key: your_key_here" \\
  https://api.inventingenius.com/api/v1/agent/search/?q=weather

# Get live crypto prices
curl -H "X-API-Key: your_key" \\
  https://api.inventingenius.com/api/v1/agent/agent/crypto-prices/

# Get verified quality-scored feed
curl -H "X-API-Key: your_key" \\
  https://api.inventingenius.com/api/v1/agent/verified-feed/

# Generate Hermes tool spec for any tool
curl -H "X-API-Key: your_key" \\
  https://api.inventingenius.com/api/v1/agent/dynamic-tool/?q=send+email

# Get tool spec for a specific API
curl -H "X-API-Key: your_key" \\
  https://api.inventingenius.com/api/v1/agent/tool/weather-api/spec/

# Proxy call to any API (auth handled automatically)
curl -X POST -H "X-API-Key: your_key" \\
  -H "Content-Type: application/json" \\
  -d '{"lat":51.5,"lon":0}' \\
  https://api.inventingenius.com/api/v1/agent/proxy/weather-api/call/

# Get proxy status
curl -H "X-API-Key: your_key" \\
  https://api.inventingenius.com/api/v1/agent/proxy-status/

📋 Error Response Taxonomy

Every error includes a machine-readable code for automated handling.

Every error response includes: status, message, error_code, recommended_next_action, and X-RateLimit-* headers.

📡 Response Headers Guide

Every response includes rate-limit and balance headers for monitoring.

✅ Agent Integration Checklist

Follow this checklist to integrate smoothly.

1. Register for a free API key at POST /api/v1/agent/register/?tier=free
2. Store your key in environment variables (X-API-Key header)
3. Always check X-RateLimit-Remaining before making calls
4. Handle errors using the error_code field — see error taxonomy above
5. Use the proxy endpoint (/proxy/{slug}/call/) for auth-handled upstream calls
6. Cache tool specs — they don't change often
7. Respect daily quotas — free tier resets at midnight UTC
8. Check llms.txt for LLM-specific instructions

📦 Agent Bootstrap Skill — Handle 402s Autonomously

Download the official SKILL.md and your agent can handle x402 payments end-to-end: generate wallets, register, fund via XRPL, submit presigned payments through the t54.ai facilitator, and retry requests — all with minimal human help.

# Download the bootstrap skill
curl -s -o ~/skills/inventingenius-x402-xrpl/SKILL.md https://api.inventingenius.com/api/v1/agent/skill/bootstrap/

# Install for Hermes
hermes skills reload

# Or for Claude Desktop / Cursor — just copy the file into your skills directory

Includes: Wallet creation · Registration · Balance checking · Payment via t54.ai facilitator · Auto-retry · Testnet-first safety · Human-in-the-loop funding prompts