gems: Reference

The resource

URI: sprout://child/{childId}/gems

Required scope: gems:read

The current gem balance and most recent transactions for one kid. Subscribers receive a push within ~1 second of any gem balance change (task reward, manual adjust, reward redemption, screen-time spend).

When it pushes

Task completion awards gems (via rewardSpec.gems).
Manual gems.adjust succeeds.
Reward redemption deducts gems.
Screen-time approval deducts gems.

Push payload

The notification frame on the SSE stream:

JSON-RPC

{
  "jsonrpc": "2.0",
  "method": "notifications/resources/updated",
  "params": { "uri": "sprout://child//gems" }
}

The frame only names the URI that changed. To get the new state, your agent calls resources/read <uri>.

Read shape

Calling resources/read sprout://child/{childId}/gems returns:

JSON

{
  "childId": "uuid",
  "balance": 42,
  "asOf": "2026-05-23T14:02:00Z",
  "recentTransactions": [
    {
      "transactionId": "uuid",
      "delta": 3,
      "reason": "Daily check-in",
      "source": "task" | "manual" | "reward" | "screentime",
      "timestamp": "2026-05-23T14:02:00Z"
    }
  ]
}

Subscribe / unsubscribe

Shell

resources/subscribe sprout://child/{childId}/gems
# ... server holds the SSE stream open, pushes on every change ...
resources/unsubscribe sprout://child/{childId}/gems

Notes

Subscribing to this resource is the cheapest way for your agent to keep a running picture of a kid's economy without polling. For the full ledger, use gems.list_transactions on demand.