Wallet & Balance Management

Two balances. One for infrastructure, one for AI. Transfer between them.

Your Hoody wallet uses a dual-balance system to separate infrastructure costs from AI spending—giving you explicit control over each budget.

API Endpoints Summary

Official Technical Reference:

This Foundation page explains the wallet and balance system. For related topics:

Balance APIs:

Wallet & Payments API - Balance checking, fund transfers (API reference)

Payment & Billing:

Billing & Payments → - Payment methods, transactions, invoices

See the full Wallet & Payments API → for endpoint documentation.

The Two-Balance System

Why Hoody uses separate balances:

General Balance

Your primary account funds. Used for:

Server rentals (bare metal hosting)
Platform infrastructure (network, proxy, services)

Add funds via credit card or other payment methods. This is your main wallet for renting servers and using Hoody.

AI Balance

A separate credit pool for AI features:

Hoody AI credits (LLM API access)
AI-powered services (code generation, automation)

Funded exclusively by transferring from General Balance. Transfers are one-way only (General → AI, not reversible). Prevents accidental AI overspending—you control the budget explicitly.

Critical distinction: General Balance funds infrastructure. AI Balance is isolated to prevent AI from draining server rental budget.

Traditional vs. Hoody Billing

Why this model changes everything:

Traditional VPS Billing

Cost Structure:

$5-20 per VM per month
Separate charge for each environment
Expensive at scale

Example: 10 containers

10 containers × $10/month = $100/month

Problem: Every container increases costs linearly.

Hoody Bare Metal Billing

Cost Structure:

One server rental (varies by specs and duration)
Unlimited containers on that server
Cost-effective scaling

Example: 100 containers

1 server rental (see marketplace for pricing)
Supports 50-200+ containers depending on specs

Solution: Same cost whether you run 5 or 500 containers.

Browse servers: Rent Servers → to view specifications and pricing

Economic transformation: The container revolution is finally economically viable.

How the Wallet System Works

General Balance (Primary Wallet)

What it funds:

Server rentals (daily, weekly, monthly)
Platform infrastructure and services

How to add funds: See Billing & Payments → for payment methods (credit card, cryptocurrency, bank transfer).

Check balance:

GET /api/v1/wallet/balances/general

AI Balance (Dedicated AI Credits)

What it funds:

Hoody AI API usage (LLMs)
AI-powered code generation
Autonomous agent operations
AI-assisted debugging

How to fund: Transfer from General Balance only

# Read the current transfer fee first
GET /api/v1/wallet/payment-availability
# -> data.ai_credit_fee_bps

# Transfer $10 to AI credits, echoing back the fee you were just shown
# Replace CURRENT_AI_CREDIT_FEE_BPS with data.ai_credit_fee_bps from GET /api/v1/wallet/payment-availability
POST /api/v1/wallet/transfers
{
  "amount": "10.00",
  "expected_fee_bps": <CURRENT_AI_CREDIT_FEE_BPS>
}

Why separate? Prevents AI services from draining your infrastructure budget. You explicitly allocate how much AI can spend.

Check balance:

GET /api/v1/wallet/balances/ai

Returns: Limit, current usage, remaining credits

Balance Workflow

How to use your wallet:

Add Funds to General Balance

Use one of three payment methods:
- Credit card (instant, via Stripe)
- Cryptocurrency (5-60 min, +5% fee, via NOWPayments)
- Bank transfer (1-3 business days, for large deposits)
See: Billing & Payments → for complete payment method details
Rent Servers

Use General Balance to rent bare metal servers.

Servers charged based on rental duration. Once rented, run unlimited containers at no additional cost.

See: Rent Servers → for marketplace and pricing
Optional: Fund AI Balance

If using AI features, transfer funds from General Balance to AI Balance.
Terminal window
```
# Replace CURRENT_AI_CREDIT_FEE_BPS with data.ai_credit_fee_bps from GET /api/v1/wallet/payment-availability
POST /api/v1/wallet/transfers
{
  "amount": "10.00",
  "expected_fee_bps": <CURRENT_AI_CREDIT_FEE_BPS>
}
```
One-way transfer only. Cannot move funds back from AI to General.

