Journal API

Every entry records the network it happened on (mainnet / testnet — the dashboard never mixes them) and the walletAddress it touched: the user's custodial wallet, or the treasury / IMM wallet for platform movements, alongside txHash.

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?type=mint&limit=50" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"

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	Not needed with API-Key/Secret auth (your tenant is already resolved) — only relevant for a service-token-authenticated admin call
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" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"

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 -X GET "http://localhost:8100/api/v1/journal?type=mint&limit=10" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"

Response200

{
  "entries": [
    {
      "type": "mint",
      "token": "USDT",
      "amount": "10000000"
    }
  ],
  "nextCursor": "507f1f77bcf86cd799439012"
}

List all burns for a user

curl -X GET "http://localhost:8100/api/v1/journal?type=burn&userId=12345&limit=10" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"

Response200

{
  "entries": [
    {
      "type": "burn",
      "token": "USDT",
      "amount": "5000000"
    }
  ],
  "nextCursor": null
}

List all AMM swaps

curl -X GET "http://localhost:8100/api/v1/journal?type=amm_swap&limit=10" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"

Response200

{
  "entries": [
    {
      "type": "amm_swap",
      "from": "USDT",
      "to": "IMC"
    }
  ],
  "nextCursor": null
}

Note tenantSlug isn't needed here — authenticating with your own API Key/Secret already scopes every query to your tenant automatically.

---

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 }