# PDF Citation Evidence

POST https://playbrightgaming.com/agent-services-mainnet/pdf-citation-evidence
Testnet: POST https://playbrightgaming.com/agent-services/pdf-citation-evidence
Free metadata: https://playbrightgaming.com/agent-services-mainnet/pdf-citation-evidence/service-info

Price: $0.003 USDC (3000 atomic), x402 v2 exact, Base mainnet eip155:8453. The Base-Sepolia test-USDC lane is eip155:84532 at the same 3000 atomic. Runtime HTTP 402 PAYMENT-REQUIRED is authoritative. No account or API key. No funded mainnet purchase is claimed.

## Input and meaning

Send exactly one PDF as either `pdfBase64` (canonical base64 in a JSON envelope; no multipart) or `url` (one explicit public HTTPS PDF URL). Never supply both. Optional `quotes` contains at most 16 exact, case-sensitive nonblank strings, each at most 512 Unicode code points. Optional `pageRanges` contains at most 25 inclusive `{start:1,end:3}` pairs. Selected pages are sorted and deduplicated; original one-based page numbers are retained. Unknown input fields are rejected.

The decoded PDF is at most 2 MiB (2,097,152 bytes). The entire PDF is at most 25 pages, including pages outside the requested ranges. Input JSON is at most 2,810,000 bytes. An invalid range or a limit failure cannot be sold as a partial success.

Illustrative URL input (the URL is a shape example, not a claim that example.com hosts this PDF):
```json
{"url":"https://example.com/document.pdf","quotes":["Exact quoted words"],"pageRanges":[{"start":1,"end":2}]}
```
For an upload, replace `url` with `pdfBase64` containing the exact PDF's canonical base64. The accepted OpenAPI includes a complete synthetic upload example.

PASS means supported selected embedded text was extracted within the bounds and all requested exact quotes were found. Without quote assertions, PASS means extraction succeeded within this profile. Deterministic quote FAIL means a requested quote was absent from complete selected extracted text. Neither verdict judges the document's claims. Empty or image-only selected pages are NEEDS_OCR / INCONCLUSIVE. Encrypted PDFs, unsupported font/encoding/filter/predictor/profile, parser warnings, resource/decompression/work/deadline limits and incomplete extraction remain no-charge uncertainty or declared failures, as appropriate. No partial-success laundering of a limit failure is permitted.

## Evidence, hashes and offsets

The response contains `schemaVersion`, `evidence`, `evidenceId`, `observedAt`, `fetchedAt`, and `receipt`. Evidence contains the verdict/code, bounded document metadata, source observations, selected per-page embedded text, quote matches, selected page numbers, warnings, parser identity and explicit hash semantics. Complete page/PDF/HTTP byte counts are supplied only when actually known; incomplete or untrusted totals remain null, never invented.

Document SHA-256 is the exact PDF bytes after HTTP Content-Encoding decoding; uploads use the exact supplied bytes. Page SHA-256 is UTF-8 extracted text after CRLF/CR -> LF only. There is no other whitespace or Unicode normalization, no serialized-page-object hash and no rendered-image hash. Raw HTTP SHA-256 is the complete final entity before Content-Encoding decode, excluding headers and HTTP transfer framing. Gzip retains separate raw and decoded hashes; incomplete bodies do not receive a fabricated complete-body hash.

Offsets are zero-based Unicode code points with half-open `[start,end)` spans into returned page text. Exact quote matches include overlapping occurrences, searched separately on each selected page; no quote may cross a page boundary. At most 256 occurrences per quote are returned; overflow refuses the response without partial success. A citation reference binds document hash + original page number + text hash + start/end offsets. It is a stable content reference, not an origin-authenticated URL.

The evidence ID hashes the complete evidence object using sorted-key-json-v1: finite JSON, keys sorted in UTF-16 order and array order retained. The ID binds parser version, request hash and extraction results but excludes observation times. The separate unsigned receipt covers the top-level payload except `receipt`, including `observedAt` and `fetchedAt`; `signature` is null. Observed time is service-start UTC; fetched time is local arrival of the complete final HTTP entity, including an HTTP error entity if present. These times are observations, not attestations. Independent full reproduction needs the exact PDF and original request; checking only the receipt proves internal checksum consistency. A verifier must not silently fetch a replacement URL body.