expected_fee_bps must echo the current ai_credit_fee_bps from GET /api/v1/wallet/payment-availability; when a fee is configured, omitting it returns 409.
Monitor Balances

Check balances anytime via API or dashboard.
Terminal window
```
GET /api/v1/wallet/balances
```
Automated monitoring recommended for production use.

Why Two Balances?

The problem with single-balance systems:

Without separation, AI services could accidentally consume your entire infrastructure budget. You’d wake up to:

Servers terminated (no funds for renewal)
AI ran thousands of expensive LLM calls overnight
No money left for core infrastructure

Hoody’s solution:

General Balance = Infrastructure

Protected from AI overspend

Server rentals and platform costs only. AI can’t touch this budget. Your infrastructure stays funded.

AI Balance = Explicit AI Budget

Hard limit on AI spending

You transfer exact amount you want AI to use. Once depleted, AI services stop. Can’t accidentally overspend.

You control both budgets explicitly. Transfer to AI Balance only when you want to use AI features, and only as much as you’re willing to spend.

Checking Your Balances

Monitor your wallet programmatically:

All Balances at Once

GET /api/v1/wallet/balances

Response:

{
  "statusCode": 200,
  "message": "Balances retrieved successfully",
  "data": {
    "general_balance": "95.50",      // Infrastructure funds
    "ai_limit": "50.00",             // Total AI credits allocated
    "ai_usage": "10.25",             // AI credits spent
    "ai_remaining": "39.75"          // AI credits available
  }
}

General Balance Only

GET /api/v1/wallet/balances/general

Returns: Current infrastructure funds

Use for: Monitoring if you need to add funds for server renewals

AI Balance Only

GET /api/v1/wallet/balances/ai

Returns: AI credit limit, usage, and remaining balance

Use for: Checking if AI has budget before running expensive LLM tasks

Balance Automation

HTTP-based wallet enables automated balance management:

The JavaScript snippets below read token from process.env.HOODY_TOKEN. Create a Hoody token with hoody auth login or the automation-token flow and export it:
export HOODY_TOKEN="hdy_…"

const token = process.env.HOODY_TOKEN;

Monitor General Balance

// Check if funds are running low
async function checkInfrastructureBalance() {
  const response = await fetch('https://api.hoody.icu/api/v1/wallet/balances/general', {
    headers: { 'Authorization': `Bearer ${token}` }
  });

  const data = await response.json();
  const balance = parseFloat(data.data.general_balance);

  // Warn if below 2x monthly server costs
  const monthlyServerCosts = 150; // Your server rentals
  if (balance < monthlyServerCosts * 2) {
    await sendAlert(`Low balance: $${balance}. Server renewals at risk.`);
  }
}

Monitor AI Balance

// Check AI budget before expensive tasks
async function canAffordAITask(estimatedCost) {
  const response = await fetch('https://api.hoody.icu/api/v1/wallet/balances/ai', {
    headers: { 'Authorization': `Bearer ${token}` }
  });

  const data = await response.json();
  const remaining = parseFloat(data.data.ai_remaining);

  return remaining >= estimatedCost;
}

Auto-Fund AI for Tasks

// Transfer to AI only when needed, with limits
async function fundAIForTask(estimatedCost) {
  const aiBalance = await fetch('https://api.hoody.icu/api/v1/wallet/balances/ai', {
    headers: { 'Authorization': `Bearer ${token}` }
  }).then(r => r.json());

  const remaining = parseFloat(aiBalance.data.ai_remaining);

  if (remaining < estimatedCost) {
    const needed = estimatedCost - remaining;

    // Read the live fee — when one is configured it MUST be echoed back,
    // otherwise the transfer is rejected 409 TRANSFER_FEE_CONFIRMATION_REQUIRED
    const availability = await fetch('https://api.hoody.icu/api/v1/wallet/payment-availability', {
      headers: { 'Authorization': `Bearer ${token}` }
    }).then(r => r.json());

    // Transfer only what's needed (remember: one-way only!)
    const res = await fetch('https://api.hoody.icu/api/v1/wallet/transfers', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        amount: needed.toFixed(2),
        expected_fee_bps: availability.data.ai_credit_fee_bps
      })
    });
    if (!res.ok) throw new Error(`AI top-up failed: ${res.status}`);
  }
}

