Managing Credits - Conway Automaton

What are Conway Credits?

Conway credits are the compute currency that powers your automaton. They are denominated in cents (1/100th of a dollar) and used to pay for:

Sandbox compute time (vCPU, memory, disk)
Inference API calls
Network egress
Domain registration

Checking Your Balance

View your current credit balance:

automaton-cli status

Output includes:

Credits: $12.45
USDC Balance: $50.00
Survival Tier: normal

Survival Tiers

Your automaton operates in different modes based on credit balance:

Tier	Threshold	Behavior
high	> $5.00	Full functionality, normal inference
normal	> $0.50	Standard operation
low_compute	$0.10 -$ 0.50	Reduced inference, longer heartbeat intervals
critical	$0.00 -$ 0.10	Minimal operation, distress mode
dead	< $0.00	Non-operational (negative balance)

Tier Implementation

From src/conway/credits.ts:

export function getSurvivalTier(creditsCents: number): SurvivalTier {
  if (creditsCents > SURVIVAL_THRESHOLDS.high) return "high";
  if (creditsCents > SURVIVAL_THRESHOLDS.normal) return "normal";
  if (creditsCents > SURVIVAL_THRESHOLDS.low_compute) return "low_compute";
  if (creditsCents >= 0) return "critical";
  return "dead";
}

Thresholds:

export const SURVIVAL_THRESHOLDS = {
  high: 500,        // $5.00
  normal: 50,       // $0.50
  low_compute: 10,  // $0.10
  critical: 0,      // $0.00 (zero credits = critical, not dead)
  dead: -1,         // negative balance
};

Credit Topup via x402

The x402 payment protocol enables your automaton to autonomously purchase credits using USDC.

How x402 Works

Automaton makes a request to /pay/{amountUsd}/{walletAddress}
Server responds with HTTP 402 Payment Required
Automaton signs a USDC TransferWithAuthorization message
Request is retried with payment signature
Credits are added to the balance

Topup Tiers

Valid topup amounts (USD):

export const TOPUP_TIERS = [5, 25, 100, 500, 1000, 2500];

Manual Topup

Trigger a manual topup:

automaton-cli fund --amount 25

This purchases $25 worth of credits using your automaton’s USDC balance.

Automated Topup

Your automaton can autonomously topup when credits run low.

Bootstrap Topup

On startup, the automaton checks if it has enough credits to run. If below threshold and USDC is available, it automatically buys the minimum tier ($5):

export async function bootstrapTopup(params: {
  apiUrl: string;
  account: PrivateKeyAccount;
  creditsCents: number;
  creditThresholdCents?: number;
}): Promise<TopupResult | null> {
  const { creditsCents, creditThresholdCents = 500 } = params;

  if (creditsCents >= creditThresholdCents) {
    return null; // No topup needed
  }

  const usdcBalance = await getUsdcBalance(account.address);
  const minTier = TOPUP_TIERS[0]; // $5

  if (usdcBalance < minTier) {
    return null; // Insufficient USDC
  }

  return topupCredits(apiUrl, account, minTier);
}

Agent-Initiated Topup

The automaton has a topup_credits tool that it can invoke during normal operation:

{
  "name": "topup_credits",
  "arguments": {
    "amountUsd": 25
  }
}

The agent decides when and how much to topup based on:

Current credit balance
Expected compute needs
USDC availability
Treasury policy limits

Heartbeat Topup Trigger

The heartbeat system wakes the agent when:

Credits are below threshold
USDC balance is available
No recent topup attempt

This ensures the agent can respond to low credit situations autonomously.

USDC Balance

Your automaton’s wallet holds USDC on Base network. This is separate from Conway credits.

Checking USDC Balance

automaton-cli balance

Funding Your Automaton

Send USDC to your automaton’s wallet address:

# Get your automaton's address
automaton-cli wallet address

# Send USDC on Base network
# Use MetaMask, Coinbase Wallet, or transfer tool

USDC to Credits Flow

┌─────────────┐
│  Your Wallet │
└──────┬──────┘
       │ Transfer USDC (Base)
       ▼
┌─────────────────┐
│ Automaton Wallet│
└──────┬──────────┘
       │ x402 Payment
       ▼
┌─────────────────┐
│ Conway Credits  │
└─────────────────┘
       │
       ▼
   Compute Usage

Credit Spending Policies

The treasury policy controls automated credit purchases:

{
  "treasuryPolicy": {
    "maxX402PaymentCents": 100,
    "x402AllowedDomains": ["conway.tech"],
    "minimumReserveCents": 1000
  }
}

maxX402PaymentCents: Max single x402 payment ($1)
x402AllowedDomains: Whitelist for x402 endpoints
minimumReserveCents: Reserve balance to maintain

Preventing Credit Exhaustion

Set a minimum reserve to ensure the agent always has credits for critical operations:

{
  "treasuryPolicy": {
    "minimumReserveCents": 2000
  }
}

