{
  "openapi": "3.1.0",
  "info": {
    "title": "Greenlight AgentAI Scan API",
    "description": "Pre-action security checks for blockchain addresses, URLs, and AIS-aligned agent submissions before irreversible crypto actions. Returns machine-readable security findings with signed attestation. No wallet connection required for basic usage. Greenlight reports findings — it does not authorize or approve actions.",
    "version": "1.1.0",
    "contact": {
      "name": "Greenlight AI",
      "url": "https://greenlightagent.com",
      "email": "support@5thnode.com"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://greenlightagent.com"
    }
  },
  "servers": [
    {
      "url": "https://greenlightagent.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/v1/pre-action-checks": {
      "post": {
        "operationId": "preActionCheck",
        "summary": "Submit a structured pre-action security check",
        "description": "Primary endpoint for agent-native security analysis. Accepts AIS-aligned agent identity, intent, and action context. Returns a signed findings payload with deterministic validation, per-finding details, derived signals, and an Ed25519 attestation. Greenlight reports findings — it does not make proceed/stop decisions.",
        "tags": ["Pre-Action Checks"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PreActionCheckRequest"
              },
              "examples": {
                "swap_check": {
                  "summary": "Check a Uniswap router before swapping",
                  "value": {
                    "agent_context": {
                      "agent_id": "trading-bot-01",
                      "operator_id": "fund-alpha",
                      "wallet_address": "0xabc123...",
                      "ais_ref": "aid:agent-001"
                    },
                    "intent": {
                      "intent_type": "swap",
                      "chain": "ethereum",
                      "protocol": "uniswap_v3",
                      "amount": "1000",
                      "asset_in": "USDC",
                      "asset_out": "ETH"
                    },
                    "action_context": {
                      "target_type": "address",
                      "target": "0xdef456...",
                      "target_role": "router"
                    },
                    "policy_context": {
                      "risk_profile": "standard",
                      "max_value_usd": 1000,
                      "first_time_interaction": false
                    }
                  }
                },
                "minimal_check": {
                  "summary": "Minimal required fields only",
                  "value": {
                    "agent_context": {
                      "agent_id": "my-agent"
                    },
                    "intent": {
                      "intent_type": "transfer"
                    },
                    "action_context": {
                      "target_type": "address",
                      "target": "0xdAC17F958D2ee523a2206206994597C13D831ec7"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Findings payload returned successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreActionCheckResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (missing required fields, bad address, or unsafe URL)",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (30 requests per minute)"
          },
          "501": {
            "description": "Target type not yet implemented (e.g., tx)"
          }
        }
      }
    },
    "/v1/scans": {
      "post": {
        "operationId": "createScan",
        "summary": "Submit a security analysis",
        "description": "Submit a blockchain address or URL for security analysis. Returns a signed findings payload with outcome, signal weight, and per-finding details. Intended for consumption by agent runtimes or policy engines — Greenlight does not make proceed/stop decisions.",
        "tags": ["Scans"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScanRequest"
              },
              "examples": {
                "scan_token": {
                  "summary": "Scan a token contract before swapping",
                  "value": {
                    "target_type": "address",
                    "target": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
                    "chain": "ethereum",
                    "context": {
                      "purpose": "about-to-swap",
                      "client": "my-ai-agent/1.0"
                    }
                  }
                },
                "scan_url": {
                  "summary": "Check a dApp URL before connecting",
                  "value": {
                    "target_type": "url",
                    "target": "https://example-defi.com",
                    "context": {
                      "purpose": "pre-connect",
                      "client": "my-wallet-agent/2.0"
                    }
                  }
                },
                "scan_solana": {
                  "summary": "Check a Solana address",
                  "value": {
                    "target_type": "address",
                    "target": "DqnyyAaDioyCLkWyQVNRaVyWCpppF1P46LMEsRYCdPk9",
                    "chain": "solana"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Findings payload returned successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScanResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (bad address format, unsafe URL, or validation error)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (30 requests per minute)"
          },
          "501": {
            "description": "Target type not yet implemented (e.g., tx)"
          }
        }
      }
    },
    "/v1/scans/{scan_id}": {
      "get": {
        "operationId": "getScan",
        "summary": "Retrieve a findings payload",
        "description": "Retrieve a previously completed findings payload by its scan ID. Results expire after 24 hours.",
        "tags": ["Scans"],
        "parameters": [
          {
            "name": "scan_id",
            "in": "path",
            "required": true,
            "description": "The UUID of the scan to retrieve",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "X-Request-ID",
            "in": "header",
            "required": false,
            "description": "Optional request tracking ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Findings payload found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScanResponse"
                }
              }
            }
          },
          "404": {
            "description": "Scan not found"
          },
          "410": {
            "description": "Findings payload has expired (older than 24 hours)"
          }
        }
      }
    },
    "/.well-known/agent-service.json": {
      "get": {
        "operationId": "getAgentManifest",
        "summary": "Agent discovery manifest",
        "description": "Returns the agent-service.json manifest describing endpoints, supported targets, findings outcomes, security checks, pricing, and public keys for attestation verification.",
        "tags": ["Discovery"],
        "responses": {
          "200": {
            "description": "Agent service manifest",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PreActionCheckRequest": {
        "type": "object",
        "required": ["agent_context", "intent", "action_context"],
        "properties": {
          "agent_context": {
            "type": "object",
            "required": ["agent_id"],
            "description": "AIS-aligned agent identity. Only agent_id is required.",
            "properties": {
              "agent_id": { "type": "string", "maxLength": 255, "description": "Unique identifier of the acting agent" },
              "operator_id": { "type": "string", "maxLength": 255, "nullable": true, "description": "Human, team, or organization operating the agent" },
              "wallet_address": { "type": "string", "maxLength": 255, "nullable": true, "description": "Execution wallet for the action" },
              "ais_ref": { "type": "string", "maxLength": 255, "nullable": true, "description": "Optional AIS or AID reference for the acting agent" }
            }
          },
          "intent": {
            "type": "object",
            "required": ["intent_type"],
            "description": "Declared action intent",
            "properties": {
              "intent_type": {
                "type": "string",
                "enum": ["swap", "transfer", "approve", "lend", "add_liquidity", "stake", "bridge", "withdraw", "other"],
                "description": "Type of action the agent intends to take"
              },
              "chain": { "type": "string", "maxLength": 50, "nullable": true },
              "protocol": { "type": "string", "maxLength": 255, "nullable": true },
              "amount": { "type": "string", "maxLength": 100, "nullable": true },
              "asset_in": { "type": "string", "maxLength": 100, "nullable": true },
              "asset_out": { "type": "string", "maxLength": 100, "nullable": true }
            }
          },
          "action_context": {
            "type": "object",
            "required": ["target_type", "target"],
            "description": "The specific target being evaluated",
            "properties": {
              "target_type": { "type": "string", "enum": ["address", "url", "tx"] },
              "target": { "type": "string", "minLength": 1, "maxLength": 2048 },
              "target_role": { "type": "string", "maxLength": 100, "nullable": true, "description": "Role of the target in the transaction (e.g., router, vault, recipient)" }
            }
          },
          "policy_context": {
            "type": "object",
            "nullable": true,
            "description": "Operator-defined policy parameters. All fields optional.",
            "properties": {
              "risk_profile": { "type": "string", "enum": ["conservative", "standard", "aggressive"], "nullable": true },
              "max_value_usd": { "type": "number", "nullable": true },
              "first_time_interaction": { "type": "boolean", "nullable": true }
            }
          }
        }
      },
      "PreActionCheckResponse": {
        "type": "object",
        "properties": {
          "check_id": { "type": "string", "description": "Unique identifier for this check, prefixed with pac_" },
          "timestamp": { "type": "integer", "description": "Unix timestamp when the check was completed" },
          "elapsed_ms": { "type": "integer" },
          "request_id": { "type": "string" },
          "deterministic_validation": {
            "type": "object",
            "properties": {
              "payload_valid": { "type": "boolean" },
              "target_type_recognized": { "type": "boolean" },
              "required_fields_present": { "type": "boolean" }
            }
          },
          "submitted_context": {
            "type": "object",
            "description": "Echo of the parsed submitted context for audit logging",
            "properties": {
              "agent_id": { "type": "string" },
              "operator_id": { "type": "string", "nullable": true },
              "wallet_address": { "type": "string", "nullable": true },
              "ais_ref": { "type": "string", "nullable": true },
              "intent_type": { "type": "string" },
              "chain": { "type": "string", "nullable": true },
              "protocol": { "type": "string", "nullable": true },
              "target_type": { "type": "string" },
              "target": { "type": "string" },
              "target_role": { "type": "string", "nullable": true }
            }
          },
          "findings_summary": {
            "type": "object",
            "properties": {
              "outcome": { "type": "string", "enum": ["no_issues_detected", "issues_detected", "high_risk_signals_detected"] },
              "level": { "type": "string", "enum": ["none", "medium", "high"] },
              "issues_count": { "type": "integer" },
              "signal_weight": { "type": "integer" },
              "summary": { "type": "string" }
            }
          },
          "security_findings": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string", "description": "Machine-readable finding identifier" },
                "category": { "type": "string", "enum": ["contract_risk", "permission_risk", "phishing_risk", "address_risk", "general_risk"] },
                "severity": { "type": "string", "enum": ["critical", "high", "medium", "low", "info"] },
                "message": { "type": "string" }
              }
            }
          },
          "evidence": {
            "type": "object",
            "properties": {
              "sources": { "type": "array", "items": { "type": "string" } },
              "checks_run": { "type": "integer" }
            }
          },
          "signals": {
            "type": "object",
            "description": "Boolean signals derived from findings for easy policy engine consumption",
            "properties": {
              "contract_verified": { "type": "boolean" },
              "known_malicious": { "type": "boolean" },
              "first_time_interaction": { "type": "boolean", "nullable": true },
              "signal_weight": { "type": "integer" }
            }
          },
          "attestation": {
            "type": "object",
            "properties": {
              "type": { "type": "string", "enum": ["signed_findings_attestation"] },
              "issuer": { "type": "string" },
              "issued_at": { "type": "integer", "description": "Unix timestamp" },
              "expires_at": { "type": "integer", "description": "Unix timestamp, 15 minutes after issuance" },
              "signature": { "type": "string", "description": "ed25519:<hex_signature> over canonical JSON of the findings payload" },
              "signature_alg": { "type": "string", "enum": ["ed25519"] }
            }
          },
          "disclaimer": { "type": "string" }
        }
      },
      "ScanRequest": {
        "type": "object",
        "required": ["target_type", "target"],
        "properties": {
          "target_type": {
            "type": "string",
            "enum": ["address", "url", "tx"],
            "description": "Type of target to analyze. 'address' for blockchain addresses/contracts, 'url' for dApp/DeFi URLs, 'tx' for transaction payloads (coming soon)."
          },
          "target": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2048,
            "description": "The address or URL to analyze."
          },
          "chain": {
            "type": "string",
            "maxLength": 50,
            "description": "Optional blockchain network. Auto-detected from address format if omitted.",
            "enum": ["ethereum", "solana", "bitcoin", "polygon", "base", "arbitrum", "optimism", "bsc", "avalanche", "sui"]
          },
          "context": {
            "type": "object",
            "description": "Optional context about the request",
            "properties": {
              "purpose": {
                "type": "string",
                "maxLength": 100,
                "description": "Why the analysis is being performed (e.g., 'about-to-swap', 'pre-connect')"
              },
              "risk_tolerance": {
                "type": "string",
                "enum": ["low", "medium", "high"],
                "description": "Agent's risk tolerance level — for policy engine use"
              },
              "client": {
                "type": "string",
                "maxLength": 255,
                "description": "Identifier for the calling agent or application (e.g., 'my-agent/1.0')"
              }
            }
          },
          "payment": {
            "type": "object",
            "description": "Payment information (not required during beta)",
            "properties": {
              "method": {
                "type": "string",
                "enum": ["txhash", "api_key", "none"]
              },
              "tx_hash": { "type": "string", "maxLength": 128 },
              "payer_address": { "type": "string", "maxLength": 128 },
              "currency": { "type": "string", "maxLength": 20 },
              "amount": { "type": "string", "maxLength": 50 }
            }
          }
        }
      },
      "ScanResponse": {
        "type": "object",
        "properties": {
          "scan_id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for this scan"
          },
          "status": {
            "type": "string",
            "enum": ["queued", "running", "complete", "failed"]
          },
          "payload_valid": {
            "type": "boolean",
            "description": "Confirms the findings payload was successfully generated"
          },
          "target_type_recognized": {
            "type": "boolean",
            "description": "Confirms the target_type is a supported, recognized type"
          },
          "received_at": {
            "type": "string",
            "format": "date-time"
          },
          "completed_at": {
            "type": "string",
            "format": "date-time"
          },
          "elapsed_ms": {
            "type": "integer",
            "description": "Time taken to complete the analysis in milliseconds"
          },
          "target_type": {
            "type": "string",
            "enum": ["address", "url"]
          },
          "target": {
            "type": "string",
            "description": "The analyzed address or URL"
          },
          "chain": {
            "type": "string",
            "nullable": true,
            "description": "Blockchain network if applicable"
          },
          "findings": {
            "type": "object",
            "description": "High-level findings summary. Intended for policy engine consumption.",
            "properties": {
              "outcome": {
                "type": "string",
                "enum": ["no_issues_detected", "issues_detected", "high_risk_signals_detected"],
                "description": "no_issues_detected = no findings returned; issues_detected = one or more findings present; high_risk_signals_detected = high signal-weight threshold exceeded"
              },
              "summary": {
                "type": "string",
                "description": "Neutral description of the findings outcome for agent runtime logging"
              },
              "signal_weight": {
                "type": "integer",
                "description": "Internal weighted severity score (0-100). Provided for transparency; policy engine should define its own thresholds."
              },
              "findings_count": {
                "type": "integer",
                "description": "Number of individual findings returned"
              }
            }
          },
          "findings_detail": {
            "type": "array",
            "description": "Individual security findings. Empty array means no findings were returned.",
            "items": {
              "$ref": "#/components/schemas/Finding"
            }
          },
          "evidence": {
            "type": "object",
            "description": "Information about the checks performed",
            "properties": {
              "sources": {
                "type": "array",
                "items": { "type": "string" },
                "description": "List of security services consulted"
              },
              "checks_run": {
                "type": "integer",
                "description": "Number of security checks performed"
              },
              "expires_at": {
                "type": "string",
                "format": "date-time",
                "description": "When this findings payload expires (24 hours after completion)"
              }
            }
          },
          "attestation": {
            "$ref": "#/components/schemas/Attestation"
          },
          "result_url": {
            "type": "string",
            "description": "URL to retrieve this findings payload later"
          },
          "request_id": {
            "type": "string",
            "description": "Request tracking ID"
          }
        }
      },
      "Finding": {
        "type": "object",
        "description": "An individual security finding from a specific check source",
        "properties": {
          "code": {
            "type": "string",
            "description": "Machine-readable finding code (e.g., HONEYPOT, MALICIOUS_ADDRESS, PHISHING_SITE)"
          },
          "label": {
            "type": "string",
            "description": "Short human-readable label"
          },
          "detail": {
            "type": "string",
            "description": "Detailed explanation of the finding"
          },
          "severity": {
            "type": "string",
            "enum": ["critical", "high", "medium", "low", "info"],
            "description": "Severity level used to compute signal_weight. For policy engine use."
          }
        }
      },
      "Attestation": {
        "type": "object",
        "description": "Ed25519 cryptographic attestation confirming the integrity and issuer of the findings payload",
        "properties": {
          "issuer": {
            "type": "string",
            "description": "Always 'Greenlight AgentAI'"
          },
          "attestation_type": {
            "type": "string",
            "enum": ["signed_findings_attestation"],
            "description": "Always 'signed_findings_attestation'"
          },
          "issued_at": {
            "type": "string",
            "format": "date-time"
          },
          "signature": {
            "type": "string",
            "description": "Hex-encoded Ed25519 signature over canonical JSON of the signed findings payload"
          },
          "signature_alg": {
            "type": "string",
            "enum": ["ed25519"]
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "details": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": { "type": "string" },
                "message": { "type": "string" }
              }
            }
          },
          "request_id": { "type": "string" }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Pre-Action Checks",
      "description": "Structured agent pre-action security analysis with AIS-aligned context, intent, and signed findings"
    },
    {
      "name": "Scans",
      "description": "Lightweight scan endpoint for address and URL analysis"
    },
    {
      "name": "Discovery",
      "description": "Agent discoverability and service manifest"
    }
  ],
  "externalDocs": {
    "description": "Greenlight API Documentation",
    "url": "https://greenlightagent.com/v1/docs"
  }
}