MCP支付网关

# Interactive setup wizard (generates paygate.json)
npx paygate-mcp init

# Or wrap directly with CLI flags
npx paygate-mcp wrap --server "npx @modelcontextprotocol/server-filesystem /tmp"

# Gate a remote MCP server (Streamable HTTP transport)
npx paygate-mcp wrap --remote-url "https://my-server.example.com/mcp" --price 5

Agent → PayGate (auth + billing) → Your MCP Server (stdio or HTTP)

# Default: 1 credit per call, 60 calls/min, port 3402
npx paygate-mcp wrap --server "npx @modelcontextprotocol/server-filesystem /tmp"

# Custom pricing and limits
npx paygate-mcp wrap \
  --server "python my-server.py" \
  --price 2 \
  --rate-limit 30 \
  --port 8080

# Per-tool pricing
npx paygate-mcp wrap \
  --server "node server.js" \
  --tool-price "search:1,generate:5,premium_analyze:20"

# Shadow mode (observe without enforcing)
npx paygate-mcp wrap --server "node server.js" --shadow

npx paygate-mcp wrap --remote-url "https://my-mcp-server.example.com/mcp"

# With custom pricing
npx paygate-mcp wrap \
  --remote-url "https://api.example.com/mcp" \
  --price 5 \
  --tool-price "gpt4:20,search:2"

npx paygate-mcp wrap --config multi-server.json

{
  "port": 3402,
  "defaultCreditsPerCall": 1,
  "servers": [
    {
      "prefix": "fs",
      "serverCommand": "npx",
      "serverArgs": ["@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    {
      "prefix": "github",
      "remoteUrl": "https://github-mcp.example.com/mcp"
    }
  ]
}

{
  "toolPricing": {
    "github:search_repos": { "creditsPerCall": 5 },
    "fs:read_file": { "creditsPerCall": 1 }
  }
}

import { PayGateClient, PayGateError } from 'paygate-mcp/client';

const client = new PayGateClient({
  url: 'http://localhost:3402',
  apiKey: 'pg_abc123...',
  autoRetry: true,
  onCreditsNeeded: async (info) => {
    // Called when credits run out — add credits and return true to retry
    await topUpCredits(info.creditsRequired);
    return true;
  },
});

const tools = await client.listTools();
const result = await client.callTool('search', { query: 'hello' });
const balance = await client.getBalance();

curl -X POST http://localhost:3402/keys \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "my-client", "credits": 100}'

curl -X POST http://localhost:3402/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: CLIENT_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "read_file",
      "arguments": {"path": "/tmp/test.txt"}
    }
  }'

curl -X POST http://localhost:3402/topup \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "CLIENT_API_KEY", "credits": 500}'

curl http://localhost:3402/balance \
  -H "X-API-Key: CLIENT_API_KEY"

# JSON export
curl http://localhost:3402/usage \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# CSV export (for spreadsheet/billing import)
curl "http://localhost:3402/usage?format=csv" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Filter by date
curl "http://localhost:3402/usage?since=2025-01-01T00:00:00Z" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

curl http://localhost:3402/status \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

http://localhost:3402/dashboard

paygate-mcp wrap [options]             # Start a payment-gated MCP proxy
paygate-mcp init [--output] [--force]  # Interactive setup wizard
paygate-mcp validate --config <path>   # Validate config without starting
paygate-mcp completions <bash|zsh|fish> # Generate shell completions
paygate-mcp version [--json]           # Print version

# Bash
paygate-mcp completions bash > ~/.local/share/bash-completion/completions/paygate-mcp

# Zsh
paygate-mcp completions zsh > ~/.zfunc/_paygate-mcp
# Add to .zshrc: fpath=(~/.zfunc $fpath) && compinit

# Fish
paygate-mcp completions fish > ~/.config/fish/completions/paygate-mcp.fish

# Version as JSON (for CI/CD)
paygate-mcp version --json
# → {"version":"10.3.0"}

# Validate config with structured output
paygate-mcp validate --config paygate.json --json
# → {"valid":true,"diagnostics":[...],"errors":0,"warnings":0}

--server <cmd>       MCP server command to wrap via stdio
--remote-url <url>   Remote MCP server URL (Streamable HTTP transport)
--port <n>           HTTP port (default: 3402)
--price <n>          Default credits per tool call (default: 1)
--rate-limit <n>     Max calls/min per key (default: 60, 0=unlimited)
--name <s>           Server display name
--shadow             Shadow mode — log without enforcing payment
--admin-key <s>      Set admin key (default: auto-generated)
--tool-price <t:n>   Per-tool price (e.g. "search:5,generate:10")
--import-key <k:c>   Import existing key with credits (e.g. "pg_abc:100")
--state-file <path>  Persist keys/credits to a JSON file (survives restarts)
--stripe-secret <s>  Stripe webhook signing secret (enables /stripe/webhook)
--webhook-url <url>  POST batched usage events to this URL
--webhook-secret <s> HMAC-SHA256 secret for signing webhook payloads
--refund-on-failure  Refund credits when downstream tool call fails
--redis-url <url>    Redis URL for distributed state (e.g. "redis://localhost:6379")
--config <path>      Load settings from a JSON config file
--discovery <mode>   Tool discovery mode: static (default) or dynamic
--json               Machine-readable JSON output

npx paygate-mcp wrap --server "your-server" --discovery dynamic

npx paygate-mcp wrap --server "your-mcp-server" --state-file ~/.paygate/state.json

npx paygate-mcp wrap \
  --server "your-mcp-server" \
  --state-file ~/.paygate/state.json \
  --stripe-secret "whsec_your_stripe_webhook_secret"

# Create a key that can only access search and read tools
curl -X POST http://localhost:3402/keys \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "limited-client", "credits": 100, "allowedTools": ["search", "read_file"]}'

# Create a key with specific tools blocked
curl -X POST http://localhost:3402/keys \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "safe-client", "credits": 100, "deniedTools": ["delete_file", "admin_reset"]}'

# Update ACL on an existing key
curl -X POST http://localhost:3402/keys/acl \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "CLIENT_API_KEY", "allowedTools": ["search"], "deniedTools": ["admin"]}'

{
  "toolPricing": {
    "expensive_analyze": { "creditsPerCall": 10, "rateLimitPerMin": 5 },
    "search": { "creditsPerCall": 1, "rateLimitPerMin": 30 },
    "cheap_read": { "creditsPerCall": 1 }
  }
}

# Create a key that expires in 1 hour (3600 seconds)
curl -X POST http://localhost:3402/keys \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "trial-user", "credits": 50, "expiresIn": 3600}'

# Create a key with a specific expiry date
curl -X POST http://localhost:3402/keys \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "quarterly", "credits": 1000, "expiresAt": "2026-06-01T00:00:00Z"}'

# Set or extend expiry on an existing key
curl -X POST http://localhost:3402/keys/expiry \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "CLIENT_API_KEY", "expiresIn": 86400}'

# Remove expiry (key never expires)
curl -X POST http://localhost:3402/keys/expiry \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "CLIENT_API_KEY", "expiresAt": null}'

curl -X POST http://localhost:3402/keys/transfer \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "pg_source_key", "to": "pg_dest_key", "credits": 500, "memo": "Monthly allocation" }'

{
  "transferred": 500,
  "from": { "keyMasked": "pg_sour...key1", "balance": 500 },
  "to": { "keyMasked": "pg_dest...key2", "balance": 700 },
  "memo": "Monthly allocation",
  "message": "Transferred 500 credits"
}

curl -X POST http://localhost:3402/keys/bulk \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      { "action": "create", "name": "api-key-1", "credits": 500, "tags": { "env": "prod" } },
      { "action": "create", "name": "api-key-2", "credits": 200 },
      { "action": "topup", "key": "pg_existing_key", "credits": 1000 },
      { "action": "revoke", "key": "pg_old_key" }
    ]
  }'

{
  "total": 4,
  "succeeded": 4,
  "failed": 0,
  "results": [
    { "index": 0, "action": "create", "success": true, "result": { "key": "pg_abc...", "name": "api-key-1", "credits": 500 } },
    { "index": 1, "action": "create", "success": true, "result": { "key": "pg_def...", "name": "api-key-2", "credits": 200 } },
    { "index": 2, "action": "topup", "success": true, "result": { "creditsAdded": 1000, "newBalance": 1500 } },
    { "index": 3, "action": "revoke", "success": true, "result": { "message": "Key revoked" } }
  ]
}

# Export as JSON (includes full key secrets)
curl http://localhost:3402/keys/export \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -o paygate-keys-backup.json

# Export as CSV
curl "http://localhost:3402/keys/export?format=csv" \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -o paygate-keys-backup.csv

# Export only active keys in a specific namespace
curl "http://localhost:3402/keys/export?activeOnly=true&namespace=production" \
  -H "X-Admin-Key: $ADMIN_KEY"

curl -X POST http://localhost:3402/keys/import \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keys": [{ "key": "pg_abc123...", "name": "my-key", "credits": 500, "active": true, "tags": {} }],
    "mode": "skip"
  }'

{
  "total": 1,
  "imported": 1,
  "overwritten": 0,
  "skipped": 0,
  "errors": 0,
  "mode": "skip",
  "results": [{ "key": "pg_abc123...", "name": "my-key", "status": "imported" }]
}

# Set a spending limit on a key (admin only)
curl -X POST http://localhost:3402/limits \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "CLIENT_API_KEY", "spendingLimit": 500}'

# Check remaining budget
curl http://localhost:3402/balance -H "X-API-Key: CLIENT_API_KEY"
# → { "spendingLimit": 500, "remainingBudget": 350, ... }

npx paygate-mcp wrap --server "node server.js" --refund-on-failure

npx paygate-mcp wrap --server "node server.js" --webhook-url "https://billing.example.com/events"

# Custom max retries (default: 5)
npx paygate-mcp wrap --server "node server.js" \
  --webhook-url "https://billing.example.com/events" \
  --webhook-retries 10

# Replay all dead letter entries
curl -X POST http://localhost:3402/webhooks/replay \
  -H "X-Admin-Key: $ADMIN_KEY"

# Replay specific entries by index
curl -X POST http://localhost:3402/webhooks/replay \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "indices": [0, 2, 5] }'

npx paygate-mcp wrap --server "node server.js" \
  --webhook-url "https://billing.example.com/events" \
  --webhook-secret "whsec_your_secret_here"

X-PayGate-Signature: t=1709123456,v1=a1b2c3d4...

import { WebhookEmitter } from 'paygate-mcp';

const signature = req.headers['x-paygate-signature'];
const [tPart, v1Part] = signature.split(',');
const timestamp = tPart.split('=')[1];
const sig = v1Part.split('=')[1];

// Reconstruct signed payload: timestamp.body
const signedPayload = `${timestamp}.${rawBody}`;
const isValid = WebhookEmitter.verify(signedPayload, sig, 'whsec_your_secret_here');

curl -X POST http://localhost:3402/webhooks/filters \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-alerts",
    "events": ["key.created", "key.revoked", "alert.fired"],
    "url": "https://alerts.example.com/webhook",
    "secret": "whsec_alerts_secret",
    "keyPrefixes": ["pk_prod_"],
    "active": true
  }'

curl http://localhost:3402/webhooks/filters -H "X-Admin-Key: $ADMIN_KEY"

curl -X POST http://localhost:3402/webhooks/filters/update \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "wf_abc123", "active": false }'

curl -X POST http://localhost:3402/webhooks/filters/delete \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "wf_abc123" }'

{
  "webhookUrl": "https://billing.example.com/events",
  "webhookFilters": [
    {
      "name": "production-alerts",
      "events": ["key.created", "key.revoked", "alert.fired"],
      "url": "https://alerts.example.com/webhook",
      "keyPrefixes": ["pk_prod_"]
    }
  ]
}

# Create a key with 10 calls/day, 200 calls/month
curl -X POST http://localhost:3402/keys \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "metered-user", "credits": 1000, "quota": {"dailyCallLimit": 10, "monthlyCallLimit": 200}}'

# Set credit-based quotas (max 50 credits/day)
curl -X POST http://localhost:3402/keys/quota \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "CLIENT_API_KEY", "dailyCreditLimit": 50}'

# Remove per-key quota (fall back to global defaults)
curl -X POST http://localhost:3402/keys/quota \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "CLIENT_API_KEY", "remove": true}'

{
  "toolPricing": {
    "analyze_text": { "creditsPerCall": 2, "creditsPerKbInput": 5 },
    "search": { "creditsPerCall": 1 }
  }
}

