---
title: "billing.vibes-purchase-from-balance-request@1"
canonical: "https://openvibe.services/docs/contracts/billing.vibes-purchase-from-balance-request"
updated: null
---

# billing.vibes-purchase-from-balance-request@1

HTML: [billing.vibes-purchase-from-balance-request@1](https://openvibe.services/docs/contracts/billing.vibes-purchase-from-balance-request)

# BillingVibesPurchaseFromBalanceRequest `billing.vibes-purchase-from-balance-request@1`

Generated at 2026-11-13 06:25:48 UTC from [`openvibe-contracts v0.419.0`](https://github.com/OpenVibers/OpenVibe.Contracts/tree/v0.419.0) and [`openvibe-sdk v0.161.0`](https://github.com/OpenVibers/OpenVibe.SDK/tree/v0.161.0).

- Version: 1.0.0
- Owner: billing
- Visibility: first-party
- Status: active
- Compatibility: backward
- Schema: [`https://openvibe.network/contracts/billing/vibes-purchase-from-balance-request.v1.json`](/docs/contracts/billing.vibes-purchase-from-balance-request.json)

billing.vibes-purchase-from-balance-request@1: body of POST /api/me/vibes/from-balance (D12). Buys a whole number of Vibes with the signed-in person's Balance at the same Vibes price as a pack, charging exact nano-USD; Vibes -> Balance is never allowed. vibes is a whole integer (Vibes have no fractions); the money side is integer nano-USD (D1), never a float. idempotency\_key makes the purchase exactly once.

## Fields

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `vibes` | integer | yes | How many whole Vibes to buy. | - `minimum 1` |
| `idempotency_key` | string | yes | Unique per mutation. A replay with the same key and body returns the first answer and changes nothing. | - `pattern ^[A-Za-z0-9._:-]{8,128}$` |

## Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

 Valid: pack

~~~~
{
  "vibes": 1250,
  "idempotency_key": "vibes-buy-001"
}
~~~~

Rejected: fraction

~~~~
{
  "vibes": 12.5,
  "idempotency_key": "vibes-buy-001"
}
~~~~

Rejected: string-vibes

~~~~
{
  "vibes": "1250",
  "idempotency_key": "vibes-buy-001"
}
~~~~

Rejected: zero

~~~~
{
  "vibes": 0,
  "idempotency_key": "vibes-buy-001"
}
~~~~

## Validate

~~~~
const contracts = require('openvibe-contracts');
contracts.validate('billing.vibes-purchase-from-balance-request@1', value);   // { valid, errors: [{ path, message }] }
~~~~