Testril's data-liquidity model connects paid materialization, titled coverage, subsequent paid reads, and wallet accounting. For agents, the useful questions are: what was bought, what is still covered, what was earned, and what can be claimed?
Inspect a wallet's accounting
{"tool":"inspect","arguments":{"subject":"nft","wallet":"<WALLET_ADDRESS>"}}
The response's nfts array has one card per claim-right the wallet holds. Each
card includes its nft, nft_chain_id, nft_contract, purchases, and
lifetime totals such as paid, refunded, cost, earned, claimed,
unclaimed, and pnl. NFT accounting is the deliberate exception to the
0.9.0 {atoms, usd} money object: its monetary values, including cost,
earned, and signed pnl, remain bare decimal strings of USDC atoms. Preserve
exact integer arithmetic. A purchase can appear at payment before data
delivery. Inspect the relevant job and coverage separately.
Each purchase records its quote ID, bound-function ID, original requested window, and accounting. The original window may include blocks already covered even though only unpaid holes were bought. Do not equate requested block count with charged block count.
Purchase earnings and read counts follow the blocks actually delivered. When
historical attribution cannot be reconstructed, a purchase omits earned,
pnl, and reads. On each card, sum known purchase earnings plus
earned_unattributed to reconcile lifetime earned; missing attribution does
not forfeit unclaimed rewards.
Data availability is a different ledger
Expiry and materialized geometry live on inspect subject:bound_function.
Wallet accounting is not a guarantee that all purchased blocks are currently
available. A purchase is titled before its claim-right mint finishes. During
that interval its card carries minting: true; retry inspection until its NFT
is ready.
Cards follow current ownership at the chain tip. The response's unavailable
array lists claim-rights on a chain that could not be read as
{nft, nft_chain_id, reason} beside cards that were read; it is not a zero
balance. The original payer may no longer hold a claim-right.
Claim existing rewards
{"tool":"claim_rewards","arguments":{"nft":"<CLAIM_RIGHT_ID>"}}
Inspect the selected card's unclaimed amount first. Keep the actual claim response and re-inspect the wallet afterward. The implementation handles eligible USDC atoms; it does not promise that a newly bought window will earn enough to cover its cost.
The minimum claim is 10,000 atoms ($0.01). Below that minimum, the response
reports claimed "0", reason: "below_minimum", and no transfer. A card still
marked minting: true returns claim_right_minting and pays nothing. Claims
follow current claim-right ownership; an unreadable ownership record is a
refusal, not proof that no rewards exist.
Rewards are paid on the NFT's recorded collection network even when read fees
were paid on other networks. The claim response's network, when present,
identifies that payout chain; claim_rewards takes no network selector. A
wallet can hold one claim-right per payment chain and can receive more through
on-chain transfers. Its first materialize payment on a payment chain starts a
claim-right there; if the wallet later no longer owns it, its next purchase on
that chain starts another. Keep a pending claim's network during recovery.
Paid reads and shared value
A paid read of titled coverage can contribute to holder accounting according to the implementation's pricing and overlap rules. A quote alone is not earned revenue. Coverage overlap, retention, prices, and the actual completed paid read matter. Use the current card and settlement records as evidence instead of projecting a yield from a marketing tagline.