# Augur - Full Documentation

> Deterministic Base contract admission control for agents on Base. Returns an effective decision, policy recommendation, supporting findings, and a 0-100 score. Pay $0.10/call via x402 in USDC on Base.

## Overview

Augur is a paid HTTP API for deterministic pre-transaction contract admission control on Base (EIP-155:8453). Use Augur before your agent buys, routes funds, approves, pays, or interacts. Call before pay. Call before approve. Call before interact. Augur is deterministic preflight for Base contract actions. It uses deterministic bytecode pattern matching (no LLM) for fast, reliable results. It is a fast bytecode gate, not a full security audit, simulator, runtime monitor, or guarantee. Payment is via the x402 HTTP payment protocol - no API key, no signup, no subscription.

## Endpoint

```
GET https://augurrisk.com/analyze?address={base_contract_address}
POST https://augurrisk.com/analyze  (body: {"address": "{base_contract_address}"})
```

**Payment:** $0.10 USDC on Base via x402. Send a request, receive 402 with payment details, sign USDC authorization, retry with `PAYMENT-SIGNATURE` header.

## First Successful Paid Call

Use this exact request as the canonical integration check:

```http
GET https://augurrisk.com/analyze?address=0x4200000000000000000000000000000000000006
PAYMENT-SIGNATURE: <x402-payment-proof>
```

Expected first success: HTTP `200` JSON with `decision: "allow"`, `level: "safe"`, and `score: 0`.
If the request is missing `address`, appends another path after the address, or uses a malformed address, Augur returns `422` before payment.

## Request Parameters

| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| address   | string | Yes      | Base mainnet contract address, 0x-prefixed, 40 hex chars |
| action    | string | No       | Optional action-aware context. V1 currently supports only `approve` |
| spender   | string | No       | Required when `action=approve`; Base spender address |
| chain     | string | No       | Optional action-aware chain context. V1 currently supports only `base` |

## Example: Safe Contract

```json
{
  "address": "0x4200000000000000000000000000000000000006",
  "score": 0,
  "level": "safe",
  "decision": "allow",
  "contract_decision": "allow",
  "recommended_policy": {
    "action": "allow",
    "summary": "Allow by default for first-pass automation. Continue only if this matches your broader strategy and trust model.",
    "reason_codes": []
  },
  "bytecode_size": 4632,
  "findings": [],
  "category_scores": {}
}
```

## Example: Proxy Contract With Resolved Implementation

```json
{
  "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "score": 50,
  "level": "medium",
  "decision": "manual_review",
  "contract_decision": "manual_review",
  "recommended_policy": {
    "action": "manual_review",
    "summary": "Escalate before interaction. Use a human review step or a heavier tool before the workflow proceeds.",
    "reason_codes": [
      "elevated_risk_score",
      "upgradeable_proxy",
      "selfdestruct_signal",
      "delegatecall_surface"
    ]
  },
  "bytecode_size": 234,
  "findings": [
    {
      "detector": "delegatecall",
      "severity": "info",
      "title": "DELEGATECALL in proxy pattern",
      "description": "Contract uses DELEGATECALL with standard proxy storage slots (EIP-1967/1822). This is expected proxy behavior.",
      "points": 10
    },
    {
      "detector": "proxy",
      "severity": "info",
      "title": "Proxy contract detected",
      "description": "Contract uses standard proxy storage slots (EIP-1967 or EIP-1822). The implementation contract should also be analyzed.",
      "points": 10
    },
    {
      "detector": "impl_selfdestruct",
      "severity": "critical",
      "title": "SELFDESTRUCT opcode found",
      "description": "Contract contains SELFDESTRUCT which allows the owner to destroy the contract and drain all funds.",
      "points": 30
    }
  ],
  "category_scores": {
    "delegatecall": 10,
    "proxy": 10,
    "impl_selfdestruct": 30
  },
  "implementation": {
    "address": "0x2cE6409Bc2Ff3E36834E44e15bbE83e4aD02d779",
    "bytecode_size": 201,
    "findings": [
      {
        "detector": "impl_selfdestruct",
        "severity": "critical",
        "title": "SELFDESTRUCT opcode found",
        "description": "Contract contains SELFDESTRUCT which allows the owner to destroy the contract and drain all funds.",
        "points": 30
      }
    ],
    "category_scores": {
      "selfdestruct": 30
    }
  }
}
```

## Example: Action-Aware Approve Request

```http
GET https://augurrisk.com/analyze?address=0x4200000000000000000000000000000000000006&action=approve&spender=0x1111111111111111111111111111111111111111&chain=base
```

The top-level `decision` becomes the effective action-aware gate, while `contract_decision` preserves the contract-only policy action and `action_evaluation` shows the approval-specific detail.

## Example: Action-Aware Approve Response

