> Current public reference note (2026-10-07): this document preserves the earlier private fixture contract. A subsequent authenticated non-money StatsBin connection is deployed for invited integrations. Its access details and credentials remain private. Statements below about unconfigured production URL/authentication describe the original fixture scope. Payable services, recipient configuration, and payment activation remain absent. # StatsBin customer-zero contract v2 (proposed, not deployed) ## Public inspection and machine value On 2026-09-25 the bounded public review fetched only `/robots.txt`, `/` and `/supply` from StatsBin. The home/supply pages are HTML with Next.js asset markers; robots permits pages but disallows `/api/`. No documented API link or network JSON route was found in those pages. No guessed API path, validator link/RPC, private server, credentials or administration interface was accessed. This is **no suitable machine endpoint found within the reviewed public surface**, not proof no API exists. [Bounded evidence](evidence/statsbin-public-review-2026-09-25.json). The [public home page](https://statsbin.com/) exposes height, total/circulating LUNC supply and other analytics; [supply](https://statsbin.com/supply) supports the choice of a normalized height/supply snapshot. Prices, burn interpretations and validator-specific data are excluded from this first resource. The observed public values are rounded presentation data, not a source of inferred micro-unit precision. Production must use StatsBin's existing authorized cached source with known timestamps and exact base-unit values; unavailable precision/freshness produces an error. No new validator/RPC dependency is permitted. An agent could buy a bounded, normalized, versioned observation for a report, network-context display, or another data service without scraping HTML and guessing units/timestamps. The service value would be serialization, freshness validation and reliable delivery/status, not exclusive access to otherwise public facts. Willingness to pay is unproven. It must not be used as a consensus trust anchor, payment proof, gas estimate or authenticated chain-parameter source. ## Version and proposed routes The earlier unimplemented v1 resource used decimal LUNC text. Preserve it as a historical draft. This v2 contract uses integer-string **uluna** and explicit request/response digests. HTTP namespace v1 is the first proposed route API; `schemaVersion:"2"` identifies this corrected payload independently. No deployed consumer exists to migrate. `/api/` fits the observed public routing boundary; the exact server directory layout remains unknown until StatsBin's own project is inspected. These are proposed paths, not discovered endpoints. | Method/path | Purpose | Caching | | --- | --- | --- | | GET `/api/v1/luncagent/network-snapshot` | Authenticated read-only current snapshot | private, max-age ≤30 seconds, must-revalidate | | POST `/api/v1/luncagent/network-snapshot/deliveries` | Durable idempotent resource delivery | private, no-store | | GET `/api/v1/luncagent/network-snapshot/deliveries/{deliveryId}` | Authoritative stored outcome | private, no-store | The data concerns the public network, but these integration routes require HMAC. They are not payable routes, do not charge a caller and must not be mounted in LUNCAgent public discovery yet. HTTPS is mandatory outside the loopback fixture. No production base URL, recipient or authentication secret is configured. Canonical source: [JSON Schema](schemas/statsbin-customer-zero-v2.schema.json). `additionalProperties:false` applies throughout. HTTP resource/status/error bodies are tested against it; semantic checks below are required in addition. ## Deterministic resource Canonical encoding is compact UTF-8 JSON, no BOM/newline, no insignificant spaces, exact field order as below (synthetic illustrative values): ```json {"schemaVersion":"2","network":"cosmos:columbus-5","chainId":"columbus-5","source":"statsbin-public","sourceUrl":"https://statsbin.com/","observedAt":"2026-09-25T12:00:00.000Z","expiresAt":"2026-09-25T12:02:00.000Z","height":"30555978","asset":{"denom":"uluna","decimals":6},"supplyUluna":{"total":"6448067570006000000","circulating":"5490664007823000000"}} ``` Money uses canonical nonnegative integer strings (maximum 30 digits), no floating point, sign, leading zeros or exponent; 1 LUNC = 1000000 uluna. Height is a positive integer string, up to 20 digits. Circulating supply cannot exceed total. No null, missing or guessed source metrics, private fields or validator identifiers. `observedAt` is the source observation time, UTC milliseconds, never fetch time substituted for old data. For an aggregate, conservatively use the oldest relevant source observation; do not imply the height authenticates each metric. Confirm source chain identity from the existing cache. `expiresAt=observedAt+120000ms`. Future observations and `now>=expiresAt` fail closed; current snapshot GET returns 503 RESOURCE_UNAVAILABLE. Invalid calendars are rejected. Same source observation produces identical bytes and digest independent of response time. ETag is quoted lowercase SHA-256 of canonical resource bytes. Max-age is `min(30,floor((expiresAt-now)/1000))`. Authenticate and check freshness **before** If-None-Match; exact matching ETag returns empty 304, stale data never returns 304. Responses are private-cacheable because authentication is required; shared CDN caching is prohibited. Errors and delivery/status are no-store. Clients must still enforce expiry; a replayed stored delivery may now contain expired data. ## HMAC over HTTPS Headers: `X-Luncagent-Credential` (UUID), `X-Luncagent-Timestamp` (Unix milliseconds as integer string), `X-Luncagent-Nonce` (fresh unpredictable 22–96-character base64url/alphanumeric token), `X-Luncagent-Scope`, `X-Luncagent-Signature` (lowercase HMAC-SHA256 hex). Scope is `statsbin:public-network-metadata:read`. Maximum request body 65536 bytes; GET body must be empty. No query string, redirect, method override, path rewrite, percent-encoded alternate route or trailing slash. Trusted edge must preserve the signed original route and bytes. Sign the exact eight UTF-8 lines below with LF separators and no trailing LF: ```text LUNCAGENT-MERCHANT-HMAC-V1 statsbin:public-network-metadata:read ``` Use at least 32 random key bytes when separately authorized later; no production key is generated now. Constant-time MAC comparison, maximum absolute skew 60000ms, active credential validity and scope checks are required. Atomically recheck revocation/validity and insert nonce using database time; replay uniqueness is `(integrationId,nonce)` across credentials and rotations. Fail closed on store failure; never fallback to process memory in production. Do not TTL-prune nonce or delivery safety history without a separately reviewed retention policy. Rotation stages a new credential/key under the same integration with bounded overlap, switches clients, then revokes the old credential. A new key does not reset nonce history or delivery ownership. Revocation is checked on every call, including GET/304. Keys stay in protected secret storage, never the metadata database, logs, URLs or payloads. Do not log bodies/signatures/credential headers. ## Durable delivery and status LUNCAgent allocates stable `deliveryId` and `quoteId` before quoting, persists the request, and binds its digest into quote/outbox. The canonical digest input is compact JSON in this exact order: ```json {"schemaVersion":"2","deliveryId":"delivery_one","quoteId":"quote_one","resourceKey":"statsbin-public-network-metadata-v2"} ``` POST adds `requestDigest`, lowercase SHA-256 of those bytes. StatsBin recomputes it. A durable unique key `(integrationId,deliveryId)` atomically stores the winning request digest and complete immutable outcome bytes. Repeating the same ID/digest returns those exact bytes; a different valid digest returns 409 IDEMPOTENCY_CONFLICT. Concurrent losers return the committed winner. Metadata acquisition is read-only; outcome persistence is the one delivery effect. | Outcome | HTTP | Meaning | | --- | --- | --- | | APPLIED | 200 | Stored resource, requestDigest, responseDigest and appliedAt | | NOT_APPLIED | 422 | Durable terminal rejection: RESOURCE_UNAVAILABLE, checkedAt and requestDigest | | UNKNOWN / NOT_SEEN | 202 | No authoritative completed row; an in-flight operation may exist | | UNKNOWN / STATUS_UNAVAILABLE | 503 | Outcome store unavailable; no absence inferred | NOT_APPLIED is reserved for a persisted terminal refusal, not a failed query or missing row. A stale/invalid/unavailable source creates that immutable refusal; the same ID cannot later turn into APPLIED when the source recovers. GET does not create deliveries or tombstones. `responseDigest` is SHA-256 of the canonical resource bytes, not the mutable status lookup time. APPLIED and NOT_APPLIED replay byte-for-byte; UNKNOWN checkedAt may change. Applied resources remain immutable even after expiry: recovery proves the original delivery, not current freshness. On response loss, retry/status-query only the original ID with a **new HMAC nonce**. No UNKNOWN, timeout, missing row or delivery failure permits a second payment. LUNCAgent retains the original payment/proof/receipt and reconciles its outbox. Terminal non-delivery requires a separately governed refund/support decision; this contract adds no refund or replacement-spending authority. Errors are `{schemaVersion:"2",error:{code,message}}`, generic fixed messages. 400 INVALID_REQUEST; 401 UNAUTHENTICATED (also replay/revoked credentials); 403 FORBIDDEN (wrong scope); 404 NOT_FOUND; 409 IDEMPOTENCY_CONFLICT; 503 RESOURCE_UNAVAILABLE for current-resource GET. Oversized transport bodies return 413 PAYLOAD_TOO_LARGE; transport failure returns 503 TRANSPORT_UNAVAILABLE, both using the same no-store JSON error envelope. Clients fail closed on either. No exception/body/credential reflection. ## Disabled service definition and evidence boundaries `stagedStatsBinService` defines service/version/merchant/schema/freshness/asset/ network/protocol/delivery metadata in private code. Pilot resource price remains 1000000 uluna; `controlled-pilot-1` fees remain disabled. Endpoint and merchant recipient are null; Terra Classic x402 remains experimental/unavailable. No production catalogue/payment route is changed or advertised operational. The loopback HTTP fixture uses exact contracts and PostgreSQL delivery/nonce records in the complete isolated-chain rehearsal. Synthetic metadata refers to columbus-5 only as informational fixture content; payment is solely on luncagent-local-1. Fixture data is not a fetched current StatsBin observation. Local HTTP is a test seam, not a permitted production transport downgrade.