# Fund the AI wallet and see what the platform costs you

Put a card on file for your group’s kernel wallet, buy kernels when you need them, and read what the platform is charging you — the kernel ledger, the usage day by day, the AI usage by surface, and the platform’s charges.

Pricing & money · a play in 4 steps.

## The steps

1. Attach the payment method that pays for top-ups. — [attachTokenAccountBillingMethod](/reference/billing-and-the-wallet/attachTokenAccountBillingMethod/)
2. Buy kernels — one press with the stored card, or a purchase you set up — the balance credits through one recorded purchase. — [purchaseTokensNow](/reference/billing-and-the-wallet/purchaseTokensNow/), [createTokenPurchase](/reference/token-purchase/createTokenPurchase/)
3. Read the kernel ledger — every charge, purchase and adjustment on the balance. — [tokenEntries](/reference/billing-and-the-wallet/tokenEntries/)
4. Read the usage day by day, the AI usage by surface, and the platform’s charges to your group. — [usageReport](/reference/billing-and-the-wallet/usageReport/), [aiUsage](/reference/billing-and-the-wallet/aiUsage/), [billingCharges](/reference/billing-charge/billingCharges/)

## The calls

Every operation this use case runs, in the order it first appears, with the request and the response its reference page shows.

### attachTokenAccountBillingMethod

[attachTokenAccountBillingMethod](/reference/billing-and-the-wallet/attachTokenAccountBillingMethod/) — mutation · Attach a payment method to your group’s kernel wallet — how top-ups get paid.

**Example request**

```graphql
mutation ExampleAttachTokenAccountBillingMethod($input: AttachTokenAccountBillingMethodInput!) {
  attachTokenAccountBillingMethod(input: $input) {
    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:

```json
{
  "input": {
    "methodRef": "<method ref>"
  }
}
```

Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`.

**Example response**

```json
{
  "data": {
    "attachTokenAccountBillingMethod": {
      "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": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

### purchaseTokensNow

[purchaseTokensNow](/reference/billing-and-the-wallet/purchaseTokensNow/) — mutation · Buy kernels NOW with the stored card — one press, no checkout.

**Example request**

```graphql
mutation ExamplePurchaseTokensNow($input: NewTokenPurchaseInput!) {
  purchaseTokensNow(input: $input) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    usdAmountCents
    tokensPurchased
    volumeTierCode
    rateCardVersion
    stripePaymentIntentId
    settledAt
  }
}
```

Variables:

```json
{
  "input": {
    "caption": "Blue jeans",
    "usdAmountCents": 1
  }
}
```

Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`.

**Example response**

```json
{
  "data": {
    "purchaseTokensNow": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "TP-EXMP-0000-000F",
      "type": "TokenPurchase",
      "caption": "Blue jeans",
      "status": "created",
      "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",
      "usdAmountCents": 1,
      "tokensPurchased": 1,
      "volumeTierCode": "BJ-001",
      "rateCardVersion": 1,
      "stripePaymentIntentId": "<stripe payment intent id>",
      "settledAt": "2027-01-31T00:00:00.000Z"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

### createTokenPurchase

[createTokenPurchase](/reference/token-purchase/createTokenPurchase/) — mutation · Buy kernels — top up your group’s prepaid balance.

**Example request**

```graphql
mutation ExampleCreateTokenPurchase($input: NewTokenPurchaseInput!) {
  createTokenPurchase(input: $input) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    usdAmountCents
    tokensPurchased
    volumeTierCode
    rateCardVersion
    stripePaymentIntentId
    settledAt
  }
}
```

Variables:

```json
{
  "input": {
    "caption": "Blue jeans",
    "usdAmountCents": 1
  }
}
```

Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`.

**Example response**

