# TokenAccount

object type

A TokenAccount — \*\*the ONE-per-GROUP token wallet / platform billing unit\*\* (AT/stack billing of MERCHANTS; 1 org or 100 orgs share ONE pool — is the billing aggregation point; per-org figures are consumption ATTRIBUTION, reporting-only). The wallet is a GROUP-scoped SINGLETON enforced by the tokenAccountSingleton UNIQ marker minted IN the create txn. \*\*Wallet existence IS the metering arm\*\* (ruling): no wallet ⇒ the group is unbilled (the DVLP posture); opening one arms the rater (the slice-4 leg). balance = Σ TokenEntry amounts EXACTLY, cached in the SAME transaction as every ledger append — SIGNED (ruling: the ledger never lies; a transient sub-zero overshoot is honest state; exhaustion balance ≤ 0 fires the system:token_exhaustion CASCADE-suspend of member orgs, reload ≤0→>0 fires system:token_reload unsuspend-to-ACTIVE). The auto-top-off block is CONFIG this slice (the FIRING engine + stored-method custody = the rater leg, deferral 5); its budget cap is a LAZY month-keyed counter (ruling — rolls by key comparison, no scheduled reset). FSM: active(i) ⇄ inactive (paused — purchases/grants refuse REF_STATE; the rater still debits: usage happened) → doomed (gate-protected; the inbound-ref set is EMPTY by design — entries and purchases are FAMILY \[the GiftRegistry vacuous-gate class]). Platform billing is USD-only. NOT searchable (platform-internal — never merchant search content). Template class A16_BILLING (platform billing ≠ floor work — owner/manager/assoc_mgr; hand-derived v23).

## Fields

