ROSCA Groups

Who it's for: Market women, traders, and salaried workers who want to save together and take turns receiving a lump sum — just like a traditional susu or tontine. Why it matters: ROSCA groups eliminate the middleman — no bank account needed, contributions are enforced on-chain, and payouts happen automatically to the elected recipient.

ROSCA (Rotating Savings and Credit Association) is the digital version of the African susu — a group of people pool contributions each cycle, and one member receives the full pot.

`POST /group/create`

Deploy a new savings group (createGroup on-chain). The admin sets all group parameters upfront.

Request

{
  "adminAddressId": "wallet-uuid",
  "adminAddress": "0xabc...",
  "config": {
    "groupName": "Market Women GH Q1",
    "amountPerPerson": "50000000",
    "adminFeeBps": 100,
    "contributionPeriod": 2592000,
    "currency": "0x3126627A607E730E3eCF9BbfFD67fa18Deaab846",
    "collateralAmount": "10000000",
    "requireCollateral": true,
    "maxParticipants": 12,
    "biddingEnabled": false,
    "defaultHandlingEnabled": true,
    "interestEnabled": false,
    "midCycleJoinEnabled": false,
    "midCycleLeaveEnabled": false,
    "loanIntegrationEnabled": false,
    "resetEnabled": false,
    "biddingPeriod": 0,
    "minimumBidAmount": "0",
    "gracePeriod": 86400,
    "maxMissedContributions": 1,
    "interestRate": 0
  }
}

Field	Notes
`amountPerPerson`	Per-cycle contribution in base units (6 dec for cGHS)
`contributionPeriod`	Seconds between contribution rounds
`collateralAmount`	Required collateral per participant (if `requireCollateral`)
`currency`	cGHS address: `0x3126627A607E730E3eCF9BbfFD67fa18Deaab846`
`adminFeeBps`	Admin fee in basis points (100 = 1%)
`gracePeriod`	Seconds after due date before a missed contribution is counted

Response

{ "id": "d1-uuid", "status": "pending" }

`POST /group/:groupId/join`

Join a group by depositing collateral (if required).

Request

{
  "userAddressId": "wallet-uuid",
  "userAddress": "0xabc..."
}

The Transaction batch call is: [approve(diamond, collateralAmount), joinGroup(groupId)].

`POST /group/:groupId/contribute`

Pay your contribution for the current cycle.

Request

{
  "userAddressId": "wallet-uuid",
  "userAddress": "0xabc...",
  "amount": "50000000"
}

`POST /group/:groupId/vote`

Vote for who should receive the pot this cycle (if voting is enabled).

Request

{
  "userAddressId": "wallet-uuid",
  "userAddress": "0xabc...",
  "candidate": "0xdef..."
}

`POST /group/:groupId/disburse`

Admin disburses the cycle pot to the elected recipient.

Request

{
  "adminAddressId": "wallet-uuid",
  "adminAddress": "0xabc...",
  "recipient": "0xdef..."
}

`POST /group/:groupId/advance`

Advance to the next cycle (admin only).

Read Endpoints

GET  /group/:groupId              — on-chain group state (viem)
GET  /group/:groupId/participants — all participant addresses
GET  /group/user/:address         — groups the user belongs to (D1)
GET  /group/contribution/:id      — contribution status (D1)