```json
{
  "data": {
    "createTokenPurchase": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "TP-EXMP-0000-000F",
      "type": "TokenPurchase",
      "caption": "Blue jeans",
      "status": "created",
      "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",
      "usdAmountCents": 1,
      "tokensPurchased": 1,
      "volumeTierCode": "BJ-001",
      "rateCardVersion": 1,
      "stripePaymentIntentId": "<stripe payment intent id>",
      "settledAt": "2027-01-31T00:00:00.000Z"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

### tokenEntries

[tokenEntries](/reference/billing-and-the-wallet/tokenEntries/) — query · Your group’s kernel ledger — every charge, purchase, and adjustment on your prepaid balance.

**Example request**

```graphql
query ExampleTokenEntries($limit: Int) {
  tokenEntries(limit: $limit) {
    items {
      id
      type
      caption
      status
      parentId
      rootId
      createdAt
      updatedAt
      revisionNum
      revision
      entryKind
      amountTokens
      reason
      tokenPurchaseId
      billingChargeId
      transferCounterpartRootId
      transferCounterpartEntryId
      carriedInMicroTokens
      carriedOutMicroTokens
      rateCardVersion
    }
    nextToken
  }
}
```

Variables:

```json
{
  "limit": 1
}
```

**Example response**

```json
{
  "data": {
    "tokenEntries": {
      "items": [
        {
          "id": "01900000-0000-7000-8000-37386ae00000",
          "type": "<type>",
          "caption": "Blue jeans",
          "status": "<status>",
          "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",
          "entryKind": "<entry kind>",
          "amountTokens": 1,
          "reason": "Correcting a miscount.",
          "tokenPurchaseId": "01900000-0000-7000-8000-28e82c5c0000",
          "billingChargeId": "01900000-0000-7000-8000-34d522a50000",
          "transferCounterpartRootId": "01900000-0000-7000-8000-6176046e0000",
          "transferCounterpartEntryId": "01900000-0000-7000-8000-d67bafcc0000",
          "carriedInMicroTokens": 1,
          "carriedOutMicroTokens": 1,
          "rateCardVersion": 1
        }
      ],
      "nextToken": "<the cursor from the previous page>"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": null,
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

### usageReport

[usageReport](/reference/billing-and-the-wallet/usageReport/) — query · What your group’s use of the platform consumes, day by day, in kernels — with a per-kind breakdown, and a drill to one person or one sitting.

**Example request**

```graphql
query ExampleUsageReport($days: Int) {
  usageReport(days: $days) {
    totalCalls
    totalKernels
  }
}
```

Variables:

```json
{
  "days": 1
}
```

**Example response**

```json
{
  "data": {
    "usageReport": {
      "totalCalls": 1,
      "totalKernels": 1.5
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": null,
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

### aiUsage

[aiUsage](/reference/billing-and-the-wallet/aiUsage/) — query · Your group’s AI usage by day — calls, tokens, and spend, with a per-surface breakdown.

**Example request**

```graphql
query ExampleAiUsage($days: Int) {
  aiUsage(days: $days) {
    totalCalls
    totalTokensInput
    totalTokensOutput
    totalCostUsd
  }
}
```

Variables:

```json
{
  "days": 1
}
```

**Example response**

```json
{
  "data": {
    "aiUsage": {
      "totalCalls": 1,
      "totalTokensInput": 1,
      "totalTokensOutput": 1,
      "totalCostUsd": "<total cost usd>"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": null,
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

### billingCharges

[billingCharges](/reference/billing-charge/billingCharges/) — query · The platform’s usage charges to your group — the transparency ledger.

**Example request**

```graphql
query ExampleBillingCharges($filter: FilterInput) {
  billingCharges(filter: $filter) {
    items {
      id
      sysId
      type
      caption
      status
      parentId
      rootId
      createdAt
      updatedAt
      revisionNum
      revision
      chargeKind
      usdAmountCents
      periodMonth
      stripePaymentIntentId
      settledAt
    }
    nextToken
    matchCount
  }
}
```

Variables:

```json
{
  "filter": {
    "clauses": [
      {
        "field": "caption",
        "op": "contains",
        "values": [
          "Blue"
        ]
      }
    ]
  }
}
```

**Example response**

```json
{
  "data": {
    "billingCharges": {
      "items": [
        {
          "id": "01900000-0000-7000-8000-37386ae00000",
          "sysId": "BC-EXMP-0000-000F",
          "type": "BillingCharge",
          "caption": "Blue jeans",
          "status": "created",
          "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",
          "chargeKind": "<charge kind>",
          "usdAmountCents": 1,
          "periodMonth": "<period month>",
          "stripePaymentIntentId": "<stripe payment intent id>",
          "settledAt": "2027-01-31T00:00:00.000Z"
        }
      ],
      "nextToken": "<the cursor from the previous page>",
      "matchCount": 1
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": null,
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```