Wallet & Balance Management

Your Hoody wallet holds two balances: a General Balance for infrastructure and an AI Balance for Hoody AI usage. Funds move from General to AI and never back, so you set each budget explicitly.

API Endpoints Summary

This page explains the wallet and its two balances. The endpoint reference and the payment methods are documented elsewhere:

Wallet & Payments API - Balance checking, fund transfers
Billing & Payments → - Payment methods, transactions, invoices

The two-balance system

General Balance

Your primary account funds, spent on:

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

Add funds with a credit card or another payment method.

AI Balance

A separate credit pool for AI features:

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

Funded only by transfer from the General Balance. Transfers run one way (General → AI) and cannot be reversed, so the AI Balance is a ceiling you set on AI spending.

The General Balance funds infrastructure. The AI Balance is isolated, so AI usage cannot drain the budget you keep for server rentals.

Traditional vs. Hoody billing

The two models differ in how they price each additional environment.

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

How the wallet works

General Balance

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

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>
}

The separation keeps AI services from drawing on your infrastructure budget: you allocate how much AI can spend, and it cannot spend more.

Check balance:

GET /api/v1/wallet/balances/ai

Returns: Limit, current usage, remaining credits

Balance workflow

Add funds to the 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 the General Balance to rent bare metal servers.

Servers are charged by rental duration. Containers have no per-unit cost: once a server exists, you can create as many as its capacity allows.

See: Rent Servers → for marketplace and pricing
Fund the AI Balance (optional)

If you use AI features, transfer funds from the General Balance to the 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>
}
```
Transfers are one way. You 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 through the API or the dashboard.
Terminal window
```
GET /api/v1/wallet/balances
```
For production use, run these checks on a schedule.

Why the balances are separate

With a single balance, AI usage can consume the whole infrastructure budget:

Thousands of expensive LLM calls run overnight
No money is left for core infrastructure
Servers are terminated because renewal has no funds

Hoody splits the wallet so that the two budgets cannot reach each other.

General Balance funds infrastructure

Server rentals and platform costs draw on this balance only. AI usage cannot reach it, so your infrastructure stays funded.

AI Balance caps AI spending

You transfer the exact amount you want AI to use. When it runs out, AI services stop rather than spending more.

You set both budgets. Transfer to the AI Balance only when you want to use AI features, and only as much as you are willing to spend.

Balance checks

Three endpoints read the wallet: both balances at once, the General Balance alone, or the AI Balance alone.

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: Checking whether you need to add funds before a server renewal

AI Balance only

GET /api/v1/wallet/balances/ai

Returns: AI credit limit, usage, and remaining balance

Use for: Checking whether AI has budget before an expensive LLM task

Balance automation

Every balance endpoint is plain HTTP, so a script can read the wallet and act on what it finds.

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 the General Balance

// Check if funds are running low
async function checkInfrastructureBalance() {
  const response = await fetch('https://api.hoody.com/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 the AI Balance

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

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

  return remaining >= estimatedCost;
}

Top up the AI Balance on demand

// Transfer to AI only when needed, with limits
async function fundAIForTask(estimatedCost) {
  const aiBalance = await fetch('https://api.hoody.com/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.com/api/v1/wallet/payment-availability', {
      headers: { 'Authorization': `Bearer ${token}` }
    }).then(r => r.json());

    // Transfer only what's needed; transfers are one way
    const res = await fetch('https://api.hoody.com/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}`);
  }
}

Cost optimization

Consolidate containers

One server hosts many containers, which changes the arithmetic against per-VM pricing:

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

Consolidate workloads onto fewer servers when possible.

Right-size servers

Do not over-provision:

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

Separating dev, staging, and production usually takes 2-3 servers at most.

AI budget management

Set the AI budget in code and check it before you spend it:

// 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.com/api/v1/wallet/payment-availability', {
  headers: { 'Authorization': `Bearer ${token}` }
}).then(r => r.json());

await fetch('https://api.hoody.com/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.com/api/v1/wallet/balances/ai', {
  headers: { 'Authorization': `Bearer ${token}` }
}).then(r => r.json());
// Stop AI tasks if aiBalance.data.ai_remaining drops below threshold

Use snapshots instead of idle containers

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

A deleted container consumes no server resources, so more active containers fit on the same machine.

What you pay for

Your account is charged for two things and nothing else.

Server rentals

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

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

AI usage

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

AI is optional and server rentals do not include it, so you pay for it only if you use it.

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 the AI Balance, because funds cannot move back
Transfer only what you plan to use immediately
Budget conservatively: transferring again is easy, and an excess sits stuck in AI credit

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 if my General Balance hits zero during a rental?

Your servers enter a grace period and you are prompted to add funds. If the balance is not restored within that period, services may be paused so debt does not accumulate. Keeping 2-3x monthly server costs as a buffer avoids the interruption.

Can I get refunds for unused server time?

Server rentals are generally non-refundable once provisioned, as with other hosting services. If a technical problem prevents you from using the server, contact support; those cases are handled individually.

How quickly do payments get credited to my account?

Credit card payments via Stripe typically process within seconds, and your General Balance updates as soon as payment succeeds. Some payment methods take longer and show a pending status while they process.

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

No. Transfers run one way, General → AI. That is intentional, so transfer 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?

The limit is hard. Once ai_remaining reaches $0, AI services stop until you transfer more from the General Balance, so runaway AI costs never reach the infrastructure budget.

Can I set automated spending limits?

Not built in yet. Implement your own with the balance API: check the General Balance before server operations and the AI Balance before LLM tasks, and alert when either approaches your threshold.

How quickly can I check my balance?

The API answers immediately: GET /api/v1/wallet/balances. Scripts can poll every few seconds if needed, and the dashboard shows the same figures.

Can an AI agent transfer funds on its own?

Technically yes, through the API with the right auth. Because transfers are one way, the safer pattern is to have the agent alert you when the AI Balance runs low and approve the transfer yourself.

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

Transfer to AI Balance fails

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

Too much transferred to AI Balance

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

Reality: The funds are stuck. Transfers run one way and cannot move AI → General.

Prevention:

Transfer conservatively
Start with small amounts ($10-20)
Transfer more as needed
You can always transfer more, and never less

Balance shows the 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 the discrepancy is still unexplained, contact support with the transaction IDs.

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