{
  "openapi": "3.0.0",
  "info": {
    "title": "IsoFort API",
    "description": "Public integration surface: risk scoring, pre-send verification, transaction screening and webhooks. Administrative, model and operational endpoints are intentionally not published.",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.isofort.ai"
    }
  ],
  "paths": {
    "/api/risk/address/{address}": {
      "get": {
        "operationId": "RiskScoringController_assessAddress",
        "parameters": [
          {
            "name": "address",
            "required": true,
            "in": "path",
            "description": "Blockchain address to assess",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "chain",
            "required": false,
            "in": "query",
            "description": "Blockchain (default: ETHEREUM)",
            "schema": {}
          }
        ],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get comprehensive risk assessment for an address",
        "tags": [
          "Risk Scoring Engine"
        ]
      }
    },
    "/api/risk/address/{address}/enriched": {
      "post": {
        "operationId": "RiskScoringController_assessAddressEnriched",
        "parameters": [
          {
            "name": "address",
            "required": true,
            "in": "path",
            "description": "Blockchain address to assess",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AssessEnrichedDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Risk assessment with optional Web2 identity enrichment. PII identifiers are hashed in-process and never persist.",
        "tags": [
          "Risk Scoring Engine"
        ]
      }
    },
    "/api/risk/transaction": {
      "post": {
        "operationId": "RiskScoringController_assessTransaction",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AssessTransactionDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Assess transaction risk",
        "tags": [
          "Risk Scoring Engine"
        ]
      }
    },
    "/api/risk/screen": {
      "post": {
        "operationId": "RiskScoringController_screenAddresses",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScreenAddressesDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Batch screen multiple addresses",
        "tags": [
          "Risk Scoring Engine"
        ]
      }
    },
    "/api/transactions/check": {
      "post": {
        "operationId": "TransactionsController_checkTransaction",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CheckTransactionDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Transaction analyzed successfully"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Analyze a transaction for fraud risk",
        "tags": [
          "transactions"
        ]
      }
    },
    "/api/transactions/batch": {
      "post": {
        "operationId": "TransactionsController_batchCheck",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchCheckDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Batch analysis complete"
          }
        },
        "security": [
          {
            "bearer": []
          },
          {
            "bearer": []
          }
        ],
        "summary": "Analyze multiple transactions (auth required)",
        "tags": [
          "transactions"
        ]
      }
    },
    "/api/transactions/history": {
      "get": {
        "operationId": "TransactionsController_getHistory",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          },
          {
            "bearer": []
          }
        ],
        "summary": "Get user transaction check history",
        "tags": [
          "transactions"
        ]
      }
    },
    "/api/transactions/recent": {
      "get": {
        "operationId": "TransactionsController_getRecent",
        "parameters": [
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get latest analyzed transactions",
        "tags": [
          "transactions"
        ]
      }
    },
    "/api/transactions/{id}": {
      "get": {
        "operationId": "TransactionsController_getById",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transaction check found"
          },
          "404": {
            "description": "Transaction check not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get a specific transaction check by ID",
        "tags": [
          "transactions"
        ]
      }
    },
    "/api/pre-send/verify-recipient": {
      "post": {
        "description": "Given the payer, the recipient, and (optionally) the payer address book, returns an ok / warn / block verdict — flagging recipients that look like a counterparty the payer already paid but are a different, freshly-created impostor.",
        "operationId": "PreSendController_verifyRecipient",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerifyRecipientDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Verdict for the recipient."
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Verify a recipient before sending (address-poisoning pre-send protection).",
        "tags": [
          "pre-send"
        ]
      }
    },
    "/api/api/webhooks": {
      "post": {
        "description": "Create a new webhook subscription for watchlist alerts and events",
        "operationId": "WebhooksController_createWebhook",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateWebhookDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook created successfully"
          },
          "400": {
            "description": "Invalid request body"
          },
          "401": {
            "description": "Unauthorized"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create webhook subscription",
        "tags": [
          "Webhooks"
        ]
      },
      "get": {
        "description": "Get all webhook subscriptions for the authenticated user",
        "operationId": "WebhooksController_getWebhooks",
        "parameters": [],
        "responses": {
          "200": {
            "description": "List of webhooks"
          },
          "401": {
            "description": "Unauthorized"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List user webhooks",
        "tags": [
          "Webhooks"
        ]
      }
    },
    "/api/api/webhooks/{id}": {
      "get": {
        "description": "Get detailed information about a specific webhook",
        "operationId": "WebhooksController_getWebhook",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Webhook ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook details"
          },
          "404": {
            "description": "Webhook not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get webhook details",
        "tags": [
          "Webhooks"
        ]
      },
      "put": {
        "description": "Update an existing webhook subscription",
        "operationId": "WebhooksController_updateWebhook",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Webhook ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateWebhookDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook updated"
          },
          "404": {
            "description": "Webhook not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update webhook",
        "tags": [
          "Webhooks"
        ]
      },
      "delete": {
        "description": "Remove a webhook subscription",
        "operationId": "WebhooksController_deleteWebhook",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Webhook ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook deleted"
          },
          "404": {
            "description": "Webhook not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Delete webhook",
        "tags": [
          "Webhooks"
        ]
      }
    },
    "/api/api/webhooks/{id}/test": {
      "post": {
        "description": "Send a test payload to the webhook endpoint to verify configuration",
        "operationId": "WebhooksController_testWebhook",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Webhook ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Test result"
          },
          "404": {
            "description": "Webhook not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Test webhook",
        "tags": [
          "Webhooks"
        ]
      }
    },
    "/api/api/webhooks/{id}/trigger": {
      "post": {
        "description": "Send a custom payload to the webhook endpoint",
        "operationId": "WebhooksController_triggerWebhook",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Webhook ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook triggered"
          },
          "404": {
            "description": "Webhook not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Trigger webhook manually",
        "tags": [
          "Webhooks"
        ]
      }
    },
    "/api/api/webhooks/{id}/deliveries": {
      "get": {
        "description": "Get webhook delivery history with optional status filter",
        "operationId": "WebhooksController_getDeliveryLogs",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Webhook ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "offset",
            "required": false,
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "status",
            "required": false,
            "in": "query",
            "schema": {
              "enum": [
                "PENDING",
                "SUCCESS",
                "FAILED",
                "RETRYING"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Delivery logs"
          },
          "404": {
            "description": "Webhook not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get delivery logs",
        "tags": [
          "Webhooks"
        ]
      }
    },
    "/api/api/webhooks/{id}/stats": {
      "get": {
        "description": "Get delivery statistics for a webhook",
        "operationId": "WebhooksController_getWebhookStats",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Webhook ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook statistics"
          },
          "404": {
            "description": "Webhook not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get webhook statistics",
        "tags": [
          "Webhooks"
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "AssessEnrichedDto": {
        "type": "object",
        "properties": {
          "chain": {
            "type": "string",
            "description": "Blockchain (default: ETHEREUM)"
          },
          "identifiers": {
            "type": "object",
            "description": "PII identifiers (hashed in-process, never persisted)"
          },
          "consent": {
            "type": "object",
            "description": "Consent envelope for Web2 enrichment"
          },
          "demoScenario": {
            "type": "string",
            "enum": [
              "clean",
              "medium",
              "high",
              "critical"
            ]
          }
        }
      },
      "AssessTransactionDto": {
        "type": "object",
        "properties": {
          "txHash": {
            "type": "string",
            "description": "Transaction hash",
            "example": "0x1234567890abcdef..."
          },
          "fromAddress": {
            "type": "string",
            "description": "From address",
            "example": "0x8589427373d6d84e98730d7795d8f6f8731fda16"
          },
          "toAddress": {
            "type": "string",
            "description": "To address",
            "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
          },
          "chain": {
            "type": "string",
            "description": "Blockchain (default: ETHEREUM)",
            "example": "ETHEREUM"
          },
          "value": {
            "type": "string",
            "description": "Transaction value in ETH",
            "example": "1.5"
          },
          "gasPrice": {
            "type": "string",
            "description": "Gas price in wei",
            "example": "20000000000"
          }
        },
        "required": [
          "txHash",
          "fromAddress",
          "toAddress"
        ]
      },
      "ScreenAddressesDto": {
        "type": "object",
        "properties": {
          "addresses": {
            "description": "Array of blockchain addresses to screen",
            "example": [
              "0x8589427373d6d84e98730d7795d8f6f8731fda16",
              "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "chain": {
            "type": "string",
            "description": "Blockchain (default: ETHEREUM)",
            "example": "ETHEREUM"
          }
        },
        "required": [
          "addresses"
        ]
      },
      "CheckTransactionDto": {
        "type": "object",
        "properties": {
          "txHash": {
            "type": "string",
            "description": "Transaction hash",
            "example": "0xabc123..."
          },
          "chain": {
            "type": "string",
            "enum": [
              "ETHEREUM",
              "POLYGON",
              "BSC",
              "ARBITRUM",
              "OPTIMISM",
              "BASE",
              "AVALANCHE"
            ],
            "default": "ETHEREUM"
          },
          "fromAddress": {
            "type": "string",
            "description": "Sender address (if known)"
          },
          "toAddress": {
            "type": "string",
            "description": "Receiver address (if known)"
          },
          "value": {
            "type": "string",
            "description": "Transaction value in ETH"
          },
          "gasPrice": {
            "type": "string",
            "description": "Gas price in gwei"
          },
          "input": {
            "type": "string",
            "description": "Transaction input data (for contract calls)"
          }
        },
        "required": [
          "txHash"
        ]
      },
      "BatchCheckDto": {
        "type": "object",
        "properties": {
          "transactions": {
            "description": "Array of transactions to check",
            "minItems": 1,
            "maxItems": 50,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CheckTransactionDto"
            }
          }
        },
        "required": [
          "transactions"
        ]
      },
      "VerifyRecipientDto": {
        "type": "object",
        "properties": {
          "payer": {
            "type": "string",
            "description": "The address about to send funds."
          },
          "recipient": {
            "type": "string",
            "description": "The recipient address to verify before sending."
          },
          "chain": {
            "type": "string",
            "default": "ETHEREUM"
          },
          "addressBook": {
            "description": "The payer's known address book (addresses they have paid). If omitted, the payer transfer history is fetched. Passing it keeps the check fast + private.",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "payer",
          "recipient"
        ]
      },
      "CreateWebhookDto": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "Webhook endpoint URL (must be http:// or https://; SSRF guard rejects RFC1918 / loopback / link-local at delivery time)",
            "example": "https://api.example.com/webhooks/isofort"
          },
          "events": {
            "type": "array",
            "description": "Events to subscribe to",
            "example": [
              "watchlist.activity",
              "risk.critical"
            ],
            "items": {
              "type": "string",
              "enum": [
                "watchlist.activity",
                "watchlist.high_risk",
                "watchlist.critical",
                "transaction.flagged",
                "transaction.sanctioned",
                "transaction.mixer",
                "risk.increase",
                "risk.critical",
                "case.action.file_sar",
                "case.action.freeze_address",
                "case.action.block_address",
                "case.action.close_p0",
                "kyt.verdict.issued",
                "kyt.verdict.block",
                "kyt.verdict.hold",
                "all"
              ]
            }
          },
          "name": {
            "type": "string",
            "description": "Friendly name for the webhook",
            "example": "Production Alerts"
          },
          "secret": {
            "type": "string",
            "description": "Optional secret for HMAC signature verification",
            "example": "whsec_abc123"
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether the webhook is enabled",
            "default": true
          }
        },
        "required": [
          "url",
          "events"
        ]
      },
      "UpdateWebhookDto": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "Webhook endpoint URL",
            "example": "https://api.example.com/webhooks/isofort"
          },
          "events": {
            "type": "array",
            "description": "Events to subscribe to",
            "example": [
              "watchlist.activity",
              "risk.critical"
            ],
            "items": {
              "type": "string",
              "enum": [
                "watchlist.activity",
                "watchlist.high_risk",
                "watchlist.critical",
                "transaction.flagged",
                "transaction.sanctioned",
                "transaction.mixer",
                "risk.increase",
                "risk.critical",
                "case.action.file_sar",
                "case.action.freeze_address",
                "case.action.block_address",
                "case.action.close_p0",
                "kyt.verdict.issued",
                "kyt.verdict.block",
                "kyt.verdict.hold",
                "all"
              ]
            }
          },
          "name": {
            "type": "string",
            "description": "Friendly name for the webhook",
            "example": "Production Alerts"
          },
          "secret": {
            "type": "string",
            "description": "Optional secret for HMAC signature verification",
            "example": "whsec_abc123"
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether the webhook is enabled"
          }
        }
      }
    },
    "securitySchemes": {
      "bearer": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "type": "http"
      },
      "api-key": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  },
  "tags": [
    {
      "name": "transactions",
      "description": "Transaction analysis"
    }
  ]
}