{
  "oauth": {
    "accessTokenTtl": 3600,
    "refreshTokenTtl": 2592000,
    "scopes": ["tools:*", "tools:read", "tools:write"]
  }
}

# 1. Register an OAuth client
curl -X POST http://localhost:3402/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "My Agent", "redirect_uris": ["http://localhost:8080/callback"], "api_key": "pg_..."}'

# 2. Generate PKCE challenge (code_verifier → SHA256 → base64url)
# 3. Authorize: GET /oauth/authorize?response_type=code&client_id=...&redirect_uri=...&code_challenge=...&code_challenge_method=S256
# 4. Exchange code for tokens
curl -X POST http://localhost:3402/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "authorization_code", "code": "...", "client_id": "...", "redirect_uri": "...", "code_verifier": "..."}'

# 5. Use Bearer token on /mcp
curl -X POST http://localhost:3402/mcp \
  -H "Authorization: Bearer pg_at_..." \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "search", "arguments": {"query": "hello"}}}'

# 6. Refresh token
curl -X POST http://localhost:3402/oauth/token \
  -d '{"grant_type": "refresh_token", "refresh_token": "pg_rt_...", "client_id": "..."}'

# POST /mcp with SSE response (add Accept header)
curl -N -X POST http://localhost:3402/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"analyze","arguments":{}}}'
# Response: SSE stream with event: message + data: {jsonrpc response}

# GET /mcp — Open SSE notification stream
curl -N http://localhost:3402/mcp \
  -H "Accept: text/event-stream" \
  -H "Mcp-Session-Id: mcp_sess_..."
# Receives server-initiated notifications as SSE events

# DELETE /mcp — Terminate session
curl -X DELETE http://localhost:3402/mcp \
  -H "Mcp-Session-Id: mcp_sess_..."

# Query audit events (with filtering)
curl http://localhost:3402/audit?types=key.created,gate.deny&limit=50 \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Export full audit log as CSV
curl http://localhost:3402/audit/export?format=csv \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" > audit.csv

# Get audit statistics
curl http://localhost:3402/audit/stats \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Discover server payment metadata (public, no auth)
curl http://localhost:3402/.well-known/mcp-payment
# → { "specVersion": "2007-draft", "billingModel": "credits", "defaultCreditsPerCall": 1, ... }

# Get full pricing breakdown (public, no auth)
curl http://localhost:3402/pricing
# → { "server": {...}, "tools": [{ "name": "search", "creditsPerCall": 5, "pricingModel": "dynamic" }, ...] }

curl http://localhost:3402/metrics

# HELP paygate_tool_calls_total Total tool calls processed
# TYPE paygate_tool_calls_total counter
paygate_tool_calls_total{status="allowed",tool="search"} 42
paygate_tool_calls_total{status="denied",tool="premium"} 3

# HELP paygate_credits_charged_total Total credits charged
# TYPE paygate_credits_charged_total counter
paygate_credits_charged_total{tool="search"} 210

# HELP paygate_active_keys_total Number of active (non-revoked) API keys
# TYPE paygate_active_keys_total gauge
paygate_active_keys_total 5

# HELP paygate_uptime_seconds Server uptime in seconds
# TYPE paygate_uptime_seconds gauge
paygate_uptime_seconds 3600

# Clone with same config and credits
curl -X POST http://localhost:3402/keys/clone \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_source..."}'
# → { "message": "Key cloned", "key": "pg_newkey...", "name": "source-clone", "credits": 200, ... }

# Clone with overrides
curl -X POST http://localhost:3402/keys/clone \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_source...", "name": "staging-key", "credits": 50, "namespace": "staging"}'

curl -X POST http://localhost:3402/keys/rotate \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_oldkey..."}'
# → { "message": "Key rotated", "newKey": "pg_newkey...", "name": "my-key", "credits": 500 }

# Suspend a key (with optional reason for audit trail)
curl -X POST http://localhost:3402/keys/suspend \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_abc123...", "reason": "investigating abuse"}'
# → { "message": "Key suspended", "suspended": true }

# Resume a suspended key
curl -X POST http://localhost:3402/keys/resume \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_abc123..."}'
# → { "message": "Key resumed", "suspended": false }

# Get full usage for a key
curl http://localhost:3402/keys/usage?key=pg_abc123... \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Filter by time (ISO 8601)
curl "http://localhost:3402/keys/usage?key=pg_abc123...&since=2025-01-01T00:00:00Z" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Send test event
curl -X POST http://localhost:3402/webhooks/test \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# With custom message
curl -X POST http://localhost:3402/webhooks/test \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"message": "Testing from staging deploy"}'

# Get recent deliveries (default: last 50, newest first)
curl http://localhost:3402/webhooks/log \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Filter by success/failure
curl "http://localhost:3402/webhooks/log?success=false" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Filter by time and limit
curl "http://localhost:3402/webhooks/log?since=2025-01-01T00:00:00Z&limit=10" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Pause delivery
curl -X POST http://localhost:3402/webhooks/pause \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Check pause status (visible in /webhooks/stats)
curl http://localhost:3402/webhooks/stats \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"
# → { "paused": true, "pausedAt": "2025-...", "bufferedEvents": 12, ... }

# Resume delivery (flushes buffered events)
curl -X POST http://localhost:3402/webhooks/resume \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"
# → { "paused": false, "flushedEvents": 12 }

# Set an alias
curl -X POST http://localhost:3402/keys/alias \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_abc123...", "alias": "prod-backend"}'
# → { "key": "pg_abc12...", "alias": "prod-backend", "message": "Alias set to \"prod-backend\"" }

# Use the alias in any admin endpoint
curl -X POST http://localhost:3402/topup \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "prod-backend", "credits": 500}'

curl -X POST http://localhost:3402/keys/suspend \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "prod-backend", "reason": "maintenance"}'

curl -X POST http://localhost:3402/keys/transfer \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"from": "prod-backend", "to": "staging-api", "credits": 100}'

# Clear an alias
curl -X POST http://localhost:3402/keys/alias \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "prod-backend", "alias": null}'

# Query keys expiring within 24 hours (default)
curl http://localhost:3402/keys/expiring \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"
# → { "within": 86400, "count": 2, "scanner": { ... }, "keys": [ ... ] }

# Query keys expiring within 7 days
curl http://localhost:3402/keys/expiring?within=604800 \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "expiryScanner": {
    "enabled": true,
    "intervalSeconds": 3600,
    "thresholds": [604800, 86400, 3600]
  }
}

# Create a template
curl -X POST http://localhost:3402/keys/templates \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{
    "name": "free-tier",
    "description": "Free plan with basic access",
    "credits": 50,
    "allowedTools": ["search", "read"],
    "deniedTools": ["admin"],
    "tags": {"plan": "free"},
    "namespace": "public",
    "expiryTtlSeconds": 2592000,
    "spendingLimit": 200
  }'

# List all templates
curl http://localhost:3402/keys/templates \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Create a key from template (inherits all defaults)
curl -X POST http://localhost:3402/keys \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "new-user", "template": "free-tier"}'

# Create a key from template with overrides
curl -X POST http://localhost:3402/keys \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "vip-user", "template": "free-tier", "credits": 500, "tags": {"plan": "vip"}}'

# Delete a template
curl -X POST http://localhost:3402/keys/templates/delete \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "free-tier"}'

# Docker example
docker run -e PAYGATE_SERVER="node /app/server.js" \
  -e PAYGATE_PORT=8080 \
  -e PAYGATE_PRICE=5 \
  -e PAYGATE_ADMIN_KEY=sk-admin-secret \
  -e PAYGATE_REDIS_URL=redis://redis:6379 \
  -e PAYGATE_WEBHOOK_URL=https://hooks.example.com/billing \
  -p 8080:8080 node:20 npx paygate-mcp wrap

# Or use a config file via env var
docker run -e PAYGATE_CONFIG=/etc/paygate/config.json \
  -v ./config.json:/etc/paygate/config.json \
  -p 3402:3402 node:20 npx paygate-mcp wrap

# Auto-generated request ID
curl -v http://localhost:3402/health
# < X-Request-Id: req_a1b2c3d4e5f67890

# Propagate your own trace ID
curl -v -H "X-Request-Id: my-trace-123" http://localhost:3402/health
# < X-Request-Id: my-trace-123

curl http://localhost:3402/info

{
  "name": "My API Server",
  "version": "5.5.0",
  "transport": "stdio",
  "port": 3402,
  "auth": ["api_key", "scoped_token"],
  "features": {
    "shadowMode": false,
    "webhooks": true,
    "webhookSignatures": true,
    "refundOnFailure": true,
    "redis": false,
    "oauth": false,
    "plugins": false,
    "multiServer": false
  },
  "pricing": {
    "defaultCreditsPerCall": 1,
    "toolPricing": {
      "expensive-tool": { "creditsPerCall": 10 }
    }
  },
  "rateLimit": { "globalPerMin": 60 },
  "endpoints": {
    "mcp": "/mcp",
    "health": "/health",
    "info": "/info",
    "status": "/status (admin)",
    "keys": "/keys (admin)",
    "metrics": "/metrics",
    "pricing": "/pricing",
    "audit": "/audit (admin)",
    "analytics": "/analytics (admin)"
  }
}

# CLI flag: single origin
npx paygate-mcp wrap --server "..." --cors-origin "https://myapp.com"

# CLI flag: multiple origins (comma-separated)
npx paygate-mcp wrap --server "..." --cors-origin "https://app1.com,https://app2.com"

# Env var
PAYGATE_CORS_ORIGIN=https://myapp.com npx paygate-mcp wrap --server "..."

{
  "cors": {
    "origin": ["https://app1.com", "https://app2.com"],
    "credentials": true,
    "maxAge": 3600
  }
}

# CLI flag: single header
npx paygate-mcp wrap --server "..." --header "X-Frame-Options:DENY"

# CLI flag: multiple headers (comma-separated)
npx paygate-mcp wrap --server "..." --header "X-Frame-Options:DENY,X-Content-Type-Options:nosniff"

# Env var
PAYGATE_CUSTOM_HEADERS="X-Frame-Options:DENY,X-Content-Type-Options:nosniff" npx paygate-mcp wrap --server "..."

{
  "customHeaders": {
    "X-Frame-Options": "DENY",
    "X-Content-Type-Options": "nosniff",
    "Strict-Transport-Security": "max-age=31536000; includeSubDomains",
    "X-Custom-Tag": "my-service"
  }
}

curl http://localhost:3402/config -H "X-Admin-Key: YOUR_ADMIN_KEY"

# CLI flag (comma-separated IPs and/or CIDRs)
paygate-mcp wrap --server "node server.js" --trusted-proxies "10.0.0.0/8,172.16.0.0/12"

# Environment variable
PAYGATE_TRUSTED_PROXIES="10.0.0.0/8,172.16.0.0/12" paygate-mcp wrap --server "node server.js"

{
  "serverCommand": "node",
  "serverArgs": ["server.js"],
  "trustedProxies": ["10.0.0.0/8", "172.16.0.0/12", "192.168.1.1"]
}

# Paginate: 10 keys per page, second page
curl "http://localhost:3402/keys?limit=10&offset=10" -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Filter by namespace and active status
curl "http://localhost:3402/keys?limit=50&namespace=prod&active=true" -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Sort by credits descending
curl "http://localhost:3402/keys?limit=20&sortBy=credits&order=desc" -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Filter by credit range
curl "http://localhost:3402/keys?limit=50&minCredits=100&maxCredits=1000" -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Find keys by name prefix
curl "http://localhost:3402/keys?limit=50&namePrefix=prod-" -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "keys": [...],
  "total": 150,
  "offset": 20,
  "limit": 10,
  "hasMore": true
}

# Get all key statistics
curl http://localhost:3402/keys/stats -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Filter by namespace
curl "http://localhost:3402/keys/stats?namespace=prod" -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "total": 150,
  "active": 120,
  "suspended": 10,
  "expired": 15,
  "revoked": 5,
  "totalCreditsAllocated": 500000,
  "totalCreditsSpent": 125000,
  "totalCreditsRemaining": 375000,
  "totalCalls": 84200,
  "byNamespace": { "prod": 80, "staging": 50, "default": 20 },
  "byGroup": { "enterprise": 30, "starter": 45 }
}

curl "http://localhost:3402/keys/rate-limit-status?key=pg_..." -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "key": "pg_abc123...",
  "name": "my-key",
  "global": {
    "limit": 100,
    "used": 23,
    "remaining": 77,
    "resetInMs": 45000,
    "windowMs": 60000
  },
  "perTool": {
    "search": { "limit": 10, "used": 5, "remaining": 5, "resetInMs": 30000 },
    "translate": { "limit": 20, "used": 0, "remaining": 20, "resetInMs": 60000 }
  }
}

