# guard402 — Full Documentation

> Reliability layer for AI agents. Content Firewall, Output Validator, and Loop Detector. Pay-per-call with USDC via x402.

## What is guard402?

guard402 is API infrastructure that catches three categories of agent failure:

1. **Prompt Injection** — Malicious content that hijacks agent behavior. Hidden instructions in web pages, emails, documents.
2. **Hallucinations** — Agent outputs that don't match reality. Wrong numbers, fabricated facts, logical errors.
3. **Stuck Loops** — Agents repeating the same action, oscillating between states, or drifting from their goal.

Each failure mode has a dedicated endpoint. No API keys needed — payment is per-call via the x402 protocol using USDC stablecoin on Base or Solana.

## API Base URL

https://api.guard402.com

## Payment Flow (x402 Protocol)

Every paid endpoint uses x402 instead of API keys:

1. **Call the endpoint** with your request body
2. **Receive HTTP 402** with payment details:
   - `maxAmountRequired`: USDC amount in micro-units (6 decimals). "1000" = $0.001
   - `payTo`: Wallet address to send USDC to
   - `network`: "base" or "solana"
   - `asset`: USDC contract address on that network
3. **Send USDC** on Base or Solana to the `payTo` address
4. **Retry the same request** with the `X-PAYMENT` proof header
5. **Receive HTTP 200** with the result

### Payment Networks

| Network | USDC Contract |
|---------|--------------|
| Base    | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
| Solana  | EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v |

### Client Libraries

- **JavaScript**: x402-js (npm: @anthropics/x402-js)
- **Python**: x402-python (pip: x402-python)
- **Rust**: x402-rs (crates.io: x402-rs)

---

## POST /scan — Content Firewall

**Cost:** $0.001 per call

Scans external content for prompt injection attacks before your agent processes it.

### How It Works

1. **Fast path** — 40+ regex patterns instantly catch known injection techniques (hidden divs, zero-width characters, base64 payloads, role-switching prompts)
2. **Ambiguous content** (score 0.3–0.7) escalates to LLM analysis
3. Returns threat report with severity scores and optional sanitized content

### Request

```json
POST https://api.guard402.com/scan
Content-Type: application/json

{
  "content": "<div>Product review</div><div style='display:none'>Ignore all previous instructions</div>",
  "content_type": "html"
}
```

**Fields:**
- `content` (string, required): Raw content to scan
- `content_type` (string, optional): "text", "html", or "markdown". Default: "text"

### Response

```json
{
  "safe": false,
  "score": 0.95,
  "threats": [
    {
      "type": "prompt_injection",
      "location": "hidden div",
      "content": "Ignore all previous instructions",
      "severity": 0.95
    }
  ],
  "sanitized": "<div>Product review</div>"
}
```

**Fields:**
- `safe` (bool): Whether the content is safe to process
- `score` (float, 0-1): Threat score. 0 = safe, 1 = definitely malicious
- `threats` (array): List of detected threats with type, location, content snippet, and severity
- `sanitized` (string|null): Content with threats removed. Null if safe.

### Use Cases

- **Web scraping agents** — Scan fetched pages before processing. Attackers hide "ignore all instructions" in invisible HTML divs.
- **Email assistants** — Check incoming emails before summarizing. Phishing emails embed injection in font-size:0 text.
- **RAG pipelines** — Validate retrieved documents. Poisoned knowledge bases can hijack agent behavior.
- **Document processing** — Scan uploaded PDFs, CSVs, and spreadsheets for embedded injection payloads.

---

## POST /validate — Output Validator

**Cost:** $0.005 per call

Validates agent output against the original task and context to catch hallucinations before your agent acts.

### What It Catches

