BlvkWare Check API

openapi: 3.2.0
info:
  contact:
    email: agents@blvkware.dev
    name: BlvkWare
    url: https://blvkware.dev/hallux
  description: 'HALLUX is a negative dataset: a registry of identifiers that do not exist but that production models confidently emit.


    Every identifier resolves to exactly one verdict.


    | Verdict | Meaning | Agent action |

    |---|---|---|

    | `exists` | Present in the authoritative registry now. | Proceed. |

    | `deprecated` | Exists but is retired, yanked, or superseded. | Proceed with the replacement in `successor`. |

    | `absent` | Not present. No record of model emission. | Do not proceed. Likely a typo or a private name. |

    | `phantom` | Not present, and emitted by production models at or above the attestation threshold. | Do not proceed. This is a hallucination with a track record. |

    | `squat` | Was phantom, and has since been registered. | Do not install. Treat as hostile until proven otherwise. |

    | `unknown` | Namespace supported but registry unreachable, or identifier outside coverage. | Fail open or closed per your own policy. Do not treat as `exists`. |


    `squat` is the signal to care about: a name models invent, that a stranger has since registered, is a supply-chain attack caught before the first install.


    HALLUX never returns `exists` on uncertainty. When an upstream registry is unreachable the verdict is `unknown` with a reason code. Treating `unknown` as permission is a choice the caller makes.'
  license:
    name: Business Source License 1.1
    url: https://blvkware.dev/legal/bsl-1.1
  summary: Does this identifier actually exist? Call before install, import, fetch, or citation.
  title: HALLUX Check API
  version: 0.1.0
servers:
- description: production
  url: https://api.blvkware.dev/hallux/v1
tags:
- description: Resolve identifiers to verdicts.
  name: Check
paths:
  /check:
    post:
      description: 'The endpoint agent frameworks and CI pipelines should call: one round trip for a whole dependency set. Identifiers are resolved concurrently and the order of `results` matches the order of `identifiers`.'
      operationId: checkBatch
      requestBody:
        content:
          application/json:
            example:
              identifiers:
              - namespace: pkg.pypi
                value: requests-oauth2-helper
              - namespace: pkg.npm
                value: react-dom
              receipt: true
            schema:
              $ref: '#/components/schemas/CheckRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckResponse'
          description: Verdicts, in request order.
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
      summary: Check up to 100 identifiers
      tags:
      - Check
  /check/{namespace}/{value}:
    get:
      description: 'Single lookup. Free tier, no auth, no receipt. This exists so the cost of trying HALLUX is one curl command.


        Call this before running an install command, importing a module, fetching a documented endpoint, or emitting a citation.'
      operationId: checkIdentifier
      parameters:
      - description: 'Live namespaces: cite.doi, pkg.crates, pkg.go, pkg.maven, pkg.npm, pkg.nuget, pkg.pypi'
        in: path
        name: namespace
        required: true
        schema:
          enum:
          - cite.doi
          - pkg.crates
          - pkg.go
          - pkg.maven
          - pkg.npm
          - pkg.nuget
          - pkg.pypi
          type: string
      - description: The identifier, URL encoded.
        in: path
        name: value
        required: true
        schema:
          type: string
      - description: Skip nearest-name analysis. Slightly faster; no `successor` or `nearestExisting`.
        in: query
        name: nosuggest
        required: false
        schema:
          default: false
          type: boolean
      responses:
        '200':
          content:
            application/json:
              examples:
                exists:
                  summary: Proceed
                  value:
                    checkedAt: '2026-09-20T14:22:08Z'
                    confidence: 1
                    evidence:
                      registryCheckedAt: '2026-09-20T14:22:08Z'
                      registryStatus: found
                    namespace: pkg.npm
                    recommendation: proceed
                    value: react-dom
                    verdict: exists
                phantom:
                  summary: A hallucination with a track record
                  value:
                    checkedAt: '2026-09-20T14:22:08Z'
                    confidence: 0.97
                    evidence:
                      attestations: 412
                      firstObserved: '2025-11-04'
                      lastObserved: '2026-09-19'
                      nearestExisting:
                      - requests-oauthlib
                      observedFrom:
                      - gpt-class
                      - claude-class
                      - llama-class
                      registryCheckedAt: '2026-09-20T14:22:08Z'
                      registryStatus: not_found
                    namespace: pkg.pypi
                    recommendation: do_not_install
                    successor: requests-oauthlib
                    value: requests-oauth2-helper
                    verdict: phantom
                squat:
                  summary: Slopsquatting in progress
                  value:
                    checkedAt: '2026-09-20T14:22:08Z'
                    confidence: 0.99
                    evidence:
                      attestationsBeforeRegistration: 1188
                      phantomSince: '2026-01-18'
                      publisherPriorPackages: 0
                      registeredAt: '2026-06-02'
                      registryCheckedAt: '2026-09-20T14:22:08Z'
                      registryStatus: found
                    namespace: pkg.npm
                    recommendation: block
                    successor: openai
                    value: openai-node-sdk
                    verdict: squat
              schema:
                $ref: '#/components/schemas/Result'
          description: A verdict.
        '402':
          $ref: '#/components/responses/PaymentRequired'
      summary: Check one identifier
      tags:
      - Check
