> ## Documentation Index
> Fetch the complete documentation index at: https://docs.limitguard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Entity Check

> Full entity trust check.

Always runs country risk and sanctions; runs each other data source
whose identifier is provided (up to 8 total), computes a trust score,
assigns a cluster, and returns a recommendation.

`entity_name` and `country` are required; identifiers (kvk_number,
cbe_number, domain, iban, vat_number, wallet_address) are optional and
raise confidence. With none, only country risk and sanctions run (plus a
KVK name search for NL), at lower confidence.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/entity/check
openapi: 3.1.0
info:
  title: LimitGuard.ai
  description: Trust Intelligence API - Entity verification and risk scoring
  version: 0.1.0
servers:
  - url: https://api.limitguard.ai
security: []
paths:
  /v1/entity/check:
    post:
      summary: Entity Check
      description: |-
        Full entity trust check.

        Always runs country risk and sanctions; runs each other data source
        whose identifier is provided (up to 8 total), computes a trust score,
        assigns a cluster, and returns a recommendation.

        `entity_name` and `country` are required; identifiers (kvk_number,
        cbe_number, domain, iban, vat_number, wallet_address) are optional and
        raise confidence. With none, only country risk and sanctions run (plus a
        KVK name search for NL), at lower confidence.
      operationId: entity_check_v1_entity_check_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityCheckRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustResponse'
        '404':
          description: 'Not cached (X-Response-Quality: cached) — no data source was called'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - APIKeyHeader: []
