X402ScanResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/flint-network/json-schema/flint-network-x402-scan-response-schema.json",
  "title": "X402ScanResponse",
  "x-generated": "2026-11-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/flint-network-openapi.json#/components/schemas/X402ScanResponse",
  "type": "object",
  "required": [
    "ok",
    "verdict",
    "score",
    "record_id",
    "record_url",
    "signed_record",
    "scan",
    "service_payment",
    "receipt_url",
    "receipt_page_url",
    "caller_obligation",
    "passport_binding"
  ],
  "properties": {
    "caller_obligation": {
      "$ref": "#/$defs/CallerObligation"
    },
    "step_up": {
      "type": "object",
      "description": "Present only when verdict is step_up; the remediation menu."
    },
    "passport_binding": {
      "$ref": "#/$defs/PassportBinding"
    },
    "ok": {
      "const": true
    },
    "verdict": {
      "$ref": "#/$defs/VerdictDecision"
    },
    "score": {
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "top_reasons": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "record_id": {
      "type": "string",
      "pattern": "^frv_"
    },
    "record_url": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri",
      "description": "Human-readable authorization record URL, derived by FLINT from the record ID."
    },
    "receipt_url": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri",
      "description": "Machine retrieval URL for the signed settlement-receipt envelope."
    },
    "receipt_page_url": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri",
      "description": "Human-readable Scout service-payment receipt URL."
    },
    "signed_record": {
      "type": "string"
    },
    "record": {
      "type": "object"
    },
    "scan": {
      "type": "object",
      "required": [
        "profile",
        "status",
        "transaction_intent_commitment",
        "payer_wallet_commitment",
        "external_provider_calls",
        "model_calls",
        "bounded_paid_path_executed",
        "external_provider_path_executed",
        "record_persisted",
        "record_persistence_status",
        "replay_protection_status",
        "trust_graph_ingest_attempted",
        "passport_upgraded"
      ],
      "properties": {
        "profile": {
          "const": "marketplace_basic_v1"
        },
        "status": {
          "const": "completed"
        },
        "transaction_intent_commitment": {
          "type": "string",
          "pattern": "^sha256_[a-f0-9]{64}$"
        },
        "payer_wallet_commitment": {
          "type": "string",
          "pattern": "^sha256_[a-f0-9]{64}$"
        },
        "external_provider_calls": {
          "const": 0
        },
        "model_calls": {
          "const": 0
        },
        "bounded_paid_path_executed": {
          "const": true
        },
        "external_provider_path_executed": {
          "const": false
        },
        "record_persisted": {
          "type": "boolean"
        },
        "record_persistence_status": {
          "enum": [
            "persisted",
            "unavailable"
          ]
        },
        "replay_protection_status": {
          "enum": [
            "completed",
            "unavailable"
          ]
        },
        "trust_graph_ingest_attempted": {
          "type": "boolean"
        },
        "passport_upgraded": {
          "type": "boolean"
        }
      }
    },
    "service_payment": {
      "type": "object",
      "required": [
        "purpose",
        "status",
        "distinct_from_scanned_transaction",
        "receipt_status",
        "receipt_id"
      ],
      "properties": {
        "purpose": {
          "const": "flint_transaction_scan_service_fee"
        },
        "status": {
          "const": "settled"
        },
        "method": {
          "type": "string",
          "enum": [
            "x402",
            "scout_credit"
          ],
          "description": "How this scan's service fee was paid. scout_credit means no x402 settlement or fsr_ receipt was issued for this call."
        },
        "distinct_from_scanned_transaction": {
          "const": true
        },
        "receipt_status": {
          "enum": [
            "issued",
            "unavailable",
            "disabled"
          ]
        },
        "receipt_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "credits_remaining": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Present when method is scout_credit."
        }
      }
    },
    "settlement_receipt": {
      "type": [
        "object",
        "null"
      ]
    },
    "compliance": {
      "type": "object"
    }
  },
  "$defs": {
    "CallerObligation": {
      "type": "object",
      "description": "FLINT does not hold keys and cannot stop the scanned transfer. This is the enforce-or-attest contract: the caller (or passport owner) must report what happened.",
      "required": [
        "enforcement",
        "statement",
        "report_url",
        "caller_binding_token"
      ],
      "properties": {
        "enforcement": {
          "const": "caller"
        },
        "statement": {
          "type": "string"
        },
        "report_url": {
          "type": "string",
          "format": "uri"
        },
        "caller_binding_token": {
          "type": "string",
          "description": "Lets an anonymous x402 caller report its own outcome without an account. Random, single-use per record."
        }
      }
    },
    "PassportBinding": {
      "type": "object",
      "description": "Whether a passport_id was presented on this scan and whether it was creditable. A presented passport's flint_agent_id is always carried here, even when not credited; the record's own Trust Graph merge key (agent.flint_agent_id / graph.flint_agent_id) is the passport's faid only when credited is true.",
      "required": [
        "presented"
      ],
      "properties": {
        "presented": {
          "type": "boolean"
        },
        "passport_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "flint_agent_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "credited": {
          "type": "boolean"
        },
        "binding": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "credited",
            "presented_uncredited",
            null
          ],
          "description": "How this record's identity relates to the presented passport. null when no passport reached identity verification at all."
        },
        "reason_codes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "VerdictDecision": {
      "type": "string",
      "enum": [
        "allow",
        "step_up",
        "review",
        "block"
      ]
    }
  }
}