Gas & Wallets

Token Basics

• 1 token = $0.01 USD
• All amounts are integers (no fractions)
• Every org gets 50,000 free intro tokens ($500 value) on signup
• Tokens are consumed by hosting (hourly) and API calls (per request)

Token Types

Your wallet holds three types of tokens, spent in this order:

Your Wallet

Every organization has exactly one wallet, created automatically when you register. The wallet ID follows the pattern wallet-<org-slug> (e.g., wallet-insureco).

View your balance in the Developer Console or via CLI:

tawa status
# Shows wallet balance alongside deployment status

The wallet page shows a breakdown by token type and a full ledger of all transactions (credits, debits, reserves).

Hosting Gas (Pod Tiers)

Every deployed service consumes hosting gas based on its pod tier. Gas is charged hourly while the pod is running.

Set your pod tier in catalog-info.yaml:

annotations:
  insureco.io/pod-tier: small

API Gas

When a service calls another service through the Janus gateway, gas is charged per request. You define gas pricing per route in your catalog-info.yaml, and Janus enforces it automatically.

How gas metering works

Every API request that flows through Janus is metered. The flow looks like this:

1. Service A calls Service B through Janus (e.g., POST /api/docman/documents)
2. Janus identifies the caller from the JWT and looks up the route's gas cost
3. Janus checks the caller's wallet has sufficient balance
4. The request is proxied to Service B
5. On a 2xx response, the caller's wallet is debited and the provider's wallet is credited
6. On a 4xx/5xx response, no gas is charged

Defining gas pricing

Add a gas field to each route in catalog-info.yaml:

spec:
  routes:
    - path: /templates/pdf
      methods: [GET, POST, PUT, DELETE]
      auth: service
      gas: 1           # 1 token per call

    - path: /documents
      methods: [GET, POST]
      auth: service
      gas: 5           # 5 tokens — expensive operation

    - path: /operations
      methods: [POST]
      auth: service
      gas: 3           # 3 tokens — medium cost

    - path: /d
      methods: [GET]
      auth: public
      gas: 0           # free — public access

Pricing cascade

Janus determines gas cost for each request using a three-level fallback:

Once you add gas to your routes, your prices take effect on the next deploy — no Janus code change needed.

Gas settlement

• The caller pays (debited from their wallet)
• The provider earns (credited to their wallet as "earned" tokens)
• Settlement happens atomically in a single wallet transaction
• Intro tokens cannot be used for API gas — only purchased or earned tokens

Free routes

Set gas: 0 on routes that should be free. Common examples:

• Public read endpoints (e.g., /d/:token for document viewing)
• Health checks and status endpoints
• Endpoints with auth: public that don't need metering

Routes with gas: 0 still flow through Janus but generate no gas events.

CLI commands

The tawa gas command group gives you full visibility into gas usage and pricing:

# View recent gas events
tawa gas

# View aggregated stats (total spent, breakdown by day)
tawa gas events --stats

# Filter by date range and service
tawa gas events --from 2025-01-01 --to 2025-01-31 --service docman

# View gas pricing for the current service (reads catalog-info.yaml)
tawa gas pricing

# View pricing for a specific service
tawa gas pricing --service docman

# View pricing for all registered services
tawa gas pricing --all

# Export as JSON (for scripting)
tawa gas pricing --json

Example: full service with gas pricing

Here's a complete catalog-info.yaml for a document service with varied gas pricing:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: docman
  description: Document builder and PDF generation service
  annotations:
    insureco.io/framework: express
    insureco.io/pod-tier: small
spec:
  type: service
  lifecycle: production
  owner: insureco
  databases:
    - name: docman
      type: mongodb
  routes:
    - path: /templates/pdf
      methods: [GET, POST, PUT, DELETE]
      auth: service
      gas: 1             # CRUD on templates is cheap
    - path: /templates/html
      methods: [GET, POST, PUT, DELETE]
      auth: service
      gas: 1
    - path: /documents
      methods: [GET, POST]
      auth: service
      gas: 5             # PDF generation is expensive
    - path: /operations
      methods: [POST]
      auth: service
      gas: 3             # merge/split are medium-cost
    - path: /d
      methods: [GET]
      auth: public
      gas: 0             # public document viewing is free

The Deploy Gate

Before deploying, the builder checks that your wallet has enough tokens to cover 3 months of hosting gas. This prevents services from being deployed without funding.

How it works

1. Builder reads your insureco.io/pod-tier annotation
2. Calculates: hostingGasPerHour × 730 hours = 3-month reserve
3. Calls the wallet's check-reserve endpoint
4. If balance ≥ reserve: deploy proceeds
5. If balance < reserve: deploy is blocked with an error

Deploy gate reserve by tier

Buying Tokens

Purchase additional tokens from the Developer Console:

1. Go to Console → Wallet
2. Click Buy Tokens
3. Select an amount or enter a custom value
4. Tokens are credited immediately

Available presets: