AlmondTill/G3N API

On this page

tokenAccount

query · in the family Token account

What it does

Look up one record — your group’s kernel wallet — the prepaid balance that pays for platform usage.

A TokenAccount by id, within the caller's OWN org-group family; requires authentication. A cross-tenant id reads as null (not-found) AND trips the rootId tripwire server-side.

What happens

Reads only — changes nothing.

Who may call it

Capability area: Billing and the wallet — Your platform bill, token purchases and the usage and cost reads.

Arguments

NameTypeRequiredNotes
idID ID!yesThe id of the record.

Returns

TokenAccount — 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).

Example request

query ExampleTokenAccount($id: ID!) {
  tokenAccount(id: $id) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    balance
    lowBalanceThreshold
    dailyBurnThresholdKernels
    autoTopOffMonth
    autoTopOffSpentUsdCents
    autoTopOffDay
    autoTopOffSpentDayUsdCents
    autoTopOffPendingMethod
    autoTopOffPrimaryFailedDay
    autoTopOffBackupFailedDay
    burn7dKernels
    runwayDays
    microTokenCarry
    lowBalanceSince
    autoTopOffPendingPurchaseId
    topOffCappedSince
    baseFeePaidMonth
    includedMonth
    includedGranted
    includedRemaining
    affiliateCreditCents
    frozenKernels
    storageSnapshotDay
    currency
  }
}

Variables:

{
  "id": "01900000-0000-7000-8000-37386ae00000"
}

Example response

{
  "data": {
    "tokenAccount": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "TA-EXMP-0000-000F",
      "type": "TokenAccount",
      "caption": "Blue jeans",
      "status": "active",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "balance": 1,
      "lowBalanceThreshold": 1,
      "dailyBurnThresholdKernels": 1,
      "autoTopOffMonth": "<auto top off month>",
      "autoTopOffSpentUsdCents": 1,
      "autoTopOffDay": "2027-01-31",
      "autoTopOffSpentDayUsdCents": 1,
      "autoTopOffPendingMethod": "<auto top off pending method>",
      "autoTopOffPrimaryFailedDay": "2027-01-31",
      "autoTopOffBackupFailedDay": "2027-01-31",
      "burn7dKernels": 1,
      "runwayDays": 1.5,
      "microTokenCarry": 1,
      "lowBalanceSince": "<low balance since>",
      "autoTopOffPendingPurchaseId": "01900000-0000-7000-8000-80a20c5b0000",
      "topOffCappedSince": "<top off capped since>",
      "baseFeePaidMonth": "<base fee paid month>",
      "includedMonth": "<included month>",
      "includedGranted": 1,
      "includedRemaining": 1,
      "affiliateCreditCents": 1,
      "frozenKernels": 1,
      "storageSnapshotDay": "2027-01-31",
      "currency": "USD"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": null,
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}

Errors this call can answer