Journal API

Append-only double-entry accounting ledger. Every on-chain operation (mint, burn, approve, transfer, swap) is recorded with debitAccount / creditAccount.

▸API ConfigurationNot configured

List Entries

List Journal Entries

curl -X GET "http://localhost:8100/api/v1/journal?tenantSlug=comet&type=mint&limit=50" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE"

Response200

{ "entries": [{ "id": "507f1f77bcf86cd799439011", "tenantId": "comet", "userId": 12345, "chain": "celo", "token": "USDT", "type": "mint", "amount": "10000000", "txHash": "0xabc...", "from": "custodial::comet::12345", "to": "mintable::celo::usdt", "debitAccount": "custodial::comet::12345", "creditAccount": "mintable::celo::usdt", "extRef": "mint-001", "createdAt": "2024-01-15T10:30:00Z" }], "nextCursor": "507f1f77bcf86cd799439012" }

Query Parameters:

Param	Type	Description
tenantSlug	string	Filter by tenant (defaults to "comet")
type	string	Filter by entry type: mint, burn, approve, amm_swap, amm_swap_quote, tokenize_airtime, tokenize_burn
limit	number	Max results (default 100)
cursor	string	Pagination cursor (from nextCursor)

---

Account Balances

Aggregated balance per account.

Account Balances

curl -X GET "http://localhost:8100/api/v1/journal/balances?tenantSlug=comet" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE"

Response200

{ "balances": [{ "account": "custodial::comet::12345", "chain": "celo", "token": "USDT", "totalIn": "10000000", "totalOut": "0" }, { "account": "mintable::celo::usdt", "chain": "celo", "token": "USDT", "totalIn": "0", "totalOut": "10000000" }, { "account": "airtime_inventory::comet", "chain": "celo", "token": "IMC", "totalIn": "50000000", "totalOut": "50000000" }] }

---

Entry Types

Type	Description
mint	Tokens minted to custodial wallet
burn	Tokens burned from custodial wallet
approve	ERC-20 allowance granted
amm_swap	On-chain token-to-token swap executed
amm_swap_quote	Quote only (no on-chain tx)
tokenize_airtime	Airtime-backed token minted (backing-aware)
tokenize_burn	Airtime-backed token burned (backing-aware)
tokenize_convert	Cross-asset conversion

---

Example Queries

List all mints

curl "http://localhost:8100/api/v1/journal?tenantSlug=comet&type=mint&limit=10" \
  -H "X-Service-Token: YOUR_TOKEN"

List all burns for a user

curl "http://localhost:8100/api/v1/journal?tenantSlug=comet&type=burn&userId=12345&limit=10" \
  -H "X-Service-Token: YOUR_TOKEN"

List all AMM swaps

curl "http://localhost:8100/api/v1/journal?tenantSlug=comet&type=amm_swap&limit=10" \
  -H "X-Service-Token: YOUR_TOKEN"

---

Accounting Model

Every operation creates a debit and credit entry:

Mint 100 USDT to user #12345:
  debit:  custodial::comet::12345   +100 USDT
  credit: mintable::celo::usdt       -100 USDT

Tokenize 50 IMC to user #12345 (airtime-backed):
  debit:  airtime_inventory::comet   +50 IMC
  credit: chain::celo::imc           -50 IMC

Burn 50 IMC from user #12345 (airtime redemption):
  debit:  chain::celo::imc           +50 IMC
  credit: airtime_inventory::comet   -50 IMC

Swap 50 USDT → IMC for user #12345:
  debit:  custodial::comet::12345   +99.7 USDT (0.3% fee)
  credit: amm::celo::usdt            -100 USDT
  debit:  custodial::comet::12345   +199.8 IMC
  credit: amm::celo::imc             -199.8 IMC

---

MongoDB Index

{ tenant_id: 1, user_id: 1, created_at: -1 }