openapi: 3.0.0 info: title: LedgerBrain API version: 1.0.0 description: > Blockchain intelligence, compliance, and entity management. ## Overview Screen addresses, transactions, and entities for risk across **Bitcoin, Ethereum, Solana, BSC, Tron, and Ripple**. ## Authentication All endpoints require a JWT Bearer token: ``` Authorization: Bearer ``` ## Key Features | Feature | Description | |---------|-------------| | **KYT (Know Your Transaction)** | Score transactions for risk — sanctions, fraud, darknet, mixing | | **KYA (Know Your Address)** | Score addresses — entity attribution, risk factors, behavioral signals | | **KYE (Know Your Entity)** | Manage, tag, and investigate blockchain entities | | **Credits** | Track your API usage | | **Subscriptions** | Manage your plan | x-ai-summary: > LedgerBrain is a blockchain compliance API. Key capabilities: (1) KYT — POST /api/v1/kyt/analyze to risk-score a cryptocurrency transaction by txid and chain; returns riskScore 0-100 and riskLevel (low/medium/high/critical). (2) KYA — POST /api/v1/kya/analyze to risk-score a wallet address; same response shape. (3) KYE — GET /api/v1/kye/entities to list/search known blockchain entities with risk data. All endpoints require a JWT Bearer token. Credits are consumed per query; check balance at GET /api/v1/credits/balance. Supported chains: bitcoin, ethereum, solana, binance-smart-chain, tron, ripple. license: name: Proprietary contact: name: LedgerBrain Support url: https://ledgerbrain.io email: support@ledgerbrain.io servers: - url: https://api.ledgercore.io description: LedgerBrain API v1 (LedgerLink Unified Gateway) components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: "JWT Bearer token for API authentication. Include as: Authorization: Bearer " schemas: Error: type: object properties: error: type: string description: Error message describing what went wrong example: "Missing required parameters: exchange and symbol are required" success: type: boolean example: false message: type: string description: Human-readable error message example: "Missing required parameter: exchange" statusCode: type: integer description: HTTP status code example: 400 code: type: string description: Error code for programmatic handling (optional) example: VALIDATION_ERROR errors: type: array description: Detailed validation errors (when applicable) items: type: object properties: field: type: string description: Field that caused the error example: exchange message: type: string description: Field-specific error message example: Exchange parameter is required example: - field: exchange message: Exchange parameter is required details: type: string description: Additional error details (optional) example: Invalid date format provided description: Error response format required: - error - statusCode - code PaginationInfo: type: object properties: total: type: integer description: Total number of items example: 150 limit: type: integer description: Items per page example: 50 offset: type: integer description: Current offset example: 0 hasMore: type: boolean description: Whether more items exist example: true StripeCheckoutRequest: type: object required: - priceId - successUrl - cancelUrl - userId properties: priceId: type: string successUrl: type: string format: uri cancelUrl: type: string format: uri userId: type: string planName: type: string planPeriod: type: string StripeCheckoutResponse: type: object properties: sessionId: type: string checkoutUrl: type: string format: uri PayPalSubscriptionRequest: type: object required: - planId - successUrl - cancelUrl - userId properties: planId: type: string successUrl: type: string format: uri cancelUrl: type: string format: uri userId: type: string planName: type: string planPeriod: type: string PayPalSubscriptionResponse: type: object properties: subscriptionId: type: string approvalUrl: type: string format: uri SubscriptionStatusResponse: type: object properties: success: type: boolean data: type: object nullable: true properties: provider: type: string enum: - stripe - paypal status: type: string currentPeriodEnd: type: integer format: int64 nullable: true planId: type: string nullable: true priceId: type: string nullable: true customerId: type: string nullable: true subscriptionId: type: string UnifiedQuery: type: object properties: dataType: type: string description: The type of data to query enum: - transactions - balances - assets - candle_exchanges - candle_pairs - candle_timeframes - candles - trades - trade_exchanges - trade_pairs - trade_currencies - histogram - risk_score - entities ReferenceEntity: type: object properties: id: type: integer description: Unique identifier name: type: string description: Name of the entity example: id: 1 name: Example Entity Region: allOf: - $ref: "#/components/schemas/ReferenceEntity" - type: object properties: code: type: string example: EU Country: allOf: - $ref: "#/components/schemas/ReferenceEntity" - type: object properties: countryCode: type: string example: US regionId: type: integer example: 1 Blockchain: allOf: - $ref: "#/components/schemas/ReferenceEntity" - type: object properties: slug: type: string chainId: type: integer Token: allOf: - $ref: "#/components/schemas/ReferenceEntity" - type: object properties: symbol: type: string slug: type: string ExchangeListResponse: type: array description: List of exchange names that have trade data available items: type: string description: Exchange identifier example: luno example: - binance - coinbase - kraken - luno - valr - bitfinex CandleData: type: object description: OHLCV candle data for a specific timeframe required: - timestamp - open - high - low - close - volume - interval - exchange - symbol properties: timestamp: type: string format: date description: Candle timestamp (start of interval) example: 2025-07-01 open: type: number format: float description: Opening price example: 42350.75 high: type: number format: float description: Highest price during interval example: 42450.25 low: type: number format: float description: Lowest price during interval example: 42280.5 close: type: number format: float description: Closing price example: 42380 volume: type: number format: float description: Trading volume during interval example: 125.43 interval: type: string description: Candle interval/timeframe example: 1h exchange: type: string description: Exchange identifier example: binance symbol: type: string description: Trading pair symbol example: BTC-USDT TradingPairListResponse: type: array description: List of trading pairs available on an exchange items: type: string description: Trading pair symbol in BASE-QUOTE format pattern: ^[A-Z0-9]+-[A-Z0-9]+$ example: XBT-IDR example: - XBT-IDR - XBT-MYR - XBT-NGN - XBT-USDC - XBT-USDT - XBT-ZAR CurrencyListResponse: type: array description: List of individual currencies available items: type: string description: Currency code pattern: ^[A-Z0-9]+$ example: XBT example: - XBT - ETH - USDT - IDR - ZAR IntervalListResponse: type: array description: List of available candle intervals/timeframes items: type: string description: Interval specification enum: - 1m - 3m - 5m - 15m - 30m - 1h - 2h - 4h - 6h - 8h - 12h - 1d - 3d - 1w - 1M example: 1h example: - 1m - 5m - 15m - 1h - 4h - 1d OrderBookLevel: type: object description: Single level in an orderbook (bid or ask) required: - price - quantity properties: price: type: number format: float description: Price level example: 42350.75 quantity: type: number format: float description: Quantity available at this price level example: 1.25 OrderBookData: type: object description: Complete orderbook data with bids and asks required: - timestamp - exchange - symbol - bids - asks properties: timestamp: type: string format: date description: Orderbook timestamp example: 2025-07-01T12:34:56.789Z exchange: type: string description: Exchange identifier example: binance symbol: type: string description: Trading pair symbol example: BTC-USDT bids: type: array description: Buy orders (bids) sorted by price descending items: $ref: "#/components/schemas/OrderBookLevel" asks: type: array description: Sell orders (asks) sorted by price ascending items: $ref: "#/components/schemas/OrderBookLevel" depth: type: integer description: Number of levels in each side example: 10 DepthListResponse: type: array description: List of available orderbook depths items: type: integer description: Available depth level example: 10 example: - 5 - 10 - 20 - 50 - 100 TradeData: type: object description: Individual trade execution data required: - timestamp - price - quantity - side - exchange - symbol properties: timestamp: type: string format: date description: Trade execution timestamp example: 2025-07-01 price: type: number format: float description: Trade execution price example: 42350.75 quantity: type: number format: float description: Trade volume/quantity example: 0.025 side: type: string enum: - buy - sell description: Trade side (buy or sell) example: buy exchange: type: string description: Exchange identifier example: luno symbol: type: string description: Trading pair symbol example: XBT-IDR id: type: string description: Unique trade identifier (if available) example: "123456789" TradeStats: type: object description: Comprehensive trade statistics for a trading pair required: - totalTrades - totalVolume - averagePrice - highPrice - lowPrice - buyVolume - sellVolume - buyCount - sellCount - timeRange properties: totalTrades: type: integer description: Total number of trades example: 15420 totalVolume: type: number format: float description: Total trading volume example: 1250.75 averagePrice: type: number format: float description: Average trade price example: 42350.25 highPrice: type: number format: float description: Highest trade price example: 42850 lowPrice: type: number format: float description: Lowest trade price example: 41950.5 buyVolume: type: number format: float description: Total buy volume example: 625.3 sellVolume: type: number format: float description: Total sell volume example: 625.45 buyCount: type: integer description: Number of buy trades example: 7710 sellCount: type: integer description: Number of sell trades example: 7710 timeRange: type: object description: Time range of the data properties: start: type: string format: date description: Start timestamp example: 2025-07-01 end: type: string format: date description: End timestamp example: 2025-07-01 TradeHistogramBucket: type: object description: Histogram bucket for trade size distribution required: - bucket - percentage - count - volume properties: bucket: type: string description: Size range of the bucket example: 0.00-1.00 percentage: type: number format: float description: Percentage of total volume in this bucket example: 25.5 count: type: integer description: Number of trades in this bucket example: 1250 volume: type: number format: float description: Total volume in this bucket example: 320.75 BitcoinBlock: type: object properties: hash: type: string description: Block hash blockHeight: type: integer description: Block height blockTime: type: integer description: Block timestamp balances: type: integer description: Balance processing status BitcoinTransaction: type: object properties: hash: type: string description: Transaction hash blockHeight: type: integer description: Block height containing the transaction blockTime: type: integer description: Block timestamp vouts: type: array items: $ref: "#/components/schemas/BitcoinVout" BitcoinVout: type: object properties: hash: type: string description: Transaction hash idx: type: integer description: Index in transaction vout: type: integer description: Output index blockheight: type: integer description: Block height address: type: string description: Recipient address amount: type: number format: decimal description: Amount in BTC BitcoinBalanceChange: type: object properties: hash: type: string description: Transaction hash address: type: string description: Bitcoin address blockHeight: type: integer description: Block height total_in: type: number format: decimal description: Total incoming amount total_out: type: number format: decimal description: Total outgoing amount balance_change: type: number format: decimal description: Net change in balance balance_net: type: number format: decimal description: Resulting balance timestamp: type: integer description: Timestamp of the block BitcoinAddressWithBalance: type: object properties: address: type: string description: Bitcoin address balance: type: number format: decimal description: Current balance meta: type: object description: Address metadata label: type: string description: Address label CompanyMetrics: type: object properties: id: type: string description: Unique identifier for the metrics record example: altvest-capital-2025-09-17 companyId: type: string description: Company identifier example: altvest-capital companyName: type: string description: Company display name example: Altvest Capital date: type: string format: date description: Snapshot date example: 2025-09-17 marketCap: type: number description: Market capitalization example: 218131586.874 marketCapFullyDiluted: type: number description: Fully diluted market capitalization example: 416007461.574 sharesOutstanding: type: number description: Number of shares outstanding example: 175629297 sharesOutstandingDiluted: type: number description: Diluted shares outstanding example: 334949647 sharePrice: type: number description: Current share price example: 1.242 btcHeld: type: number description: Bitcoin holdings example: 2249 btcPrice: type: number description: Bitcoin price example: 98671.61837276985 bitcoinNav: type: number description: Bitcoin net asset value example: 221912469.72035939 btcValuePerShare: type: number description: Bitcoin value per share example: 1.2635276318412831 btcValuePerDilutedShare: type: number description: Bitcoin value per diluted share example: 0.6625248651787933 btcTotalReturn: type: number nullable: true description: Bitcoin total return example: 0.5543389622471738 btcYield: type: number nullable: true description: Bitcoin yield example: 0.011699414675140574 btcYieldYTD: type: number nullable: true description: Bitcoin yield year-to-date example: 15.36585365 btcYieldQTD: type: number nullable: true description: Bitcoin yield quarter-to-date example: 0.19395017 btcGain: type: number nullable: true description: Bitcoin gain example: null btcGainYTD: type: number nullable: true description: Bitcoin gain year-to-date example: 614.634146 btcGainQTD: type: number nullable: true description: Bitcoin gain quarter-to-date example: 346.78290396 fiatGainYTD: type: number nullable: true description: Fiat gain year-to-date example: 60587603.96634022 fiatGainQTD: type: number nullable: true description: Fiat gain quarter-to-date example: 34184149.03266028 btcDollarGain: type: number nullable: true description: Bitcoin dollar gain example: null shareOutperformance: type: number description: Share outperformance vs Bitcoin example: 5.371492728295837 daysToCoverMNAV: type: number description: Days to cover market cap with average volume example: 54.027414043948255 tradeVolume: type: number description: Trading volume example: 0 mnav: type: number description: Market cap to NAV ratio example: 0.9829622785455734 pcv: type: number description: Price to crypto value ratio example: 0.4927913656782108 enterpriseValue: type: number description: Enterprise value example: 218131586.874 currency: type: string description: Reporting currency example: ZAR createdAt: type: string format: date-time description: Record creation timestamp updatedAt: type: string format: date-time description: Record update timestamp Company: type: object properties: id: type: string description: Company identifier example: altvest-capital name: type: string description: Company name example: Altvest Capital currency: type: string description: Reporting currency example: ZAR createdAt: type: string format: date-time updatedAt: type: string format: date-time MetalPrice: type: object properties: datapoint_timestamp: type: string format: date-time description: Timestamp of the price data base: type: string description: Base metal (e.g., gold, silver) quote: type: string description: Quote currency (e.g., USD, EUR) price: type: number format: decimal description: Price value unit: type: string description: Unit of measurement MoneywebData: type: object properties: datapoint_timestamp: type: string format: date-time description: Timestamp of the data point market: type: string description: Market identifier value: type: number format: decimal description: Market value currency: type: string description: Currency of the value NewsArticle: type: object properties: title: type: string description: Article title example: Bitcoin Reaches New All-Time High link: type: string nullable: true description: Article URL example: https://www.coindesk.com/markets/2024/01/01/bitcoin-reaches-new-ath pubDate: type: string format: date-time nullable: true description: Publication date example: 2024-01-01T12:00:00Z source: type: string description: News source name example: coindesk image: type: string nullable: true description: Article image URL example: https://www.coindesk.com/resizer/image.jpg categories: type: array items: type: string description: Article categories/tags example: - Markets - Bitcoin - Trading description: type: string description: Article description/snippet example: Bitcoin surpassed its previous all-time high... author: type: string description: Article author example: John Doe LatestCandleData: type: object properties: exchange: type: string description: Exchange name example: valr base: type: string description: Base currency (normalized to BTC from XBT) example: BTC open: type: number description: Opening price example: 1234567.89 high: type: number description: Highest price example: 1245000 low: type: number description: Lowest price example: 1220000 close: type: number description: Closing price example: 1238900.5 volume: type: number description: Trading volume example: 12.5678 datetime: type: string description: Candle datetime example: 2025-08-28T00:00:00Z LatestCandlesResponse: type: object properties: success: type: boolean example: true data: type: array items: $ref: "#/components/schemas/LatestCandleData" metadata: type: object properties: total: type: number example: 15 limit: type: number example: 50 offset: type: number example: 0 exchanges: type: array items: type: string example: - valr - luno - altcointrader bases: type: array items: type: string example: - BTC - ETH - LTC - XRP - USDT - USDC error: type: string example: null Entity: type: object properties: id: type: string description: Unique identifier for the entity example: 123e4567-e89b-12d3-a456-426614174000 name: type: string description: Official name of the entity example: Binance type: type: string description: Classification of the entity example: cex status: type: string description: Operational status example: active hqCountry: type: string description: Country code of headquarters (ISO 3166-1 alpha-2) example: KY website: type: string description: Official website URL example: https://www.binance.com description: type: string description: Brief description of the entity example: Largest cryptocurrency exchange by trading volume yearEstablished: type: integer description: Year the entity was founded example: 2017 createdAt: type: string format: date-time description: Timestamp when the record was created updatedAt: type: string format: date-time description: Timestamp when the record was last updated EntityInput: type: object required: - name - type properties: name: type: string description: Official name of the entity example: Binance type: type: string description: Classification of the entity example: cex status: type: string description: Operational status example: active hqCountry: type: string description: Country code of headquarters example: KY website: type: string description: Official website URL example: https://www.binance.com description: type: string description: Brief description of the entity example: Global cryptocurrency exchange yearEstablished: type: integer description: Year the entity was founded example: 2017 responses: UnauthorizedError: description: Authentication required content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Authentication required ForbiddenError: description: Admin privileges required content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Admin privileges required code: type: string example: INSUFFICIENT_PERMISSIONS security: - BearerAuth: [] x-tagGroups: - name: Getting Started tags: - Health & Monitoring - name: Transaction Screening (KYT) tags: - KYT (Know Your Transaction) - name: Address Screening (KYA) tags: - KYA (Know Your Address) - name: Entity Management (KYE) tags: - Know Your Entity (KYE) - KYE - name: Account tags: - Credits - Subscription Plans - User Profile Management paths: /api/v1/blockchain-risk/reg-user: get: summary: Register user for risk scoring (Temporarily disabled) description: User registration endpoint for blockchain risk analysis services tags: - KYT (Know Your Transaction) responses: "403": description: Registration temporarily unavailable content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: forbidden message: type: string example: Registration is temporarily unavailable /api/v1/blockchain-risk/risk-score: get: summary: Calculate blockchain risk score for address or transaction description: > Analyzes blockchain addresses or transactions to calculate risk scores based on: - Transaction patterns and counterparty analysis - Exposure to sanctioned entities or high-risk services - Historical transaction behavior - Network clustering and entity relationships tags: - KYT (Know Your Transaction) parameters: - in: query name: sources required: true schema: type: string enum: - bitcoin - ethereum description: Blockchain source to analyze example: bitcoin - in: query name: address schema: type: string description: Blockchain address to analyze (required if txid not provided) example: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa - in: query name: txid schema: type: string description: Transaction hash to analyze (required if address not provided) example: f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16 - in: query name: asset required: true schema: type: string enum: - btc - eth description: Asset type example: btc - in: query name: direction required: true schema: type: string enum: - SEND - RECEIVE - BOTH description: Transaction direction to analyze (not required for Ethereum) example: BOTH - in: query name: timeout schema: type: integer description: Query timeout in milliseconds example: 25000 responses: "200": description: Risk score calculated successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: address: type: string example: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa riskScore: type: number description: Risk score from 0 (low risk) to 100 (high risk) example: 15.5 riskLevel: type: string enum: - LOW - MEDIUM - HIGH - SEVERE example: LOW exposures: type: array items: type: object properties: category: type: string example: exchange exposure: type: number example: 0.75 timestamp: type: string format: date-time "400": description: Bad request - missing or invalid parameters content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Provide either address or txHash for risk_score queries. "500": description: Internal server error /api/v1/blockchain-risk/risk-score-tx-history: get: summary: Get risk score transaction history (Temporarily disabled) description: Retrieve historical risk scores for an address's transactions over time tags: - KYT (Know Your Transaction) responses: "403": description: Feature temporarily unavailable content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: forbidden message: type: string example: Risk score transaction history is temporarily unavailable /api/v1/blockchain-risk/risk-score-bulk-txHashs: get: summary: Bulk risk score calculation for multiple transactions (Temporarily disabled) description: Calculate risk scores for multiple transaction hashes in a single request tags: - KYT (Know Your Transaction) responses: "403": description: Feature temporarily unavailable content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: forbidden message: type: string example: Risk score bulk processing is temporarily unavailable /api/v1/credits/packages: get: summary: Get available credit packages description: Returns all active credit packages, optionally filtered by application tags: - Credits parameters: - in: query name: applicationId schema: type: string description: Filter packages by application ID responses: "200": description: List of credit packages content: application/json: schema: type: object properties: success: type: boolean data: type: array items: type: object /api/v1/credits/packages/{packageId}: get: summary: Get credit package details description: Returns details of a specific credit package tags: - Credits parameters: - in: path name: packageId required: true schema: type: string responses: "200": description: Credit package details "404": description: Package not found /api/v1/credits/balance: get: summary: Get user credit balance description: Returns the current credit balance for a user in a specific application tags: - Credits parameters: - in: query name: userId required: true schema: type: string - in: query name: applicationId required: true schema: type: string responses: "200": description: User credit balance content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: balance: type: integer description: Total available credits (subscription + purchased) subscription_balance: type: integer description: Credits from subscription renewal — resets each billing period purchased_balance: type: integer description: Credits from one-time top-up purchases — never expire lifetime_earned: type: integer lifetime_spent: type: integer /api/v1/credits/check: post: summary: Check if user has sufficient credits description: Validates if a user has enough credits for an operation tags: - Credits requestBody: required: true content: application/json: schema: type: object required: - userId - applicationId - amount properties: userId: type: string applicationId: type: string amount: type: integer responses: "200": description: Credit check result /api/v1/credits/consume: post: summary: Consume credits description: Deducts credits from a user's balance tags: - Credits requestBody: required: true content: application/json: schema: type: object required: - userId - applicationId - amount properties: userId: type: string applicationId: type: string amount: type: integer reason: type: string metadata: type: object responses: "200": description: Credits consumed successfully "400": description: Insufficient credits /api/v1/credits/grant: post: summary: Grant credits to user description: Adds credits to a user's balance (admin/promotional use) tags: - Credits requestBody: required: true content: application/json: schema: type: object required: - userId - applicationId - amount properties: userId: type: string applicationId: type: string amount: type: integer reason: type: string metadata: type: object responses: "200": description: Credits granted successfully /api/v1/credits/transactions: get: summary: Get credit transaction history description: Returns the transaction history for a user tags: - Credits parameters: - in: query name: userId required: true schema: type: string - in: query name: applicationId required: true schema: type: string - in: query name: limit schema: type: integer default: 50 - in: query name: offset schema: type: integer default: 0 - in: query name: transactionType schema: type: string enum: - purchase - grant - consume - refund - expire - adjustment responses: "200": description: Transaction history /api/v1/credits/stats: get: summary: Get application credit statistics description: Returns credit usage statistics for an application tags: - Credits parameters: - in: query name: applicationId required: true schema: type: string responses: "200": description: Application statistics /api/v1/credits/spend-history: get: summary: Get credit spend history description: > Returns a detailed history of credits spent by the user, enriched with what each credit was spent on (KYT/KYA/KYE analysis, chain, address, risk score). Joins credit transactions with user activity for full context. tags: - Credits parameters: - in: query name: userId required: true schema: type: string - in: query name: applicationId required: true schema: type: string - in: query name: limit schema: type: integer default: 50 - in: query name: offset schema: type: integer default: 0 - in: query name: startDate schema: type: string format: date description: Filter from date (YYYY-MM-DD) - in: query name: endDate schema: type: string format: date description: Filter to date (YYYY-MM-DD) responses: "200": description: Credit spend history with analysis context content: application/json: schema: type: object properties: success: type: boolean data: type: array items: type: object properties: transactionId: type: integer creditsSpent: type: integer balanceBefore: type: integer balanceAfter: type: integer action: type: string description: What the credits were spent on (e.g. KYT_ANALYZE, KYA_ANALYZE, KYE_ANALYZE) endpoint: type: string timestamp: type: string format: date-time reason: type: string activity: type: object description: Linked user activity with full analysis context (chain, address, risk score) summary: type: object properties: totalSpent: type: integer transactionCount: type: integer byAction: type: object description: Credits spent per action type /api/v1/subscription-plans: get: summary: List all active subscription plans description: Get all publicly available subscription plans. No authentication required. tags: - Subscription Plans parameters: - in: query name: application_id schema: type: string description: Filter by application ID responses: "200": description: List of subscription plans content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: $ref: "#/components/schemas/SubscriptionPlan" count: type: integer example: 3 "500": description: Server error /api/v1/subscription-plans/{planId}: get: summary: Get subscription plan details description: Get details of a specific subscription plan by ID. No authentication required. tags: - Subscription Plans parameters: - in: path name: planId required: true schema: type: string description: Subscription plan ID responses: "200": description: Subscription plan details content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: "#/components/schemas/SubscriptionPlan" "404": description: Plan not found "500": description: Server error /api/v1/kyt/analyze: post: summary: Analyze cryptocurrency address for risk assessment description: > Perform comprehensive risk analysis on a Bitcoin or Ethereum address using our internal KYT engine. The analysis includes: - **Risk Score**: Overall risk rating (0-100) - **Risk Factors**: Detailed breakdown of risk indicators - **Entity Attribution**: Known entity associations - **Sanctions Check**: OFAC and international sanctions screening - **Transaction Patterns**: Behavioral analysis and pattern detection - **Cluster Analysis**: Related addresses and wallet groupings **Response Time**: 10-60 seconds for fresh analysis depending on address complexity **Supported Chains** (mandatory): - `bitcoin` - Legacy, SegWit, and Taproot transactions - `ethereum` - Native ETH and ERC-20 token transactions - `solana` - Native Solana transactions - `binance-smart-chain` - BSC transactions - `tron` - Tron network transactions - `ripple` - XRP Ledger transactions **Asset Parameter**: - Only supported when `chain=ethereum` - Must be a contract address (e.g. USDT: `0xdAC17F958D2ee523a2206206994597C13D831ec7`) - Omitting asset includes all assets tags: - KYT (Know Your Transaction) security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - txid - chain properties: txid: type: string description: Transaction ID (64 hex characters, 0x prefix optional for ETH) chain: type: string enum: - bitcoin - ethereum - solana - binance-smart-chain - tron - ripple description: Blockchain network (mandatory) asset: type: string description: ERC-20 contract address. Only supported when chain=ethereum. Omitting includes all assets. timeout: type: integer minimum: 1000 maximum: 900000 description: Request timeout in milliseconds (default 300000 = 5 minutes) default: 300000 hops: type: integer minimum: 1 maximum: 10 description: Maximum number of hops to traverse in transaction graph analysis default: 3 extraWaitMs: type: integer minimum: 0 maximum: 600000 description: Additional wait time in milliseconds (deprecated - use timeout instead) crawlTimeout: type: integer minimum: 1000 maximum: 900000 description: Crawl timeout in milliseconds (deprecated - use timeout instead) reference_id: type: string description: Optional client reference ID echoed back by the upstream KYT API referenceId: type: string description: CamelCase alias for reference_id (deprecated — prefer reference_id) receive_address: type: string description: Optional destination/receive address forwarded to the upstream KYT API examples: btcTx: summary: Bitcoin transaction analysis value: txid: 4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b chain: bitcoin ethTx: summary: Ethereum transaction analysis value: txid: "0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060" chain: ethereum erc20Tx: summary: ERC-20 token transaction analysis (USDT) value: txid: "0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060" chain: ethereum asset: "0xdAC17F958D2ee523a2206206994597C13D831ec7" solanaTx: summary: Solana transaction analysis value: txid: 5UfDuX7hXbMjBJSEBaGEi4VJoxofmHBiLwNh3Sdv4fembFQKMGhQNGkXFbBBRNqC3ag1GQRFnVEhXoxJRG1KkFEj chain: solana bscTx: summary: Binance Smart Chain transaction analysis value: txid: "0x0e3e2778b3cbb4a6a0c76b1e52e9e0e1c2e1e3e4e5e6e7e8e9eaebecedeeeff0" chain: binance-smart-chain tronTx: summary: Tron transaction analysis value: txid: a6f3eaa3d97a3e1e0d3e4e5e6e7e8e9eaebecedeeeff0f1f2f3f4f5f6f7f8f9fa chain: tron rippleTx: summary: Ripple (XRP) transaction analysis value: txid: E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7 chain: ripple responses: "200": description: Successful risk analysis content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object description: KYT analysis results from internal engine properties: address: type: string example: 1JsuWQuHX2kAGKxjBHomPeVrrH87XDCtEJ riskScore: type: number description: Overall risk score (0-100) example: 25 riskLevel: type: string enum: - low - medium - high - critical example: low analysis: type: object description: Detailed risk analysis examples: lowRisk: summary: Low Risk Address value: success: true data: address: 1JsuWQuHX2kAGKxjBHomPeVrrH87XDCtEJ riskScore: 15 riskLevel: low analysis: entityType: exchange sanctioned: false mixerExposure: 0 darknetExposure: 0 highRisk: summary: High Risk Address value: success: true data: address: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa riskScore: 85 riskLevel: high analysis: entityType: unknown sanctioned: false mixerExposure: 45 darknetExposure: 30 "400": description: Invalid request - missing or invalid address content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Address is required "401": description: Unauthorized - missing or invalid JWT token content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Internal server error or KYT engine unavailable content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: "KYT analysis failed: Connection timeout" /api/v1/kyt/{responseId}: get: summary: Get KYT response by ID description: > Retrieve a previously submitted KYT transaction analysis response by its UUID. This endpoint allows you to fetch the results of a KYT analysis that was previously performed, using the response ID returned from the `/kyt/analyze` endpoint. **Use Cases**: - Retrieve cached analysis results - Check status of long-running analyses - Access historical KYT reports - Share analysis results across systems tags: - KYT (Know Your Transaction) security: - BearerAuth: [] parameters: - name: responseId in: path required: true schema: type: string format: uuid description: UUID of the KYT response example: 315b97d5-3f2c-4fc9-908d-19a98e357d21 responses: "200": description: KYT response found and returned successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object description: Complete KYT analysis results properties: response: type: object description: Full analysis response from KYT engine metadata: type: object description: Analysis metadata including graph and performance data "401": description: Unauthorized - missing or invalid JWT token content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Response not found - invalid or expired response ID content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Response not found "500": description: Internal server error content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string /api/v1/kyt/health: get: summary: Check KYT engine health status description: > Verify the availability and health of the internal KYT analysis engine. This endpoint is useful for: - Monitoring KYT service availability - Pre-flight checks before batch analysis - Integration health verification - Uptime monitoring and alerting **Note**: This endpoint still requires JWT authentication even though it's a health check, as it exposes internal service status information. tags: - KYT (Know Your Transaction) security: - BearerAuth: [] responses: "200": description: KYT engine health status content: application/json: schema: type: object properties: success: type: boolean example: true healthy: type: boolean description: Whether the KYT engine is operational example: true service: type: string example: KYT API examples: healthy: summary: KYT Engine Healthy value: success: true healthy: true service: KYT API unhealthy: summary: KYT Engine Unavailable value: success: true healthy: false service: KYT API "401": description: Unauthorized - missing or invalid JWT token content: application/json: schema: $ref: "#/components/schemas/Error" /api/v1/kya/analyze: post: summary: Analyze address for risk assessment description: > Perform comprehensive risk analysis on a cryptocurrency address. **Response Time**: 10-60 seconds for fresh analysis depending on address complexity **Supported Chains** (mandatory): - `bitcoin` - Legacy, SegWit, and Taproot addresses - `ethereum` - EOA and contract addresses - `solana` - Native Solana addresses - `binance-smart-chain` - BSC addresses - `tron` - Tron network addresses - `ripple` - XRP Ledger addresses **Asset Parameter**: - Only supported when `chain=ethereum` - Must be a contract address (e.g. USDT: `0xdAC17F958D2ee523a2206206994597C13D831ec7`) - Omitting asset includes all assets tags: - KYA (Know Your Address) security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - address - chain properties: address: type: string description: Blockchain address to analyze chain: type: string enum: - bitcoin - ethereum - solana - binance-smart-chain - tron - ripple description: Blockchain network (mandatory) asset: type: string description: ERC-20 contract address. Only supported when chain=ethereum. Omitting includes all assets. extraWaitMs: type: integer minimum: 0 maximum: 600000 description: Additional wait time in milliseconds crawlTimeout: type: integer minimum: 1000 maximum: 900000 description: Crawl timeout in milliseconds reference_id: type: string description: Optional client reference ID echoed back by the upstream KYT API referenceId: type: string description: CamelCase alias for reference_id (deprecated — prefer reference_id) receive_address: type: string description: Optional destination/receive address forwarded to the upstream KYA API examples: btcAddress: summary: Bitcoin address analysis value: address: bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh chain: bitcoin ethAddress: summary: Ethereum address analysis value: address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" chain: ethereum erc20Address: summary: ERC-20 token address analysis (USDT) value: address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" chain: ethereum asset: "0xdAC17F958D2ee523a2206206994597C13D831ec7" solanaAddress: summary: Solana address analysis value: address: 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM chain: solana bscAddress: summary: Binance Smart Chain address analysis value: address: "0x8894E0a0c962CB723c1ef8a1B6F5e7E1dE9b0D1a" chain: binance-smart-chain tronAddress: summary: Tron address analysis value: address: TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH chain: tron rippleAddress: summary: Ripple (XRP) address analysis value: address: rN7n3473SaZBCG4dFL83w7p1W9cgZw6w3Y chain: ripple responses: "200": description: Successful analysis content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object description: Risk analysis results including risk score and factors "400": description: Invalid request - missing required fields or invalid format "401": description: Unauthorized - missing or invalid JWT token "500": description: Internal server error /api/v1/kya/{responseId}: get: summary: Get KYA response by ID description: Retrieve a previously submitted KYA analysis response by its UUID. tags: - KYA (Know Your Address) security: - BearerAuth: [] parameters: - name: responseId in: path required: true schema: type: string format: uuid description: UUID of the KYA response responses: "200": description: Response found content: application/json: schema: type: object properties: success: type: boolean data: type: object "401": description: Unauthorized "404": description: Response not found /api/v1/credits/estimate: post: summary: Estimate credit cost for planned analysis description: > Calculate the estimated credit cost for a KYT/KYA/KYE analysis before executing it. This allows users to understand the cost and ensure they have sufficient credits. The estimation considers: - Crawling strategy (basic trace, deep dive, full forensics) - Number of hops - Data sources required - Historical depth - Processing mode (batch vs realtime) - Complexity factors (mixers, cross-chain, DeFi) tags: - Credits security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - strategy - chain properties: strategy: type: string enum: - basic_trace - deep_dive - full_forensics description: Crawling strategy example: deep_dive chain: type: string enum: - bitcoin - ethereum - solana - binance-smart-chain - tron - ripple description: Blockchain network example: ethereum hops: type: integer minimum: 1 maximum: 10 description: Number of transaction hops to trace example: 3 historicalDepth: type: string enum: - last_30_days - last_90_days - last_year - full_history default: last_30_days description: How far back to analyze transactions realtime: type: boolean default: false description: Use realtime processing (higher cost) includeDefi: type: boolean default: false description: Include DeFi protocol analysis includeMixers: type: boolean default: false description: Include mixer/tumbler detection crossChain: type: boolean default: false description: Enable cross-chain tracking applicationId: type: string description: Application ID for credit tracking examples: basicTrace: summary: Basic trace (1 hop) value: strategy: basic_trace chain: bitcoin hops: 1 deepDive: summary: Deep dive (3 hops with DeFi) value: strategy: deep_dive chain: ethereum hops: 3 includeDefi: true historicalDepth: last_90_days fullForensics: summary: Full forensics with all features value: strategy: full_forensics chain: ethereum realtime: true includeMixers: true crossChain: true historicalDepth: full_history responses: "200": description: Credit estimation calculated successfully content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: estimation: type: object properties: min: type: integer description: Minimum credits required max: type: integer description: Maximum credits that may be charged estimated: type: integer description: Most likely credit cost breakdown: type: object description: Detailed cost breakdown explanation: type: array items: type: string description: Human-readable explanation of costs userBalance: type: integer description: User's current credit balance (if authenticated) canAfford: type: boolean description: Whether user has sufficient credits "401": description: Authentication required "500": description: Server error /api/v1/credits/pricing: get: summary: Get pricing information and strategy details description: | Returns comprehensive pricing information including: - Available crawling strategies and their costs - Data source cost multipliers - Historical depth multipliers - Processing mode costs - Complexity bonuses tags: - Credits responses: "200": description: Pricing information retrieved successfully content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: strategies: type: array items: type: object properties: id: type: string name: type: string description: type: string baseMultiplier: type: string typicalCost: type: string useCase: type: string dataSourceCosts: type: object historicalDepthMultipliers: type: object processingModes: type: object complexityBonuses: type: object "500": description: Server error /health/system: get: summary: Get comprehensive system health status description: Returns detailed health information including circuit breakers, repositories, and database connectivity tags: - Health & Monitoring responses: "200": description: System health status retrieved successfully content: application/json: schema: type: object properties: status: type: string enum: - healthy - degraded - unhealthy example: healthy circuitBreakers: type: object properties: bitcoin: $ref: "#/components/schemas/CircuitBreakerStatus" ethereum: $ref: "#/components/schemas/CircuitBreakerStatus" config: $ref: "#/components/schemas/CircuitBreakerStatus" repositories: type: object properties: bitcoin: $ref: "#/components/schemas/RepositoryHealth" ethereum: $ref: "#/components/schemas/RepositoryHealth" config: $ref: "#/components/schemas/RepositoryHealth" summary: type: object properties: totalCircuitBreakers: type: integer example: 3 healthyCircuitBreakers: type: integer example: 3 openCircuitBreakers: type: integer example: 0 timestamp: type: integer example: 1694444444444 "503": description: System is unhealthy content: application/json: schema: $ref: "#/components/schemas/HealthError" /health/resilience/config: get: summary: Get system resilience configuration description: Returns current resilience configuration including circuit breaker settings and thresholds tags: - Health & Monitoring responses: "200": description: Resilience configuration retrieved successfully content: application/json: schema: type: object properties: circuitBreakerDefaults: type: object properties: failureThreshold: type: integer example: 5 recoveryTimeout: type: integer example: 60000 timeWindow: type: integer example: 60000 databases: type: object properties: bitcoin: $ref: "#/components/schemas/DatabaseResilienceConfig" ethereum: $ref: "#/components/schemas/DatabaseResilienceConfig" config: $ref: "#/components/schemas/DatabaseResilienceConfig" timestamp: type: integer example: 1694444444444 "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/Error" /health/ping: get: summary: Simple ping health check description: Basic health check endpoint that returns server status and uptime tags: - Health & Monitoring responses: "200": description: Server is healthy and responding content: application/json: schema: type: object properties: status: type: string example: ok timestamp: type: integer example: 1694444444444 uptime: type: number description: Server uptime in seconds example: 3600.123 /users/app-profile: get: summary: Get current user's profile description: Retrieves the authenticated user's profile information tags: - User Profile Management security: - BearerAuth: [] responses: "200": description: User profile retrieved successfully content: application/json: schema: $ref: "#/components/schemas/UserProfile" "401": description: Authentication required content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: User profile not found content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/Error" post: summary: Create user profile description: Creates a new user profile for the authenticated user tags: - User Profile Management security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - preferredAccountType properties: preferredAccountType: type: string enum: - individual - business - enterprise description: User's preferred account type example: individual profileData: type: object description: Additional profile information properties: firstName: type: string example: John lastName: type: string example: Doe company: type: string example: Acme Corp timezone: type: string example: UTC preferences: type: object properties: notifications: type: boolean example: true theme: type: string enum: - light - dark example: dark responses: "201": description: User profile created successfully content: application/json: schema: $ref: "#/components/schemas/UserProfile" "401": description: Authentication required content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: User profile already exists content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/Error" put: summary: Update user profile description: Updates the authenticated user's profile information tags: - User Profile Management security: - BearerAuth: [] requestBody: required: false content: application/json: schema: type: object properties: preferredAccountType: type: string enum: - individual - business - enterprise description: Updated preferred account type example: business profileData: type: object description: Updated profile information properties: firstName: type: string example: Jane lastName: type: string example: Smith company: type: string example: New Corp timezone: type: string example: America/New_York preferences: type: object properties: notifications: type: boolean example: false theme: type: string enum: - light - dark example: light responses: "200": description: User profile updated successfully content: application/json: schema: $ref: "#/components/schemas/UserProfile" "401": description: Authentication required content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: User profile not found content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/Error" /organizations: get: summary: Get user's organizations description: Retrieves all organizations associated with the authenticated user tags: - User Profile Management security: - BearerAuth: [] responses: "200": description: User organizations retrieved successfully content: application/json: schema: type: array items: $ref: "#/components/schemas/Organization" "401": description: Authentication required content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/Error" post: summary: Create new organization description: Creates a new organization with the authenticated user as owner tags: - User Profile Management security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string description: Organization name example: Acme Trading Corp details: type: object description: Additional organization details properties: description: type: string example: A leading cryptocurrency trading company website: type: string format: uri example: https://acmetrading.com industry: type: string example: Financial Services size: type: string enum: - startup - small - medium - large - enterprise example: medium responses: "201": description: Organization created successfully content: application/json: schema: $ref: "#/components/schemas/Organization" "400": description: Organization name is required content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Authentication required content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/Error" /organizations/{id}: get: summary: Get organization by ID description: Retrieves a specific organization by its ID tags: - User Profile Management security: - BearerAuth: [] parameters: - in: path name: id required: true schema: type: string description: Organization ID example: org_123456789 responses: "200": description: Organization retrieved successfully content: application/json: schema: $ref: "#/components/schemas/Organization" "401": description: Authentication required content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Organization not found content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/Error" put: summary: Update organization description: Updates an organization (requires owner or admin privileges) tags: - User Profile Management security: - BearerAuth: [] parameters: - in: path name: id required: true schema: type: string description: Organization ID example: org_123456789 requestBody: required: false content: application/json: schema: type: object properties: name: type: string description: Updated organization name example: Acme Trading Corporation details: type: object description: Updated organization details properties: description: type: string example: An innovative cryptocurrency trading platform website: type: string format: uri example: https://newacmetrading.com industry: type: string example: Blockchain Technology size: type: string enum: - startup - small - medium - large - enterprise example: large responses: "200": description: Organization updated successfully content: application/json: schema: $ref: "#/components/schemas/Organization" "401": description: Authentication required content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: Insufficient permissions (must be owner or admin) content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Organization not found content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/Error" /organizations/{id}/members: get: summary: Get organization members description: Retrieves all members of a specific organization tags: - User Profile Management security: - BearerAuth: [] parameters: - in: path name: id required: true schema: type: string description: Organization ID example: org_123456789 responses: "200": description: Organization members retrieved successfully content: application/json: schema: type: array items: type: object properties: id: type: string description: Member ID example: mem_123456789 clerkUserId: type: string description: Clerk user ID example: user_2abc123def456 role: type: string enum: - OWNER - ADMIN - MEMBER description: Member role in organization example: ADMIN joinedAt: type: string format: date-time description: Date when user joined organization status: type: string enum: - active - pending - suspended description: Member status example: active profile: type: object properties: firstName: type: string example: John lastName: type: string example: Doe email: type: string format: email example: john.doe@example.com "401": description: Authentication required content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Organization not found content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/Error" /api/v1/kye/entities: get: summary: List entities with risk data description: > Paginated entity list with the latest risk assessment joined per entity. Each entity includes risk level, risk score, confidence, and last assessment date. Supports alphabetical filtering, name search, risk level filtering, and sorting. tags: - Know Your Entity (KYE) parameters: - in: query name: page schema: type: integer default: 1 description: Page number - in: query name: limit schema: type: integer default: 20 description: Items per page - in: query name: letter schema: type: string maxLength: 1 description: Filter by first letter of entity name (A-Z) example: A - in: query name: search schema: type: string description: Search by entity name (partial match) - in: query name: risk_level schema: type: string enum: - LOW - MEDIUM - HIGH - VERY_HIGH description: Filter by risk level - in: query name: sort_by schema: type: string enum: - name - risk_level - risk_score - updated default: name description: Sort column - in: query name: sort_dir schema: type: string enum: - asc - desc default: asc description: Sort direction - in: query name: sort_dir schema: type: string enum: - asc - desc default: asc description: Sort direction (ascending or descending) responses: "200": description: Paginated entity list with risk data content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Entity" type: object properties: entity_id: type: integer name: type: string type: type: string hq_country: type: string risk_level: type: string nullable: true risk_score: type: number nullable: true updated_at: type: string format: date-time nullable: true confidence: type: string nullable: true pagination: type: object properties: total: type: integer description: Total number of records matching filter page: type: integer description: Current page number limit: type: integer description: Items per page pages: type: integer description: Total number of pages success: type: boolean "500": description: Server error post: summary: Create entity description: Add a new entity to the registry. tags: - Know Your Entity (KYE) requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/EntityInput" responses: "201": description: Entity successfully created content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: "#/components/schemas/Entity" message: type: string example: Entity created successfully "400": description: Invalid input data "500": description: Internal server error /api/v1/kye/entities/{id}: get: summary: Get entity details description: Retrieve detailed information for a specific entity by its ID. tags: - Know Your Entity (KYE) parameters: - in: path name: id required: true schema: type: string description: Unique identifier of the entity responses: "200": description: Entity details found content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Entity" "404": description: Entity not found "500": description: Server error put: summary: Update entity description: Update an existing entity's information. tags: - Know Your Entity (KYE) parameters: - in: path name: id required: true schema: type: string description: Unique identifier of the entity requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/EntityInput" responses: "200": description: Entity updated successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: "#/components/schemas/Entity" message: type: string example: Entity updated successfully "404": description: Entity not found "500": description: Server error delete: summary: Delete entity description: Remove an entity from the registry. tags: - Know Your Entity (KYE) parameters: - in: path name: id required: true schema: type: string description: Unique identifier of the entity responses: "200": description: Entity deleted successfully content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Entity deleted successfully "404": description: Entity not found "500": description: Server error /api/v1/kye/entities/search: get: summary: Search entities by name or alias description: Search for entities using partial name or alias matching. For example, searching "bitx" will find Luno (which has BitX as an alias). tags: - Know Your Entity (KYE) parameters: - in: query name: q required: true schema: type: string minLength: 2 description: Search term (minimum 2 characters) example: bitx - in: query name: limit schema: type: integer default: 20 maximum: 100 description: Maximum number of results to return responses: "200": description: Search results with matched entities content: application/json: schema: type: object properties: success: type: boolean data: type: array items: type: object properties: entityId: type: integer entityName: type: string matchType: type: string matchedValue: type: string website: type: string type: type: string hqCountry: type: string meta: type: object properties: searchTerm: type: string count: type: integer limit: type: integer "400": description: Invalid search parameters "500": description: Server error /api/v1/kye/entities/overview/stats: get: summary: Get labels overview statistics description: | Returns aggregate statistics for the labels dashboard including: - Total entity count - Number of entities with risk assessments - Risk level distribution (for pie chart) - Risk score band distribution (for pie chart) tags: - Know Your Entity (KYE) responses: "200": description: Overview statistics content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: totalEntities: type: integer example: 2415 entitiesAssessed: type: integer example: 1800 riskLevelDistribution: type: array items: type: object properties: risk_level: type: string example: MEDIUM count: type: integer example: 850 riskScoreBands: type: array items: type: object properties: band: type: string example: MEDIUM count: type: integer example: 720 "500": description: Server error /api/v1/kye/entities/crawl-request: post: summary: Submit entity crawl request description: > Submit a request to crawl or re-crawl a specific entity. Requires authentication. The centralised list is visible to all users, allowing different users to put forward different entities to be crawled. For new entities that don't exist yet, omit entityId (or send 0) and provide entityName instead. tags: - Know Your Entity (KYE) requestBody: required: true content: application/json: schema: type: object required: - reason properties: entityId: type: integer nullable: true description: ID of the entity to crawl. Omit or send 0 for new entity requests. example: 1100 entityName: type: string description: Name of the entity (required when entityId is omitted or 0) example: Valora reason: type: string description: Why the crawl is needed (minimum 10 characters) example: Entity profile data is outdated, last crawled over 6 months ago priority: type: string enum: - low - normal - high - urgent default: normal description: Priority level for the crawl request responses: "201": description: Crawl request submitted successfully "400": description: Invalid input "401": description: Authentication required "404": description: Entity not found /api/v1/kye/entities/crawl-requests: get: summary: List all crawl requests description: | Get the centralised list of entity crawl requests. Supports filtering by entity, status, requester, and priority. tags: - Know Your Entity (KYE) parameters: - in: query name: entity_id schema: type: integer description: Filter by entity ID - in: query name: status schema: type: string enum: - pending - in_progress - completed - rejected - failed description: Filter by request status - in: query name: requested_by schema: type: string description: Filter by requester user ID - in: query name: priority schema: type: string enum: - low - normal - high - urgent description: Filter by priority - in: query name: limit schema: type: integer default: 50 - in: query name: offset schema: type: integer default: 0 responses: "200": description: List of crawl requests "500": description: Server error /api/v1/kye/entities/crawl-requests/{id}: get: summary: Get crawl request by ID tags: - Know Your Entity (KYE) parameters: - in: path name: id required: true schema: type: integer responses: "200": description: Crawl request details "404": description: Not found /api/v1/kye/entities/crawl-requests/{id}/status: patch: summary: Update crawl request status description: Admin operation to update the status of a crawl request tags: - Know Your Entity (KYE) parameters: - in: path name: id required: true schema: type: integer requestBody: required: true content: application/json: schema: type: object required: - status properties: status: type: string enum: - pending - in_progress - completed - rejected - failed adminNotes: type: string responses: "200": description: Status updated "400": description: Invalid status "404": description: Not found /api/v1/kye/entities/{id}/profile: get: summary: Get complete entity profile description: Returns comprehensive entity information including basic details, executives, compliance, licenses, timeline, transactions, media coverage, and statistics tags: - Know Your Entity (KYE) parameters: - in: path name: id required: true schema: type: integer description: Entity ID responses: "200": description: Complete entity profile content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: entity: $ref: "#/components/schemas/Entity" executives: type: array items: $ref: "#/components/schemas/EntityExecutive" compliance: type: array items: $ref: "#/components/schemas/EntityCompliance" licenses: type: array items: $ref: "#/components/schemas/EntityLicense" timeline: type: array items: $ref: "#/components/schemas/EntityTimeline" media: type: array items: $ref: "#/components/schemas/EntityMedia" statistics: type: array items: $ref: "#/components/schemas/EntityStatistic" "404": description: Entity not found "500": description: Server error /api/v1/kye/entities/{id}/aliases: get: summary: Get entity aliases description: Returns alternative names and identifiers for the entity tags: - Know Your Entity (KYE) parameters: - in: path name: id required: true schema: type: integer description: Entity ID responses: "200": description: List of aliases "500": description: Server error /api/v1/kye/entities/{id}/beneficial-owners: get: summary: Get entity beneficial owners description: Returns shareholders and ultimate beneficial owners tags: - Know Your Entity (KYE) parameters: - in: path name: id required: true schema: type: integer description: Entity ID responses: "200": description: List of beneficial owners "500": description: Server error /api/v1/kye/entities/{id}/executives: get: summary: Get entity executives description: Returns list of key executives and leadership team members tags: - Know Your Entity (KYE) parameters: - in: path name: id required: true schema: type: integer description: Entity ID - in: query name: current schema: type: boolean description: Filter to only current executives responses: "200": description: List of executives "500": description: Server error /api/v1/kye/entities/{id}/compliance: get: summary: Get entity compliance metrics description: Returns compliance metrics including staff compliance rates and regulatory status tags: - Know Your Entity (KYE) parameters: - in: path name: id required: true schema: type: integer description: Entity ID - in: query name: period schema: type: string description: Filter by period (e.g., "2026-Q1", "2026") responses: "200": description: Compliance metrics "500": description: Server error /api/v1/kye/entities/{id}/licenses: get: summary: Get entity licenses description: Returns regulatory licenses and compliance documentation tags: - Know Your Entity (KYE) parameters: - in: path name: id required: true schema: type: integer description: Entity ID - in: query name: active schema: type: boolean description: Filter to only active licenses responses: "200": description: List of licenses "500": description: Server error /api/v1/kye/entities/{id}/timeline: get: summary: Get entity timeline description: Returns chronological timeline of key events and milestones tags: - Know Your Entity (KYE) parameters: - in: path name: id required: true schema: type: integer description: Entity ID - in: query name: event_type schema: type: string description: Filter by event type (e.g., "funding", "launch", "regulatory") - in: query name: limit schema: type: integer default: 50 description: Maximum number of events to return responses: "200": description: Timeline events "500": description: Server error /api/v1/kye/entities/{id}/transactions: get: summary: Get entity transactions description: Returns transaction history for the entity tags: - Know Your Entity (KYE) parameters: - in: path name: id required: true schema: type: integer description: Entity ID - in: query name: limit schema: type: integer default: 100 description: Maximum number of transactions to return - in: query name: offset schema: type: integer default: 0 description: Pagination offset - in: query name: transaction_type schema: type: string description: Filter by transaction type - in: query name: start_date schema: type: string format: date-time description: Filter transactions from this date - in: query name: end_date schema: type: string format: date-time description: Filter transactions until this date responses: "200": description: Transaction history "500": description: Server error /api/v1/kye/entities/{id}/media: get: summary: Get entity media coverage description: Returns news articles and media mentions tags: - Know Your Entity (KYE) parameters: - in: path name: id required: true schema: type: integer description: Entity ID - in: query name: limit schema: type: integer default: 50 description: Maximum number of media items to return - in: query name: offset schema: type: integer default: 0 description: Pagination offset - in: query name: media_type schema: type: string description: Filter by media type (e.g., "news", "press_release", "blog") - in: query name: sentiment schema: type: string description: Filter by sentiment (e.g., "positive", "neutral", "negative") responses: "200": description: Media coverage "500": description: Server error /api/v1/kye/entities/{id}/statistics: get: summary: Get entity statistics description: Returns aggregated metrics and KPIs tags: - Know Your Entity (KYE) parameters: - in: path name: id required: true schema: type: integer description: Entity ID - in: query name: stat_type schema: type: string description: Filter by statistic type - in: query name: period schema: type: string description: Filter by period (e.g., "2026-Q1", "2026") responses: "200": description: Entity statistics "500": description: Server error /api/v1/kye/entities/{id}/risk-assessments: get: summary: Get entity risk assessments description: Returns risk scoring and analysis data tags: - Know Your Entity (KYE) parameters: - in: path name: id required: true schema: type: integer description: Entity ID - in: query name: latest schema: type: boolean description: Return only the latest risk assessment responses: "200": description: Risk assessment data "500": description: Server error /api/v1/kye/entities/{id}/risk-assessments/latest: get: summary: Get latest risk assessment description: Returns the most recent risk assessment for the entity tags: - Know Your Entity (KYE) parameters: - in: path name: id required: true schema: type: integer description: Entity ID responses: "200": description: Latest risk assessment data "404": description: No risk assessment found "500": description: Server error