Docs/WaveGuard

WaveGuard API Reference

Physics-based anomaly detection. 37 endpoints. GPU-accelerated. No API key required for basic access.

Base URL: https://api.emergentphysicslab.com/waveguardOpen Swagger UI

Authentication Core Endpoints Agent Integration Python SDK Response Schema Encoders Error Handling Rate Limits

#Authentication

WaveGuard is open access — no API key required for basic requests. Rate limiting applies to prevent abuse.

FREEDirect REST calls — no key, rate-limited

x402Micropayments ($0.001/scan) via USDC on Base — unlimited rate for AI agents

MCPModel Context Protocol for Claude / GPT tool use — no key needed

#Core Endpoints

POST/v1/scan

Run an anomaly scan on your data. Returns anomaly score, classification, and physics fingerprint.

Request

{
  "data": [100, 102, 101, 105, 130, 108, 107],
  "encoder": "json",
  "threshold": 3.0
}

Response

{
  "is_anomaly": true,
  "score": 4.27,
  "threshold": 3.0,
  "classification": "anomaly",
  "fingerprint": {
    "energy_mean": 0.523,
    "energy_std": 0.187,
    "chi_min": 17.2,
    "chi_max": 19.0,
    "spectral_peaks": [0.125, 0.250]
  },
  "metadata": {
    "encoder": "json",
    "grid_size": 32,
    "steps": 100,
    "elapsed_ms": 47
  }
}

GET/v1/scan

Query-parameter version. Pass data as comma-separated values.

Request

GET /v1/scan?data=100,102,101,105,130,108&encoder=json&threshold=3.0

Response

Same response schema as POST /v1/scan

POST/v1/fingerprint

Get the raw physics fingerprint without anomaly classification. Useful for building your own scoring.

Request

{
  "data": [100, 102, 101, 105, 130, 108, 107],
  "encoder": "json"
}

Response

{
  "fingerprint": {
    "energy_mean": 0.523,
    "energy_std": 0.187,
    "chi_min": 17.2,
    "chi_max": 19.0,
    "well_fraction": 0.12,
    "void_fraction": 0.65,
    "spectral_peaks": [0.125, 0.250],
    "spectral_power": [0.89, 0.34]
  },
  "metadata": {
    "encoder": "json",
    "grid_size": 32,
    "steps": 100,
    "elapsed_ms": 38
  }
}

POST/v1/compare

Compare two data samples by their physics fingerprints. Returns similarity score and per-feature distances.

Request

{
  "data_a": [100, 102, 101, 105, 103],
  "data_b": [100, 102, 101, 200, 103],
  "encoder": "json"
}

Response

{
  "similarity": 0.34,
  "distance": 8.72,
  "per_feature": {
    "energy_mean": 2.1,
    "energy_std": 5.4,
    "chi_min": 1.2
  }
}

GET/v1/health

Health check. Returns service status and version.

Request

No body required

Response

{
  "status": "healthy",
  "version": "1.0.0",
  "gpu": true,
  "uptime_seconds": 3600
}

GET/v1/tier

Returns pricing tier information and current rate limits.

Request

No body required

Response

{
  "tier": "free",
  "rate_limit": "fair use",
  "x402_price_usd": 0.001,
  "x402_asset": "USDC",
  "x402_network": "base"
}

#AI Agent Integration

MCP (Model Context Protocol)

Connect Claude, GPT, or any MCP-compatible agent directly to WaveGuard.

MCP Config (claude_desktop_config.json)

{
  "mcpServers": {
    "waveguard": {
      "command": "npx",
      "args": [
        "-y",
        "@smithery/cli@latest",
        "run",
        "@gpartin/waveguard-mcp",
        "--config",
        "{\"serverUrl\": \"https://api.emergentphysicslab.com/waveguard\"}"
      ]
    }
  }
}

x402 Micropayments

AI agents can pay per-scan using the x402 protocol. $0.001 in USDC on Base per request.

Discovery Endpoint

GET /.well-known/x402

{
  "version": "1.0",
  "paymentRequirements": {
    "asset": "USDC",
    "network": "base",
    "amount": "0.001",
    "recipient": "0x..."
  },
  "endpoints": ["/v1/scan", "/v1/fingerprint", "/v1/compare"]
}

Agent Discovery

Standard discovery endpoints for AI agent tooling:

GET /.well-known/ai-plugin.json
GET /.well-known/agent.json
GET /.well-known/openapi.json
GET /v1/agent/tools
GET /v1/agent/mcp
GET /v1/agent/langchain

#Python SDK

Install

pip install WaveGuardClient

Anomaly Scan

from waveguard_client import WaveGuardClient

client = WaveGuardClient(
    base_url="https://api.emergentphysicslab.com/waveguard"
)

# Scan a data array
result = client.scan(
    data=[100, 102, 101, 105, 130, 108, 107],
    encoder="json",
    threshold=3.0,
)

print(f"Anomaly: {result.is_anomaly}")
print(f"Score:   {result.score}")
print(f"Finger:  {result.fingerprint}")

Compare Fingerprints

# Compare two data samples
comparison = client.compare(
    data_a=[100, 102, 101, 105, 103],
    data_b=[100, 102, 101, 200, 103],
)
print(f"Similarity: {comparison.similarity}")
print(f"Distance:   {comparison.distance}")

#Response Schema

Field	Type	Description
is_anomaly	boolean	True if score exceeds threshold
score	float	Mahalanobis distance from normal baseline
threshold	float	Anomaly threshold (default 3.0)
classification	string	"normal" or "anomaly"
fingerprint	object	Physics fingerprint (see below)
fingerprint.energy_mean	float	Mean wave energy density
fingerprint.energy_std	float	Energy standard deviation
fingerprint.chi_min	float	Minimum chi value (deepest well)
fingerprint.chi_max	float	Maximum chi value
fingerprint.well_fraction	float	Fraction of cells with chi < 17
fingerprint.void_fraction	float	Fraction of cells with chi > 19
fingerprint.spectral_peaks	float[]	Peak frequencies from FFT
metadata.elapsed_ms	int	Processing time in milliseconds
metadata.grid_size	int	Lattice grid size used
metadata.steps	int	Evolution steps run

#Encoders

Encoders map your data onto the 3D lattice. Choose based on your data format:

json

General-purpose. Works with any JSON-serializable array of numbers. Maps values to lattice amplitudes using spatial hashing.

Best for: Default choice for most data

timeseries

Optimized for ordered time-series data. Preserves temporal structure on the lattice with proper windowing.

Best for: Sensor data, metrics, price history

The full WaveGuard engine supports 8 encoders including tabular, correlation-aware, and image encoders. The API exposes the two most common ones. Contact us for enterprise access to all encoders.

#Error Handling

Status	Meaning	Action
200	Success	Parse JSON response
400	Bad request (invalid data or encoder)	Check request body format
402	Payment required (x402)	Include x402 payment header
422	Validation error	Check field types and constraints
429	Rate limited	Wait and retry, or use x402 for unlimited
500	Server error	Retry after a moment
503	GPU cold start	Retry in 10-30 seconds

Cold starts: The GPU backend runs on Modal and may take 10-30 seconds to warm up after periods of inactivity. First requests may see 503 errors. Subsequent requests are fast (<500ms).

#Rate Limits

Tier	Rate	Notes
Free	Fair use	No key required. Suitable for testing and low-volume use.
x402	Unlimited	$0.001/scan in USDC. No rate limit for paying requests.