BlvkWare Corpus 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 Corpus API
  version: 0.1.0
servers:
- description: production
  url: https://api.blvkware.dev/hallux/v1
tags:
- description: The phantom ledger itself.
  name: corpus
paths:
  /corpus:
    get:
      description: JSONL. Rolling 30-day window free with attribution; full history, model attribution and live feed under commercial licence.
      operationId: streamCorpus
      parameters:
      - in: query
        name: namespace
        schema:
          enum:
          - cite.doi
          - pkg.crates
          - pkg.go
          - pkg.maven
          - pkg.npm
          - pkg.nuget
          - pkg.pypi
          type: string
      - in: query
        name: state
        schema:
          enum:
          - phantom
          - squat
          type: string
      - description: Full history. Requires a licence.
        in: query
        name: full
        schema:
          default: false
          type: boolean
      responses:
        '200':
          content:
            application/jsonl:
              schema:
                type: string
          description: JSONL stream.
        '402':
          $ref: '#/components/responses/PaymentRequired'
      summary: Stream the phantom ledger
      tags:
      - corpus
components:
  responses:
    PaymentRequired:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
      description: The open allowance is spent. The body names the price, asset and networks.
  schemas:
    Problem:
      properties:
        error:
          type: string
        message:
          type: string
      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