NetworkCoinsChangeRequest network.coins-change-request@1
Generated at from
openvibe-contracts v0.53.0 and
openvibe-sdk v0.11.0.
- Version
- 1.0.0
- Owner
- network
- Visibility
- first-party
- Status
- active
- Compatibility
- backward
- Schema
https://openvibe.network/contracts/network/coins-change-request.v1.json
network.coins-change-request@1: bodies of network.coins.credit and network.coins.debit on OpenVibe.Network (OpenCoins: loyalty, never money). POST /internal/coins/credit and POST /internal/coins/debit: { user_id, app_id?, amount, reason?, ref?, idempotency_key }. user_id is the Network user id (the integer, never a subject). Refusals are { error } bodies: 400 invalid_user_id, invalid_amount or missing_idempotency_key; 404 user_not_found; a debit larger than the balance is 409 { error: insufficient_funds, balance }. Unknown fields are ignored.
Fields
| Field | Type | Required | Description | Constraints |
|---|---|---|---|---|
user_id | integer | string | yes | The Network user id whose wallet changes. |
|
app_id | string | The app the coins move for. A service token may only name its own (svc:live → live); anything else is 403 capability.owner_denied. The shared internal key may name any. | ||
amount | integer | yes | OpenCoins, a positive whole number (a string is refused: 400 invalid_amount). |
|
reason | string | null | Why, kept on the ledger row. | ||
ref | string | null | The caller's reference for the row (an order, a game, …). | ||
idempotency_key | string | yes | Unique per mutation. A replay returns the first answer and changes nothing (400 missing_idempotency_key without it). |
|
Examples
From the contract's own test fixtures: valid ones validate, rejected ones must fail.
Valid: credit
{
"user_id": 1042,
"app_id": "live",
"amount": 25,
"reason": "watch_streak",
"ref": "stream:8812",
"idempotency_key": "live:streak:1042:2026-09-25"
}Valid: string-user
{
"user_id": "77",
"amount": 5,
"idempotency_key": "games:prize:77:rnd_551"
}Rejected: no-key
{
"user_id": 1042,
"amount": 25
}Rejected: string-amount
{
"user_id": 1042,
"amount": "25",
"idempotency_key": "k1"
}Validate
const contracts = require('openvibe-contracts');
contracts.validate('network.coins-change-request@1', value); // { valid, errors: [{ path, message }] }