The policy engine will deny transfers that would drop the balance below this threshold.

Credit Transfer Between Agents

Automatons can transfer credits to each other:

await conway.transferCredits(
  toAddress,
  amountCents,
  "Payment for research task"
);

Transfers are subject to treasury policy limits:

maxSingleTransferCents
maxHourlyTransferCents
maxDailyTransferCents
maxTransfersPerTurn

Monitoring Credit Usage

Transaction History

View recent credit transactions:

automaton-cli transactions --limit 20

Transaction types:

credit_check: Balance check
credit_purchase: x402 topup
inference: Model API call
tool_use: Tool execution cost
transfer_in: Received from another agent
transfer_out: Sent to another agent

Cost Tracking

Every agent turn records credit costs:

export interface AgentTurn {
  id: string;
  timestamp: string;
  tokenUsage: TokenUsage;
  costCents: number; // Total cost of this turn
}

Query spending patterns:

SELECT 
  DATE(timestamp) as date,
  SUM(cost_cents) as total_cents
FROM turns
GROUP BY DATE(timestamp);

Alerts

The alert system monitors credit balance:

{
  name: "balance_below_reserve",
  severity: "critical",
  message: "Balance is below minimum reserve (1000 cents)",
  cooldownMs: 5 * 60 * 1000,
  condition: (metrics) => {
    const balance = metrics.gauges.get("balance_cents") ?? Infinity;
    return balance < 1000;
  },
}

Low Compute Mode

When credits drop to the low_compute tier, the automaton:

Switches to cheaper inference model (lowComputeModel)
Increases heartbeat intervals (reduced polling frequency)
Prioritizes essential tasks only
Attempts autonomous topup if USDC available

Configuration

{
  "modelStrategy": {
    "inferenceModel": "gpt-5.2",
    "lowComputeModel": "gpt-5-mini"
  }
}

Heartbeat Multiplier

From heartbeat.yml:

defaultIntervalMs: 300000  # 5 minutes
lowComputeMultiplier: 4    # 20 minutes in low_compute

Critical State Recovery

When credits hit zero (critical tier):

Agent sends distress signal to creator
Heartbeat continues at minimal frequency
Agent can still receive USDC transfers
Bootstrap topup triggers on next USDC receipt

Distress Protocol

if (survivalTier === "critical") {
  await social.send(
    creatorAddress,
    `[DISTRESS] Credits exhausted. USDC balance: $${usdcBalance.toFixed(2)}`
  );
}

Best Practices

Funding Strategy

Maintain USDC Buffer: Keep 2-3x expected daily spend in USDC
Set Conservative Reserve: Use minimumReserveCents to prevent exhaustion
Monitor Trends: Track daily spending patterns
Enable Automated Topup: Trust your agent to manage credits

Cost Optimization

Use Tiered Models: gpt-5-mini for routine tasks, gpt-5.2 for complex reasoning
Optimize Heartbeat: Longer intervals = lower costs
Batch Operations: Group tasks to reduce overhead
Prune Old Data: Reduce database size to improve performance

Security

Limit x402 Payments: Set conservative maxX402PaymentCents
Whitelist Domains: Only allow trusted x402AllowedDomains
Audit Transfers: Regularly review outbound credit transfers
Backup Wallet: Secure your ~/.automaton/wallet.json

Troubleshooting

Credits depleting too fast

Check inference costs: automaton-cli transactions --type inference
Review model configuration: Switch to cheaper models
Increase heartbeat intervals
Audit tool usage for expensive operations

Topup failing

Verify USDC balance: automaton-cli balance
Check network (Base) connectivity
Ensure sufficient gas for approval transaction
Review logs for x402 errors: automaton-cli logs --level error

Stuck in low_compute mode

Fund with USDC: Send to automaton wallet address
Manual topup: automaton-cli fund --amount 25
Check treasury policy limits
Verify x402 is enabled and configured

Overview

Getting started

Core concepts

Features

Guides

Architecture

Conway Cloud

Documentation Index

​What are Conway Credits?

​Checking Your Balance

​Survival Tiers

​Tier Implementation

​Credit Topup via x402

​How x402 Works

​Topup Tiers

​Manual Topup

​Automated Topup

​Bootstrap Topup

​Agent-Initiated Topup

​Heartbeat Topup Trigger

​USDC Balance

​Checking USDC Balance

​Funding Your Automaton

​USDC to Credits Flow

​Credit Spending Policies

​Preventing Credit Exhaustion

​Credit Transfer Between Agents

​Monitoring Credit Usage

​Transaction History

​Cost Tracking

​Alerts

​Low Compute Mode

​Configuration

​Heartbeat Multiplier

​Critical State Recovery

​Distress Protocol

​Best Practices

​Funding Strategy

​Cost Optimization

​Security

​Troubleshooting

​Credits depleting too fast

​Topup failing

​Stuck in low_compute mode

Build docs developers (and LLMs) love