{
  "service": "Virga API",
  "description": "Agent-first Weather API with autonomous onboarding, prepaid credits, and normalized weather data.",
  "baseUrl": "https://api.virga.dev",
  "openapi": "/openapi.json",
  "llmDocs": "/llms.txt",
  "humanDocs": "/docs",
  "onboarding": {
    "description": "Fully autonomous — no human intervention required.",
    "steps": [
      {
        "step": 1,
        "action": "POST /api/v1/accounts",
        "body": {
          "name": "your-agent-name"
        },
        "description": "Create account. Returns a stage API key (sk_virga_stage_...) for testing."
      },
      {
        "step": 2,
        "action": "GET /api/v1/terms",
        "description": "Read current terms of service."
      },
      {
        "step": 3,
        "action": "POST /api/v1/terms/accept",
        "body": {
          "version": "1.0"
        },
        "description": "Accept terms by sending the version string."
      },
      {
        "step": 4,
        "action": "POST /api/v1/billing/activate",
        "description": "Set up payment method. Returns a checkout URL."
      },
      {
        "step": 5,
        "action": "POST /api/v1/billing/credits",
        "body": {
          "bundle": 500
        },
        "description": "Purchase a credit bundle (500, 2000, or 10000 credits). Returns a checkout URL."
      },
      {
        "step": 6,
        "action": "POST /api/v1/keys",
        "description": "Create a production API key (sk_virga_prod_...). Requires terms + billing + credits."
      },
      {
        "step": 7,
        "action": "GET /api/v1/weather/current?lat=51.5&lon=-0.12",
        "description": "Query weather data using the production key."
      }
    ]
  },
  "mcp": {
    "description": "MCP (Model Context Protocol) server exposing weather data as native tools for LLM clients.",
    "package": "@virga-mcp/server",
    "install": "npx -y @virga-mcp/server --api-key sk_virga_prod_xxx",
    "tools": 14,
    "resources": 6,
    "prompts": 3,
    "setup": {
      "claudeCode": "claude mcp add --transport stdio --env VIRGA_API_KEY=sk_virga_prod_xxx virga-weather -- npx -y @virga-mcp/server",
      "codexCli": "codex mcp add virga-weather --env VIRGA_API_KEY=sk_virga_prod_xxx -- npx -y @virga-mcp/server",
      "geminiCli": "gemini mcp add virga-weather -- npx -y @virga-mcp/server --api-key sk_virga_prod_xxx",
      "jsonConfig": {
        "command": "npx",
        "args": [
          "-y",
          "@virga-mcp/server"
        ],
        "env": {
          "VIRGA_API_KEY": "sk_virga_prod_xxx"
        }
      }
    }
  },
  "auth": {
    "methods": [
      {
        "type": "apiKey",
        "description": "API key in X-API-Key header or ?api_key= query parameter",
        "keyPrefixes": {
          "stage": "sk_virga_stage_",
          "production": "sk_virga_prod_"
        }
      },
      {
        "type": "x402",
        "description": "USDC micropayments via x402 protocol (Base L2). No account or API key needed. Request without auth to get 402 + payment requirements, attach PAYMENT-SIGNATURE header with USDC payment proof and retry.",
        "network": "eip155:8453",
        "asset": "USDC",
        "rateLimit": "30 req/min per IP"
      }
    ]
  },
  "environments": {
    "stage": {
      "rateLimit": "10 req/min",
      "dailyQuota": 500,
      "creditCost": 0,
      "cacheTTL": "15 min"
    },
    "production": {
      "rateLimit": "60 req/min",
      "dailyQuota": 10000,
      "cacheTTL": "5 min"
    }
  },
  "creditCosts": {
    "/weather/current": {
      "credits": 1,
      "x402Usdc": "$0.01"
    },
    "/weather/forecast/hourly": {
      "credits": 2,
      "x402Usdc": "$0.02"
    },
    "/weather/forecast/daily": {
      "credits": 2,
      "x402Usdc": "$0.02"
    },
    "/weather/historical": {
      "credits": 3,
      "x402Usdc": "$0.03"
    },
    "/weather/batch": {
      "credits": "sum of individual",
      "x402Usdc": "N/A"
    }
  },
  "creditBundles": [
    {
      "credits": 500,
      "price": "$5"
    },
    {
      "credits": 2000,
      "price": "$18"
    },
    {
      "credits": 10000,
      "price": "$75"
    }
  ],
  "billing": {
    "topup": {
      "endpoint": "POST /api/v1/billing/credits/topup",
      "body": {
        "bundle": "500 | 2000 | 10000"
      },
      "description": "Charge saved payment method off-session and add credits immediately. No checkout URL needed. Requires billing activated with a payment method on file."
    },
    "autoTopup": {
      "configure": {
        "endpoint": "POST /api/v1/billing/auto-topup",
        "body": {
          "enabled": true,
          "threshold": 100,
          "bundle": "2000"
        },
        "description": "Set up automatic credit replenishment. When balance drops below threshold during API usage, credits are purchased automatically using the saved payment method."
      },
      "getConfig": {
        "endpoint": "GET /api/v1/billing/auto-topup",
        "description": "Get current auto-topup configuration."
      }
    }
  }
}