Tip gems

gems_adjust with an audit reason. Rate-limited (~5/min sustained, 20 burst). High-sensitivity scope requires explicit parent consent at OAuth.

Adjust gems

API call

gems_adjust({
childId: "019c5228-...",
delta: 5,
reason: "helped set the table without being asked"
}, headers={"Idempotency-Key": "sha256(childId+delta+reason+date)"})

The reason field

Every gems_adjust writes an audit row with the supplied reason. Parents see these in the transaction log. Write a reason that makes sense to the parent when they review it later: "lunch had a vegetable (auto-checked)" not "vision_pass=true".

Idempotency

Use the Idempotency-Key header on every call. Hash your payload (childId + delta + reason + date is a good key). Same key with the same envelope produces the same result without double-spending.

Rate limits

~5 adjustments/min sustained
20 burst
Rate-limit errors return { "error": "RATE_LIMITED", "retryAfter": N }

Surface rate-limit errors to the parent. Do not silently retry.

Negative deltas

You can remove gems with a negative delta. Same audit trail, same rate limits. Use sparingly and with a clear reason.

infoThe gems:adjust scope is high-sensitivity. The parent must explicitly opt in by name at OAuth time (not just bulk-approve). If your token lacks this scope, gems_adjust will fail with a clear error.