components:
  responses:
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
      description: The request could not be understood.
    PaymentRequired:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
      description: The open allowance is spent. The body names the price, asset and networks.
  schemas:
    CheckRequest:
      properties:
        identifiers:
          items:
            $ref: '#/components/schemas/Identifier'
          maxItems: 100
          minItems: 1
          type: array
        receipt:
          default: false
          description: Request an Ed25519 receipt over `checkedAt` and `results`. Paid tier.
          type: boolean
      required:
      - identifiers
      type: object
    CheckResponse:
      properties:
        checkedAt:
          format: date-time
          type: string
        receipt:
          $ref: '#/components/schemas/Receipt'
        results:
          items:
            $ref: '#/components/schemas/Result'
          type: array
        safeToProceed:
          type: boolean
        summary:
          type: object
      required:
      - checkedAt
      - results
      type: object
    Problem:
      properties:
        error:
          type: string
        message:
          type: string
      type: object
    Receipt:
      description: Ed25519 signature over the RFC 8785 canonical JSON of `checkedAt` and `results`. Verify against https://blvkware.dev/.well-known/blvkware-attestation.pub
      properties:
        alg:
          const: Ed25519
          type: string
        canonicalization:
          const: RFC8785
          type: string
        covers:
          items:
            type: string
          type: array
        keyId:
          type: string
        signature:
          type: string
      type: object
    Evidence:
      description: Everything that was true at decision time.
      properties:
        attestations:
          type: integer
        attestationsBeforeRegistration:
          type: integer
        firstObserved:
          type: string
        lastObserved:
          type: string
        nearestExisting:
          items:
            type: string
          type: array
        note:
          type: string
        observedFrom:
          items:
            type: string
          type: array
        phantomSince:
          type: string
        publisherPriorPackages:
          type: integer
        registeredAt:
          type: string
        registryCheckedAt:
          format: date-time
          type: string
        registryStatus:
          enum:
          - found
          - not_found
          - deprecated
          - unreachable
          type: string
        stale:
          type: boolean
      type: object
    Result:
      properties:
        confidence:
          maximum: 1
          minimum: 0
          type: number
        evidence:
          $ref: '#/components/schemas/Evidence'
        namespace:
          type: string
        reason:
          description: Only on the `unknown` verdict.
          enum:
          - namespace_unsupported
          - registry_unreachable
          - malformed_identifier
          - quota_exceeded
          type: string
        recommendation:
          type: string
        successor:
          description: The identifier to use instead. Present only when it can be named with confidence.
          type: string
        value:
          type: string
        verdict:
          enum:
          - exists
          - deprecated
          - absent
          - phantom
          - squat
          - unknown
          type: string
      required:
      - namespace
      - value
      - verdict
      - confidence
      type: object
    Identifier:
      properties:
        namespace:
          enum:
          - cite.doi
          - pkg.crates
          - pkg.go
          - pkg.maven
          - pkg.npm
          - pkg.nuget
          - pkg.pypi
          type: string
        value:
          maxLength: 512
          type: string
      required:
      - namespace
      - value
      type: object
