{
  "openapi": "3.1.0",
  "info": {
    "title": "AgentShield API",
    "version": "1.0.0",
    "description": "Wallet security infrastructure for autonomous AI agents. Prevents drain attacks through contract allowlisting and real-time monitoring.",
    "contact": {
      "email": "security@agentshield.io"
    }
  },
  "servers": [
    {
      "url": "https://agentshield.win",
      "description": "Production"
    }
  ],
  "paths": {
    "/verify": {
      "get": {
        "operationId": "verifyContract",
        "summary": "Verify contract safety",
        "description": "Check if a smart contract is safe to interact with. Returns safety score, risk flags, and recommendation. Requires x402 payment of $0.001 USDC.",
        "parameters": [
          {
            "name": "contract",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^0x[0-9a-fA-F]{40}$"
            },
            "description": "Contract address to verify",
            "example": "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D"
          },
          {
            "name": "chain",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "ethereum",
                "base",
                "polygon",
                "arbitrum"
              ],
              "default": "ethereum"
            }
          }
        ],
        "security": [
          {
            "x402": []
          }
        ],
        "responses": {
          "200": {
            "description": "Verification result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "address": {
                      "type": "string"
                    },
                    "chain": {
                      "type": "string"
                    },
                    "safe": {
                      "type": "boolean"
                    },
                    "score": {
                      "type": "number",
                      "minimum": 0,
                      "maximum": 1
                    },
                    "verdict": {
                      "type": "string",
                      "enum": [
                        "APPROVED",
                        "BLOCKED",
                        "UNKNOWN"
                      ]
                    },
                    "risk_level": {
                      "type": "string",
                      "enum": [
                        "LOW",
                        "MEDIUM",
                        "HIGH",
                        "CRITICAL"
                      ]
                    },
                    "flags": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "name": {
                      "type": "string",
                      "nullable": true
                    },
                    "protocol": {
                      "type": "string",
                      "nullable": true
                    },
                    "recommendation": {
                      "type": "string"
                    },
                    "query_id": {
                      "type": "string"
                    },
                    "verified_at": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required — x402 payment instructions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "x402Version": {
                      "type": "integer"
                    },
                    "accepts": {
                      "type": "array"
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/monitor": {
      "post": {
        "operationId": "registerMonitor",
        "summary": "Register wallet for drain monitoring",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "wallet",
                  "callback_url"
                ],
                "properties": {
                  "wallet": {
                    "type": "string",
                    "description": "Wallet address to monitor"
                  },
                  "callback_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "URL to POST drain alerts to"
                  },
                  "threshold_pct": {
                    "type": "number",
                    "default": 20,
                    "description": "Balance drop % that triggers alert"
                  },
                  "agent_id": {
                    "type": "string",
                    "description": "Your agent identifier — used to freeze all linked wallets"
                  },
                  "chains": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "default": [
                      "ethereum",
                      "base"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Monitor registered successfully"
          }
        }
      }
    },
    "/freeze": {
      "post": {
        "operationId": "emergencyFreeze",
        "summary": "Emergency freeze all agent wallets",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "wallet": {
                    "type": "string"
                  },
                  "agent_id": {
                    "type": "string"
                  },
                  "reason": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wallets frozen"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "X-PAYMENT",
        "description": "x402 payment authorization header. If missing, server returns 402 with payment instructions."
      }
    }
  }
}