> For the complete documentation index, see [llms.txt](https://nytshift.gitbook.io/nytshift-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nytshift.gitbook.io/nytshift-docs/agents-identity-and-data/commercial-revenue.md).

# Commercial revenue and usage

Use this runbook when reviewing NIGHTSHIFT revenue, reconciling a commercial export or investigating `SIGNER REVENUE UNAVAILABLE` in the terminal.

## Read the statement

1. Start the supervised localhost runtime and confirm `pnpm local:health` is safe.
2. Open Terminal **Safety settings** and unlock the local operator session.
3. Read **Commercial control**:
   * **Earned builder fees** are exact fee-token totals from retained Hyperliquid fill evidence.
   * **Claim state not reconciled** means NIGHTSHIFT has not compared those fills with Hyperliquid referral claims or withdrawals.
   * **Agent proposals / automation** are metered attempts, not currency.
   * **Payment collection unconfigured** means premium revenue is zero for NIGHTSHIFT accounting purposes because no payment proof exists.
4. Use **Copy statement** only into operator-controlled accounting storage. The digest checks local content consistency; it is not third-party attestation.

The browser calls operator-only `GET /api/commercial`. That route reads premium checkpoints locally and calls authenticated loopback `GET /v1/revenue/summary` on the signer. Neither response contains account, order, CLOID, trade, wallet, builder address, customer, license or credential identifiers.

## Coverage interpretation

`bounded-local` means all retained positive builder-fee fills in this signer database were scanned exactly. It does not mean all Hyperliquid activity is present. Each order must first have been submitted with a retained NIGHTSHIFT scope and reconciled through the documented user-fill endpoint, whose available history is bounded to the most recent 10,000 fills per account.

Hyperliquid currently documents lowercase-address daily LZ4 builder-fill archives and builder totals in referral state. NIGHTSHIFT does not ingest either yet because the daily CSV schema and claim-accounting semantics are not pinned in a reviewed contract. Do not manually merge them into the SQLite store.

## Failure response

* `OPERATOR SESSION REQUIRED`: unlock a new 15-minute local session.
* `SIGNER REVENUE UNAVAILABLE`: confirm `pnpm signer:health`, loopback URL/token configuration and execution-store health. No premium state or fee total should be inferred from the failure.
* `SIGNER REVENUE RESPONSE INVALID`: treat signer/web contract versions as mismatched or the store projection as unsafe. Stop release work, run `pnpm contracts:check`, `pnpm test:py` and `pnpm handoff:check`, then inspect the diff.
* Empty totals with zero fills are valid. A configured builder rate or accepted order does not create revenue.

Protect the revenue ledger through the separate stopped-signer snapshot workflow in [`arcus-execution-store-recovery.md`](/nytshift-docs/arcus/arcus-execution-store-recovery.md). Public checkpoint backups do not contain the signer database.

## Before collecting premium payments

Choose a payment provider and pricing explicitly. The later billing control plane must verify provider webhooks, make issuance/renewal/revocation idempotent, preserve payment and trading authority as separate gates, reconcile central usage across installations and handle tax/refund/chargeback state. Until that work exists, do not mark a signed license or local usage as paid revenue.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://nytshift.gitbook.io/nytshift-docs/agents-identity-and-data/commercial-revenue.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.