Credit pools

List credit pools and budget settings for a scope (usually an AI project). Used by the dealer UI tab Budget (Ngân sách sub-tab — not Hạn mức, which is AI projects set_budget).

Dealer UI

On 79ai-style apps, Credit pools, + Nạp, and LEDGER usually appear only when Share credit is on (set_share_credit / enabled=1). Use action=list after enabling share credit to load settings and catalog.

Authentication matches other platform V2 calls: Bearer + form access_token, registration domain, device fields.

Playground

Playground — Home feed → Project billing when running npm run docs:stack (worker labels match the UI).

Playground (Home feed)

Section Project billing on POST /gateway/credit-pools (same-origin when using npm run docs:stack):

Playground worker	JSON action	Main form fields
List pools	list	scope_type, scope_id (project id_base), language
Pool transactions	ledger	scope_type, scope_id, optional limit, language
Create & fund pool	create	scope_id, name, amount, currency_name, status, optional tags / note
Top up pool	deposit	scope_id, pool_id, amount, optional note
Delete pool	delete	scope_id, pool_id
Shared credits	set_share_credit	id_base, enabled (0/1)

List pools for a project

POST https://api.gommo.net/api/v2/credit-pools
Content-Type: application/x-www-form-urlencoded

Field	Required	Notes
action	yes	list
scope_type	yes	project (also workspace, chat_group, campaign, custom in catalog)
scope_id	yes	Project id_base from AI projects list
domain, access_token	yes
language	optional	e.g. vi

PowerShell

$domain = $env:GOMMO_API_DOMAIN
if (-not $domain) { throw 'Set GOMMO_API_DOMAIN' }
$h = @{ Authorization = "Bearer $env:TOKEN"; 'Content-Type' = 'application/x-www-form-urlencoded' }
$scopeId = '<project_id_base>'
$body = "access_token=$env:TOKEN&domain=$domain&action=list&scope_type=project&scope_id=$scopeId&language=vi"
Invoke-RestMethod -Method Post -Uri 'https://api.gommo.net/api/v2/credit-pools' -Headers $h -Body $body

Response shape (pass-through)

• data.pools[] — funded pools (empty → UI “no credit pool yet”)
• data.settings.share_credit_enabled — members share project pools when 1
• data.settings.budget_ceiling — max allocatable from wallet into this scope
• data.catalog.currencies[] — e.g. credits_ai, balance, chat turns
• data.summary[], data.tags[], data.statuses[]

Self-host gateway (Mode B)

POST {gateway}/gateway/credit-pools with JSON:

{
  "action": "list",
  "scope_type": "project",
  "scope_id": "<project id_base>",
  "language": "vi"
}

Bearer required. Gateway adds domain when omitted. Aliases: scopeType, scopeId, id_base / projectId for scope_id when scope_type is project.

OpenAPI: openapi.yaml — /gateway/credit-pools.

Share credit toggle (verified)

POST https://api.gommo.net/api/v2/credit-pools with action=set_share_credit:

Field	Required	Notes
id_base	yes	Project UUID (same as list scope_id)
enabled	yes	0 (off) or 1 (on) — not share_credit_enabled in the request
domain, access_token	yes

Mode B:

{
  "action": "set_share_credit",
  "id_base": "<project id_base>",
  "enabled": 1,
  "language": "vi"
}

Gateway accepts legacy JSON alias share_credit_enabled and maps it to enabled. Responses often include share_credit_enabled on projectInfo / data.settings.

Playground: Shared credits.

Ledger (verified)

Expand LEDGER at the bottom of the budget sub-tab (after share credit is on).
POST https://api.gommo.net/api/v2/credit-pools:

Field	Required	Notes
action	yes	ledger
scope_type	yes	project
scope_id	yes	Project id_base
limit	optional	Dealer UI often sends 20
page	optional	Pagination if upstream supports it

Response (pass-through): { "success": true, "data": { "items": [ … ] } } — empty items when no pool activity yet.

Mode B:

{
  "action": "ledger",
  "scope_type": "project",
  "scope_id": "<project id_base>",
  "limit": 20,
  "language": "vi"
}

Playground: Pool transactions.

Related

• AI projects — member_list, set_budget
• Home feed cookbook

Create pool & first fund (verified — Tạo pool & nạp)

When no pool exists yet, the dealer form Tạo pool & nạp calls:

POST https://api.gommo.net/api/v2/credit-pools with action=create (not deposit).

Field	Required	Notes
scope_type	yes	project
scope_id	yes	Project id_base
name	yes	Pool display name
amount	yes	Integer credits (dealer UI may enforce minimum, e.g. 200_000)
currency_name	yes	Capture used credit_ai — match catalog from action=list
status	yes	e.g. shared (team) or private
tags	optional	Tag string
note	optional	e.g. first deposit note

Mode B:

{
  "action": "create",
  "scope_type": "project",
  "scope_id": "<project id_base>",
  "name": "hehehe",
  "amount": 200000,
  "currency_name": "credit_ai",
  "status": "shared",
  "tags": "sssss",
  "note": "First fund into project pool",
  "language": "vi"
}

Gateway aliases: currency / currencyName → currency_name.

After success, action=list returns data.pools[] with balance, status, note; LEDGER may show entries.

Playground: Create & fund pool.

Delete pool (verified — Xóa)

Removes a pool from the project scope. Dealer UI Xóa sends:

POST https://api.gommo.net/api/v2/credit-pools with action=delete.

Field	Required	Notes
scope_type	yes	project
scope_id	yes	Project id_base
pool_id	yes	Pool UUID from action=list → data.pools[].id

Response (pass-through): { "success": true, "data": { "ok": true } }.

Wallet refund

data.ok === true means the pool delete was accepted upstream. It does not guarantee unused balance returns to your personal wallet — verify balance and ledger after delete.

Mode B:

{
  "action": "delete",
  "scope_type": "project",
  "scope_id": "<project id_base>",
  "pool_id": "<from list data.pools[].id>",
  "language": "vi"
}

Gateway alias: poolId → pool_id.

Playground: Delete pool.

Deposit into existing pool (verified — Bơm / + Nạp)

When a pool already exists, dealer Bơm (and the + Nạp flow on the same form) calls:

POST https://api.gommo.net/api/v2/credit-pools with action=deposit.

Field	Required	Notes
scope_type	yes	project
scope_id	yes	Project id_base
pool_id	yes	From action=list → data.pools[].id
amount	yes	Integer credits; dealer UI often enforces minimum 200_000
note	optional	e.g. Nap vao Project pool

Wallet reserve (verified): upstream requires the personal wallet to keep at least 100_000 credits after the transfer. To deposit amount, you need wallet balance ≥ amount + 100_000. Otherwise HTTP 200 with error: 1 and a Vietnamese message (not a gateway validation error).

Mode B:

{
  "action": "deposit",
  "scope_type": "project",
  "scope_id": "<project id_base>",
  "pool_id": "<from list>",
  "amount": 200000,
  "note": "Nap vao Project pool",
  "language": "vi"
}

Gateway aliases: poolId → pool_id.

Playground: Top up pool.

First pool vs top-up

No pool yet → action=create (Tạo pool & nạp). Pool exists → action=deposit with pool_id.

AI projects pass-through

Member invite, invite_revoke, and kick are documented on AI projects (Project workspace). Playground: Invite member, Revoke invite, Remove member.