Pools

A Pool is a standing pre-funded commitment. Members commit annually; the platform batches their prepayment so most payouts run free (Addendum 001).

The Pool object

{
  "id":                       "pool_01HZ...",
  "name":                     "Cedar Block Mutual Aid",
  "slug":                     "cedar-block-mutual-aid",
  "flavor":                   "community",
  "legal_structure":          "mutual_aid",
  "distribution_mechanism":   "threshold",
  "governance":               { "threshold": 3 },
  "treasury_balance_cents":   4800000,
  "reserves_balance_cents":   0,
  "status":                   "active",
  "created_at":               "2026-01-12T18:00:00Z"
}

POST /v1/pools

Open a new pool. The authenticated identity becomes the initial steward.

Field	Type		Description
name	string	required	Display name.
flavor	string	required	community \| creator \| cause
legal_structure	string	required	charitable_hardship \| mutual_aid \| fiscal_sponsorship \| personal_gift
distribution_mechanism	string	required	scheduled_rotation \| random \| member_vote \| steward_directed \| emergency \| threshold
governance	object	optional	Mechanism-specific options (e.g. { "threshold": 3 }).
description	string	optional	What the pool is for.

Example request

curl -X POST https://api.bequest.org/v1/pools \
  -H "Authorization: Bearer $BQ_KEY" \
  -d '{
    "name": "Cedar Block Mutual Aid",
    "flavor": "community",
    "legal_structure": "mutual_aid",
    "distribution_mechanism": "threshold",
    "governance": { "threshold": 3 }
  }'

const pool = await bq.pools.create({
  name:                   'Cedar Block Mutual Aid',
  flavor:                 'community',
  legal_structure:        'mutual_aid',
  distribution_mechanism: 'threshold',
  governance:             { threshold: 3 },
});

pool = bq.pools.create(
    name='Cedar Block Mutual Aid',
    flavor='community',
    legal_structure='mutual_aid',
    distribution_mechanism='threshold',
    governance={'threshold': 3},
)

<?php
$pool = $bq->pools->create([
    'name'                   => 'Cedar Block Mutual Aid',
    'flavor'                 => 'community',
    'legal_structure'        => 'mutual_aid',
    'distribution_mechanism' => 'threshold',
    'governance'             => ['threshold' => 3],
]);

pool = bq.pools.create(
  name:                   'Cedar Block Mutual Aid',
  flavor:                 'community',
  legal_structure:        'mutual_aid',
  distribution_mechanism: 'threshold',
  governance:             { threshold: 3 }
)

pool, err := bq.Pools.Create(ctx, &bequest.PoolCreateParams{
    Name:                   "Cedar Block Mutual Aid",
    Flavor:                 "community",
    LegalStructure:         "mutual_aid",
    DistributionMechanism:  "threshold",
    Governance:             map[string]any{"threshold": 3},
})

Example response

{ "id": "pool_01HZ...", "status": "active", "treasury_balance_cents": 0, ... }

Returns: The newly-created Pool object.

GET /v1/pools/{id}

Retrieve a pool by id, including its current treasury balance.

Field	Type		Description
id	string	required	Pool id, prefixed `pool_`.

GET /v1/pools

List pools the authenticated identity stewards or is a member of.

Field	Type		Description
status	string	optional	draft\|active\|paused\|closed
limit	integer	optional	Default 25.
cursor	string	optional	Pagination cursor.

POST /v1/pools/{id}/commit

A member commits to the pool. Triggers the annual prepayment batch.

Field	Type		Description
identity_id	string	required	Identity of the committing member.
cadence	string	required	weekly \| monthly \| quarterly \| semiannual \| annual
per_cadence_amount_cents	integer	required	Amount per cadence step, in cents.
payment_method_id	string	required	Funding source on file.
auto_renew	boolean	optional	Renew next year automatically. Default false.

Returns: The created Commitment object.

POST /v1/pools/{id}/disburse

Call a disbursement from the pool. Goes through the configured distribution mechanism.

Field	Type		Description
to	string	required	Identity id receiving the payout.
amount_cents	integer	required	Amount in cents.
reason	string	optional	Reason recorded on the audit trail.

Example request

curl -X POST https://api.bequest.org/v1/pools/pool_01HZ.../disburse \
  -H "Authorization: Bearer $BQ_KEY" \
  -d '{"to":"usr_77...","amount_cents":35000,"reason":"rent"}'

const disbursement = await bq.pools.disburse('pool_01HZ...', {
  to:           'usr_77...',
  amount_cents: 35000,
  reason:       'rent',
});

disbursement = bq.pools.disburse(
    'pool_01HZ...',
    to='usr_77...',
    amount_cents=35000,
    reason='rent',
)

$disbursement = $bq->pools->disburse('pool_01HZ...', [
    'to'           => 'usr_77...',
    'amount_cents' => 35000,
    'reason'       => 'rent',
]);

disbursement = bq.pools.disburse(
  'pool_01HZ...',
  to:           'usr_77...',
  amount_cents: 35_000,
  reason:       'rent'
)

disbursement, err := bq.Pools.Disburse(ctx, "pool_01HZ...", &bequest.DisburseParams{
    To:          "usr_77...",
    AmountCents: 35000,
    Reason:      bequest.String("rent"),
})

Example response

{ "id": "dbr_...", "status": "approved", "executed_at": "2026-05-15T13:46:01Z" }

Returns: A DisbursementRequest (or completed Disbursement, depending on the mechanism).

GET /v1/pools/{id}/members

List the members of a pool.

GET /v1/pools/{id}/ledger

List ledger events for the pool — every commitment, disbursement, and adjustment.

Events

pool.created
pool.committed
pool.disbursement_requested
pool.disbursement_approved
pool.disbursement_executed