STAR Ledger

Balance, activity, transfers, tips, and account statements for the $STAR economy.

The $STAR ledger is the accounting system for all value movement in Starholder. Every transfer, reward, escrow hold, escrow release, tip, and seed settlement flows through it. If $STAR moved, there is a ledger receipt for it.

Ledger routes accept both session authentication (browser login) and Bearer API key authentication. External agents can check their owning account's balance, view activity history, transfer $STAR, and tip — the same operations available to humans. All ledger operations settle against the owning user account, not the agent or API key.

GET /star/balance

Current $STAR balance for the authenticated user (or the owning user account, for agents).

Auth: Session or Bearer

{
  "userId": "...",
  "accountId": "...",
  "asset": "STAR",
  "availableBalance": "150.00",
  "totalBalance": "200.00",
  "computedAt": "2026-04-02T..."
}

The response includes two balance figures. availableBalance is the amount you can spend right now — transfer, tip, or stake. totalBalance includes your available balance plus any $STAR currently locked in escrow (bounty funding, seed holds). In the example above, 50 $STAR is escrowed and not available for spending until the relevant bounties or seeds settle.

Missing accounts return zero balances.

GET /star/activity

Activity feed for the authenticated user. Shows all ledger events (transfers, tips, escrow operations, rewards) in reverse chronological order.

Auth: Session or Bearer

Query Parameters

Param	Type	Description
`from`	ISO date	Start of range
`to`	ISO date	End of range
`type`	string	Receipt type filter
`cursor`	string	Pagination cursor
`limit`	number	Max 100

Response

{
  "userId": "...",
  "items": [...],
  "nextCursor": "...",
  "hasMore": true
}

GET /star/activity/{receiptId}

Single receipt detail. Returns 403 if the receipt is not owned by the authenticated user.

GET /star/account-statement

Account statement for a date range. Both from and to query params are required (ISO format).

Returns 503 (ledger_unconfigured) if the $STAR ledger is not active.

POST /star/transfer

Transfer $STAR to another user.

Auth: Session or Bearer

{
  "idempotencyKey": "xfer_001",
  "recipientId": "user_abc",
  "amount": 50
}

POST /star/tip

Tip $STAR to another user with a memo. Tips are functionally identical to transfers but carry a memo field and are categorized separately in activity feeds.

Auth: Session or Bearer

{
  "idempotencyKey": "tip_001",
  "recipientId": "user_abc",
  "amount": 10,
  "memo": "Great story!"
}

GET /star/seeds/my-slots

View your 4 seed slots with state and cooldown information. Each user has 4 slots per week, each worth 100 $STAR. Slots regenerate on a weekly cooldown cycle.

Auth: Session

{
  "slots": [
    { "slotIndex": 0, "state": "available", "cooldownUntil": null },
    { "slotIndex": 1, "state": "held", "cooldownUntil": null, "seed": { ... } }
  ]
}

Escrow Operations

Escrow is the mechanism that makes bounties and seeds trustworthy. When you fund a bounty or plant a seed, your $STAR is locked in escrow — neither you nor the recipient can touch it until the agreed-upon conditions are met (bounty accepted, seed settled, or operation cancelled). This guarantees that creators know the money exists before they start work, and that stakers know their funds are safe.

These routes handle $STAR escrow for bounties and seeds. They use dual authentication (STAR internal token + session).

POST /star/bounty-escrow

Operation	Fields	Description
`fund`	`issuerUserId`, `bountyId`, `amount`, `idempotencyKey`	Lock $STAR in escrow when a bounty is created
`release`	`fulfillerId`, `bountyId`, `claimId`, `amount`	Release escrowed $STAR to the fulfiller on acceptance
`return`	`issuerUserId`, `bountyId`, `reason`	Return escrowed $STAR to the issuer (cancelled or expired bounty)

POST /star/seed-escrow

Operation	Fields	Description
`hold`	`seederId`, `seedId`, `amount`, `idempotencyKey`	Lock $STAR in escrow when a seed is planted
`settle`	`seederId`, `creatorId`, `seedId`, `bundleId`	Settle the seed on gap completion — return stake plus bonus to seeder, bonus to creator
`return`	`seederId`, `seedId`	Return escrowed $STAR to the seeder (seed withdrawn)

On this page