{
  "openapi": "3.1.0",
  "info": {
    "title": "Crypto AML Checker API",
    "version": "1.1.0",
    "description": "Free public checker. Heuristic scores; recent explorer pages and publicly attributed labels. No business-tier API is promised."
  },
  "servers": [
    {
      "url": "/",
      "description": "Current host: cryptorisk.site or cryptoaml.online"
    }
  ],
  "paths": {
    "/v1/check": {
      "post": {
        "summary": "Free wallet check; 20 requests/IP/minute",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "address"
                ],
                "additionalProperties": false,
                "properties": {
                  "chain": {
                    "type": "string",
                    "description": "BTC, ETH, TRON or empty/omitted for auto-detect"
                  },
                  "address": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Risk heuristic and coverage, not a safety guarantee",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Report"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                }
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                }
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                }
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request/address/checksum",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Endpoint missing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "description": "20 checks/IP/minute; wait Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "504": {
            "description": "Timeout",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/v1/stats": {
      "get": {
        "summary": "Distinct (chain,address) count",
        "responses": {
          "200": {
            "description": "Published database statistics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "total"
                  ],
                  "properties": {
                    "total": {
                      "type": "integer"
                    },
                    "last_updated": {
                      "type": "string",
                      "format": "date"
                    }
                  }
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/v1/sources": {
      "get": {
        "summary": "Source status, with cached independent oracle probe",
        "parameters": [
          {
            "name": "chain",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "BTC",
                "ETH",
                "TRON"
              ],
              "default": "ETH"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Availability and last complete imports",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "chain",
                    "checked_at",
                    "sources"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok",
                        "degraded"
                      ]
                    },
                    "chain": {
                      "type": "string"
                    },
                    "checked_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "sources": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "source",
                          "status",
                          "entries"
                        ],
                        "properties": {
                          "source": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "checked",
                              "unavailable",
                              "stale",
                              "not_applicable",
                              "disabled",
                              "skipped"
                            ]
                          },
                          "entries": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "last_success": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "last_attempt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "last_finished": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request/address/checksum",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "summary": "Readiness including all enabled applicable sources and ETH/TRON issuer data",
        "parameters": [
          {
            "name": "scope",
            "in": "query",
            "required": false,
            "description": "core limits the status code and overall status to database, cache and configuration; every check is still listed",
            "schema": {
              "type": "string",
              "enum": [
                "core"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "checks": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "object",
                        "properties": {
                          "status": {
                            "type": "string"
                          },
                          "detail": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "503": {
            "description": "Degraded infrastructure, sources or missing ETH explorer configuration",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "checks": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "object",
                        "properties": {
                          "status": {
                            "type": "string"
                          },
                          "detail": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error",
          "code",
          "request_id"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "hint": {
            "type": "string"
          }
        }
      },
      "Report": {
        "type": "object",
        "required": [
          "chain",
          "address",
          "score",
          "level",
          "analysis_status",
          "analyzed",
          "sources",
          "analyzed_at",
          "database_version",
          "cached"
        ],
        "properties": {
          "chain": {
            "type": "string",
            "enum": [
              "BTC",
              "ETH",
              "TRON"
            ]
          },
          "address": {
            "type": "string"
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "level": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high",
              "critical"
            ]
          },
          "analysis_status": {
            "type": "string",
            "enum": [
              "match_found",
              "exposure_found",
              "verified_clean",
              "partially_analyzed",
              "unable_to_analyze"
            ]
          },
          "matches": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "object",
              "properties": {
                "source": {
                  "type": "string"
                },
                "category": {
                  "type": "string",
                  "enum": [
                    "sanction",
                    "ransomware",
                    "scam",
                    "issuer_frozen"
                  ]
                },
                "confidence": {
                  "type": "string",
                  "enum": [
                    "high",
                    "medium",
                    "low"
                  ]
                },
                "scope": {
                  "type": "string",
                  "enum": [
                    "BTC",
                    "ETH",
                    "TRON",
                    "EVM"
                  ]
                },
                "currency_hint": {
                  "type": "string"
                },
                "metadata": {
                  "type": "object",
                  "additionalProperties": true
                },
                "first_seen": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                },
                "last_seen": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                }
              }
            }
          },
          "analyzed": {
            "type": "object",
            "properties": {
              "available": {
                "type": "boolean"
              },
              "reason": {
                "type": "string"
              },
              "tx_count": {
                "type": "integer"
              },
              "counterparty_count": {
                "type": "integer"
              },
              "limited": {
                "type": "boolean"
              },
              "assets": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "properties": {
                    "asset": {
                      "type": "string"
                    },
                    "decimals": {
                      "type": "integer"
                    },
                    "total_raw": {
                      "type": "string",
                      "pattern": "^[0-9]+$"
                    },
                    "exposed_raw": {
                      "type": "string",
                      "pattern": "^[0-9]+$"
                    },
                    "exposure_percent": {
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    },
                    "ambiguous": {
                      "type": "boolean"
                    }
                  }
                }
              },
              "exposure_percent": {
                "type": "number",
                "description": "Maximum of asset percentages, never a sum of raw units."
              },
              "hop_matches": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "hop2_intermediaries_checked": {
                "type": "integer"
              },
              "hop2_intermediaries_succeeded": {
                "type": "integer"
              },
              "hop2_counterparty_count": {
                "type": "integer"
              },
              "hop2_exposure_ratio": {
                "type": "number"
              },
              "window": {
                "type": "string"
              }
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "source",
                "status",
                "entries"
              ],
              "properties": {
                "source": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "checked",
                    "unavailable",
                    "stale",
                    "not_applicable",
                    "disabled",
                    "skipped"
                  ]
                },
                "entries": {
                  "type": "integer",
                  "minimum": 0
                },
                "last_success": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                },
                "last_attempt": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                },
                "last_finished": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                }
              }
            }
          },
          "analyzed_at": {
            "type": "string",
            "format": "date-time"
          },
          "database_version": {
            "type": "integer"
          },
          "cached": {
            "type": "boolean"
          }
        }
      },
      "Source": {
        "type": "object",
        "required": [
          "source",
          "status",
          "entries"
        ],
        "properties": {
          "source": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "checked",
              "unavailable",
              "stale",
              "not_applicable",
              "disabled",
              "skipped"
            ]
          },
          "entries": {
            "type": "integer",
            "minimum": 0
          },
          "last_success": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "last_attempt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "last_finished": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "Match": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "enum": [
              "sanction",
              "ransomware",
              "scam",
              "issuer_frozen"
            ]
          },
          "confidence": {
            "type": "string",
            "enum": [
              "high",
              "medium",
              "low"
            ]
          },
          "scope": {
            "type": "string",
            "enum": [
              "BTC",
              "ETH",
              "TRON",
              "EVM"
            ]
          },
          "currency_hint": {
            "type": "string"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "first_seen": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "last_seen": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "AssetExposure": {
        "type": "object",
        "properties": {
          "asset": {
            "type": "string"
          },
          "decimals": {
            "type": "integer"
          },
          "total_raw": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "exposed_raw": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "exposure_percent": {
            "type": "number",
            "minimum": 0,
            "maximum": 100
          },
          "ambiguous": {
            "type": "boolean"
          }
        }
      }
    }
  }
}