---
title: "Go SDK — Wallet & billing"
description: "Wallet balance, usage queries, top-ups, and billing configuration with the Metalhost Go SDK."
url: "https://metalhost.net/docs/developers/guides/sdk-wallet"
---

# Go SDK — Wallet & billing

Billing is org-scoped via `WalletServiceClient`. Amounts are in **minor units** (cents for USD). Fund the wallet before creating prepaid VMs or bare-metal leases.

## Balance and forecast

```
wallet := walletv1connect.NewWalletServiceClient(httpClient, base)
resp, err := wallet.GetWalletBalance(ctx, connect.NewRequest(
    &walletv1.GetWalletBalanceRequest{
        Name: "organizations/my-org/wallets/default",
    },
))
balanceMinor := resp.Msg.GetBalanceMinor()
```

```
wallet.GetCostForecast(ctx, connect.NewRequest(
    &walletv1.GetCostForecastRequest{WalletName: walletName},
))
```

## Usage

```
usage, err := wallet.QueryUsage(ctx, connect.NewRequest(
    &walletv1.QueryUsageRequest{
        ProjectName: "projects/my-app",
        StartTimeUnix: start,
        EndTimeUnix:   end,
        GroupBy:       walletv1.UsageGroupBy_USAGE_GROUP_BY_CATEGORY,
    },
))
```

Group by category, resource, or datacenter. Export CSV via `ExportUsage` (returns signed download URL).

Categories include: Bare Metal, vCPU, Memory, GPU, VM Storage, Data Transfer, Public IPv4. **Data Transfer** meters VM egress only — bare-metal leases include unlimited bandwidth and do not bill transfer.

## Top-ups

### Card (Stripe)

```
intent, err := wallet.CreateStripeTopUpIntent(ctx, connect.NewRequest(
    &walletv1.CreateStripeTopUpIntentRequest{
        WalletName:        "organizations/my-org/wallets/default",
        AmountMinor:       5000,
        PaymentMethodName: "organizations/my-org/payment-methods/pm_abc",
    },
))
// Complete payment client-side with Stripe.js using intent.GetClientSecret()
```

Attach cards first with `CreateCardSetupIntent` + `AttachPaymentMethod`. List via `ListPaymentMethods`.

### Crypto (Coinbase)

```
checkout, err := wallet.CreateCoinbaseTopUpCheckout(ctx, connect.NewRequest(
    &walletv1.CreateCoinbaseTopUpCheckoutRequest{
        WalletName:  "organizations/my-org/wallets/default",
        AmountMinor: 5000,
    },
))
// Redirect user to checkout.GetHostedUrl()
```

Settled 1:1 in USD. Minimum $5 (`500` minor units).

## Auto-recharge and alerts

```
wallet.ConfigureAutoRecharge(ctx, connect.NewRequest(
    &walletv1.ConfigureAutoRechargeRequest{
        WalletName:        "organizations/my-org/wallets/default",
        Enabled:           true,
        ThresholdMinor:    1000,
        AmountMinor:       5000,
        PaymentMethodName: "organizations/my-org/payment-methods/pm_abc",
    },
))
```

```
wallet.ConfigureWalletAlerts(ctx, connect.NewRequest(
    &walletv1.ConfigureWalletAlertsRequest{
        WalletName: walletName,
        BalanceAlertMinor:   ptr(int64(1000)),
        DaysRemainingAlert:  ptr(int32(7)),
    },
))
```

## Invoices

```
wallet.ListInvoices(ctx, connect.NewRequest(&walletv1.ListInvoicesRequest{
    BillingAccountName: "organizations/my-org/billing-accounts/default",
}))
wallet.DownloadInvoicePDF(ctx, connect.NewRequest(&walletv1.DownloadInvoicePDFRequest{
    Name: invoiceName,
}))
```

Monthly close statements — accounting records, not amounts due.

## Public pricing

```
wallet.ListPublicMeterRates(ctx, connect.NewRequest(
    &walletv1.ListPublicMeterRatesRequest{},
))
```

Unauthenticated — meter rates for quoting (same data as catalog pricing).

> **prepay model**
>
> Creates with monthly billing modes and bare-metal prepaid terms debit the wallet immediately. Insufficient balance → `FailedPrecondition`.

## What's next

- [Dashboard — Wallet & top-ups](https://metalhost.net/docs/dashboard/guides/wallet-topup.md)
- [Dashboard — Billing & usage](https://metalhost.net/docs/dashboard/guides/billing.md)
- [Examples → wallet](https://metalhost.net/docs/developers/examples.md#wallet)