{ "openapi": "3.1.0", "info": { "title": "AI DECISIONS Compliance API", "description": "Address risk screening for crypto compliance: sanctions hits, mixer exposure, AI-agent detection and a population-calibrated risk tier per address across Ethereum, Bitcoin, Tron, Base, Arbitrum and Gnosis. Every label resolves to a primary public source.\n\nAuthentication: `X-API-Key` header. Keys and tiers: https://aidecisions.ai/pricing. Human-readable docs: https://aidecisions.ai/docs. Try without an account: https://aidecisions.ai/check. Methodology: https://ssrn.com/abstract=7366202.", "version": "0.1.0", "contact": { "name": "AI DECISIONS", "url": "https://aidecisions.ai" } }, "servers": [ { "url": "https://api.aidecisions.ai", "description": "Production" } ], "tags": [ { "name": "Compliance", "description": "Transaction risk scoring and AI-agent detection for crypto exchanges and EMI license holders. Per-check pricing available." } ], "paths": { "/compliance/agent-detection": { "post": { "tags": [ "Compliance" ], "summary": "Detect AI-agent transaction patterns", "description": "Classify whether a sequence of transactions indicates AI-agent or human behavior. Analyzes timing regularity, amount variance, weekday distribution, and topology of sender/receiver addresses. Returns agent probability, classification label, and behavioral indicators.", "operationId": "agent_detection_compliance_agent_detection_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDetectionRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDetectionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/compliance/export": { "get": { "tags": [ "Compliance" ], "summary": "Export compliance checks as CSV or JSON", "operationId": "export_checks_compliance_export_get", "parameters": [ { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(csv|json)$", "default": "csv", "title": "Format" } }, { "name": "check_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(transaction|agent)$" }, { "type": "null" } ], "title": "Check Type" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Date From" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Date To" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Export Checks Compliance Export Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/compliance/history": { "get": { "tags": [ "Compliance" ], "summary": "List compliance check history", "operationId": "list_checks_compliance_history_get", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Page Size" } }, { "name": "check_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(transaction|agent)$" }, { "type": "null" } ], "title": "Check Type" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Date From" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Date To" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Checks Compliance History Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/compliance/transaction-check": { "post": { "tags": [ "Compliance" ], "summary": "Score transaction compliance risk", "description": "Analyze a single transaction for AML/CFT compliance risk. Combines rule-based checks (jurisdiction, structuring thresholds) with optional graph-centrality and GNN anomaly scores. Sender/receiver that are on-chain addresses are additionally run through the sanctions/mixer screening pipeline — a sanctioned address in the pair is an immediate high risk with block_and_review. Returns a composite risk score, risk level, contributing factors, and a recommended action (proceed / review / block).", "operationId": "transaction_check_compliance_transaction_check_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionCheckRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionCheckResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/health": { "get": { "tags": [ "System" ], "summary": "Health check", "operationId": "health_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Response Health Health Get" } } } } }, "security": [] } }, "/investigate/chains": { "get": { "tags": [ "Investigation", "investigation" ], "summary": "Served chains and whether a transaction history is available", "description": "The six chains the screening pipeline serves; `history_available` says whether /investigate fetches a transaction list for the chain in this deployment.", "operationId": "list_chains_investigate_chains_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChainCapabilities" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/investigate/{chain}/address/{address}": { "get": { "tags": [ "Investigation", "investigation" ], "summary": "Investigate a blockchain address", "description": "Full investigation: screening verdict (same pipeline as POST /v1/screen), transactions, graph, agent detection.", "operationId": "investigate_address_investigate__chain__address__address__get", "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string", "title": "Chain" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "depth", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 3, "minimum": 1, "description": "Graph exploration depth (hops)", "default": 1, "title": "Depth" }, "description": "Graph exploration depth (hops)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "minimum": 10, "description": "Max transactions to fetch", "default": 500, "title": "Limit" }, "description": "Max transactions to fetch" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigationResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/investigate/{chain}/address/{address}/export": { "get": { "tags": [ "Investigation", "investigation" ], "summary": "Export investigation report", "description": "Export as PDF, CSV, or JSON.", "operationId": "export_investigation_investigate__chain__address__address__export_get", "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string", "title": "Chain" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "format", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ExportFormat", "default": "pdf" } }, { "name": "depth", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 3, "minimum": 1, "default": 1, "title": "Depth" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "minimum": 10, "default": 500, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/tiers": { "get": { "tags": [ "Tiers" ], "summary": "Get tier definitions", "description": "Return all tier definitions (features, limits, SLA).", "operationId": "get_tiers_tiers_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Get Tiers Tiers Get" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/ai-agents/labels/{address}": { "get": { "tags": [ "AI Agents" ], "summary": "Get Labels", "description": "Return all known labels for an address.", "operationId": "get_labels_v1_ai_agents_labels__address__get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Labels V1 Ai Agents Labels Address Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/ai-agents/score": { "post": { "tags": [ "AI Agents" ], "summary": "Score Address", "description": "Classify an address as AI agent, human, or unknown.\n\nThis endpoint combines:\n1. Known-label lookup (exact match in curated labels)\n2. Heuristic scoring (until GNN model is deployed)\n\nThe GraphSAGE model trained in Sprint 46 will replace the heuristic once\ntraining completes on A100.", "operationId": "score_address_v1_ai_agents_score_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/ai-agents/similar": { "post": { "tags": [ "AI Agents" ], "summary": "Find Similar", "description": "CLOSED (Sprint 64 T3.4) — this legacy stub answered a HARDCODED\nsimilarity of 0.85 for every neighbour, which reads as a real\nmeasurement. The real behavioural similarity lives at\nPOST /v1/similar/{chain}/{address} (faiss over the joint embedding\nspace, ENTERPRISE `similar` feature). Skeleton rule: unimplemented\nendpoints answer 501, never fabricated numbers.", "operationId": "find_similar_v1_ai_agents_similar_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimilarRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimilarResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/screen/{chain}/{address}": { "post": { "tags": [ "Screening", "Screening" ], "summary": "Screen address", "description": "Real-time address screening: risk score, entity category, VASP match, mixer exposure, sanctions hit, cross-chain bridge exposure, top contributing features. Sprint 60 A.1 returns 200 OK with a fully-typed response; enrichment blocks are populated incrementally as Tracks B/C/D/E/G land — blocks return null while their providers are still stubs.", "operationId": "screen_address_v1_screen__chain___address__post", "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/src__api__schemas__screen__Chain" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256, "title": "Address" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ScreenRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreenResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/similar": { "get": { "tags": [ "Similar" ], "summary": "Get Similar", "description": "Return top-K cosine-nearest neighbours on the Sprint 46 GNN\npenultimate embeddings.\n\nExcludes the query address itself. Returns HTTP 404 when the address\nis not in the pre-loaded embedding set, HTTP 503 when the matrix\nhas not been built (artefact missing on disk).", "operationId": "get_similar_v1_similar_get", "parameters": [ { "name": "address", "in": "query", "required": true, "schema": { "type": "string", "description": "Query address (EVM hex or BTC base58/bech32)", "title": "Address" }, "description": "Query address (EVM hex or BTC base58/bech32)" }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "description": "Chain identifier", "default": "ethereum", "title": "Chain" }, "description": "Chain identifier" }, { "name": "top_k", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of neighbours to return", "default": 10, "title": "Top K" }, "description": "Number of neighbours to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimilarResponseSchema" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/similar/{chain}/{address}": { "post": { "tags": [ "Similar" ], "summary": "Post Similar", "description": "Real guilt-by-association: top-K labelled behavioural neighbours.\n\nServed by the on-request VM's faiss index over joint v5 embeddings. Each\nneighbour carries its OWN chain (the index is joint — a neighbour may be on\nthe other chain) and any known label (\"OFAC-SDN\", entity name/category).\n\nTwo modes over the same index (see FaissSimilarStore.similar): raw\n(default) = the frozen S3.a evidence surface; labelled = the product\nsurface the Maltego T2 transform consumes (61.6.b) and the 61.3.b anchor\ncriterion measures.\n\n503 when the index is not wired (laptop / Lambda — idle=$0, S0 topology).\n404 when the address is not a node in the graph (no embedding).", "operationId": "post_similar_v1_similar__chain___address__post", "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/src__api__schemas__screen__Chain" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256, "title": "Address" } }, { "name": "top_k", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 15, "title": "Top K" } }, { "name": "labelled", "in": "query", "required": false, "schema": { "type": "boolean", "description": "true → nearest KNOWN entities: over-fetch deep, drop unlabelled, return the top_k nearest that carry a label (guilt-by-association surface; labelled peers sit at rank ~200, far past any raw top_k)", "default": false, "title": "Labelled" }, "description": "true → nearest KNOWN entities: over-fetch deep, drop unlabelled, return the top_k nearest that carry a label (guilt-by-association surface; labelled peers sit at rank ~200, far past any raw top_k)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelledSimilarResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "AgentDetectionRequest": { "properties": { "transactions": { "items": { "$ref": "#/components/schemas/TransactionRecord" }, "type": "array", "maxItems": 10000, "minItems": 1, "title": "Transactions", "description": "List of transaction records" } }, "type": "object", "required": [ "transactions" ], "title": "AgentDetectionRequest", "examples": [ { "transactions": [ { "amount": 500.0, "receiver": "0xD4E5F6", "sender": "0xA1B2C3", "timestamp": "2026-01-15T10:00:00" }, { "amount": 500.0, "receiver": "0xD4E5F6", "sender": "0xA1B2C3", "timestamp": "2026-01-15T10:10:00" }, { "amount": 500.0, "receiver": "0xD4E5F6", "sender": "0xA1B2C3", "timestamp": "2026-01-15T10:20:00" } ] } ] }, "AgentDetectionResponse": { "properties": { "agent_probability": { "type": "number", "title": "Agent Probability" }, "classification": { "type": "string", "title": "Classification" }, "indicators": { "items": { "$ref": "#/components/schemas/AgentIndicator" }, "type": "array", "title": "Indicators" }, "transaction_count": { "type": "integer", "title": "Transaction Count" }, "interval_data": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Interval Data" }, "amount_data": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Amount Data" }, "weekday_counts": { "anyOf": [ { "additionalProperties": { "type": "integer" }, "type": "object" }, { "type": "null" } ], "title": "Weekday Counts" }, "topology": { "anyOf": [ { "$ref": "#/components/schemas/TopologyGraph" }, { "type": "null" } ] } }, "type": "object", "required": [ "agent_probability", "classification", "indicators", "transaction_count" ], "title": "AgentDetectionResponse", "examples": [ { "agent_probability": 0.85, "amount_data": [ 500.0, 500.0, 500.0 ], "classification": "likely_agent", "indicators": [ { "detail": "Transaction intervals have very low variance (CV=0.02)", "indicator": "timing_regularity", "score": 0.95 }, { "detail": "All transactions have identical amounts", "indicator": "amount_uniformity", "score": 1.0 } ], "interval_data": [ 600.0, 600.0 ], "topology": { "edges": [ { "amount": 1500.0, "count": 3, "source": "0xA1B2C3", "target": "0xD4E5F6" } ], "nodes": [ { "id": "0xA1B2C3", "risk": 0.85, "type": "wallet" }, { "id": "0xD4E5F6", "risk": 0.1, "type": "wallet" } ] }, "transaction_count": 3, "weekday_counts": { "Fri": 0, "Mon": 0, "Sat": 0, "Sun": 0, "Thu": 3, "Tue": 0, "Wed": 0 } } ] }, "AgentIndicator": { "properties": { "indicator": { "type": "string", "maxLength": 128, "title": "Indicator" }, "detail": { "type": "string", "maxLength": 512, "title": "Detail" }, "score": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Score", "default": 0.0 } }, "type": "object", "required": [ "indicator", "detail" ], "title": "AgentIndicator", "description": "A single behavioral indicator from agent detection." }, "BridgeExposure": { "properties": { "bridges": { "items": { "type": "string" }, "type": "array", "title": "Bridges" }, "destination_chain": { "anyOf": [ { "$ref": "#/components/schemas/Chain-Output" }, { "type": "null" } ] }, "last_seen": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Seen" } }, "type": "object", "title": "BridgeExposure", "description": "Cross-chain bridge counterparty exposure (Sprint 60 Track G).\n\nCounterparty match against the 9-bridge registry (Ronin, Multichain,\nWormhole, WBTC, Stargate, Synapse, Celer, Hop, LayerZero). When a\ncross-chain trace is available, destination_chain points to the\nother side of the hop." }, "Chain-Output": { "type": "string", "enum": [ "ethereum", "tron", "bitcoin", "bsc", "polygon", "arbitrum", "base", "gnosis" ], "title": "Chain", "description": "Chains supported by the screening API.\n\nSprint 59: ETH + Tron graph-backed. Sprint 60 adds BSC, Polygon,\nArbitrum, BTC (per docs/product-targets-exchange-first.md Sprint 60\nmapping). The enum is declared here at full scope so the API surface\ndoes not change between sprints — only the implementation fills in." }, "ChainCapabilities": { "properties": { "chains": { "items": { "$ref": "#/components/schemas/ChainCapability" }, "type": "array", "title": "Chains" } }, "type": "object", "required": [ "chains" ], "title": "ChainCapabilities" }, "ChainCapability": { "properties": { "chain": { "type": "string", "title": "Chain" }, "native_symbol": { "type": "string", "title": "Native Symbol" }, "history_available": { "type": "boolean", "title": "History Available" }, "transactions_source": { "type": "string", "title": "Transactions Source" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note" } }, "type": "object", "required": [ "chain", "native_symbol", "history_available", "transactions_source" ], "title": "ChainCapability" }, "ExportFormat": { "type": "string", "enum": [ "pdf", "csv", "json" ], "title": "ExportFormat" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "InvestigationResult": { "properties": { "address": { "type": "string", "title": "Address" }, "chain": { "type": "string", "title": "Chain" }, "risk": { "$ref": "#/components/schemas/RiskScore" }, "screen": { "anyOf": [ { "$ref": "#/components/schemas/ScreenVerdict" }, { "type": "null" } ], "description": "Screening pipeline verdict; null when the pipeline failed" }, "screen_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Screen Error", "description": "Why `screen` is null, if it is" }, "transaction_count": { "type": "integer", "title": "Transaction Count" }, "first_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Seen" }, "last_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Seen" }, "native_symbol": { "type": "string", "title": "Native Symbol", "default": "" }, "total_received": { "type": "number", "title": "Total Received", "description": "Native-asset volume received", "default": 0 }, "total_sent": { "type": "number", "title": "Total Sent", "description": "Native-asset volume sent", "default": 0 }, "token_totals": { "items": { "$ref": "#/components/schemas/TokenTotal" }, "type": "array", "title": "Token Totals", "description": "Per-token transfer counts and volumes" }, "unique_counterparties": { "type": "integer", "title": "Unique Counterparties", "default": 0 }, "known_entity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Known Entity", "description": "Exchange name, mixer, etc. if known" }, "agent_indicators": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Agent Indicators", "default": [] }, "topology": { "additionalProperties": true, "type": "object", "title": "Topology", "default": { "nodes": [], "edges": [] } }, "transactions": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Transactions", "default": [] }, "transactions_source": { "type": "string", "title": "Transactions Source", "description": "etherscan_v2 / tronscan / blockstream / screening_only", "default": "" }, "chain_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Chain Note", "description": "Honest caption for screening-only chains" }, "investigation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Investigation Id" }, "generated_at": { "type": "string", "title": "Generated At", "default": "" } }, "type": "object", "required": [ "address", "chain", "risk", "transaction_count" ], "title": "InvestigationResult" }, "LabelledNeighbour": { "properties": { "address": { "type": "string", "title": "Address" }, "chain": { "type": "string", "title": "Chain" }, "similarity": { "type": "number", "maximum": 1.0, "minimum": -1.0, "title": "Similarity" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Url" } }, "type": "object", "required": [ "address", "chain", "similarity" ], "title": "LabelledNeighbour", "description": "One neighbour from the real index, with its own chain + known label." }, "LabelledSimilarResponse": { "properties": { "query": { "type": "string", "title": "Query" }, "chain": { "type": "string", "title": "Chain" }, "neighbours": { "items": { "$ref": "#/components/schemas/LabelledNeighbour" }, "type": "array", "title": "Neighbours" } }, "type": "object", "required": [ "query", "chain", "neighbours" ], "title": "LabelledSimilarResponse", "description": "Shape of POST /v1/similar/{chain}/{address} (real faiss path)." }, "MixerExposure": { "properties": { "direct": { "type": "boolean", "title": "Direct", "default": false }, "indirect_hops": { "anyOf": [ { "type": "integer", "maximum": 20.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Indirect Hops" }, "taint_score": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Taint Score" }, "mixer_names": { "items": { "type": "string" }, "type": "array", "title": "Mixer Names" }, "output_side": { "type": "boolean", "title": "Output Side", "default": false }, "hours_since_mixer": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Hours Since Mixer" } }, "type": "object", "title": "MixerExposure", "description": "Direct + indirect + output-side mixer provenance (Sprint 60 Track D.1 + D.2 + D.4)." }, "RiskFactor": { "properties": { "rule": { "type": "string", "maxLength": 128, "title": "Rule" }, "detail": { "type": "string", "maxLength": 512, "title": "Detail" }, "severity": { "type": "string", "maxLength": 32, "title": "Severity" } }, "type": "object", "required": [ "rule", "detail", "severity" ], "title": "RiskFactor", "description": "A single risk factor from rule-based scoring." }, "RiskScore": { "properties": { "overall": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Overall", "description": "Secondary heuristic composite 0-1 (agent probability + structural). NOT the verdict — see `screen`." }, "agent_probability": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Agent Probability", "description": "AI-agent detection probability" }, "structural_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Structural Score", "description": "Structural analysis score" }, "label": { "type": "string", "title": "Label", "description": "Verdict label: derived from the screening risk tier when the pipeline answered (critical / high_risk / medium_risk / low_risk); heuristic fallback only when `screen` is null." } }, "type": "object", "required": [ "overall", "label" ], "title": "RiskScore" }, "ScoreRequest": { "properties": { "address": { "type": "string", "title": "Address", "description": "Ethereum address (0x-prefixed hex)" } }, "type": "object", "required": [ "address" ], "title": "ScoreRequest" }, "ScoreResponse": { "properties": { "address": { "type": "string", "title": "Address" }, "classification": { "type": "string", "title": "Classification", "description": "'ai_agent' | 'human' | 'unknown'" }, "confidence": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Confidence" }, "model_version": { "type": "string", "title": "Model Version" }, "labels": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Labels" }, "reasoning": { "type": "string", "title": "Reasoning" } }, "type": "object", "required": [ "address", "classification", "confidence", "model_version", "reasoning" ], "title": "ScoreResponse" }, "ScreenRequest": { "properties": { "include_topology": { "type": "boolean", "title": "Include Topology", "default": false }, "include_counterparties": { "type": "boolean", "title": "Include Counterparties", "default": false } }, "additionalProperties": false, "type": "object", "title": "ScreenRequest", "description": "Optional request body; current skeleton accepts empty body too." }, "ScreenResponse": { "properties": { "address": { "type": "string", "maxLength": 256, "title": "Address" }, "chain": { "$ref": "#/components/schemas/Chain-Output" }, "risk_score": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Risk Score" }, "confidence": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Confidence" }, "category": { "type": "string", "enum": [ "vasp", "mixer", "defi_protocol", "personal", "exchange_depositor", "ai_agent", "unknown" ], "title": "Category" }, "risk_tier": { "type": "integer", "enum": [ 1, 2, 3, 4, 5 ], "title": "Risk Tier" }, "vasp": { "anyOf": [ { "$ref": "#/components/schemas/VaspMatch" }, { "type": "null" } ] }, "mixer_exposure": { "anyOf": [ { "$ref": "#/components/schemas/MixerExposure" }, { "type": "null" } ] }, "bridge_exposure": { "anyOf": [ { "$ref": "#/components/schemas/BridgeExposure" }, { "type": "null" } ] }, "sanctions_hit": { "type": "boolean", "title": "Sanctions Hit", "default": false }, "flags": { "items": { "type": "string" }, "type": "array", "title": "Flags" }, "top_features": { "items": { "type": "string" }, "type": "array", "maxItems": 5, "title": "Top Features" }, "model_version": { "type": "string", "maxLength": 64, "title": "Model Version" }, "scored_at": { "type": "string", "format": "date-time", "title": "Scored At" } }, "type": "object", "required": [ "address", "chain", "risk_score", "category", "risk_tier", "model_version", "scored_at" ], "title": "ScreenResponse", "description": "Response schema for POST /v1/screen/{chain}/{address}.\n\nSprint 60 Track A.1 ships the architecture: build pipeline returns\n200 OK with fully-typed response. Each enrichment block (vasp,\nmixer_exposure, sanctions_hit, bridge_exposure) is populated by its\nown provider; providers default to null-returning stubs which\nTracks E / D / G replace with real lookups.\n\n`top_features` carries the top-5 input feature names by absolute\ncontribution magnitude (per Sprint 60 contract A.1) — empty list\nwhen the detector provider stub is in place." }, "ScreenVerdict": { "properties": { "risk_tier": { "type": "integer", "maximum": 5.0, "minimum": 1.0, "title": "Risk Tier" }, "tier_label": { "type": "string", "title": "Tier Label" }, "category": { "type": "string", "title": "Category" }, "sanctions_hit": { "type": "boolean", "title": "Sanctions Hit" }, "mixer_direct": { "type": "boolean", "title": "Mixer Direct" }, "flags": { "items": { "type": "string" }, "type": "array", "title": "Flags", "default": [] }, "top_features": { "items": { "type": "string" }, "type": "array", "title": "Top Features", "default": [] }, "risk_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Risk Score", "description": "Neural score; null = detector degraded" }, "model_version": { "type": "string", "title": "Model Version" }, "scored_at": { "type": "string", "title": "Scored At" }, "entity_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Entity Name" }, "entity_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Entity Source" }, "entity_source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Entity Source Url" } }, "type": "object", "required": [ "risk_tier", "tier_label", "category", "sanctions_hit", "mixer_direct", "model_version", "scored_at" ], "title": "ScreenVerdict", "description": "The /v1/screen verdict for the investigated address (contract 2.2b)." }, "SimilarNeighbour": { "properties": { "address": { "type": "string", "title": "Address" }, "similarity": { "type": "number", "maximum": 1.0, "minimum": -1.0, "title": "Similarity" } }, "type": "object", "required": [ "address", "similarity" ], "title": "SimilarNeighbour", "description": "Single neighbour in the similarity response." }, "SimilarRequest": { "properties": { "address": { "type": "string", "title": "Address" }, "k": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "K", "default": 10 } }, "type": "object", "required": [ "address" ], "title": "SimilarRequest" }, "SimilarResponse": { "properties": { "query_address": { "type": "string", "title": "Query Address" }, "neighbors": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Neighbors" }, "model_version": { "type": "string", "title": "Model Version" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note" } }, "type": "object", "required": [ "query_address", "neighbors", "model_version" ], "title": "SimilarResponse" }, "SimilarResponseSchema": { "properties": { "query": { "type": "string", "title": "Query" }, "chain": { "type": "string", "title": "Chain" }, "neighbours": { "items": { "$ref": "#/components/schemas/SimilarNeighbour" }, "type": "array", "title": "Neighbours" } }, "type": "object", "required": [ "query", "chain", "neighbours" ], "title": "SimilarResponseSchema", "description": "Shape of `/v1/similar` response — stable across embedding backends." }, "TokenTotal": { "properties": { "token": { "type": "string", "title": "Token" }, "transfers": { "type": "integer", "title": "Transfers" }, "received": { "type": "number", "title": "Received" }, "sent": { "type": "number", "title": "Sent" } }, "type": "object", "required": [ "token", "transfers", "received", "sent" ], "title": "TokenTotal" }, "TopologyEdge": { "properties": { "source": { "type": "string", "title": "Source" }, "target": { "type": "string", "title": "Target" }, "amount": { "type": "number", "title": "Amount" }, "count": { "type": "integer", "title": "Count" } }, "type": "object", "required": [ "source", "target", "amount", "count" ], "title": "TopologyEdge" }, "TopologyGraph": { "properties": { "nodes": { "items": { "$ref": "#/components/schemas/TopologyNode" }, "type": "array", "title": "Nodes", "default": [] }, "edges": { "items": { "$ref": "#/components/schemas/TopologyEdge" }, "type": "array", "title": "Edges", "default": [] } }, "type": "object", "title": "TopologyGraph" }, "TopologyNode": { "properties": { "id": { "type": "string", "title": "Id" }, "type": { "type": "string", "title": "Type", "default": "wallet" }, "risk": { "type": "number", "title": "Risk", "default": 0.0 } }, "type": "object", "required": [ "id" ], "title": "TopologyNode" }, "TransactionCheckRequest": { "properties": { "amount": { "type": "number", "maximum": 1000000000.0, "minimum": 0.0, "title": "Amount", "description": "Transaction amount" }, "sender": { "type": "string", "maxLength": 256, "title": "Sender", "description": "Sender entity name or on-chain address" }, "receiver": { "type": "string", "maxLength": 256, "title": "Receiver", "description": "Receiver entity name or on-chain address" }, "chain": { "anyOf": [ { "$ref": "#/components/schemas/src__api__schemas__screen__Chain" }, { "type": "null" } ], "description": "Blockchain of sender/receiver when they are on-chain addresses. Optional: EVM (0x…) and Tron (T…) forms are recognised without it; set explicitly for bitcoin and other chains." }, "sender_jurisdiction": { "type": "string", "maxLength": 128, "title": "Sender Jurisdiction", "description": "Sender jurisdiction", "default": "" }, "receiver_jurisdiction": { "type": "string", "maxLength": 128, "title": "Receiver Jurisdiction", "description": "Receiver jurisdiction", "default": "" }, "currency": { "type": "string", "maxLength": 10, "title": "Currency", "description": "Transaction currency", "default": "USD" }, "graph_centrality": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Graph Centrality", "default": 0.0 }, "gnn_score": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Gnn Score", "default": 0.0 } }, "type": "object", "required": [ "amount", "sender", "receiver" ], "title": "TransactionCheckRequest", "examples": [ { "amount": 9500, "currency": "USD", "gnn_score": 0.62, "graph_centrality": 0.45, "receiver": "Global Logistics SA", "receiver_jurisdiction": "switzerland", "sender": "Acme Trading Ltd", "sender_jurisdiction": "panama" } ] }, "TransactionCheckResponse": { "properties": { "risk_score": { "type": "number", "title": "Risk Score" }, "risk_level": { "type": "string", "title": "Risk Level" }, "risk_factors": { "items": { "$ref": "#/components/schemas/RiskFactor" }, "type": "array", "title": "Risk Factors" }, "recommendation": { "type": "string", "title": "Recommendation" }, "components": { "additionalProperties": { "type": "number" }, "type": "object", "title": "Components" } }, "type": "object", "required": [ "risk_score", "risk_level", "risk_factors", "recommendation", "components" ], "title": "TransactionCheckResponse", "examples": [ { "components": { "centrality_score": 0.45, "gnn_score": 0.62, "rule_score": 0.65 }, "recommendation": "review", "risk_factors": [ { "detail": "Sender jurisdiction 'panama' is high-risk", "rule": "high_risk_sender_jurisdiction", "severity": "high" }, { "detail": "Amount $9,500 is just below $10,000 reporting threshold", "rule": "potential_structuring", "severity": "medium" } ], "risk_level": "high", "risk_score": 0.78 } ] }, "TransactionRecord": { "properties": { "timestamp": { "type": "string", "maxLength": 64, "title": "Timestamp", "description": "ISO 8601 timestamp" }, "amount": { "type": "number", "maximum": 1000000000.0, "minimum": 0.0, "title": "Amount", "description": "Transaction amount" }, "sender": { "type": "string", "maxLength": 256, "title": "Sender", "description": "Sender address", "default": "unknown_sender" }, "receiver": { "type": "string", "maxLength": 256, "title": "Receiver", "description": "Receiver address", "default": "unknown_receiver" } }, "type": "object", "required": [ "timestamp", "amount" ], "title": "TransactionRecord" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "VaspLicense": { "properties": { "jurisdiction": { "type": "string", "maxLength": 8, "title": "Jurisdiction" }, "license_id": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "License Id" }, "regulator": { "type": "string", "maxLength": 128, "title": "Regulator" }, "license_status": { "anyOf": [ { "type": "string", "enum": [ "active", "revoked", "pending", "surrendered" ] }, { "type": "null" } ], "title": "License Status" }, "license_date": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ], "title": "License Date" }, "casp_registered": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Casp Registered" } }, "type": "object", "required": [ "jurisdiction", "regulator" ], "title": "VaspLicense", "description": "One VASP license record. An entity can hold N licenses across regimes.\n\nSprint 60 Track E.1.7 merge produces multi-jurisdiction entities\n(e.g. Coinbase = US FinCEN + NY DFS + UK FCA + ...). The\n`VaspMatch.licenses` list preserves every regime; the legacy\nsingle-license fields on VaspMatch remain populated from the first\nlist entry for backwards compatibility (contract A.1: extension\nonly, no field removals)." }, "VaspMatch": { "properties": { "name": { "type": "string", "maxLength": 256, "title": "Name" }, "jurisdiction": { "anyOf": [ { "type": "string", "maxLength": 8 }, { "type": "null" } ], "title": "Jurisdiction" }, "license_id": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "License Id" }, "regulator": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Regulator" }, "license_status": { "anyOf": [ { "type": "string", "enum": [ "active", "revoked", "pending", "surrendered" ] }, { "type": "null" } ], "title": "License Status" }, "casp_registered": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Casp Registered" }, "licenses": { "items": { "$ref": "#/components/schemas/VaspLicense" }, "type": "array", "title": "Licenses" } }, "type": "object", "required": [ "name" ], "title": "VaspMatch", "description": "VASP directory match populated by Sprint 60 Track E scrape pipeline.\n\nSingle-license fields (jurisdiction / license_id / regulator /\nlicense_status / casp_registered) carry the first license from the\n`licenses` list for backwards compatibility with B.V.3 skeleton\nconsumers. New consumers should iterate `licenses` to enumerate\nevery regime an entity is registered under." }, "src__api__schemas__screen__Chain": { "type": "string", "enum": [ "ethereum", "tron", "bitcoin", "bsc", "polygon", "arbitrum", "base", "gnosis" ], "title": "Chain", "description": "Chains supported by the screening API.\n\nSprint 59: ETH + Tron graph-backed. Sprint 60 adds BSC, Polygon,\nArbitrum, BTC (per docs/product-targets-exchange-first.md Sprint 60\nmapping). The enum is declared here at full scope so the API surface\ndoes not change between sprints — only the implementation fills in." } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Tenant API key. Register at https://app.aidecisions.ai/onboarding." } } } }