# Models ## The ErrorResponse object ```json {"openapi":"3.1.0","info":{"title":"Crystal-Clear API","version":"1.0.0"},"components":{"schemas":{"ErrorResponse":{"properties":{"detail":{"type":"string","title":"Detail","description":"Human-readable explanation of what went wrong"}},"type":"object","required":["detail"],"title":"ErrorResponse","description":"Standard error envelope returned for 4xx/5xx responses."}}}} ``` ## The RawTxRiskRequest object ```json {"openapi":"3.1.0","info":{"title":"Crystal-Clear API","version":"1.0.0"},"components":{"schemas":{"RawTxRiskRequest":{"properties":{"raw_tx":{"type":"string","title":"Raw Tx","description":"0x-hex of the signed transaction"},"sender_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sender Address","description":"The 0x-hex address of the sender. Required if 'raw_tx' is an unsigned transaction. Ignored if 'raw_tx' is a signed transaction."},"block_tag":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Block Tag","description":"Block tag or number","default":"latest"},"latest_offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latest Offset","description":"Limit first-time checks to N latest blocks (performance control)","default":100},"from_block":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From Block","description":"Lower bound block for first-time checks"},"to_block":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To Block","description":"Upper bound block for first-time checks"},"interaction_type":{"anyOf":[{"type":"string","enum":["sender_direct","sender_transitive","contract_direct","contract_transitive"]},{"type":"null"}],"title":"Interaction Type","description":"Specific interaction type to evaluate. If omitted, all applicable types are used."}},"type":"object","required":["raw_tx"],"title":"RawTxRiskRequest","description":"Request model for raw signed transaction risk check."}}}} ``` ## The SimulationResponse object ```json {"openapi":"3.1.0","info":{"title":"Crystal-Clear API","version":"1.0.0"},"components":{"schemas":{"SimulationResponse":{"properties":{"status":{"type":"string","enum":["OK","DANGEROUS","POTENTIAL_DANGEROUS"],"title":"Status","description":"Overall risk verdict. OK = no issues found; DANGEROUS = at least one first-time or unverified contract interaction; POTENTIAL_DANGEROUS = scan data is incomplete so risk cannot be ruled out."},"interaction_status":{"anyOf":[{"additionalProperties":{"type":"string","enum":["dangerous","ok","not_checked","potential_dangerous"]},"propertyNames":{"enum":["sender_direct","sender_transitive","contract_direct","contract_transitive"]},"type":"object"},{"type":"null"}],"title":"Interaction Status","description":"Per-interaction-type risk status. Each key is an interaction type and its value is one of: ok, dangerous, potential_dangerous, or not_checked."},"details":{"items":{"$ref":"#/components/schemas/SimulationResultItem"},"type":"array","title":"Details","description":"Per-contract breakdown of risk signals for every address touched by the transaction"},"dangerous_interaction_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Dangerous Interaction Types","description":"Interaction types that triggered the DANGEROUS verdict (e.g. [\"contract_direct\"]). Null when status is OK."},"danger_reason":{"anyOf":[{"type":"string","enum":["FIRST_TIME_INTERACTION","MISSING_HISTORY","UNVERIFIED"]},{"type":"null"}],"title":"Danger Reason","description":"Root cause of a non-OK verdict. FIRST_TIME_INTERACTION = sender/contract has never called this address; MISSING_HISTORY = no historical scan data available; UNVERIFIED = contract source code is not verified on-chain."}},"type":"object","required":["status","details"],"title":"SimulationResponse","description":"Aggregated risk verdict for a simulated or decoded transaction."},"SimulationResultItem":{"properties":{"address":{"type":"string","title":"Address","description":"Checksummed Ethereum address of the touched contract"},"first_time":{"type":"boolean","title":"First Time","description":"True if the sender has never interacted with this contract across any of the checked interaction types"},"verification":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Verification","description":"Source-code verification status from Etherscan/Sourcify (e.g. {\"verification\": \"verified\", \"compiler\": \"solc\", ...}). Null when verification data is unavailable."},"depth":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Depth","description":"Call depth at which this contract was reached during trace simulation (0 = direct target, 1+ = internal/delegate call)"},"types":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"title":"Types","description":"Map of EVM call types to their frequency for this address (e.g. {\"CALL\": 2, \"DELEGATECALL\": 1})"},"interaction_first_time":{"anyOf":[{"additionalProperties":{"type":"boolean"},"type":"object"},{"type":"null"}],"title":"Interaction First Time","description":"Per-interaction-type first-time flag. Keys are interaction types (sender_direct, sender_transitive, contract_direct, contract_transitive); values are true if this is the first recorded interaction of that type."},"interaction_state":{"anyOf":[{"additionalProperties":{"type":"string","enum":["FOUND","MISSING"]},"type":"object"},{"type":"null"}],"title":"Interaction State","description":"Per-interaction-type data availability. FOUND means historical scan data exists; MISSING means no scan data is available and the result is best-effort."}},"type":"object","required":["address","first_time"],"title":"SimulationResultItem","description":"Risk analysis result for a single contract touched during the transaction."}}}} ``` ## The SimulationResultItem object ```json {"openapi":"3.1.0","info":{"title":"Crystal-Clear API","version":"1.0.0"},"components":{"schemas":{"SimulationResultItem":{"properties":{"address":{"type":"string","title":"Address","description":"Checksummed Ethereum address of the touched contract"},"first_time":{"type":"boolean","title":"First Time","description":"True if the sender has never interacted with this contract across any of the checked interaction types"},"verification":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Verification","description":"Source-code verification status from Etherscan/Sourcify (e.g. {\"verification\": \"verified\", \"compiler\": \"solc\", ...}). Null when verification data is unavailable."},"depth":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Depth","description":"Call depth at which this contract was reached during trace simulation (0 = direct target, 1+ = internal/delegate call)"},"types":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"title":"Types","description":"Map of EVM call types to their frequency for this address (e.g. {\"CALL\": 2, \"DELEGATECALL\": 1})"},"interaction_first_time":{"anyOf":[{"additionalProperties":{"type":"boolean"},"type":"object"},{"type":"null"}],"title":"Interaction First Time","description":"Per-interaction-type first-time flag. Keys are interaction types (sender_direct, sender_transitive, contract_direct, contract_transitive); values are true if this is the first recorded interaction of that type."},"interaction_state":{"anyOf":[{"additionalProperties":{"type":"string","enum":["FOUND","MISSING"]},"type":"object"},{"type":"null"}],"title":"Interaction State","description":"Per-interaction-type data availability. FOUND means historical scan data exists; MISSING means no scan data is available and the result is best-effort."}},"type":"object","required":["address","first_time"],"title":"SimulationResultItem","description":"Risk analysis result for a single contract touched during the transaction."}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://mab-xyz.gitbook.io/mab-xyz-docs/backend-api/models.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.