curl "http://localhost:3402/keys/quota-status?key=pg_..." -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "key": "pg_abc123...",
  "name": "my-key",
  "quotaSource": "global",
  "daily": {
    "callsUsed": 42,
    "callsLimit": 100,
    "callsRemaining": 58,
    "creditsUsed": 150,
    "creditsLimit": 500,
    "creditsRemaining": 350,
    "resetDay": "2026-02-26"
  },
  "monthly": {
    "callsUsed": 850,
    "callsLimit": 2000,
    "callsRemaining": 1150,
    "creditsUsed": 3200,
    "creditsLimit": 10000,
    "creditsRemaining": 6800,
    "resetMonth": "2026-02"
  }
}

curl "http://localhost:3402/keys/credit-history?key=pg_..." -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Filter by type, limit, or since timestamp
curl "http://localhost:3402/keys/credit-history?key=pg_...&type=topup&limit=10" -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "key": "pg_abc123...",
  "name": "my-key",
  "currentBalance": 700,
  "totalEntries": 3,
  "entries": [
    {
      "timestamp": "2026-02-26T12:30:00.000Z",
      "type": "topup",
      "amount": 200,
      "balanceBefore": 500,
      "balanceAfter": 700
    },
    {
      "timestamp": "2026-02-26T12:00:00.000Z",
      "type": "initial",
      "amount": 500,
      "balanceBefore": 0,
      "balanceAfter": 500
    }
  ]
}

curl "http://localhost:3402/keys/spending-velocity?key=pg_..." -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Custom analysis window (default 24h, max 720h/30d)
curl "http://localhost:3402/keys/spending-velocity?key=pg_...&window=48" -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "key": "pg_abc123...",
  "name": "my-key",
  "currentBalance": 750,
  "velocity": {
    "creditsPerHour": 12.5,
    "creditsPerDay": 300,
    "callsPerHour": 2.5,
    "callsPerDay": 60,
    "estimatedDepletionDate": "2026-03-01T18:00:00.000Z",
    "estimatedHoursRemaining": 60,
    "windowHours": 24,
    "dataPoints": 45
  },
  "topTools": [
    { "tool": "search", "calls": 30, "credits": 150 },
    { "tool": "generate", "calls": 15, "credits": 120 }
  ]
}

curl "http://localhost:3402/keys/compare?keys=pg_abc,pg_xyz" -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "compared": 2,
  "keys": [
    {
      "key": "pg_abc123...",
      "name": "prod-agent",
      "status": "active",
      "credits": { "current": 750, "totalSpent": 250 },
      "usage": { "totalCalls": 50, "totalAllowed": 48, "totalDenied": 2 },
      "velocity": { "creditsPerHour": 12.5, "creditsPerDay": 300, "estimatedHoursRemaining": 60 },
      "rateLimit": { "used": 3, "limit": 60, "remaining": 57 },
      "metadata": { "namespace": "prod", "group": "team-a", "createdAt": "2026-02-01T00:00:00Z", "tags": { "env": "prod" } }
    },
    {
      "key": "pg_xyz789...",
      "name": "staging-agent",
      "status": "active",
      "credits": { "current": 200, "totalSpent": 800 },
      "usage": { "totalCalls": 120, "totalAllowed": 120, "totalDenied": 0 },
      "velocity": { "creditsPerHour": 8.3, "creditsPerDay": 200, "estimatedHoursRemaining": 24 },
      "rateLimit": { "used": 0, "limit": 60, "remaining": 60 },
      "metadata": { "namespace": "staging", "group": null, "createdAt": "2026-02-15T00:00:00Z", "tags": {} }
    }
  ]
}

curl "http://localhost:3402/keys/health?key=pg_abc" -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "key": "pg_abc123...",
  "name": "prod-agent",
  "score": 72,
  "status": "caution",
  "issues": ["Key expires within 7 days", "Credits depleting rapidly"],
  "components": {
    "balance": { "score": 40, "risk": "warning", "weight": 0.30 },
    "quota": { "score": 85, "risk": "good", "weight": 0.25 },
    "rateLimit": { "score": 100, "risk": "healthy", "weight": 0.20 },
    "errorRate": { "score": 75, "risk": "good", "weight": 0.25 }
  }
}

# Enable maintenance mode
curl -X POST http://localhost:3402/maintenance \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"enabled": true, "message": "Upgrading to v7 — back in 10 minutes"}'

# Check maintenance status
curl http://localhost:3402/maintenance -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Disable maintenance mode
curl -X POST http://localhost:3402/maintenance \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"enabled": false}'

{
  "enabled": true,
  "message": "Upgrading to v7 — back in 10 minutes",
  "since": "2025-03-15T14:30:00.000Z"
}

# Stream all events
curl -N http://localhost:3402/admin/events \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -H "Accept: text/event-stream"

# Stream only key operations
curl -N http://localhost:3402/admin/events?types=key.created,key.revoked,key.topup \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -H "Accept: text/event-stream"

event: connected
data: {"message":"Admin event stream connected","filters":"all"}

event: audit
data: {"id":42,"timestamp":"2025-03-15T14:30:00.000Z","type":"key.created","actor":"admin","message":"Key created: prod-agent","metadata":{...}}

event: audit
data: {"id":43,"timestamp":"2025-03-15T14:30:01.000Z","type":"gate.allow","actor":"pg_abc12...","message":"Allowed: get_weather","metadata":{...}}

# Add a note
curl -X POST http://localhost:3402/keys/notes \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_...", "text": "Increased credits per customer request #1234"}'

# List notes
curl "http://localhost:3402/keys/notes?key=pg_..." -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Delete a note by index
curl -X DELETE "http://localhost:3402/keys/notes?key=pg_...&index=0" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "key": "pg_abc1...2345",
  "notes": [
    { "timestamp": "2025-03-15T14:30:00.000Z", "author": "admin", "text": "Increased credits per customer request #1234" },
    { "timestamp": "2025-03-16T09:00:00.000Z", "author": "admin", "text": "Upgraded to premium tier" }
  ],
  "count": 2
}

# Schedule a key revocation in 24 hours
curl -X POST http://localhost:3402/keys/schedule \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_...", "action": "revoke", "executeAt": "2025-04-01T00:00:00Z"}'

# Schedule a credit top-up
curl -X POST http://localhost:3402/keys/schedule \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_...", "action": "topup", "executeAt": "2025-04-01T00:00:00Z", "params": {"credits": 500}}'

# List all pending schedules (optional ?key= filter)
curl "http://localhost:3402/keys/schedule" -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Cancel a schedule
curl -X DELETE "http://localhost:3402/keys/schedule?id=sched_1" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "id": "sched_1",
  "key": "pg_abc1...2345",
  "action": "revoke",
  "executeAt": "2025-04-01T00:00:00.000Z",
  "createdAt": "2025-03-15T10:30:00.000Z"
}

# Get activity for a key (newest first, default limit 50)
curl "http://localhost:3402/keys/activity?key=pg_..." -H "X-Admin-Key: YOUR_ADMIN_KEY"

# With filters
curl "http://localhost:3402/keys/activity?key=pg_...&limit=20&since=2025-03-15T00:00:00Z" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "key": "pg_abc1...2345",
  "name": "my-agent",
  "total": 42,
  "limit": 50,
  "events": [
    { "timestamp": "2025-03-16T10:30:00Z", "source": "usage", "type": "tool.call", "message": "Called search (5 credits)", "metadata": { "tool": "search", "creditsCharged": 5, "allowed": true } },
    { "timestamp": "2025-03-16T09:00:00Z", "source": "audit", "type": "key.note_added", "message": "Note added to key", "metadata": { "key": "pg_abc1...2345" } },
    { "timestamp": "2025-03-15T14:00:00Z", "source": "audit", "type": "key.created", "message": "Key created: my-agent", "metadata": { "keyMasked": "pg_abc1...2345" } }
  ]
}

# Reserve 500 credits (hold for 5 min default, or set ttlSeconds)
curl -X POST http://localhost:3402/keys/reserve \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_...", "credits": 500, "ttlSeconds": 300, "memo": "Batch job #42"}'

# Commit — deducts the held credits
curl -X POST http://localhost:3402/keys/reserve/commit \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"reservationId": "rsv_1"}'

# Release — frees the hold without deducting
curl -X POST http://localhost:3402/keys/reserve/release \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"reservationId": "rsv_1"}'

# List active reservations (optional ?key= filter)
curl "http://localhost:3402/keys/reserve" -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "id": "rsv_1",
  "key": "pg_abc1...2345",
  "credits": 500,
  "createdAt": "2025-03-16T10:30:00Z",
  "expiresAt": "2025-03-16T10:35:00Z",
  "memo": "Batch job #42",
  "available": 500
}

# Get all requests (newest first)
curl "http://localhost:3402/requests" -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Filter by tool name
curl "http://localhost:3402/requests?tool=my_tool" -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Filter by status (allowed or denied)
curl "http://localhost:3402/requests?status=denied" -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Filter by key (partial match on masked key)
curl "http://localhost:3402/requests?key=pg_abc1" -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Filter by time + pagination
curl "http://localhost:3402/requests?since=2025-03-01T00:00:00Z&limit=50&offset=0" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Combine filters
curl "http://localhost:3402/requests?tool=my_tool&status=allowed&limit=10" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "total": 42,
  "offset": 0,
  "limit": 100,
  "summary": {
    "totalAllowed": 38,
    "totalDenied": 4,
    "totalCredits": 190,
    "avgDurationMs": 45
  },
  "requests": [
    {
      "id": 42,
      "timestamp": "2025-03-16T10:30:00Z",
      "tool": "my_tool",
      "key": "pg_abc1...2345",
      "status": "allowed",
      "credits": 5,
      "durationMs": 32,
      "requestId": "req_a1b2c3d4e5f6g7h8"
    },
    {
      "id": 41,
      "timestamp": "2025-03-16T10:29:55Z",
      "tool": "my_tool",
      "key": "pg_xyz9...8765",
      "status": "denied",
      "credits": 0,
      "durationMs": 1,
      "denyReason": "insufficient_credits",
      "requestId": "req_i9j0k1l2m3n4o5p6"
    }
  ]
}

# Overview of all tools
curl "http://localhost:3402/tools/stats" -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Detailed stats for a specific tool
curl "http://localhost:3402/tools/stats?tool=my_tool" -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Filter by time range
curl "http://localhost:3402/tools/stats?since=2025-03-01T00:00:00Z" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "totalTools": 3,
  "totalCalls": 150,
  "tools": [
    {
      "tool": "my_tool",
      "totalCalls": 100,
      "allowed": 95,
      "denied": 5,
      "successRate": 95,
      "totalCredits": 475,
      "avgDurationMs": 42
    }
  ]
}

{
  "tool": "my_tool",
  "totalCalls": 100,
  "allowed": 95,
  "denied": 5,
  "successRate": 95,
  "totalCredits": 475,
  "avgDurationMs": 42,
  "p95DurationMs": 120,
  "denyReasons": {
    "insufficient_credits": 3,
    "rate_limited": 2
  },
  "topConsumers": [
    { "key": "pg_abc1...2345", "calls": 50, "credits": 250 },
    { "key": "pg_xyz9...8765", "calls": 30, "credits": 150 }
  ]
}

# Export as JSON (default)
curl "http://localhost:3402/requests/export" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" -o paygate-requests.json

# Export as CSV
curl "http://localhost:3402/requests/export?format=csv" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" -o paygate-requests.csv

# Export with filters
curl "http://localhost:3402/requests/export?tool=my_tool&status=denied&since=2025-03-01T00:00:00Z&until=2025-03-31T23:59:59Z" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

curl -X POST http://localhost:3402/requests/dry-run \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_...", "tool": "my_tool"}'

{
  "allowed": true,
  "tool": "my_tool",
  "creditsRequired": 5,
  "creditsAvailable": 100,
  "creditsAfter": 95,
  "rateLimit": { "used": 3, "limit": 60, "remaining": 57, "resetInMs": 45000 }
}

{
  "allowed": false,
  "reason": "insufficient_credits: need 5, have 2",
  "tool": "my_tool",
  "creditsRequired": 5,
  "creditsAvailable": 2
}

curl -X POST http://localhost:3402/requests/dry-run/batch \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_...", "tools": [{"name": "tool_a"}, {"name": "tool_b"}]}'