HTTP-based wallet enables AI to manage its own budget.

Cost Optimization Strategies

Consolidate Containers

One server can host many containers:

Instead of:
3 VPS × $10/month = $30/month for 3 environments

Use:
1 Hoody server rental = $X/month for unlimited containers
Create 3 containers + 50 more for experiments = same $X/month

Rule: Consolidate workloads onto fewer servers when possible.

Right-Size Servers

Don’t over-provision:

Start with mid-tier server
Monitor usage first month
Upgrade only if consistently >80% resource usage
Delete unused containers to free resources

Most users never need more than 2-3 servers (dev, staging, prod separation).

AI Budget Management

Control AI spending explicitly:

// Set strict AI limits. Any configured platform fee is deducted from the
// transfer, so the AI credit that lands is the amount minus that fee.
const availability = await fetch('https://api.hoody.icu/api/v1/wallet/payment-availability', {
  headers: { 'Authorization': `Bearer ${token}` }
}).then(r => r.json());

await fetch('https://api.hoody.icu/api/v1/wallet/transfers', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  // expected_fee_bps must echo the live fee, or the transfer is rejected 409
  body: JSON.stringify({
    amount: "10.00", // $10 AI budget this month
    expected_fee_bps: availability.data.ai_credit_fee_bps
  })
});

// Monitor AI usage
const aiBalance = await fetch('https://api.hoody.icu/api/v1/wallet/balances/ai', {
  headers: { 'Authorization': `Bearer ${token}` }
}).then(r => r.json());
// Stop AI tasks if aiBalance.data.ai_remaining drops below threshold

Separate budgets = no accidental AI overspend on infrastructure funds.

Use Snapshots Instead of Idle Containers

Pattern:

Snapshot containers you don’t use daily
Delete the live container
Restore from snapshot when needed (typically 5-15 seconds)

Benefit: Reduces server resource usage → fit more active containers.

What You Actually Pay For

Only two things:

1. Server Rentals (Infrastructure)

Charged: When you rent a bare metal server Includes: Everything—CPU, RAM, storage, bandwidth, networking, unlimited containers, all Hoody Kit HTTP services

See: Rent Servers → for marketplace pricing by server specs and location

2. AI Usage (Optional)

Charged: Only when using Hoody AI features Rate: Pay-per-token, varies by LLM model Budget: Limited by AI Balance (can’t exceed what you’ve transferred)

You only pay for AI if you use it. Server rentals don’t include AI.

Use Cases

Solo Developer

Check General Balance before server renewal
Keep 2x monthly server cost as buffer
Transfer $10-20/month to AI Balance for code assistance
Monitor both balances weekly

Digital Agency

Separate General Balance monitoring per client project
Track which servers belong to which clients
AI Balance per project for accurate client billing
Monthly balance reporting in client invoices

Enterprise Team

Automated balance monitoring across all servers
Alert when General Balance drops below threshold
Project-specific AI Balance transfers for department budgets
Integration with accounting systems via transaction API

AI-Heavy Workflow

Start with minimal AI Balance ($10-20)
Monitor AI usage daily during development
Transfer more only when approaching limit
Track AI costs per feature/project

Best Practices

General Balance:

Maintain 2-3x monthly server costs as buffer
Set calendar reminders for server renewal dates
Automated monitoring via balance API
Alert when below threshold

AI Balance:

Start small ($10-20 transfers)
Monitor usage weekly
Set hard limits in code
Separate AI budgets per project/purpose

Transfer Strategy:

Never over-transfer to AI Balance (can’t move funds back)
Transfer only what you plan to use immediately
Budget conservatively—better to transfer again than have excess stuck in AI

Automation:

Check balances before expensive operations
Auto-alert on low General Balance (servers at risk)
Pre-check AI Balance before running LLM tasks
Integration with monitoring systems

Useful Questions

How do I know when I’m running low on funds?

Check your balance programmatically via GET /api/v1/wallet/balances. Set up automated monitoring that alerts you when balance drops below a threshold (e.g., twice your monthly server costs). The Hoody dashboard also shows balance warnings.

