Gas & Wallets

Every action on the Tawa platform is metered with gas tokens. Hosting your service, calling APIs through Janus, and using PlugINS all consume tokens from your wallet.

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:

NOTE: Intro tokens are spent first so your purchased tokens are preserved longer. Earned tokens are spent last so your revenue accumulates.

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

tawa status
# Shows wallet balance alongside deployment status

tawa wallet
# Dedicated wallet view with token breakdown

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 pod tier in catalog-info.yaml:

annotations:
  insureco.io/pod-tier: small

TIP: Start with nano. The 50K intro tokens cover a nano pod for over 13 months. Upgrade only when you need more memory — you can always change the tier and redeploy.

API Gas

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

How gas metering works

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

NOTE: Gas is only charged on successful (2xx) responses. Failed requests are free.

Defining gas pricing

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: /health
      methods: [GET]
      auth: none
      gas: 0           # free

Gas settlement

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

CLI commands

# View recent gas events
tawa gas

# View aggregated stats
tawa gas events --stats

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

# View gas pricing for the current service
tawa gas pricing

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

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.

WARNING: Deploy blocked? If you see "insufficient reserve", buy more tokens or lower your pod tier in catalog-info.yaml.

Platform services (iec-wallet, janus, tawa-web, koko, bio-id) bypass the deploy gate.

Buying Tokens

Purchase tokens from the Developer Console (Console → Wallet → Buy Tokens) or via CLI:

tawa wallet buy 10000

Tokens are credited immediately.