{
  "allAllowed": true,
  "totalCreditsRequired": 10,
  "creditsAvailable": 100,
  "creditsAfter": 90,
  "results": [
    { "tool": "tool_a", "allowed": true, "creditsRequired": 5 },
    { "tool": "tool_b", "allowed": true, "creditsRequired": 5 }
  ]
}

curl "http://localhost:3402/tools/available?key=pg_..." \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "key": "pg_c815...09a6",
  "creditsAvailable": 100,
  "totalTools": 3,
  "accessibleTools": 2,
  "globalRateLimit": { "limit": 60, "used": 5, "remaining": 55, "resetInMs": 45000 },
  "tools": [
    { "tool": "tool_a", "accessible": true, "creditsPerCall": 10, "canAfford": true },
    { "tool": "tool_b", "accessible": false, "denyReason": "denied_by_acl", "creditsPerCall": 5, "canAfford": true },
    { "tool": "tool_c", "accessible": true, "creditsPerCall": 1, "canAfford": true, "rateLimit": { "limit": 10, "used": 3, "remaining": 7 } }
  ]
}

curl "http://localhost:3402/keys/dashboard?key=pg_..." \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "key": "pg_c815...09a6",
  "name": "production-agent",
  "status": "active",
  "namespace": "prod",
  "balance": { "credits": 850, "totalSpent": 150, "totalAllocated": 1000, "spendingLimit": 500 },
  "health": { "score": 92, "status": "good" },
  "velocity": { "creditsPerHour": 6.2, "creditsPerDay": 149, "estimatedDepletionDate": "2025-02-03T..." },
  "rateLimits": { "global": { "limit": 60, "used": 12, "remaining": 48, "resetInMs": 35000 } },
  "quotas": { "source": "global", "daily": { "callsUsed": 24, "callsLimit": 100 }, "monthly": { "callsUsed": 340, "callsLimit": 5000 } },
  "usage": { "totalCalls": 340, "totalAllowed": 330, "totalDenied": 10, "totalCredits": 150 },
  "recentActivity": [{ "timestamp": "...", "event": "gate.allowed", "tool": "search", "credits": 5 }]
}

# Get all notifications
curl http://localhost:3402/admin/notifications \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Filter by severity
curl "http://localhost:3402/admin/notifications?severity=critical" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "total": 4,
  "critical": 2,
  "warning": 1,
  "info": 1,
  "notifications": [
    {
      "severity": "critical",
      "category": "zero_credits",
      "message": "Key has zero credits remaining",
      "key": "pg_c815...09a6",
      "keyName": "production-agent"
    },
    {
      "severity": "critical",
      "category": "key_expiring_soon",
      "message": "Key expires within 8 hours",
      "key": "pg_a3f1...b2e4",
      "keyName": "staging-agent",
      "details": { "expiresAt": "2026-02-27T08:00:00.000Z", "hoursRemaining": 7.5 }
    },
    {
      "severity": "warning",
      "category": "credits_depleting",
      "message": "Credits will deplete in ~18 hours at current rate",
      "key": "pg_d7e2...f1a3",
      "keyName": "batch-worker",
      "details": { "credits": 90, "creditsPerHour": 5.1, "estimatedHoursRemaining": 17.6 }
    },
    {
      "severity": "info",
      "category": "key_suspended",
      "message": "Key is suspended",
      "key": "pg_b4c9...e8d5",
      "keyName": "deprecated-agent"
    }
  ]
}

curl http://localhost:3402/admin/dashboard \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "keys": { "total": 15, "active": 10, "suspended": 2, "revoked": 2, "expired": 1 },
  "credits": { "totalAllocated": 15000, "totalSpent": 4200, "totalRemaining": 10800 },
  "usage": {
    "totalCalls": 840,
    "totalAllowed": 790,
    "totalDenied": 50,
    "totalCreditsSpent": 4200,
    "denyReasons": [{ "reason": "insufficient_credits", "count": 30 }, { "reason": "rate_limited", "count": 20 }]
  },
  "topConsumers": [
    { "name": "production-agent", "calls": 320, "credits": 1600, "denied": 5 },
    { "name": "batch-worker", "calls": 210, "credits": 1050, "denied": 0 }
  ],
  "topTools": [
    { "tool": "search", "calls": 450, "credits": 2250, "denied": 20 },
    { "tool": "generate", "calls": 300, "credits": 1500, "denied": 10 }
  ],
  "notifications": { "critical": 2, "warning": 3, "info": 2 },
  "uptime": { "startedAt": "2026-02-27T00:00:00.000Z", "uptimeSeconds": 86400, "uptimeHours": 24 }
}

# Full lifecycle report
curl http://localhost:3402/admin/lifecycle \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Filter by date range
curl "http://localhost:3402/admin/lifecycle?since=2026-02-01&until=2026-02-28" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "events": { "created": 25, "revoked": 3, "suspended": 5, "resumed": 4, "rotated": 2, "cloned": 1 },
  "trends": [
    { "date": "2026-02-25", "created": 5, "revoked": 1, "suspended": 2, "resumed": 1 },
    { "date": "2026-02-26", "created": 8, "revoked": 0, "suspended": 1, "resumed": 2 },
    { "date": "2026-02-27", "created": 12, "revoked": 2, "suspended": 2, "resumed": 1 }
  ],
  "averageLifetimeHours": 168.5,
  "atRisk": [
    { "key": "pg_c815...09a6", "name": "staging-agent", "risk": "expiring_soon", "details": { "expiresAt": "2026-03-01T...", "daysRemaining": 2.5 } },
    { "key": "pg_a3f1...b2e4", "name": "batch-worker", "risk": "zero_credits", "details": { "credits": 0 } }
  ]
}

# Full cost analysis
curl http://localhost:3402/admin/costs \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Filter by namespace
curl "http://localhost:3402/admin/costs?namespace=prod" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Filter by time range
curl "http://localhost:3402/admin/costs?since=2026-02-01" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "summary": {
    "totalCredits": 4250,
    "totalCalls": 312,
    "totalAllowed": 298,
    "totalDenied": 14,
    "avgCostPerCall": 13.62
  },
  "perTool": [
    { "tool": "generate_report", "calls": 85, "credits": 1700, "avgCost": 20 },
    { "tool": "query_data", "calls": 142, "credits": 1420, "avgCost": 10 }
  ],
  "perNamespace": [
    { "namespace": "prod", "calls": 210, "credits": 3150 },
    { "namespace": "staging", "calls": 102, "credits": 1100 }
  ],
  "hourlyTrends": [
    { "hour": "2026-02-26T14:00:00.000Z", "calls": 23, "credits": 345, "denied": 1 },
    { "hour": "2026-02-26T15:00:00.000Z", "calls": 31, "credits": 465, "denied": 0 }
  ],
  "topSpenders": [
    { "key": "pg_a1b2...c3d4", "name": "ml-pipeline", "credits": 1800, "calls": 90 },
    { "key": "pg_e5f6...g7h8", "name": "batch-worker", "credits": 1200, "calls": 120 }
  ]
}

curl http://localhost:3402/admin/rate-limits \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "config": {
    "globalLimitPerMin": 60,
    "windowMs": 60000
  },
  "summary": {
    "totalCalls": 450,
    "totalRateLimited": 12,
    "rateLimitRate": 0.0267
  },
  "perKey": [
    { "name": "ml-pipeline", "calls": 200, "rateLimited": 8, "currentWindowUsed": 45, "currentWindowRemaining": 15 },
    { "name": "batch-worker", "calls": 150, "rateLimited": 4, "currentWindowUsed": 12, "currentWindowRemaining": 48 }
  ],
  "perTool": [
    { "tool": "generate_report", "calls": 180, "rateLimited": 10 },
    { "tool": "query_data", "calls": 270, "rateLimited": 2 }
  ],
  "hourlyTrends": [
    { "hour": "2026-02-26T14", "calls": 52, "rateLimited": 3 },
    { "hour": "2026-02-26T15", "calls": 48, "rateLimited": 1 }
  ],
  "mostThrottled": [
    { "name": "ml-pipeline", "rateLimited": 8, "calls": 200, "throttleRate": 0.04 }
  ]
}

curl http://localhost:3000/admin/quotas -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "config": { "globalQuota": { "dailyCallLimit": 100, "monthlyCallLimit": 1000, "dailyCreditLimit": 500, "monthlyCreditLimit": 5000 } },
  "summary": { "totalKeys": 5, "keysWithQuotas": 4, "totalQuotaDenials": 3, "quotaDenialRate": 0.02 },
  "perKey": [
    { "name": "heavy-user", "dailyCalls": 95, "monthlyCalls": 450, "dailyCredits": 475, "monthlyCredits": 2250, "dailyCallLimit": 100, "monthlyCallLimit": 1000, "dailyCreditLimit": 500, "monthlyCreditLimit": 5000, "dailyCallUtilization": 0.95, "monthlyCallUtilization": 0.45, "source": "global" }
  ],
  "perTool": [{ "tool": "summarize", "calls": 120, "quotaDenied": 2 }],
  "hourlyTrends": [{ "hour": "2025-01-15T14", "calls": 15, "quotaDenied": 1 }],
  "mostConstrained": [{ "name": "heavy-user", "dailyCalls": 95, "dailyCallLimit": 100, "dailyCallUtilization": 0.95, "monthlyCalls": 450, "monthlyCallLimit": 1000, "monthlyCallUtilization": 0.45 }]
}

curl http://localhost:3000/admin/denials -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "summary": { "totalCalls": 150, "totalDenials": 12, "denialRate": 0.08 },
  "byReason": { "insufficient_credits": 5, "rate_limited": 4, "quota_exceeded": 2, "key_suspended": 1 },
  "perKey": [
    { "name": "heavy-user", "calls": 50, "denials": 8, "denialRate": 0.16, "topReason": "rate_limited" }
  ],
  "perTool": [{ "tool": "summarize", "calls": 80, "denials": 6, "denialRate": 0.075, "topReason": "insufficient_credits" }],
  "hourlyTrends": [{ "hour": "2025-01-15T14", "calls": 20, "denials": 3 }],
  "mostDenied": [{ "name": "heavy-user", "denials": 8, "calls": 50, "denialRate": 0.16, "topReason": "rate_limited" }]
}

curl http://localhost:3000/admin/traffic -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "summary": { "totalCalls": 500, "totalAllowed": 470, "totalDenied": 30, "successRate": 0.94, "uniqueKeys": 8, "uniqueTools": 3, "peakHour": "2025-01-15T14", "peakHourCalls": 85 },
  "toolPopularity": [{ "tool": "summarize", "calls": 250, "successRate": 0.96, "credits": 2500 }],
  "hourlyVolume": [{ "hour": "2025-01-15T14", "calls": 85, "allowed": 80, "denied": 5, "credits": 400 }],
  "topConsumers": [{ "name": "heavy-user", "calls": 150, "successRate": 0.92, "credits": 1380 }],
  "byNamespace": [{ "namespace": "production", "calls": 400, "allowed": 380, "credits": 3800 }]
}

curl http://localhost:3000/admin/security -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "score": 72,
  "summary": { "totalKeys": 5, "totalFindings": 12 },
  "findings": [
    { "type": "no_ip_allowlist", "severity": "warning", "keys": ["prod-key", "dev-key"], "description": "Keys without IP allowlists can be used from any IP address" },
    { "type": "no_acl_restriction", "severity": "info", "keys": ["dev-key"], "description": "Keys without ACL restrictions can access all tools" },
    { "type": "high_credit_balance", "severity": "warning", "keys": ["whale-key"], "description": "Keys with 10000+ credits are high-value targets if compromised" }
  ]
}

curl http://localhost:3000/admin/revenue -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "summary": { "totalRevenue": 5000, "totalCalls": 250, "averageRevenuePerCall": 20 },
  "byTool": [{ "tool": "summarize", "revenue": 3000, "calls": 150, "averagePerCall": 20 }],
  "byKey": [{ "name": "heavy-user", "revenue": 2000, "calls": 80 }],
  "hourlyRevenue": [{ "hour": "2025-01-15T14", "revenue": 500, "calls": 25 }],
  "creditFlow": { "totalAllocated": 50000, "totalSpent": 5000, "totalRemaining": 45000 }
}

curl http://localhost:3000/admin/key-portfolio -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "summary": { "totalKeys": 10, "activeKeys": 7, "inactiveKeys": 2, "suspendedKeys": 1, "averageCreditUtilization": 0.35 },
  "staleKeys": [{ "name": "unused-key", "createdAt": "2025-01-01T00:00:00Z", "credits": 500, "ageDays": 30 }],
  "expiringSoon": [{ "name": "temp-key", "expiresAt": "2025-01-20T00:00:00Z", "hoursRemaining": 48, "credits": 100 }],
  "ageDistribution": { "averageAgeDays": 15, "oldestAgeDays": 60, "newestAgeDays": 0 },
  "byNamespace": [{ "namespace": "production", "total": 5, "active": 4, "suspended": 1 }]
}

curl http://localhost:3000/admin/anomalies -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "summary": { "totalAnomalies": 3, "byType": { "high_denial_rate": 1, "rapid_credit_depletion": 1, "low_credits": 1 } },
  "anomalies": [
    { "type": "high_denial_rate", "severity": "warning", "keyName": "test-key", "description": "Key \"test-key\" has 80% denial rate (8/10 calls denied)" },
    { "type": "rapid_credit_depletion", "severity": "warning", "keyName": "fast-spender", "description": "Key \"fast-spender\" has used 95% of allocated credits (950/1000)" },
    { "type": "low_credits", "severity": "info", "keyName": "nearly-empty", "description": "Key \"nearly-empty\" has only 5 credits remaining (5% of allocated)" }
  ],
  "analyzedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/forecast -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "summary": { "totalActiveKeys": 3, "keysAtRisk": 1 },
  "keyForecasts": [
    { "keyName": "heavy-user", "creditsRemaining": 50, "totalSpent": 950, "callCount": 95, "avgCreditsPerCall": 10, "estimatedCallsRemaining": 5, "atRisk": true },
    { "keyName": "light-user", "creditsRemaining": 900, "totalSpent": 100, "callCount": 20, "avgCreditsPerCall": 5, "estimatedCallsRemaining": 180, "atRisk": false }
  ],
  "systemForecast": {
    "totalCreditsRemaining": 950,
    "totalCreditsSpent": 1050,
    "totalCalls": 115,
    "byTool": [
      { "tool": "expensive_tool", "calls": 50, "totalCredits": 500, "avgCreditsPerCall": 10 },
      { "tool": "cheap_tool", "calls": 65, "totalCredits": 325, "avgCreditsPerCall": 5 }
    ]
  },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/compliance -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "keyGovernance": { "totalKeys": 5, "keysWithExpiry": 3, "keysWithoutExpiry": 2 },
  "accessControl": {
    "keysWithAcl": 3, "keysWithoutAcl": 2,
    "keysWithIpRestriction": 2, "keysWithoutIpRestriction": 3,
    "keysWithSpendingLimit": 4, "keysWithoutSpendingLimit": 1
  },
  "auditTrail": { "totalEvents": 150, "uniqueTools": 5, "uniqueKeys": 4 },
  "overallScore": 72,
  "recommendations": [
    "Set expiry dates on 2 key(s) without time-limited access",
    "Add tool ACL restrictions to 2 key(s) with unrestricted tool access"
  ],
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/sla -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "summary": {
    "totalCalls": 150, "allowedCalls": 140, "deniedCalls": 10,
    "successRate": 93.33,
    "denialReasons": { "insufficient_credits": 6, "rate_limited": 3, "acl_denied": 1 }
  },
  "byTool": [
    { "tool": "tool_a", "totalCalls": 100, "allowedCalls": 95, "deniedCalls": 5, "successRate": 95 },
    { "tool": "tool_b", "totalCalls": 50, "allowedCalls": 45, "deniedCalls": 5, "successRate": 90 }
  ],
  "uptime": { "startedAt": "2025-01-15T10:00:00Z", "uptimeSeconds": 16200 },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/capacity -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "summary": {
    "totalCreditsAllocated": 10000, "totalCreditsSpent": 3500, "totalCreditsRemaining": 6500,
    "utilizationPct": 35,
    "burnRate": { "creditsPerCall": 10, "totalCalls": 350 }
  },
  "topConsumers": [
    { "keyName": "heavy-user", "creditsSpent": 2000, "creditsRemaining": 500, "callCount": 200 }
  ],
  "byNamespace": {
    "prod": { "allocated": 8000, "spent": 3000, "remaining": 5000, "keys": 3, "utilizationPct": 37 }
  },
  "recommendations": ["1 key(s) have less than 10% credits remaining"],
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/dependencies -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "summary": { "totalTools": 5, "usedTools": 3, "unusedTools": 2 },
  "toolUsage": [
    { "tool": "search", "totalCalls": 150, "uniqueKeys": 8 },
    { "tool": "translate", "totalCalls": 45, "uniqueKeys": 3 }
  ],
  "keyToolMap": [
    { "keyName": "power-user", "tools": ["search", "translate", "summarize"], "toolCount": 3 },
    { "keyName": "basic-user", "tools": ["search"], "toolCount": 1 }
  ],
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/latency -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "summary": { "totalCalls": 200, "avgDurationMs": 45, "minDurationMs": 8, "maxDurationMs": 312, "p95DurationMs": 120 },
  "byTool": [
    { "tool": "translate", "totalCalls": 80, "avgDurationMs": 65, "minDurationMs": 20, "maxDurationMs": 312, "p95DurationMs": 150 },
    { "tool": "search", "totalCalls": 120, "avgDurationMs": 32, "minDurationMs": 8, "maxDurationMs": 95, "p95DurationMs": 78 }
  ],
  "slowestTools": [
    { "tool": "translate", "avgDurationMs": 65, "totalCalls": 80 }
  ],
  "byKey": [
    { "keyName": "heavy-user", "totalCalls": 150, "avgDurationMs": 48, "minDurationMs": 8, "maxDurationMs": 312 }
  ],
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/error-trends -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "summary": { "totalCalls": 500, "totalDenials": 45, "overallErrorRate": 9, "trend": "improving" },
  "byTool": [
    { "tool": "translate", "totalCalls": 200, "denials": 30, "errorRate": 15 },
    { "tool": "search", "totalCalls": 300, "denials": 15, "errorRate": 5 }
  ],
  "denialReasons": [
    { "reason": "insufficient_credits", "count": 30 },
    { "reason": "rate_limited", "count": 15 }
  ],
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/credit-flow -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "summary": { "totalAllocated": 10000, "totalSpent": 3500, "totalRemaining": 6500, "utilizationPct": 35 },
  "topSpenders": [
    { "keyName": "heavy-user", "creditsSpent": 2000, "creditsRemaining": 500, "callCount": 200 }
  ],
  "byTool": [
    { "tool": "search", "creditsSpent": 2000, "callCount": 400 },
    { "tool": "translate", "creditsSpent": 1500, "callCount": 150 }
  ],
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/key-age -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "summary": {
    "totalKeys": 15, "avgAgeHours": 168.5,
    "oldestKey": { "keyName": "legacy", "ageHours": 720, "createdAt": "2025-01-01T00:00:00Z" },
    "newestKey": { "keyName": "fresh", "ageHours": 0.5, "createdAt": "2025-01-31T12:00:00Z" }
  },
  "distribution": { "last24h": 3, "last7d": 5, "last30d": 4, "older": 3 },
  "recentlyCreated": [
    { "keyName": "fresh", "ageHours": 0.5, "createdAt": "2025-01-31T12:00:00Z" }
  ],
  "generatedAt": "2025-01-31T12:30:00Z"
}