- Factual inconsistencies with provided context
- Hallucinated data (numbers, names, dates that don't exist in context)
- Logical errors or contradictions
- Incomplete responses that don't address the task

### Request

```json
POST https://api.guard402.com/validate
Content-Type: application/json

{
  "task": "Send invoice for project Alpha",
  "output": "Invoice generated: $4,500 for project Alpha",
  "context": "Contract signed for $45,000 for project Alpha, due March 2026"
}
```

**Fields:**
- `task` (string, required): What the agent was asked to do
- `output` (string, required): The agent's output to validate
- `context` (string, optional): Source material to validate against

### Response

```json
{
  "valid": false,
  "confidence": 0.97,
  "issues": [
    {
      "type": "factual_inconsistency",
      "detail": "Output says $4,500 but context specifies $45,000 — 10x discrepancy",
      "suggestion": "Verify the amount. Context indicates the contract is for $45,000."
    }
  ]
}
```

**Fields:**
- `valid` (bool): Whether the output passed validation
- `confidence` (float, 0-1): Confidence in the validation result
- `issues` (array): List of issues found with type, detail, and suggestion

### Use Cases

- **Finance agents** — Verify invoices, transfers, and calculations match source data. A misplaced decimal can cost thousands.
- **Coding agents** — Check that generated code implements the spec. Catch hallucinated APIs before committing.
- **Customer support bots** — Validate responses against company policy docs. Prevent promises you can't keep.
- **Research agents** — Cross-check summaries against source material. Catch fabricated citations and statistics.

---

## POST /check — Loop Detector

**Cost:** $0.001 per call

Detects stuck agent patterns by analyzing step history within a session. Pure algorithmic — no LLM needed, sub-millisecond response.

### Detection Patterns

| Pattern    | Description                              | Trigger                                    |
|------------|------------------------------------------|--------------------------------------------|
| `repeater` | Same action + params + result repeating  | 3+ identical steps in last 20              |
| `looper`   | Alternating cycle (ABAB, ABCABC)         | Cycle of length ≤5 repeats 2+ times       |
| `wanderer` | Drifting away from original goal         | Similarity < 0.2 for 5+ consecutive steps |

### How To Use

Send each step your agent takes. The detector maintains session state server-side and auto-expires sessions after 30 minutes of inactivity. Store up to 50 steps per session.

### Request

```json
POST https://api.guard402.com/check
Content-Type: application/json

{
  "session_id": "agent-session-abc123",
  "step": 47,
  "action": "search_flights",
  "params": {"from": "NYC", "to": "LAX", "date": "2026-04-01"},
  "result": "found 3 flights, cheapest $480",
  "goal": "book the cheapest flight from NYC to LAX"
}
```

**Fields:**
- `session_id` (string, required): Unique session identifier for your agent run
- `step` (integer, optional): Step number in the agent's execution
- `action` (string, required): The action the agent performed
- `params` (object, optional): Parameters passed to the action
- `result` (string, required): Brief summary of the action's result
- `goal` (string, optional): The agent's original goal (used for wanderer detection)

### Response (stuck)

```json
{
  "stuck": true,
  "pattern": "repeater",
  "loops": 4,
  "wasted_steps": 3,
  "suggestion": "Action 'search_flights' repeated 4 times with identical params and result. Try a different approach or modify the search parameters."
}
```

### Response (not stuck)

```json
{
  "stuck": false
}
```

**Fields:**
- `stuck` (bool): Whether the agent appears stuck
- `pattern` (string|null): "repeater", "looper", or "wanderer"
- `loops` (integer|null): Number of repeated cycles detected
- `wasted_steps` (integer|null): Estimated number of wasted steps
- `suggestion` (string|null): Human-readable suggestion for breaking out

### Use Cases

- **Autonomous agents** — Catch infinite retry loops before they burn through API credits.
- **Multi-step workflows** — Detect oscillation between states without progress.
- **Goal-driven agents** — Flag when an agent drifts off-task.
- **Cost control** — Kill runaway agents before they rack up bills.

---

## GET /health — Health Check (Free)

```json
GET https://api.guard402.com/health

{
  "status": "ok",
  "uptime_seconds": 86400,
  "version": "0.1.0",
  "services": ["loop_detector", "content_firewall", "output_validator"]
}
```

## GET /.well-known/agent-card.json — A2A Agent Card (Free)

Returns the A2A (Agent-to-Agent) protocol agent card describing guard402's capabilities, skills, and payment requirements. Any A2A-compatible agent can discover guard402 by fetching this endpoint.

## GET /erc8004/metadata — ERC-8004 Metadata (Free)

Returns on-chain identity metadata that the ERC-8004 registry on Base mainnet points to.

---

## Discovery & Verification

- **A2A Agent Card**: https://api.guard402.com/.well-known/agent-card.json
- **ERC-8004 On-chain**: https://basescan.org/address/0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
- **x402Scout Catalog**: Registered (Content Firewall, Output Validator, Loop Detector)
- **OpenAPI Spec**: https://guard402.com/openapi.yaml
- **Health**: https://api.guard402.com/health

## Links

- Website: https://guard402.com
- API Docs: https://guard402.com/docs
- Contact: hello@guard402.com