What happens if my General Balance reaches zero during an active server rental?

Your servers enter a grace period. You’ll be prompted to add funds. If balance isn’t restored within the grace period, services may be paused to prevent debt accumulation. Always maintain a buffer to avoid interruption.

Can I get refunds for unused server time?

Server rentals are generally non-refundable once provisioned, similar to other hosting services. However, if you encounter technical issues preventing server use, contact support—we handle these on a case-by-case basis.

How quickly do payments get credited to my account?

Credit card payments via Stripe typically process within seconds. Your General Balance updates immediately upon successful payment processing. Some payment methods may take longer—you’ll see pending status during processing.

Can I move funds from AI Balance back to General Balance?

No. Transfers are one-way only (General → AI). This is intentional to prevent AI budget bloat. Transfer conservatively—only what you plan to use.

How do I add funds to General Balance?

See Billing & Payments → for payment methods: credit cards (instant), cryptocurrency (+5% fee, 5-60 min), or bank transfer (1-3 business days, $500+ minimum).

How does AI Balance prevent overspending?

Hard limit. Once ai_remaining reaches $0, AI services stop. You must explicitly transfer more from General Balance. This prevents runaway AI costs from draining infrastructure budget.

Can I set automated spending limits?

Not built-in yet. Implement your own via balance API—check General Balance before server operations, check AI Balance before LLM tasks. Set alerts when approaching thresholds.

How quickly can I check my balance?

Instant via API: GET /api/v1/wallet/balances. Automated scripts can poll every few seconds if needed. Dashboard shows real-time balance as well.

What if my General Balance hits zero during a server rental?

Server enters grace period. You’re alerted to add funds. If not resolved within grace, service may pause. Always maintain 2-3x monthly server costs as buffer.

Can AI automatically transfer funds from General to AI Balance?

Technically yes, via API with proper auth. But be very careful—transfers are one-way. Better to have AI alert when low, then human approves transfer.

How do I track where my General Balance is being spent?

See transaction history: GET /api/v1/wallet/transactions. Filter by server rentals vs. other charges. Download monthly reports. See Billing & Payments → for complete transaction management.

Troubleshooting

Can’t Transfer to AI Balance

Problem: POST /api/v1/wallet/transfers fails with insufficient funds error

Solution:

# Check General Balance first
GET /api/v1/wallet/balances/general

# If insufficient, add funds via one of these:
# - Credit card (instant)
# - Cryptocurrency (+5% fee, 5-60 min)
# - Bank transfer (1-3 days)

See: Billing & Payments → for payment methods

Accidentally Transferred Too Much to AI Balance

Problem: Transferred $500 to AI, only needed $50

Reality: Funds are stuck. Transfers are one-way only (cannot move AI → General).

Prevention:

Transfer conservatively
Start with small amounts ($10-20)
Transfer more as needed
Remember: can always transfer MORE, never LESS

Balance Shows Wrong Amount

Problem: Balance doesn’t match expectations

Check:

Recent transactions:
Terminal window
```
GET /api/v1/wallet/transactions?limit=10&sort_order=desc
```
Review last 10 transactions for unexpected charges
Pending payments:
- Cryptocurrency payments may show pending during confirmations
- Check payment status: GET /api/v1/wallet/payments/crypto/intents/{id} for cryptocurrency, or GET /api/v1/wallet/payments/stripe/intents/{id} for card payments
Server renewals:
- Rentals do not auto-renew; expiring servers must be renewed manually, which charges your General Balance
- Check server rental dates

If unexplained discrepancy: Contact support with transaction IDs for investigation.

What’s Next

Related pages:

Billing & Payments → - Payment methods, transactions, invoices
Wallet & Payments API → - Complete endpoint reference

Use your balance:

Rent Servers → - Spend General Balance on infrastructure

Automate monitoring:

Implement balance checks before critical operations
Set up alerts for low General Balance
Track AI spending per project

Two balances. One for servers, one for AI. Transfer between them. Monitor via HTTP. Containers are unlimited. AI is isolated.

This is wallet design for infinite computers.