```json
{
  "address": "0x4200000000000000000000000000000000000006",
  "score": 0,
  "level": "safe",
  "decision": "warn",
  "contract_decision": "allow",
  "recommended_policy": {
    "action": "warn",
    "summary": "Allow with caution only if this workflow explicitly expects the approval. Keep the spender on an allowlist and the approval scope narrow.",
    "reason_codes": [
      "action_approve_requested"
    ]
  },
  "bytecode_size": 4632,
  "findings": [],
  "category_scores": {},
  "action_context": {
    "action": "approve",
    "spender": "0x1111111111111111111111111111111111111111",
    "chain": "base"
  },
  "action_evaluation": {
    "decision": "warn",
    "recommended_policy": {
      "action": "warn",
      "summary": "Allow with caution only if this workflow explicitly expects the approval. Keep the spender on an allowlist and the approval scope narrow.",
      "reason_codes": [
        "action_approve_requested"
      ]
    }
  }
}
```

In this example:

- the contract-level `contract_decision` is still `allow`
- the primary top-level `decision` is `warn`
- the action-level `action_evaluation.decision` is `warn`
- the reason code `action_approve_requested` explains why the approval path is more cautious than the contract's default policy

Current limit: action-aware V1 supports only `approve` on Base. If no spender allowlist is configured, the live service treats spender trust as `unchecked`.

## Response Schema

| Field            | Type    | Description |
|------------------|---------|-------------|
| address          | string  | The analyzed contract address |
| score            | integer | Composite risk score, 0-100 |
| level            | string  | Risk bucket: safe, low, medium, high, critical; measurement only (`safe` is not a guarantee) |
| decision         | string  | Primary branch field: effective first-pass action, allow, warn, manual_review, or block |
| contract_decision | string | Contract-only policy action before optional action-aware escalation |
| recommended_policy | object | Policy recommendation with action equal to `decision`, summary, and stable reason_codes |
| bytecode_size    | integer | Contract bytecode size in bytes |
| findings         | array   | List of risk findings from detectors |
| category_scores  | object  | Risk points by detector category |
| implementation   | object  | Proxy implementation analysis (only for proxy contracts) |

### Finding Object

| Field       | Type    | Description |
|-------------|---------|-------------|
| detector    | string  | Detector name (e.g. proxy, reentrancy, selfdestruct) |
| severity    | string  | info, low, medium, high, or critical |
| title       | string  | Human-readable finding title |
| description | string  | Detailed explanation |
| points      | integer | Risk points contributed to composite score |

## Risk Levels

| Level    | Score Range | Meaning |
|----------|-------------|---------|
| safe     | 0-15        | No major bytecode-level risk signals detected in this scan; not a guarantee |
| low      | 16-35       | Limited bytecode-level concerns detected; review context |
| medium   | 36-55       | Notable risks, review before interacting |
| high     | 56-75       | Significant risks detected |
| critical | 76-100      | Severe risks, avoid interaction |

## Detectors

1. **Proxy Detection** - identifies upgradeable proxy behavior and can include nested implementation analysis.
2. **Reentrancy** - surfaces bytecode patterns associated with reentrant control flow risk.
3. **Selfdestruct** - flags contract destruction capability when present.
4. **Honeypot** - looks for transfer restriction patterns that can trap exits.
5. **Hidden Mint** - highlights mint-related capability that may matter for token trust decisions.
6. **Fee Manipulation** - surfaces fee and transfer-tax related bytecode signals.
7. **Delegatecall** - flags external code execution surfaces that may affect mutability or trust.
8. **Deployer Reputation** - adds deployer-history context when explorer-backed data is available.

## Error Responses

**422 - Invalid request:**
```json
{"error": "Missing 'address' query parameter"}
{"error": "Invalid Ethereum address: 0x1234"}
{"error": "No contract bytecode found at Base address: 0x4200000000000000000000000000000000000006"}
```

**402 - Payment required:** Returned with x402 payment instructions. Use an x402-compatible client to handle payment automatically.

**502 - RPC error:** Upstream Base RPC node error. Retry after a moment.

## Integration

Use any x402-compatible HTTP client. The flow is:

1. `GET /analyze?address=<addr>` → receives 402 with payment details
2. The client handles the x402 payment flow
3. The client retries with `PAYMENT-SIGNATURE`
4. Augur returns JSON risk analysis

## Links

- [Skill Doc](https://augurrisk.com/skill.md)
- [MCP Setup](https://augurrisk.com/mcp)
- [MCP Package](https://www.npmjs.com/package/augurrisk-mcp)
- [OpenAPI Spec](https://augurrisk.com/openapi.json)
- [A2A Agent Card](https://augurrisk.com/.well-known/agent-card.json)
- [AI Plugin Manifest](https://augurrisk.com/.well-known/ai-plugin.json)
- [x402 Discovery](https://augurrisk.com/.well-known/x402)
- [API Catalog (RFC 9727)](https://augurrisk.com/.well-known/api-catalog)
- [Agent Metadata](https://augurrisk.com/agent-metadata.json)
- [ERC-8004 Registry](https://8004scan.io/agents/base/19074)
- [Summary](https://augurrisk.com/llms.txt)