Skip to content

api.md

Latest commit

 

History

History
263 lines (196 loc) · 7.02 KB

api.md

File metadata and controls

263 lines (196 loc) · 7.02 KB
Raw

API Reference

Base URL: http://localhost:3000/api

All request and response bodies are JSON. All amounts are in stroops (1 XLM = 10,000,000 stroops).

GET /health

Health check. Confirms the server is running and shows the configured Stellar network.

Response 200

{
  "status": "ok",
  "network": "testnet"
}

curl

curl http://localhost:3000/health

POST /groups/create

Creates a new ROSCA group and provisions a multisig treasury account on Stellar.

Request body

Field Type Required Description
adminSecret string yes Secret key of the group admin
members string[] yes Array of member public keys (min 2)
contributionAmount number yes Amount each member contributes per cycle (stroops)
cycleDurationDays number yes Length of each cycle in days 
{
  "adminSecret": "SADMIN...",
  "members": ["GMEMBER1...", "GMEMBER2...", "GMEMBER3..."],
  "contributionAmount": 10000000,
  "cycleDurationDays": 7
}

Response 201

Field Type Description
id string UUID of the group
admin string Admin public key
members string[] Member public keys
contributionAmount number Per-member contribution (stroops)
cycleDurationDays number Cycle length in days
currentCycle number Current cycle number (starts at 1)
recipientQueue string[] Shuffled payout order
groupAccountPublicKey string Treasury account public key
status string "active"
createdAt number Unix timestamp (ms) 
{
  "id": "a1b2c3d4-...",
  "admin": "GADMIN...",
  "members": ["GMEMBER1...", "GMEMBER2...", "GMEMBER3..."],
  "contributionAmount": 10000000,
  "cycleDurationDays": 7,
  "currentCycle": 1,
  "recipientQueue": ["GMEMBER2...", "GMEMBER1...", "GMEMBER3..."],
  "groupAccountPublicKey": "GTREASURY...",
  "status": "active",
  "createdAt": 1715000000000
}

curl

curl -X POST http://localhost:3000/api/groups/create \
  -H "Content-Type: application/json" \
  -d '{
    "adminSecret": "SADMIN...",
    "members": ["GMEMBER1...", "GMEMBER2..."],
    "contributionAmount": 10000000,
    "cycleDurationDays": 7
  }'

Errors

Status Condition
400 Missing required fields
400 members has fewer than 2 entries
500 Stellar treasury creation failed

POST /groups/:id/contribute

Records a contribution from a member for the current cycle. Builds and submits a Stellar payment from the member's account to the group treasury.

Path params

Param Type Description
id string Group UUID

Request body

Field Type Required Description
memberSecret string yes Secret key of the contributing member
amount number yes Contribution amount in stroops 
{
  "memberSecret": "SMEMBER...",
  "amount": 10000000
}

Response 200

Field Type Description
success boolean true
txHash string Stellar transaction hash
groupStatus.id string Group UUID
groupStatus.currentCycle number Current cycle number
groupStatus.status string Group status ("active" / "completed")
groupStatus.allContributed boolean Whether all members have contributed this cycle
groupStatus.contributedThisCycle string[] Public keys that have contributed
groupStatus.totalMembers number Total number of members 
{
  "success": true,
  "txHash": "a3f9c2...",
  "groupStatus": {
    "id": "a1b2c3d4-...",
    "currentCycle": 1,
    "status": "active",
    "allContributed": false,
    "contributedThisCycle": ["GMEMBER1..."],
    "totalMembers": 3
  }
}

curl

curl -X POST http://localhost:3000/api/groups/a1b2c3d4-.../contribute \
  -H "Content-Type: application/json" \
  -d '{
    "memberSecret": "SMEMBER...",
    "amount": 10000000
  }'

Errors

Status Condition
400 Missing memberSecret or amount
400 amount is not a positive number
403 Member is not part of the group
404 Group not found
500 Stellar transaction failed or member already contributed

GET /groups/:id/status

Returns the current state of a group.

Note: Not yet implemented — returns a stub response.

Path params

Param Type Description
id string Group UUID

Response 200 (stub)

{
  "message": "not implemented yet",
  "endpoint": "GET /:id/status"
}

curl

curl http://localhost:3000/api/groups/a1b2c3d4-.../status

POST /groups/:id/payout

Triggers the payout for the current cycle to the next recipient in the queue.

Note: Not yet implemented — returns a stub response.

Path params

Param Type Description
id string Group UUID

Response 200 (stub)

{
  "message": "not implemented yet",
  "endpoint": "POST /:id/payout"
}

curl

curl -X POST http://localhost:3000/api/groups/a1b2c3d4-.../payout

GET /groups/:id/members

Lists all members of a group.

Note: Not yet implemented — returns a stub response.

Path params

Param Type Description
id string Group UUID

Response 200 (stub)

{
  "message": "not implemented yet",
  "endpoint": "GET /:id/members"
}

curl

curl http://localhost:3000/api/groups/a1b2c3d4-.../members