Reward
What kids work for. Gems earned per task, spent on parent-defined rewards. The loop that makes habits stick.
The reward is what kids work for. Gems earned for completing tasks; gems spent on parent-defined rewards or to unlock screen-time. The loop is what makes any habit framework stick: the kid sees a path from doing the thing to getting something they want.
Where you'll see this
In the wild: Tip gems (Build) ยท Screen-time
Shape
Two parts: the gem economy (numbers) and the reward catalog (what they buy).
- Gems: earned per
taskcompletion viarewardSpec.gems, or adjusted manually viagems.adjust. Balance is read withgems.query_balance; transactions withgems.list_transactions. - Reward catalog: parent-defined entries the kid can redeem. Each entry has a name, cost in gems, optional emoji, and a redemption flow.
A worked example
The two ways gems land. Auto-awarded via task.create:
task.create({
name: "Math drill",
assignChildIds: ["<childId>"],
runMode: "canvas",
canvasSpec: { canvasId: "<canvas>" },
assignmentSkillId: "<skill>",
scheduleSpec: { taskType: "onetime", oneTimeDate: "2026-05-25" },
rewardSpec: { gems: 10 }
})Or manually adjusted for one-off moments:
gems.adjust({
childId: "<childId>",
delta: 5,
reason: "Helped grandma with groceries"
})
# Confirm with parent before any delta > 20 (positive or negative).When to use it
Tag gems on every task that takes real effort. Even a small reward (3 gems for a daily check-in) keeps the loop alive. Reserve gems.adjust for one-off moments (bonus for outsized effort, deduction for a missed agreement); confirm with the parent before large positive or negative deltas.
Use the reward catalog to make the gem economy concrete. A balance without a redemption path stops mattering to the kid; even one or two visible rewards make the gems feel real.
Common errors
BAD_INPUT: non-integer gem amount, negativerewardSpec.gems, or attempts to redeem a reward the family doesn't have.PERMISSION_DENIED,gems.adjustrequires the high-sensitivitygems:adjustscope; missing scope rejects.
Related tools
gems.query_balance: current balance per kid.gems.list_transactions: the ledger.gems.adjust: manual delta. High-sensitivity; confirm with parent for >20.reward.create/reward.update: catalog management.reward.list: read catalog.
Roadmap for this noun
- Soon Reward catalogs that families can publish and lift from each other.
- Soon Variable currencies: beyond gems, for families that want to layer in non-economic rewards (stickers, badges, perks).