| Field | Type | Notes |
| --- | --- | --- |
| `id` | [ID](/types/#scalars) `ID!` | The record’s id — a UUID the platform assigned when the record was created; every reference to this record uses it. |
| `sysId` | [String](/types/#scalars) `String!` | The group-scoped human-facing system id (TA-…). |
| `type` | [String](/types/#scalars) `String!` | The kind of record — always `TokenAccount` here. |
| `caption` | [String](/types/#scalars) `String!` | The record’s display name — what people see it called. |
| `status` | [String](/types/#scalars) `String!` | The FSM state: active \| inactive \| doomed. |
| `parentId` | [ID](/types/#scalars) `ID!` | The parent org group; for a TokenAccount parentId === rootId. |
| `rootId` | [ID](/types/#scalars) `ID!` | The org-group family root. |
| `createdAt` | [String](/types/#scalars) `String!` | When the record was created, as a UTC timestamp. |
| `updatedAt` | [String](/types/#scalars) `String!` | When the record last changed, as a UTC timestamp. |
| `revisionNum` | [Int](/types/#scalars) `Int!` | How many times this record has been edited; the first save is 0. |
| `revision` | [ID](/types/#scalars) `ID!` | The OCC revision token — supply it on every mutation of this record; rotates on every write. |
| `refCaptions` | [RefCaption](/types/RefCaption/) `[RefCaption!]!` | The server-composed captions of this record's declared references (the referenced-caption rule) — one row per referenced id; see RefCaption. |
| `balance` | [Int](/types/#scalars) `Int!` | The cached token balance = Σ TokenEntry amounts EXACTLY — SIGNED. NEVER caller-writable — moves ONLY with ledger appends. |
| `lowBalanceThreshold` | [Int](/types/#scalars) | The low-balance warning threshold (tokens) — absent ⇒ the warning arm is unarmed (the eventDate optional-arm class). The warning ladder is EVENTS + readable state now. |
| `dailyBurnThresholdKernels` | [Int](/types/#scalars) | The daily-burn alert threshold in KERNELS/day. Absent ⇒ unarmed. Owner-set like lowBalanceThreshold; day rows over it read as breaches on the costs face (the engine-evented twin is a named wordable beside delivery). |
| `autoTopOff` | [AutoTopOffConfig](/types/AutoTopOffConfig/) | The auto-top-off block — absent ⇒ never fires. CONFIG this slice; the FIRING engine + stored-method custody ride the rater leg. Cap reached ⇒ STOP + WARN (never charges past the budget — the operator law). |
| `autoTopOffMonth` | [String](/types/#scalars) | The auto-top-off cap window's YYYY-MM month key — SERVER-stamped at fire time. |
| `autoTopOffSpentUsdCents` | [Int](/types/#scalars) | The month's cumulative auto-top-off spend — SERVER-stamped at fire; compared against the cap BEFORE each fire. |
| `autoTopOffDay` | [String](/types/#scalars) | The auto-top-off DAY window's YYYY-MM-DD key. |
| `autoTopOffSpentDayUsdCents` | [Int](/types/#scalars) | The DAY's cumulative auto-top-off spend. |
| `autoTopOffPendingMethod` | [String](/types/#scalars) | WHICH stored card the in-flight top-off charged — primary \| backup. |
| `autoTopOffPrimaryFailedDay` | [String](/types/#scalars) | The UTC day the PRIMARY card last webhook-failed a top-off. |
| `autoTopOffBackupFailedDay` | [String](/types/#scalars) | The backup twin — both stamps reading TODAY = the cards-failing emergency (nothing fires; the loud lane speaks each tick). |
| `backupBillingMethod` | [BillingMethodFacts](/types/BillingMethodFacts/) | The BACKUP method's readable facts. The charger's top-off falls back to it when the primary declines; stamped by attachTokenAccountBackupBillingMethod, removed whole by its detach. |
| `burn7dKernels` | [Int](/types/#scalars) | COMPUTED at read: the group's total kernel consumption over the LAST 7 UTC days, summed off the rater's TOTAL day lanes (the usageReport engine — exact integers). 0 on a quiet week; null only on the filtered listing lane (vitals ride the plain reads). |
| `runwayDays` | [Float](/types/#scalars) | COMPUTED at read: the balance SCALED TO KERNELS (balance is whole internal tokens — ×1,000,000) ÷ the 7-day daily kernel burn — how many days the balance lasts at the current rate. Null when the burn is 0 (no rate exists to project) or on the filtered listing lane. |
| `microTokenCarry` | [Int](/types/#scalars) | The sub-token usage accrual in µtokens, 0…999,999. SERVER-stamped — no face carries it; absent = 0. Read-exposed for transparency. |
| `lowBalanceSince` | [String](/types/#scalars) | When the CURRENT low-balance episode began. The readable half of the warning ladder — the at.billing.token_account.low_balance.v1 event is its evented twin. |
| `billingMethod` | [BillingMethodFacts](/types/BillingMethodFacts/) | The stored off-session method's READABLE facts. Present ⟺ custody is armed (the charger's top-off + base-fee arms both require it); stamped by attachTokenAccountBillingMethod, removed whole by detach. |
| `autoTopOffPendingPurchaseId` | [ID](/types/#scalars) | The in-flight auto-top-off TokenPurchase. Absent = no fire in flight. |
| `topOffCappedSince` | [String](/types/#scalars) | When the CURRENT capped episode began. Absent/null = not capped. |
| `baseFeePaidMonth` | [String](/types/#scalars) | The latest UTC YYYY-MM period the base fee SETTLED for. Absent = never collected. |
| `includedMonth` | [String](/types/#scalars) | The live included-allowance month, UTC YYYY-MM. SERVER-stamped by the base-fee settle; absent/null = no allowance ever minted, or the plain-read vitals lane was skipped (the burn7dKernels listing-lane class). |
| `includedGranted` | [Int](/types/#scalars) | What the live allowance month MINTED (tokens — monthlyIncludedTokensFor at the collected amount). Present ⟺ includedMonth is. |
| `includedRemaining` | [Int](/types/#scalars) | What the live allowance month has NOT yet drawn (tokens; drains floor-0 as the month meters; 0 after the month-roll expiry sweep). The banked balance = balance − this figure while the month lives. Present ⟺ includedMonth is. |
| `affiliateCreditCents` | [Int](/types/#scalars) | Your group’s SPENDABLE referral-earnings credit (USD cents ≥ 0): Σ your AffiliateAccrual entries exactly. When it covers your monthly base fee the cycle CREDIT-SETTLES automatically (no card charge — bill-netting first, the ruled settlement order). Absent/null = never earned a cent, or the filtered listing lane (the burn7dKernels class). |
| `frozenKernels` | [Int](/types/#scalars) | Σ kernels in transfer-FROZEN blocks: your TRUE spendable room = balance − this figure (the exhaustion gate reads it; the transfer face’s pre-submit warning derives from it). Absent/null = nothing frozen, or the filtered listing lane. |
| `storageSnapshotDay` | [String](/types/#scalars) | The latest UTC YYYY-MM-DD day a storage snapshot EMITTED for this wallet. Absent = never snapshotted. |
| `currency` | [String](/types/#scalars) `String!` | Platform billing currency — 'USD' by law. |

## Used by

- [attachTokenAccountBackupBillingMethod](/reference/billing-and-the-wallet/attachTokenAccountBackupBillingMethod/)
- [attachTokenAccountBillingMethod](/reference/billing-and-the-wallet/attachTokenAccountBillingMethod/)
- [createTokenAccount](/reference/token-account/createTokenAccount/)
- [deactivateTokenAccount](/reference/token-account/deactivateTokenAccount/)
- [detachTokenAccountBackupBillingMethod](/reference/billing-and-the-wallet/detachTokenAccountBackupBillingMethod/)
- [detachTokenAccountBillingMethod](/reference/billing-and-the-wallet/detachTokenAccountBillingMethod/)
- [doomTokenAccount](/reference/token-account/doomTokenAccount/)
- [reactivateTokenAccount](/reference/token-account/reactivateTokenAccount/)
- [tokenAccount](/reference/token-account/tokenAccount/)
- [updateTokenAccount](/reference/token-account/updateTokenAccount/)