components:
  schemas:
    EntityCheckRequest:
      properties:
        entity_name:
          type: string
          maxLength: 500
          minLength: 1
          title: Entity Name
          description: Legal entity name
        country:
          type: string
          maxLength: 2
          minLength: 2
          title: Country
          description: ISO 3166-1 alpha-2 country code
        kvk_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Kvk Number
          description: Dutch KVK number (8 digits)
        cbe_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Cbe Number
          description: 'Belgian CBE number (format: 0XXX.XXX.XXX)'
        domain:
          anyOf:
            - type: string
              maxLength: 253
            - type: 'null'
          title: Domain
          description: Entity website domain
        iban:
          anyOf:
            - type: string
              maxLength: 34
            - type: 'null'
          title: Iban
          description: IBAN for financial validation
        vat_number:
          anyOf:
            - type: string
              maxLength: 20
            - type: 'null'
          title: Vat Number
          description: EU VAT number
        wallet_address:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Wallet Address
          description: Crypto wallet address (format check only; no on-chain lookup)
        wallet_chain:
          anyOf:
            - type: string
            - type: 'null'
          title: Wallet Chain
          description: >-
            Blockchain the address is checked against (eth, base, polygon,
            arbitrum, btc, sol). Defaults to eth when omitted, so send btc or
            sol with a Bitcoin or Solana address
      additionalProperties: false
      type: object
      required:
        - entity_name
        - country
      title: EntityCheckRequest
      description: >-
        Full entity check request - always runs country risk and sanctions; runs
        each other data source whose identifier is supplied (up to 8 total).


        `entity_name` and `country` are required; identifiers (kvk_number,
        cbe_number, domain, iban, vat_number, wallet_address) are optional and
        raise confidence.
    TrustResponse:
      properties:
        trust_score:
          type: integer
          maximum: 100
          minimum: 0
          title: Trust Score
          description: Overall trust score
        trust_level:
          $ref: '#/components/schemas/TrustLevel'
        cluster:
          $ref: '#/components/schemas/Cluster'
        recommendation:
          $ref: '#/components/schemas/Recommendation'
        confidence:
          type: number
          maximum: 1
          minimum: 0
          title: Confidence
          description: Score confidence (0-1)
        top_factors:
          items:
            $ref: '#/components/schemas/TopFactor'
          type: array
          maxItems: 5
          title: Top Factors
        correlations:
          additionalProperties:
            type: number
          type: object
          title: Correlations
          description: Key correlations between signals
        sources_checked:
          type: integer
          minimum: 0
          title: Sources Checked
        processing_time_ms:
          type: integer
          minimum: 0
          title: Processing Time Ms
        enhanced_check_hint:
          anyOf:
            - $ref: '#/components/schemas/EnhancedCheckHint'
            - type: 'null'
          description: Suggested deeper check when recommendation is review or edd
        response_quality:
          type: string
          title: Response Quality
          description: 'Quality tier used for this response: cached, fresh, or enhanced'
          default: fresh
        cache_hit:
          type: boolean
          title: Cache Hit
          description: True if result was served from cache (cached tier)
          default: false
        source_data_dates:
          additionalProperties:
            type: string
          type: object
          title: Source Data Dates
          description: ISO timestamps when each data source was last retrieved
        disclaimers:
          items:
            type: string
          type: array
          title: Disclaimers
          description: Legal disclaimers for data sources used in this response
        version:
          type: string
          title: Version
          default: '1.0'
      type: object
      required:
        - trust_score
        - trust_level
        - cluster
        - recommendation
        - confidence
        - top_factors
        - sources_checked
        - processing_time_ms
      title: TrustResponse
      description: Full trust intelligence response from /v1/entity/check.
    ErrorResponse:
      properties:
        type:
          type: string
          title: Type
          default: about:blank
        title:
          type: string
          title: Title
        status:
          type: integer
          title: Status
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
        instance:
          anyOf:
            - type: string
            - type: 'null'
          title: Instance
      type: object
      required:
        - title
        - status
      title: ErrorResponse
      description: RFC 7807 Problem Details response.
    TrustLevel:
      type: string
      enum:
        - high
        - medium
        - low
        - critical
      title: TrustLevel
    Cluster:
      type: string
      enum:
        - established_eu_enterprise
        - established_eu_sme
        - verified_startup
        - unverified_new
        - high_risk_jurisdiction
        - sanctions_flagged
        - insufficient_data
        - mixed_signals
      title: Cluster
    Recommendation:
      type: string
      enum:
        - proceed
        - review
        - enhanced_due_diligence
        - block
      title: Recommendation
    TopFactor:
      properties:
        source:
          type: string
          title: Source
          description: Data source name
        signal:
          type: string
          title: Signal
          description: What was found
        impact:
          type: string
          title: Impact
          description: positive, negative, or neutral
        weight:
          type: number
          title: Weight
          description: Contribution to score (0-1)
      type: object
      required:
        - source
        - signal
        - impact
        - weight
      title: TopFactor
    EnhancedCheckHint:
      properties:
        endpoint:
          type: string
          title: Endpoint
          description: API endpoint for enhanced check
        quality:
          type: string
          title: Quality
          description: deep or extended
        price_usdc:
          type: number
          minimum: 0
          title: Price Usdc
          description: Cost via x402 payment
        adds:
          items:
            type: string
          type: array
          title: Adds
          description: Additional data sources included
        tiers:
          items:
            $ref: '#/components/schemas/DeepCheckTierOffer'
          type: array
          title: Tiers
          description: >-
            Every tier the endpoint sells; the top-level fields are the
            recommended one
        trigger_reason:
          type: string
          title: Trigger Reason
          description: Why this check was suggested
      type: object
      required:
        - endpoint
        - quality
        - price_usdc
        - adds
        - trigger_reason
      title: EnhancedCheckHint
      description: 'Upsell hint: suggests a deeper check endpoint when trust is ambiguous.'
    DeepCheckTierOffer:
      properties:
        quality:
          type: string
          title: Quality
          description: deep or extended
        response_quality:
          type: string
          title: Response Quality
          description: X-Response-Quality value that buys this tier (fresh or enhanced)
        price_usdc:
          type: number
          minimum: 0
          title: Price Usdc
          description: Cost via x402 payment
        adds:
          items:
            type: string
          type: array
          title: Adds
          description: Sources this tier actually returns
      type: object
      required:
        - quality
        - response_quality
        - price_usdc
        - adds
      title: DeepCheckTierOffer
      description: >-
        One purchasable /v1/entity/deep-check tier, as the upsell hint
        advertises it.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````