# dappgrade Score API

> dappgrade Score API is a paid API for AI agents from dappgrade.vercel.app, paid per call via x402, $0.01/call, status unknown (last checked 2026-09-14).

Returns a pre-transaction safety verdict (ok/caution/avoid/unknown) for an onchain smart contract by address and chain, with a coverage fraction and machine-readable reasons.

## Facts

- Endpoint: GET https://dappgrade.vercel.app/v1/score
- Price: $0.01/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/dappgrade-score-api-b5782bd2
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_KB4ZepiVIBryI1vmF2Z03

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability dappgrade-score-api-b5782bd2
```

Example prompt: Before I approve the transaction, check the dappgrade safety verdict for contract 0xAbCd1234...5678 on Base — is it ok, caution, or avoid, and how much of the rubric was covered?

## When to prefer this

Use this endpoint when an AI agent needs a fast, decision-shaped safety verdict on a smart contract before executing a transaction — especially in automated pipelines where aborting on 'avoid' or pausing on 'caution' is required. Prefer it over generic blockchain explorers when you need a structured verdict with machine-readable reason codes and coverage framing rather than raw on-chain data. The coverage field makes it uniquely useful for understanding how much of the rubric actually ran, so you can decide whether an 'unknown' is a gap or a genuine no-data case.

## Known failure modes

- Contract address not found or never analyzed → verdict: unknown with no scored fields (free call)
- Stale data when max_age param is set → verdict: unknown + STALE_FOR_CALLER reason (still billed)
- Invalid address format (not 0x + 40 hex chars) → validation error
- Unsupported chain identifier → error response
- Network/service unavailability → HTTP 5xx
- Insufficient USDC payment → x402 payment required error

## How this service works

dappgrade score — pre-transaction health/safety verdict for an onchain app, by contract address. Returns ok / caution / avoid / unknown with the coverage the verdict rests on.

## Output

A JSON object containing: verdict (ok/caution/avoid/unknown), score (integer or null), tier (integer or null), coverage (0–1 float indicating rubric completion), flags (array of flag strings), reasons (array of objects with code, flag, check, and detail fields for machine-readable causes), verdict_reason (prose explanation), and freshness metadata (checked_at, age_seconds, stale). A verdict of unknown with no scored fields is returned free when no data exists; unknown should never be read as safe.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "chain",
      "address"
     ],
     "properties": {
      "chain": {
       "type": "string",
       "description": "EVM chain — id (8453), CAIP-2 (eip155:8453), or name (base, mainnet, arbitrum, optimism)"
      },
      "address": {
       "type": "string",
       "pattern": "^0x[a-fA-F0-9]{40}$",
       "description": "the contract address the agent is about to call"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "properties": {
      "tier": {
       "type": [
        "integer",
        "null"
       ]
      },
      "flags": {
       "type": "array",
       "items": {
        "type": "string"
       }
      },
      "score": {
       "type": [
        "integer",
        "null"
       ]
      },
      "reasons": {
       "type": "array",
       "items": {
        "type": "object",
        "properties": {
         "code": {
          "type": "string"
         },
         "flag": {
          "type": "string",
          "description": "on CRITICAL_FLAG"
         },
         "check": {
          "type": "string",
          "description": "on CHECK_FAILED"
         },
         "detail": {
          "type": "string"
         }
        }
       },
       "description": "stable machine-readable causes behind the verdict; see /v1/methodology → reason_codes"
      },
      "verdict": {
       "enum": [
        "ok",
        "caution",
        "avoid",
        "unknown"
       ],
       "type": "string",
       "description": "decision-shaped: ok = proceed, caution = hold, avoid = abort, unknown = not rated (never read as safe)"
      },
      "coverage": {
       "type": "number",
       "description": "0..1 fraction of the rubric that actually ran; meaningless to read score without it"
      },
      "freshness": {
       "type": [
        "object",
        "null"
       ],
       "description": "checked_at/age_seconds/stale. Pass max_
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/dappgrade-score-api-b5782bd2/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from dappgrade.vercel.app](https://www.zero.xyz/host/dappgrade.vercel.app/llms.txt)