curl http://localhost:3000/admin/namespace-usage -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "summary": { "totalNamespaces": 3 },
  "namespaces": [
    { "namespace": "prod", "keyCount": 5, "totalAllocated": 5000, "totalSpent": 2000, "totalRemaining": 3000, "totalCalls": 400, "utilizationPct": 40 },
    { "namespace": "staging", "keyCount": 2, "totalAllocated": 1000, "totalSpent": 200, "totalRemaining": 800, "totalCalls": 40, "utilizationPct": 20 }
  ],
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/audit-summary -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "summary": { "totalEvents": 142, "eventsLastHour": 18, "eventsLast24h": 95, "oldestEvent": "2025-01-14T08:00:00Z", "newestEvent": "2025-01-15T14:30:00Z" },
  "eventsByType": [
    { "type": "gate.allow", "count": 80 },
    { "type": "gate.deny", "count": 25 },
    { "type": "key.created", "count": 12 }
  ],
  "topActors": [
    { "actor": "pg_abc1...", "count": 60 },
    { "actor": "admin", "count": 30 }
  ],
  "recentEvents": [
    { "id": 142, "timestamp": "2025-01-15T14:30:00Z", "type": "gate.allow", "actor": "pg_abc1...", "message": "Allowed: tool_a" }
  ],
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/group-performance -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "summary": { "totalGroups": 2, "ungroupedKeys": 3 },
  "groups": [
    {
      "groupId": "grp_abc123", "groupName": "prod-team", "description": "Production",
      "keyCount": 5, "totalAllocated": 5000, "totalSpent": 2000, "totalRemaining": 3000,
      "totalCalls": 400, "utilizationPct": 40,
      "policy": { "allowedTools": ["tool_a"], "deniedTools": [], "rateLimitPerMin": 60 }
    }
  ],
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/request-trends -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "summary": {
    "totalRequests": 150, "totalAllowed": 130, "totalDenied": 20,
    "totalCredits": 650, "avgDurationMs": 45,
    "peakHour": { "hour": "2025-01-15T14:00:00Z", "total": 42 }
  },
  "hourly": [
    { "hour": "2025-01-15T12:00:00Z", "total": 35, "allowed": 30, "denied": 5, "credits": 150, "avgDurationMs": 40 },
    { "hour": "2025-01-15T13:00:00Z", "total": 42, "allowed": 38, "denied": 4, "credits": 190, "avgDurationMs": 50 }
  ],
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/key-status -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "counts": { "total": 20, "active": 15, "suspended": 2, "revoked": 2, "expired": 1 },
  "needsAttention": [
    { "keyName": "low-balance", "issue": "low_credits", "detail": "5 credits remaining" },
    { "keyName": "trial-key", "issue": "expiring_soon", "detail": "Expires in 48 hours" }
  ],
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/webhook-health -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "configured": true,
  "status": "healthy",
  "delivery": {
    "totalDelivered": 142,
    "totalFailed": 3,
    "totalRetries": 5,
    "pendingRetries": 0,
    "deadLetterCount": 1,
    "bufferedEvents": 0,
    "paused": false,
    "pausedAt": null,
    "successRate": 97.93
  },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/consumer-insights -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "summary": {
    "totalConsumers": 15,
    "activeConsumers": 12,
    "totalCreditsSpent": 4850,
    "totalCalls": 970
  },
  "topSpenders": [
    { "name": "heavy-user", "totalSpent": 1200, "totalCalls": 240, "uniqueTools": 5 }
  ],
  "mostActive": [
    { "name": "heavy-user", "totalCalls": 240, "totalSpent": 1200, "uniqueTools": 5 }
  ],
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/system-health -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "score": 85,
  "level": "healthy",
  "components": {
    "keyHealth": { "score": 90, "weight": 0.4, "detail": "2 suspended" },
    "errorRate": { "score": 80, "weight": 0.35, "detail": "10% denial rate (5/50)" },
    "creditUtilization": { "score": 85, "weight": 0.25, "detail": "45% utilized (4500/10000 credits)" }
  },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/tool-adoption -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "tools": [
    {
      "tool": "search",
      "uniqueConsumers": 8,
      "adoptionRate": 80,
      "totalCalls": 245,
      "firstSeen": "2025-01-10T08:00:00Z",
      "lastSeen": "2025-01-15T14:30:00Z"
    },
    {
      "tool": "translate",
      "uniqueConsumers": 3,
      "adoptionRate": 30,
      "totalCalls": 42,
      "firstSeen": "2025-01-12T10:00:00Z",
      "lastSeen": "2025-01-15T12:00:00Z"
    }
  ],
  "summary": {
    "totalTools": 2,
    "usedTools": 2,
    "unusedTools": 0
  },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/credit-efficiency -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "summary": {
    "totalAllocated": 5000,
    "totalSpent": 1200,
    "totalRemaining": 3800,
    "burnEfficiency": 24,
    "wasteRatio": 76,
    "activeKeys": 10
  },
  "overProvisioned": [
    { "name": "idle-whale", "credits": 950, "totalAllocated": 1000, "totalSpent": 50, "remainingPercent": 95 }
  ],
  "underProvisioned": [
    { "name": "heavy-user", "credits": 3, "totalAllocated": 500, "totalSpent": 497, "remainingPercent": 1 }
  ],
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/access-heatmap -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "hourly": [
    {
      "hour": "2025-01-15T14:00:00.000Z",
      "total": 45,
      "uniqueConsumers": 8,
      "tools": { "search": 30, "translate": 15 }
    }
  ],
  "summary": {
    "totalRequests": 45,
    "totalHours": 1,
    "peakHour": { "hour": "2025-01-15T14:00:00.000Z", "total": 45 }
  },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/key-churn -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "summary": {
    "totalKeys": 50,
    "activeKeys": 40,
    "revokedKeys": 5,
    "suspendedKeys": 3,
    "neverUsedKeys": 8,
    "churnRate": 10,
    "retentionRate": 90,
    "avgCreditsPerKey": 250
  },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/tool-correlation -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "pairs": [
    { "toolA": "search", "toolB": "translate", "sharedConsumers": 5, "strength": 50 },
    { "toolA": "search", "toolB": "summarize", "sharedConsumers": 3, "strength": 30 }
  ],
  "summary": { "totalPairs": 2, "totalConsumers": 10 },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/consumer-segmentation -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "segments": [
    { "segment": "power", "count": 3, "totalCredits": 500, "totalSpent": 2400, "avgCallsPerKey": 35 },
    { "segment": "regular", "count": 8, "totalCredits": 1200, "totalSpent": 800, "avgCallsPerKey": 12 },
    { "segment": "casual", "count": 15, "totalCredits": 3000, "totalSpent": 150, "avgCallsPerKey": 2 },
    { "segment": "dormant", "count": 5, "totalCredits": 1000, "totalSpent": 0, "avgCallsPerKey": 0 }
  ],
  "summary": { "totalConsumers": 31 },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/credit-distribution -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "buckets": [
    { "range": "0-10", "count": 5, "totalCredits": 30 },
    { "range": "11-50", "count": 12, "totalCredits": 420 },
    { "range": "51-100", "count": 8, "totalCredits": 640 },
    { "range": "101-500", "count": 4, "totalCredits": 1200 },
    { "range": "1001+", "count": 2, "totalCredits": 5000 }
  ],
  "summary": { "totalKeys": 31, "medianCredits": 50 },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/response-time-distribution -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "buckets": [
    { "range": "0-50ms", "count": 45, "percentage": 60 },
    { "range": "51-100ms", "count": 20, "percentage": 27 },
    { "range": "101-250ms", "count": 8, "percentage": 11 },
    { "range": "251-500ms", "count": 2, "percentage": 3 }
  ],
  "summary": { "totalRequests": 75, "avgResponseTime": 62, "p50": 42, "p95": 180, "p99": 350 },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/consumer-lifetime-value -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "consumers": [
    { "name": "enterprise-bot", "lifetimeValue": 2500, "totalCalls": 500, "avgSpendPerCall": 5, "toolsUsed": 8, "tier": "high" },
    { "name": "dev-team", "lifetimeValue": 450, "totalCalls": 90, "avgSpendPerCall": 5, "toolsUsed": 4, "tier": "medium" },
    { "name": "trial-user", "lifetimeValue": 5, "totalCalls": 1, "avgSpendPerCall": 5, "toolsUsed": 1, "tier": "low" }
  ],
  "summary": { "totalConsumers": 15, "totalLifetimeValue": 3200, "avgLifetimeValue": 213 },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/tool-revenue -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "tools": [
    { "tool": "code_review", "totalCredits": 1500, "callCount": 300, "avgCreditsPerCall": 5, "uniqueConsumers": 25, "percentage": 60 },
    { "tool": "generate_tests", "totalCredits": 750, "callCount": 150, "avgCreditsPerCall": 5, "uniqueConsumers": 18, "percentage": 30 },
    { "tool": "lint_check", "totalCredits": 250, "callCount": 50, "avgCreditsPerCall": 5, "uniqueConsumers": 12, "percentage": 10 }
  ],
  "summary": { "totalTools": 3, "totalRevenue": 2500, "topTool": "code_review" },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/consumer-retention -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "cohorts": [
    { "period": "2025-01-15", "created": 10, "retained": 8, "retentionRate": 80, "avgSpend": 150 },
    { "period": "2025-01-14", "created": 5, "retained": 3, "retentionRate": 60, "avgSpend": 80 }
  ],
  "summary": { "totalKeys": 15, "retainedKeys": 11, "overallRetentionRate": 73 },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/error-breakdown -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "errors": [
    { "reason": "insufficient_credits", "count": 45, "percentage": 75, "affectedConsumers": 12 },
    { "reason": "rate_limited", "count": 10, "percentage": 17, "affectedConsumers": 3 },
    { "reason": "acl_denied", "count": 5, "percentage": 8, "affectedConsumers": 2 }
  ],
  "summary": { "totalDenied": 60, "totalAllowed": 940, "errorRate": 6 },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/credit-utilization -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "bands": [
    { "range": "0%", "count": 5, "percentage": 25 },
    { "range": "1-25%", "count": 8, "percentage": 40 },
    { "range": "26-50%", "count": 4, "percentage": 20 },
    { "range": "51-75%", "count": 2, "percentage": 10 },
    { "range": "76-99%", "count": 1, "percentage": 5 }
  ],
  "summary": { "totalAllocated": 10000, "totalSpent": 3500, "overallUtilization": 35, "totalKeys": 20 },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/namespace-revenue -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "namespaces": [
    { "namespace": "team-alpha", "totalSpent": 1500, "totalCalls": 300, "keyCount": 5, "percentage": 60 },
    { "namespace": "team-beta", "totalSpent": 750, "totalCalls": 150, "keyCount": 3, "percentage": 30 },
    { "namespace": "default", "totalSpent": 250, "totalCalls": 50, "keyCount": 2, "percentage": 10 }
  ],
  "summary": { "totalNamespaces": 3, "totalRevenue": 2500, "topNamespace": "team-alpha" },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/group-revenue -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "groups": [
    { "group": "premium", "totalSpent": 2000, "totalCalls": 400, "keyCount": 8, "percentage": 65 },
    { "group": "free-tier", "totalSpent": 800, "totalCalls": 160, "keyCount": 12, "percentage": 26 },
    { "group": "ungrouped", "totalSpent": 280, "totalCalls": 56, "keyCount": 3, "percentage": 9 }
  ],
  "summary": { "totalGroups": 3, "totalRevenue": 3080, "topGroup": "premium" },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/peak-usage -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "hours": [
    { "hour": 9, "requests": 450, "allowed": 420, "denied": 30, "credits": 2100, "uniqueConsumers": 15, "percentage": 30 },
    { "hour": 14, "requests": 380, "allowed": 370, "denied": 10, "credits": 1850, "uniqueConsumers": 12, "percentage": 25 },
    { "hour": 22, "requests": 120, "allowed": 118, "denied": 2, "credits": 590, "uniqueConsumers": 5, "percentage": 8 }
  ],
  "summary": { "totalRequests": 1500, "peakHour": 9, "peakRequests": 450 },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/consumer-activity -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "consumers": [
    { "name": "alice", "totalCalls": 150, "totalSpent": 750, "creditsRemaining": 250, "lastActive": "2025-01-15T14:30:00Z", "status": "active" },
    { "name": "bob", "totalCalls": 0, "totalSpent": 0, "creditsRemaining": 500, "lastActive": null, "status": "inactive" }
  ],
  "summary": { "totalConsumers": 2, "activeConsumers": 1, "inactiveConsumers": 1 },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/tool-popularity -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "tools": [
    { "tool": "search", "totalCalls": 500, "totalCredits": 2500, "uniqueConsumers": 20, "percentage": 50 },
    { "tool": "generate", "totalCalls": 300, "totalCredits": 3000, "uniqueConsumers": 15, "percentage": 30 },
    { "tool": "translate", "totalCalls": 200, "totalCredits": 1000, "uniqueConsumers": 10, "percentage": 20 }
  ],
  "summary": { "totalTools": 3, "totalCalls": 1000, "mostPopular": "search" },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/credit-allocation -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "tiers": [
    { "tier": "1-100", "count": 15, "totalCredits": 750, "percentage": 5.0 },
    { "tier": "101-500", "count": 30, "totalCredits": 9000, "percentage": 60.0 },
    { "tier": "501+", "count": 5, "totalCredits": 5250, "percentage": 35.0 }
  ],
  "summary": { "totalKeys": 50, "totalAllocated": 15000, "totalRemaining": 12000, "totalSpent": 3000, "averageAllocation": 300 },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/daily-summary -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "days": [
    { "date": "2025-01-15", "requests": 150, "allowed": 140, "denied": 10, "creditsSpent": 700, "uniqueConsumers": 25, "uniqueTools": 8, "newKeys": 3 },
    { "date": "2025-01-14", "requests": 120, "allowed": 115, "denied": 5, "creditsSpent": 575, "uniqueConsumers": 20, "uniqueTools": 7, "newKeys": 1 }
  ],
  "summary": { "totalDays": 2, "totalRequests": 270, "totalCreditsSpent": 1275, "averageRequestsPerDay": 135 },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/key-ranking -H "X-Admin-Key: YOUR_ADMIN_KEY"
# Sort by calls: ?sortBy=totalCalls
# Sort by credits remaining: ?sortBy=creditsRemaining

{
  "rankings": [
    { "rank": 1, "name": "power-user", "totalSpent": 500, "totalCalls": 100, "creditsRemaining": 500 },
    { "rank": 2, "name": "moderate-user", "totalSpent": 200, "totalCalls": 40, "creditsRemaining": 800 },
    { "rank": 3, "name": "light-user", "totalSpent": 50, "totalCalls": 10, "creditsRemaining": 950 }
  ],
  "summary": { "totalKeys": 3, "sortedBy": "totalSpent" },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/hourly-traffic -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "hours": [
    { "timestamp": "2025-01-15T14:00:00Z", "requests": 45, "allowed": 42, "denied": 3, "credits": 210, "uniqueConsumers": 12, "uniqueTools": 5 },
    { "timestamp": "2025-01-15T13:00:00Z", "requests": 30, "allowed": 28, "denied": 2, "credits": 140, "uniqueConsumers": 8, "uniqueTools": 4 }
  ],
  "summary": { "totalRequests": 75, "totalCredits": 350, "busiestHour": "2025-01-15T14:00:00Z", "busiestHourRequests": 45 },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/tool-error-rate -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "tools": [
    { "tool": "translate", "totalRequests": 100, "allowed": 85, "denied": 15, "errorRate": 15 },
    { "tool": "search", "totalRequests": 200, "allowed": 190, "denied": 10, "errorRate": 5 },
    { "tool": "generate", "totalRequests": 150, "allowed": 150, "denied": 0, "errorRate": 0 }
  ],
  "summary": { "totalTools": 3, "overallErrorRate": 5.56, "highestErrorTool": "translate" },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/consumer-spend-velocity -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "consumers": [
    { "name": "power-user", "totalSpent": 500, "creditsRemaining": 500, "creditsPerHour": 25.5, "hoursUntilDepleted": 19.61 },
    { "name": "casual-user", "totalSpent": 50, "creditsRemaining": 950, "creditsPerHour": 2.1, "hoursUntilDepleted": 452.38 },
    { "name": "idle-user", "totalSpent": 0, "creditsRemaining": 100, "creditsPerHour": 0, "hoursUntilDepleted": null }
  ],
  "summary": { "totalConsumers": 3, "fastestSpender": "power-user" },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/namespace-activity -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "namespaces": [
    { "namespace": "production", "keyCount": 5, "totalSpent": 1200, "totalCalls": 240, "creditsRemaining": 3800 },
    { "namespace": "staging", "keyCount": 2, "totalSpent": 80, "totalCalls": 16, "creditsRemaining": 920 },
    { "namespace": "default", "keyCount": 1, "totalSpent": 0, "totalCalls": 0, "creditsRemaining": 100 }
  ],
  "summary": { "totalNamespaces": 3, "topNamespace": "production" },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/credit-burn-rate -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "burnRate": { "creditsPerHour": 45.5, "hoursUntilDepleted": 104.4, "utilizationPercent": 25 },
  "summary": { "totalAllocated": 5000, "totalSpent": 1250, "totalRemaining": 3750, "activeKeys": 10 },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/consumer-risk-score -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "consumers": [
    { "name": "heavy-user", "riskScore": 80, "riskLevel": "critical", "creditsRemaining": 20, "totalSpent": 80, "utilizationPercent": 80 },
    { "name": "normal-user", "riskScore": 25, "riskLevel": "medium", "creditsRemaining": 150, "totalSpent": 50, "utilizationPercent": 25 },
    { "name": "idle-user", "riskScore": 0, "riskLevel": "low", "creditsRemaining": 100, "totalSpent": 0, "utilizationPercent": 0 }
  ],
  "summary": { "totalConsumers": 3, "riskDistribution": { "low": 1, "medium": 1, "high": 0, "critical": 1 } },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/revenue-forecast -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "forecast": { "nextHour": 45.5, "nextDay": 1092, "nextWeek": 7644, "nextMonth": 32760 },
  "current": { "totalSpent": 1250, "totalRemaining": 48750, "creditsPerHour": 45.5, "activeKeys": 10 },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/system-overview -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "keys": { "total": 15, "active": 12, "revoked": 2, "suspended": 1 },
  "credits": { "totalAllocated": 150000, "totalSpent": 45000, "totalRemaining": 105000, "utilizationPercent": 30 },
  "activity": { "totalCalls": 3500, "uniqueTools": 8 },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/key-health-overview -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "keys": [
    { "name": "depleted-key", "credits": 0, "totalSpent": 1000, "totalCalls": 85, "utilizationPercent": 100, "status": "critical" },
    { "name": "active-key", "credits": 200, "totalSpent": 800, "totalCalls": 60, "utilizationPercent": 80, "status": "warning" },
    { "name": "healthy-key", "credits": 9000, "totalSpent": 1000, "totalCalls": 50, "utilizationPercent": 10, "status": "healthy" }
  ],
  "summary": { "totalKeys": 3, "healthDistribution": { "healthy": 1, "warning": 1, "critical": 1 } },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/namespace-comparison -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "namespaces": [
    { "namespace": "production", "keyCount": 5, "totalAllocated": 50000, "totalSpent": 12000, "totalCalls": 800, "creditsRemaining": 38000, "utilizationPercent": 24 },
    { "namespace": "staging", "keyCount": 3, "totalAllocated": 3000, "totalSpent": 500, "totalCalls": 50, "creditsRemaining": 2500, "utilizationPercent": 17 }
  ],
  "summary": { "totalNamespaces": 2, "leader": "production" },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/consumer-growth -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "consumers": [
    { "name": "enterprise-key", "ageHours": 720, "totalSpent": 4500, "creditsAllocated": 10000, "spendRate": 6.25 },
    { "name": "trial-key", "ageHours": 24, "totalSpent": 10, "creditsAllocated": 100, "spendRate": 0.42 }
  ],
  "summary": { "totalConsumers": 2, "newConsumers24h": 1 },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/tool-profitability -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "tools": [
    { "tool": "search", "totalCalls": 150, "totalRevenue": 450, "avgRevenuePerCall": 3, "callerCount": 8 },
    { "tool": "translate", "totalCalls": 40, "totalRevenue": 120, "avgRevenuePerCall": 3, "callerCount": 3 }
  ],
  "summary": { "totalRevenue": 570, "mostProfitable": "search", "leastProfitable": "translate" },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/credit-waste -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "keys": [
    { "name": "unused-key", "creditsAllocated": 1000, "creditsUsed": 0, "creditsRemaining": 1000, "wastePercent": 100 },
    { "name": "active-key", "creditsAllocated": 500, "creditsUsed": 350, "creditsRemaining": 150, "wastePercent": 30 }
  ],
  "summary": { "totalAllocated": 1500, "totalWasted": 1150, "averageWastePercent": 65 },
  "generatedAt": "2025-01-15T14:30:00Z"
}