externalDocs:
  description: Specification, including corpus methodology
  url: https://blvkware.dev/docs/hallux-spec
x-billingNeutrality: HALLUX is never paid more because it blocked you. Billing is a function of identifiers submitted, not of the verdicts returned. A verification vendor paid per finding has a commercial reason to find more.
x-freeTier:
  authentication: none
  identifiersPerDay: 500
  receipts: false
x-methodology:
  absenceConfirmation:
    checks: 2
    minimumSpanHours: 24
  decayDays: 180
  phantomThreshold:
    attestationUnit: one model, one prompt class, one day
    attestations: 10
    modelFamilies: 2
  publicCorpusWindowDays: 30
x-payment:
  amount: '0.0008'
  asset: USDC
  billingNeutrality: HALLUX is never paid more because it blocked you. Billing is a function of identifiers submitted, not of the verdicts returned. A verification vendor paid per finding has a commercial reason to find more.
  cap:
    identifiersPerMonth: 373750
    thenMonthlyUsd: '299'
  currency: USD
  freeTier: 500 identifiers per day, unauthenticated, no signed receipt; all open-tier traffic shares a pool of 50,000 identifiers per day
  model: per-unit with a flat cap
  networks:
  - base
  - solana
  rails:
  - x402
  - stripe-mpp
  settlementConfigured: false
  tiers:
  - buyer: any agent or developer, with no account
    dailyIdentifierLimit: 500
    id: open
    includedWatches: 0
    includes:
    - Single-lookup GET, unauthenticated
    - 500 identifiers per day
    - Every verdict, including phantom and squat
    - Nearest-name suggestions and successors
    monthlyUsd: '0'
    name: Open
    perIdentifierUsd: '0'
    receipts: false
    sharedDailyPool: 50000
  - buyer: an individual agent or a small team, pay as you go
    id: metered
    includedWatches: 0
    includes:
    - Everything in Open
    - Batch endpoint, up to 100 identifiers per request
    - Signed Ed25519 receipts
    - Watches at $0.02 per identifier per month
    - Spend capped at the Team price ($299/month)
    name: Metered
    perIdentifierUsd: '0.0008'
    receipts: true
  - annualUsd: '2990'
    buyer: a company putting HALLUX in CI or in an internal agent
    id: team
    includedWatches: 100
    includes:
    - Everything in Metered, unmetered
    - 100 watched identifiers included
    - Private namespace prefixes excluded from checks and from billing
    - Receipts, and receipt verification support
    monthlyUsd: '299'
    name: Team
    receipts: true
  - annualUsd: '15000'
    buyer: registries, IDE vendors, CI platforms, security vendors, insurers
    id: feed
    includes:
    - Everything in Team
    - The full phantom ledger, not the rolling 30-day window
    - Complete history, including archived phantoms
    - Per-model attribution on every attestation
    - Live webhook stream of every verdict transition
    - Unlimited watches
    - Licence to surface findings inside your own product
    monthlyUsd: '1500'
    name: Feed
    receipts: true
  - buyer: a platform shipping HALLUX inside its own product
    id: embedded
    includes:
    - Self-hosted or white-labelled
    - Business Source Licence 1.1 commercial grant
    - Corpus delivered on your own schedule and infrastructure
    - Negotiated support terms
    monthlyUsd: from 2500
    name: Embedded
    receipts: true
  unit: identifier