Skip to main content

Shared Wallet and Funding Models

YODI charges each billable operation using the active unit tariff. The funding model determines where those charges are drawn from; it does not make different operation prices equal.

Read the Current Funding Model​

GET https://api.yodi.tg/v1/credits/me/funding

The endpoint requires the HTTP-only session cookie established by YODI sign-in (JwtCookieAuthGuard); it does not use an API-key bearer header. The API derives the account owner from the authenticated session; callers cannot select a user or wallet. A browser sends the cookie automatically. Never expose or log the cookie. The JSON examples below show the data object inside the standard YODI response envelope; they are not the complete HTTP response. All numeric values are illustrative. The data object is one of the following strict variants.

service_bucket​

{
  "fundingModel": "service_bucket",
  "services": {
    "translation": { "quota": 100, "used": 20, "reserved": 5 },
    "audio": { "quota": 0, "used": 0, "reserved": 0 },
    "sms": { "quota": 0, "used": 0, "reserved": 0 },
    "voice_call": { "quota": 0, "used": 0, "reserved": 0 }
  },
  "expiresAt": null
}

This compatibility model keeps credits isolated by service. A balance in one service cannot pay for another service. reserved is held for in-flight work and is not available to start another operation. expiresAt is the UTC expiry instant or null when no expiry is set.

shared_wallet​

{
  "fundingModel": "shared_wallet",
  "availableCredits": 75,
  "reservedCredits": 10
}

This model has one cross-service balance. availableCredits is spendable and already excludes in-flight holds. reservedCredits reports those holds; do not add it to the available amount or spend it again. A shared wallet does not create per-module allowances.

Tariffs, Holds, and Limits​

  • Read current operation prices and billing units from the public GET /v1/billing/pricing catalog. Translation, generated audio, transcription, SMS, WhatsApp, and voice calls may have different prices and units.
  • A workflow can perform more than one billable operation. A reservation is a temporary hold; the API settles the validated successful quantity and releases unused held credits according to the operation outcome.
  • Reporting categories explain charges; in shared-wallet mode they are not independent balances.
  • Plan request quotas and requests-per-minute limits are separate from credits. Wallet balance does not raise a request limit or authorize access to a module.

Compatibility and Availability​

GET /v1/credits/me and /v1/services/{name}/quota expose legacy service-bucket views. They do not prove that a shared wallet is active. Use the fundingModel returned by /v1/credits/me/funding and do not infer a model from a plan, a tariff, or a successful response from another endpoint.

The funding read can return either model according to the backend's active policy. If that policy is unavailable or fails its readiness checks, the API fails closed with its standard error envelope. Do not assume a shared-wallet cutover is active in a particular environment unless that environment has separately verified release evidence.