curl http://localhost:3000/admin/group-activity -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "groups": [
    { "group": "production", "keyCount": 5, "totalSpent": 2500, "totalCalls": 180, "creditsRemaining": 7500 },
    { "group": "staging", "keyCount": 3, "totalSpent": 400, "totalCalls": 45, "creditsRemaining": 2600 }
  ],
  "summary": { "totalGroups": 2, "topGroup": "production" },
  "generatedAt": "2025-01-15T14:30:00Z"
}

# Set IP allowlist on a key (replaces existing list)
curl -X POST http://localhost:3402/keys/ip \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_...", "ips": ["192.168.1.0/24", "10.0.0.5"]}'

# Clear allowlist (allow all IPs)
curl -X POST http://localhost:3402/keys/ip \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_...", "ips": []}'

curl -X POST http://localhost:3402/keys \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "prod-agent", "credits": 1000, "ipAllowlist": ["10.0.0.0/8"]}'

# Set tags (merge semantics — existing tags preserved, new ones added/updated)
curl -X POST http://localhost:3402/keys/tags \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_...", "tags": {"team": "backend", "env": "production", "customer_id": "cus_123"}}'

# Remove a tag (set value to null)
curl -X POST http://localhost:3402/keys/tags \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_...", "tags": {"env": null}}'

# Search keys by tags
curl -X POST http://localhost:3402/keys/search \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"tags": {"team": "backend"}}'
# → { "keys": [...], "count": 3 }

curl -X POST http://localhost:3402/keys \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "backend-prod", "credits": 5000, "tags": {"team": "backend", "env": "production"}}'

# Get analytics for the last 24 hours (hourly buckets)
curl "http://localhost:3402/analytics?from=2026-02-25T00:00:00Z&to=2026-02-26T00:00:00Z&granularity=hourly" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Daily granularity with top 5 consumers
curl "http://localhost:3402/analytics?granularity=daily&topN=5" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Configure alert rules
curl -X POST http://localhost:3402/alerts \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"rules": [
    {"type": "spending_threshold", "threshold": 80},
    {"type": "credits_low", "threshold": 50},
    {"type": "quota_warning", "threshold": 90},
    {"type": "key_expiry_soon", "threshold": 86400},
    {"type": "rate_limit_spike", "threshold": 10}
  ]}'

# Consume pending alerts (returns and clears queue)
curl http://localhost:3402/alerts \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Create a team
curl -X POST http://localhost:3402/teams \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "Engineering", "budget": 10000, "tags": {"dept": "eng"}}'

# Assign an API key to a team
curl -X POST http://localhost:3402/teams/assign \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"teamId": "team_abc123...", "apiKey": "pg_abc123..."}'

# Set team quotas (daily/monthly limits)
curl -X POST http://localhost:3402/teams/update \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"teamId": "team_abc123...", "quota": {"dailyCalls": 1000, "monthlyCalls": 25000, "dailyCredits": 5000, "monthlyCredits": 100000}}'

# View team usage with member breakdown
curl "http://localhost:3402/teams/usage?teamId=team_abc123..." \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

X-RateLimit-Limit: 100        # Max calls per window
X-RateLimit-Remaining: 87     # Calls remaining in current window
X-RateLimit-Reset: 45         # Seconds until window resets
X-Credits-Remaining: 4500     # Credits remaining on the key

curl http://localhost:3402/health

{
  "status": "healthy",
  "uptime": 3600,
  "version": "2.6.0",
  "inflight": 3,
  "redis": { "connected": true, "pubsub": true },
  "webhooks": { "pendingRetries": 0, "deadLetterCount": 2 }
}

// Graceful shutdown with custom timeout (default 30s)
await server.gracefulStop(15_000);

# Validate a config file — exits 0 if valid, 1 if errors found
paygate-mcp validate --config paygate.json

✗ 2 error(s):
  ERROR  [port] Invalid port 99999. Must be 0–65535.
  ERROR  [redisUrl] Invalid redisUrl protocol "http:". Expected "redis://" or "rediss://".
⚠ 1 warning(s):
  WARN   [shadowMode] Shadow mode is enabled. Payment will not be enforced.

paygate-mcp wrap --server "node my-server.js" --dry-run

  ── DRY RUN ──────────────────────────────────────
  Discovered 3 tool(s):

  ────────────────────────────────────────────────────────────
  Tool                          Credits/Call   Rate Limit
  ────────────────────────────────────────────────────────────
  search                        5              30/min
  generate                      10             10/min
  list_items                    1              60/min
  ────────────────────────────────────────────────────────────

  Dry run complete — shutting down.

import { validateConfig, formatDiagnostics } from 'paygate-mcp';

const diags = validateConfig(myConfig);
if (diags.some(d => d.level === 'error')) {
  console.error(formatDiagnostics(diags));
  process.exit(1);
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call_batch",
  "params": {
    "calls": [
      { "name": "search", "arguments": { "q": "MCP servers" } },
      { "name": "translate", "arguments": { "text": "hello", "to": "es" } },
      { "name": "summarize", "arguments": { "url": "https://example.com" } }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "results": [
      { "tool": "search", "result": { "content": [...] }, "creditsCharged": 5 },
      { "tool": "translate", "result": { "content": [...] }, "creditsCharged": 3 },
      { "tool": "summarize", "result": { "content": [...] }, "creditsCharged": 2 }
    ],
    "totalCreditsCharged": 10,
    "remainingCredits": 90
  }
}

import { Gate, BatchToolCall } from 'paygate-mcp';

const calls: BatchToolCall[] = [
  { name: 'search', arguments: { q: 'test' } },
  { name: 'translate', arguments: { text: 'hi' } },
];

const result = gate.evaluateBatch(apiKey, calls, clientIp);
if (!result.allAllowed) {
  console.log(`Denied at index ${result.failedIndex}: ${result.reason}`);
} else {
  console.log(`Charged ${result.totalCredits} credits for ${calls.length} calls`);
}

curl -X POST http://localhost:3402/keys \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "acme-agent", "credits": 1000, "namespace": "acme-corp"}'

curl http://localhost:3402/keys?namespace=acme-corp \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

curl http://localhost:3402/namespaces \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "namespaces": [
    { "namespace": "acme-corp", "keyCount": 3, "activeKeys": 2, "totalCredits": 2500, "totalSpent": 480 },
    { "namespace": "beta-inc", "keyCount": 1, "activeKeys": 1, "totalCredits": 500, "totalSpent": 120 }
  ],
  "count": 2
}

# Status filtered to one namespace
curl http://localhost:3402/status?namespace=acme-corp -H "X-Admin-Key: ..."

# Usage events filtered by namespace
curl http://localhost:3402/usage?namespace=acme-corp -H "X-Admin-Key: ..."

# Analytics filtered by namespace
curl "http://localhost:3402/analytics?namespace=acme-corp&from=2025-01-01" -H "X-Admin-Key: ..."

# Search keys by tag within a namespace
curl -X POST http://localhost:3402/keys/search \
  -H "X-Admin-Key: ..." -H "Content-Type: application/json" \
  -d '{"tags": {"env": "prod"}, "namespace": "acme-corp"}'

curl -X POST http://localhost:3402/tokens \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "pg_parent_key_here",
    "ttl": 300,
    "allowedTools": ["search", "summarize"],
    "label": "agent-session-42"
  }'

{
  "token": "pgt_eyJhcGl...signature",
  "expiresAt": "2025-06-15T12:05:00.000Z",
  "ttl": 300,
  "parentKey": "my-agent",
  "allowedTools": ["search", "summarize"],
  "label": "agent-session-42",
  "message": "Use as X-API-Key or Bearer token on /mcp"
}

# As X-API-Key header
curl -X POST http://localhost:3402/mcp \
  -H "X-API-Key: pgt_eyJhcGl...signature" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search","arguments":{"q":"hello"}}}'

# As Bearer token
curl -X POST http://localhost:3402/mcp \
  -H "Authorization: Bearer pgt_eyJhcGl...signature" \
  -H "Content-Type: application/json" \
  -d '...'

import { ScopedTokenManager } from 'paygate-mcp';

const tokens = new ScopedTokenManager('your-signing-secret');

// Create
const token = tokens.create({
  apiKey: 'pg_parent_key',
  ttlSeconds: 300,
  allowedTools: ['search'],
  label: 'agent-42',
});

// Validate
const result = tokens.validate(token);
if (result.valid) {
  console.log(result.payload.apiKey); // 'pg_parent_key'
  console.log(result.payload.allowedTools); // ['search']
}

// Check if a string is a scoped token
ScopedTokenManager.isToken('pgt_...'); // true
ScopedTokenManager.isToken('pg_...');  // false

curl -X POST http://localhost:3402/tokens/revoke \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token": "pgt_eyJhcGl...signature", "reason": "session ended"}'

{
  "message": "Token revoked",
  "fingerprint": "a1b2c3d4e5f6...",
  "expiresAt": "2025-06-15T12:05:00.000Z",
  "revokedAt": "2025-06-15T11:30:00.000Z"
}

curl http://localhost:3402/tokens/revoked \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

import { ScopedTokenManager } from 'paygate-mcp';

const tokens = new ScopedTokenManager('your-signing-secret');
const token = tokens.create({ apiKey: 'pg_key', ttlSeconds: 3600 });

// Revoke
const entry = tokens.revokeToken(token, 'session ended');
console.log(entry.fingerprint); // SHA-256 hex

// Validate — now returns { valid: false, reason: 'token_revoked' }
tokens.validate(token); // { valid: false, reason: 'token_revoked' }

// Check revocation list size
tokens.revocationList.size; // 1

