Create Wallet

Creates a wallet for an account and currency in one project. Meterry uses wallets for realtime balance deduction after usage is rated.

POST /v1/projects/:project_id/wallets

Authentication

Authorization: Bearer <api-key>
Content-Type: application/json

Path Parameters

Field	Required	Description
project_id	Yes	Project that owns the wallet. The account_id in the request body must belong to this project.

Request Body

{
  "account_id": "acct_xxx",
  "currency": "USD",
  "balance": "1000.00",
  "credit_limit": "100.00"
}

Field	Required	Description
account_id	Yes	Billing account ID returned by Create Account in the same project.
currency	Yes	Wallet currency. The server normalizes it to uppercase, for example USD.
balance	No	Initial wallet balance. Defaults to 0. A non-zero value also writes an initial_balance wallet ledger entry. Use a JSON string for decimal precision.
credit_limit	No	Credit limit. Defaults to 0 and must not be negative. Use a JSON string for decimal precision.

Response

{
  "id": "wal_xxx",
  "tenant_id": "t_001",
  "project_id": "proj_gateway",
  "account_id": "acct_xxx",
  "currency": "USD",
  "balance": "1000",
  "available_balance": "1100",
  "credit_limit": "100",
  "status": "active",
  "created_at": 1782720000,
  "updated_at": 1782720000
}

Notes

• available_balance is computed by the server as balance + credit_limit.
• When balance is not 0, the service writes an opening ledger entry in the same transaction as the wallet: direction is credit (debit when balance is negative), source_type is initial_balance, source_id is the wallet ID, and balance_after equals balance. Wallet history therefore explains the opening money instead of starting from an unexplained amount, and the entry can be filtered with source_type=initial_balance.
• When balance is 0 no ledger entry is written, so the history stays empty until a credit, debit, or usage reconciliation moves money.
• Creating a wallet, including one with an opening balance, does not emit a wallet.balance_changed webhook, so no wallet.available_balance.threshold_crossed is derived either. When a balance change must reach webhook consumers, create the wallet with balance=0 and fund it through Credit Wallet.
• After creation, the service initializes the realtime virtual wallet cache.
• Amount, balance, and credit fields should be sent as JSON strings to avoid floating-point precision issues.
• A wallet is unique for tenant_id + project_id + account_id + currency.