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. 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.
• 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.