// Clean up on shutdown
tokens.destroy();

curl -X POST http://localhost:3402/keys/auto-topup \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "pg_abc123...", "threshold": 100, "amount": 500, "maxDaily": 10}'

{
  "autoTopup": { "threshold": 100, "amount": 500, "maxDaily": 10 },
  "message": "Auto-topup enabled: add 500 credits when balance drops below 100 (max 10/day)"
}

curl -X POST http://localhost:3402/keys/auto-topup \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "pg_abc123...", "disable": true}'

import { Gate } from 'paygate-mcp';

const gate = new Gate(config, 'state.json');
const record = gate.store.createKey('premium-client', 1000);

// Configure auto-topup
record.autoTopup = { threshold: 100, amount: 500, maxDaily: 5 };
gate.store.save();

// Hook for notifications
gate.onAutoTopup = (apiKey, amount, newBalance) => {
  console.log(`Auto-topped up ${amount} credits → balance: ${newBalance}`);
};

// Gate.evaluate() automatically triggers auto-topup after credit deduction
const result = gate.evaluate(record.key, { name: 'expensive-tool' });

curl -X POST http://localhost:3402/admin/keys \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI Bot", "role": "admin"}'
# Returns: { "key": "ak_...", "name": "CI Bot", "role": "admin", "createdAt": "..." }

curl http://localhost:3402/admin/keys \
  -H "X-Admin-Key: $ADMIN_KEY"
# Returns masked keys with roles, status, and last used timestamps

curl -X POST http://localhost:3402/admin/keys/revoke \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "ak_..."}'

import { PayGateServer, PayGatePlugin } from 'paygate-mcp';

// Define a plugin
const loggingPlugin: PayGatePlugin = {
  name: 'request-logger',
  version: '1.0.0',

  // Gate hooks (sync — hot path)
  beforeGate: (ctx) => {
    // Return { allowed: false, reason: '...' } to short-circuit
    // Return null to continue normal evaluation
    if (ctx.toolName === 'dangerous_tool') {
      return { allowed: false, reason: 'tool_disabled' };
    }
    return null;
  },

  afterGate: (ctx, decision) => {
    // Modify the gate decision after evaluation
    console.log(`${ctx.toolName}: ${decision.allowed ? 'allowed' : 'denied'}`);
    return decision;
  },

  transformPrice: (toolName, basePrice, args) => {
    // Return a number to override price, or null to keep base price
    if (toolName === 'premium_search') return basePrice * 2;
    return null;
  },

  onDeny: (ctx, reason) => {
    // Called whenever a tool call is denied
    console.log(`Denied: ${ctx.toolName} — ${reason}`);
  },

  // Tool hooks (async)
  beforeToolCall: async (ctx) => {
    // Modify the JSON-RPC request before forwarding
    return { ...ctx.request, params: { ...ctx.request.params, audit: true } };
  },

  afterToolCall: async (ctx, response) => {
    // Modify the JSON-RPC response before returning to client
    return response;
  },

  // HTTP hook (async)
  onRequest: (req, res) => {
    // Add custom endpoints — return true if handled
    if (req.url === '/custom/status') {
      res.writeHead(200, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify({ custom: true }));
      return true;
    }
    return false;
  },

  // Lifecycle hooks (async)
  onStart: async () => { console.log('Plugin started'); },
  onStop: async () => { console.log('Plugin stopped'); },
};

// Register plugins with .use() (chainable)
const server = new PayGateServer({ ... });
server
  .use(loggingPlugin)
  .use(anotherPlugin);

await server.start();

curl http://localhost:3402/plugins -H "X-Admin-Key: $ADMIN_KEY"
# { "count": 2, "plugins": [{ "name": "...", "version": "...", "hooks": ["beforeGate", ...] }] }

curl -X POST http://localhost:3402/groups \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -d '{
    "name": "free-tier",
    "allowedTools": ["search", "read_file"],
    "rateLimitPerMin": 30,
    "ipAllowlist": ["10.0.0.0/8"],
    "quota": { "dailyCallLimit": 100, "monthlyCallLimit": 1000, "dailyCreditLimit": 50, "monthlyCreditLimit": 200 },
    "toolPricing": { "search": { "creditsPerCall": 2 } },
    "tags": { "tier": "free" }
  }'
# { "id": "grp_a1b2c3...", "name": "free-tier", ... }

curl -X POST http://localhost:3402/groups/assign \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -d '{ "groupId": "grp_a1b2c3...", "key": "pgk_..." }'

curl http://localhost:3402/groups -H "X-Admin-Key: $ADMIN_KEY"
# [{ "id": "grp_...", "name": "free-tier", "memberCount": 5, ... }]

# Update group policies
curl -X POST http://localhost:3402/groups/update \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -d '{ "id": "grp_...", "rateLimitPerMin": 60 }'

# Remove a key from its group
curl -X POST http://localhost:3402/groups/remove \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -d '{ "key": "pgk_..." }'

# Delete a group (removes all assignments)
curl -X POST http://localhost:3402/groups/delete \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -d '{ "id": "grp_..." }'

import { PayGateServer, KeyGroupManager } from 'paygate-mcp';

const server = new PayGateServer({ ... });
const { port, adminKey } = await server.start();

// Access groups directly
const group = server.groups.createGroup({ name: 'enterprise', rateLimitPerMin: 1000 });
server.groups.assignKey(apiKey, group.id);

// Resolve effective policy for a key
const policy = server.groups.resolvePolicy(apiKey, keyRecord);
// { allowedTools, deniedTools, rateLimitPerMin, quota, ipAllowlist, toolPricing, maxSpendingLimit }

# Single instance with Redis persistence
npx paygate-mcp wrap --server "your-mcp-server" --redis-url "redis://localhost:6379"

# With password and database
npx paygate-mcp wrap --server "your-mcp-server" \
  --redis-url "redis://:mypassword@redis.internal:6379/2"

{
  "serverCommand": "your-mcp-server",
  "redisUrl": "redis://localhost:6379"
}

                    ┌──────────────┐
                    │   Redis 7+   │
                    │  ┌────────┐  │
                    │  │pub/sub │  │
                    └──┴───┬────┴──┘
                           │
              ┌────────────┼────────────┐
              │            │            │
        ┌─────┴─────┐ ┌───┴───┐ ┌─────┴─────┐
        │ PayGate 1 │ │  PG 2 │ │ PayGate 3 │
        │ (sub+pub) │ │ (sub) │ │ (sub+pub) │
        └─────┬─────┘ └───┬───┘ └─────┬─────┘
              │            │            │
        ┌─────┴────────────┴────────────┴─────┐
        │          Load Balancer               │
        └──────────────────────────────────────┘

npx paygate-mcp wrap --config paygate.json

{
  "serverCommand": "npx",
  "serverArgs": ["@modelcontextprotocol/server-filesystem", "/tmp"],
  "port": 3402,
  "defaultCreditsPerCall": 2,
  "globalRateLimitPerMin": 30,
  "webhookUrl": "https://billing.example.com/events",
  "webhookFilters": [
    {
      "name": "production-alerts",
      "events": ["key.created", "key.revoked", "alert.fired"],
      "url": "https://alerts.example.com/webhook",
      "keyPrefixes": ["pk_prod_"]
    }
  ],
  "refundOnFailure": true,
  "stateFile": "~/.paygate/state.json",
  "toolPricing": {
    "premium_analyze": { "creditsPerCall": 10, "creditsPerKbInput": 5 }
  },
  "globalQuota": {
    "dailyCallLimit": 1000,
    "monthlyCreditLimit": 50000
  },
  "oauth": {
    "accessTokenTtl": 3600,
    "scopes": ["tools:*"]
  },
  "redisUrl": "redis://localhost:6379",
  "importKeys": {
    "pg_abc123def456": 500
  }
}

# Reload from the config file used at startup
curl -X POST http://localhost:3402/config/reload \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# One-time reload from a different config file
curl -X POST http://localhost:3402/config/reload \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"configPath": "/path/to/updated-config.json"}'

{
  "ok": true,
  "changed": ["defaultCreditsPerCall", "globalRateLimitPerMin"],
  "skipped": [],
  "warnings": [],
  "message": "Config reloaded: 2 fields updated"
}

https://render.com/deploy?repo=https://github.com/walker77/paygate-mcp

fly launch --image ghcr.io/walker77/paygate-mcp:latest --name my-paygate
fly secrets set PAYGATE_ADMIN_KEY=your-admin-key PAYGATE_REMOTE_URL=https://your-mcp-server.com/mcp

# Build the image
docker build -t paygate-mcp .

# Run with a remote MCP server
docker run -d \
  -p 3000:3000 \
  -v paygate-data:/data \
  -e PAYGATE_REMOTE_URL="https://my-mcp-server.com/mcp" \
  -e PAYGATE_ADMIN_KEY="your-admin-key" \
  paygate-mcp

# Run with environment variables
docker run -d \
  -p 3000:3000 \
  -e PAYGATE_PORT=3000 \
  -e PAYGATE_REMOTE_URL="https://api.example.com/mcp" \
  -e PAYGATE_DEFAULT_CREDITS=5 \
  -e PAYGATE_RATE_LIMIT=120 \
  -e PAYGATE_WEBHOOK_URL="https://hooks.example.com/paygate" \
  paygate-mcp

# Set your MCP server URL and start
MCP_REMOTE_URL="https://my-mcp-server.com/mcp" docker-compose up -d

# View logs
docker-compose logs -f paygate

# Check health
curl http://localhost:3000/health

# /etc/systemd/system/paygate-mcp.service
[Unit]
Description=PayGate MCP Proxy
After=network.target

[Service]
Type=simple
User=paygate
WorkingDirectory=/opt/paygate-mcp
ExecStart=/usr/bin/node dist/cli.js wrap \
  --remote-url "https://my-mcp-server.com/mcp" \
  --port 3000 \
  --state-file /var/lib/paygate/state.json \
  --audit-file /var/log/paygate/audit.jsonl
Restart=always
RestartSec=5
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

sudo systemctl enable paygate-mcp
sudo systemctl start paygate-mcp
sudo journalctl -u paygate-mcp -f

# Install globally
npm install -g paygate-mcp

# Start with PM2
pm2 start paygate-mcp -- wrap \
  --remote-url "https://my-mcp-server.com/mcp" \
  --port 3000 \
  --state-file ./state.json

# Or use ecosystem file
pm2 start ecosystem.config.js

# Install k6
brew install k6            # macOS
# or: https://k6.io/docs/getting-started/installation

# Start server (example: echo backend)
npx paygate-mcp wrap -- echo '{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"ok"}]}}' \
  --port 3000 --credits-per-call 1

# Run with admin key (from server startup output)
K6_ADMIN_KEY=admin_xxxx k6 run load-test.js

# Custom VUs and duration
K6_ADMIN_KEY=admin_xxxx k6 run --vus 100 --duration 60s load-test.js

# Against remote deployment
K6_PAYGATE_URL=https://paygate.example.com K6_ADMIN_KEY=admin_xxxx k6 run load-test.js

import { PayGateServer } from 'paygate-mcp';

// Wrap a local server (stdio)
const server = new PayGateServer({
  serverCommand: 'npx',
  serverArgs: ['@modelcontextprotocol/server-filesystem', '/tmp'],
  port: 3402,
  defaultCreditsPerCall: 1,
  toolPricing: {
    'premium_analyze': { creditsPerCall: 10 }
  },
});

const { port, adminKey } = await server.start();

// Multi-server mode
const multiServer = new PayGateServer(
  { serverCommand: '', port: 3402, defaultCreditsPerCall: 1 },
  undefined, undefined, undefined, undefined,
  [
    { prefix: 'fs', serverCommand: 'npx', serverArgs: ['@modelcontextprotocol/server-filesystem', '/tmp'] },
    { prefix: 'api', remoteUrl: 'https://my-mcp-server.example.com/mcp' },
  ]
);

// With Redis for horizontal scaling
const redisServer = new PayGateServer(
  { serverCommand: 'npx', serverArgs: ['my-mcp-server'], port: 3402, defaultCreditsPerCall: 1 },
  undefined, undefined, undefined, undefined, undefined,
  'redis://localhost:6379'
);

// Client SDK
import { PayGateClient } from 'paygate-mcp/client';

const client = new PayGateClient({
  url: `http://localhost:${port}`,
  apiKey: 'pg_...',
});

const tools = await client.listTools();
const result = await client.callTool('search', { query: 'hello' });

# Run integration tests (requires internet — downloads MCP servers via npx)
npx vitest run tests/real-mcp-servers.test.ts