## Bounded parser and URL transport

Parser behavior is pinned to pypdf 6.1.1. Every parse uses a disposable Python process in a Windows Job Object with a 192 MiB process committed-memory cap, 4 user-mode CPU seconds, a 5.5-second wall kill, one active child process and kill on job close. Parser stdout and parent final JSON are each capped at 1 MiB. PDF service work deadline is 13 seconds, unchanged from the accepted parser service. A separate outer paid-request timeout of 25 seconds includes bounded payment/recovery/storage; it does not extend the PDF service work deadline. Service admission allows 2 active requests in one singleton instance with no queue; cancellation holds the slot until process/pipe closure is confirmed. The parent Node process has bounded buffers but no separately measured OS memory cap.

The parser audit hook denies network/process operations and filesystem writes, and rejects reads outside installed runtime/library paths. This static boundary is not a complete OS filesystem exploit-sandbox claim. No JavaScript/actions/attachments execute; no PDF links are followed. No parser file output, OCR, image codecs, image rendering or layout reconstruction is invoked.

The conservative profile accepts supported PDF 1.0-1.7 structure, strict cross references, validated page trees, uncompressed/Flate streams without predictors/external streams, and supported standard fonts or explicit ToUnicode maps. It bounds indexed/lexical objects (8,000), indirect dereferences (40,000), page-tree depth (32), form depth (16), content operations (40,000), per decoded/content stream work (1 MiB), aggregate decoded/content work (8 MiB), extracted code points per page (32,000) and per document (160,000). Conservative work accounting may count a stream during both decoding and inspection; OS resource limits contain work preceding semantic checks.

URL mode is HTTPS/443 only and public addresses only. Every DNS A/AAAA answer is checked, a vetted destination is pinned, the connected peer is checked, normal TLS validation is retained and each redirect is revalidated. At most 3 redirects / 4 requests, 16 KiB headers per hop, a 7-second upstream deadline, a 2 MiB raw entity cap and a 2 MiB decoded PDF cap apply. URL credentials and sensitive query keys are rejected. Only service-controlled credential-free headers are sent; buyer credentials/cookies and arbitrary caller headers are never forwarded. Only complete HTTP 200 entities with identity or gzip Content-Encoding can supply a PDF. Content type is observed; PDF signature/parser validity determine acceptance. Unsupported responses are INCONCLUSIVE.

## Billing and durable replay

Chargeable means delivered, serialized, validated evidence with no INCONCLUSIVE state. PASS and a deterministic exact-quote FAIL may cost 3000 atomic. NEEDS_OCR / INCONCLUSIVE is NOT chargeable. Invalid, oversize, resource-limit, busy, internal and corrupted-evidence failures are NOT chargeable. A signed authorization is verified before execution; a chargeable result is durably prepared before settlement. Authenticated complete no-charge outcomes remain durable and replayable after accepted request binding and successful storage, with no settlement. Incomplete transport, no accepted authorization, or unavailable storage cannot promise retained delivered bytes; these failures never settle.

Replay the byte-identical original request with the same signed authorization to obtain the same order, response body bytes/hash, evidence ID and receipt identity. Exact replay performs no PDF refetch, reparse, reexecution or resettlement and emits no second payment-response header. A changed request under a used authorization is rejected. Persist the original request and response locally. If first delivery is uncertain, do not create a fresh authorization merely to retry; retain the same request/authorization. An uncertain settlement is held for read-only nonce/transaction recovery and is never blindly resubmitted. These seller durability terms do not attest to PDF origin or document truth.

## Mandatory non-claims

No OCR. No image rendering. No visual fidelity claim. No semantic/legal truth claim. No provider/origin/timestamp attestation. Unsigned evidence checksum only. Embedded or hidden text can differ from the visible page and unusual reading order remains possible even without warnings. No document truth analysis, security audit, legal judgment or authenticity certification is provided.

Full schemas: https://playbrightgaming.com/openapi.json
Catalog: https://playbrightgaming.com/agents/services.json