API Reference

All endpoints are under /api/v1 and require authentication (see Authentication →).

▸API ConfigurationNot configured

Implementation

Every endpoint, payload, and response on this page follows this choice.

Base URL

http://localhost:8100/api/v1

Endpoints Summary

Method	Endpoint	Description
Health
GET	/health	Health check (no auth required)
Wallets
POST	/wallets/create	Create custodial EVM wallet
GET	/wallets	Get wallet by userId
GET	/wallets/balance	Native CELO + token balances
Assets (Dynamic)
GET	/assets	List all registered assets
GET	/assets/:symbol/balance	Token balance
POST	/assets/:symbol/mint	Mint tokens to wallet
POST	/:symbol/send	Transfer tokens
POST	/assets/:symbol/approve	Approve spender
POST	/assets/:symbol/burn	Burn (relayer, requires approval)
POST	/assets/:symbol/burn-by-holder	Burn (holder, no approval)
IMC & Airtime (see full reference →)
POST	/airtime/redeem	Redeem a user's IMC for Airtel airtime (lock → send → burn)
GET	/admin/imc/airtime	🔒 Gateway mode, bonus, CBK rate, float
GET	/admin/imc/airtime-topup/quote	🔒 Preview the IMC a top-up mints
POST	/admin/imc/airtime-topup	🔒 Book a gateway top-up and mint its IMC to the treasury
POST	/imc/book	🔑 Book a gateway top-up with its receipt number and mint its IMC (your API keys)
POST	/imc/book-and-send	🔑 The same, then deliver the minted IMC to toAddress
GET	/admin/imc/treasury	🔒 Treasury address and IMC balance
Exchange Rates (Central Bank of Kenya — see full reference →)
GET	/rates	Every CBK rate plus the engine's stablecoins, in KES
GET	/rates/convert	Convert between currencies/stablecoins at CBK mid
Networks
GET	/networks	The active network and the view-only one (X-Network header)
Tokenization
POST	/tokenize/airtime	Mint airtime-backed asset (platform only, airtime-backed)
GET	/tokenize/status/:id	Check status
Receipt Tokenization (self-service, tenant-defined — see full reference →)
POST	/tokenize/receipt/standards	Define your own receipt schema
GET	/tokenize/receipt/standards	List your standards
POST	/tokenize/receipt/deposit	Deposit a claim under a standard
POST	/tokenize/receipt/:id/verify	Verify → mints on-chain, once
POST	/tokenize/receipt/:id/reject	Reject a claim (no mint)
POST	/tokenize/receipt/:id/redeem	Redeem (burn) outstanding quantity
GET	/tokenize/receipt/:id	Get one receipt
GET	/tokenize/receipt	List your receipts
AMM (Swaps, Celo/Uniswap V2)
GET	/swap/quote	Get swap price quote
POST	/swap/tokens	Execute token swap
GET	/swap/pools	List pools + reserves
Stellar AMM (CAP-38 — see full reference →)
GET	/stellar/pools	Get pool reserves
GET	/stellar/swap/quote	Get swap price quote
POST	/stellar/swap/execute	Execute swap
POST	/admin/stellar/pools/create	Create pool
POST	/admin/stellar/pools/deposit	Deposit liquidity
POST	/admin/stellar/pools/withdraw	Withdraw liquidity
IMM & Treasury (Internal Market Maker — see full reference →)
GET	/imm/quote	Get rate-table quote
POST	/imm/swap	Execute swap — vault-backed if funded, synthetic mint fallback otherwise
POST	/admin/imm/rates	Set a rate
GET	/admin/imm/rates	List rates
GET	/admin/imm/exposure	Check net exposure
GET	/admin/imm/vault	Check vault balance vs. ledger inventory
POST	/admin/imm/vault/fund	Fund the vault with real reserves
POST	/admin/imm/rebalance	Flatten vault imbalance via the AMM
POST/GET	/admin/corridor/nodes	Create/list Treasury vault nodes
POST	/admin/corridor/nodes/:id/seed	Seed a node's initial capital
POST/GET	/admin/corridor/corridors	Create/list Treasury corridors
POST	/admin/corridor/corridors/:id/execute	Run one honest, balance-checked cycle
POST	/admin/corridor/corridors/:id/kill-switch	Halt one corridor
POST	/admin/corridor/kill-switch	Halt every corridor (tenant-wide)
POST	/admin/corridor/rebalance/check	Run a portfolio deviation check
POST	/admin/imm/cycles/preview	🔒 Project the KES → Airtime → IMC → USDT cycle model
POST/GET	/admin/imm/cycles	🔒 Start/list arbitrage cycle runs
GET	/admin/imm/cycles/:id	🔒 One run with every cycle
POST	/admin/imm/cycles/:id/withdraw	🔒 Operator-confirmed final USDT withdrawal
Journal
GET	/journal	List journal entries
GET	/journal/balances	Account balances
Admin
POST	/admin/tenants	Create tenant
GET	/admin/tenants	List tenants
POST	/admin/assets/:symbol/register	Register asset
DELETE	/admin/assets/:symbol	Deregister asset
POST	/admin/pools/create	Create pool
POST	/admin/pools/fund	Fund pool
Token Factory
POST	/tokens/create	Deploy + register a new token
GET	/tokens	List tenant's tokens
GET	/tokens/:id	Get token by ID
POST	/tokens/:id/mint	Mint token
POST	/tokens/:id/burn	Burn token
Bridge
POST	/bridge/wrap	Wrap a token into YSH
POST	/bridge/unwrap	Unwrap YSH back to a token
POST	/bridge/multi-wrap	Wrap several tokens into YSH at once
GET	/bridge/positions/:user	Get wrapped YSH position
PSP Top-up
POST	/admin/topup/stk-push	Mobile-money STK push (deposit)
POST	/admin/topup/transfer	Mobile-money B2C transfer (withdrawal)
POST	/psp/callback	PSP delivery callback (signature-verified, not X-Service-Token)

Test It

Health Check

Health Check

curl -X GET "http://localhost:8100/health" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"

Response200

{
  "status": "ok",
  "service": "comet-engine",
  "chains": [
    "celo",
    "stellar"
  ]
}

chains lists whatever's actually configured on this instance — a fresh install shows just ["celo"] until Stellar (or any other chain) is set up. See Setting Up Stellar →.

List Assets

List Assets

curl -X GET "http://localhost:8100/api/v1/assets" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"

Response200

{
  "assets": [
    {
      "symbol": "USDT",
      "contract": "0x3C8E...DDDF",
      "decimals": 6
    },
    {
      "symbol": "IMC",
      "contract": "0xF150...d5A2",
      "decimals": 6
    }
  ],
  "count": 2
}

Create Wallet → Mint → Balance → Burn

The same one user (userId: 1) through each step — pick a chain once, the whole sequence below follows it. Full reference for each of these: Wallets, Assets, Tokenization.

Create Wallet (Celo)

curl -X POST "http://localhost:8100/api/v1/wallets/create" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -d '{
  "userId": 1
}'

Response200

{
  "address": "0xe3f53fe54f8e1b5e8c86f070e4c9c2c7fa641d0d",
  "existing": true
}

Mint a token (Celo)

curl -X POST "http://localhost:8100/api/v1/assets/ctest/mint" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -d '{
  "userId": 1,
  "amountBase": 10000000,
  "externalId": "mint-001"
}'

Response200

{
  "amount": 10,
  "chain": "celo",
  "symbol": "IMC",
  "txHash": "0x..."
}

IMC Balance (Celo)

curl -X GET "http://localhost:8100/api/v1/assets/imc/balance?userId=1&tenantSlug=comet" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"

Response200

{
  "symbol": "IMC",
  "chain": "celo",
  "balance": "10000000",
  "decimals": 6,
  "humanAmount": 10
}

Burn IMC (Celo)

curl -X POST "http://localhost:8100/api/v1/assets/imc/burn-by-holder" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -d '{
  "userId": 1,
  "amountBase": 3000000,
  "externalId": "burn-001"
}'

Response200

{
  "txHash": "0x...",
  "chain": "celo",
  "symbol": "IMC",
  "amount": 3
}

Token Swap Quote

The Celo Uniswap V2 AMM specifically — no Stellar equivalent (see Stellar AMM for that chain's separate native mechanism), so no toggle below.

Swap Quote

curl -X GET "http://localhost:8100/api/v1/swap/quote?from=USDT&to=IMC&amountIn=1000000" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"

Response200

{
  "from": "USDT",
  "to": "IMC",
  "amountIn": "1000000",
  "amounts": [
    "1000000",
    "997000"
  ]
}

Execute Swap

Execute Swap

curl -X POST "http://localhost:8100/api/v1/swap/tokens" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -d '{
  "userId": 1,
  "from": "USDT",
  "to": "IMC",
  "amountIn": "1000000"
}'

Response200

{
  "status": "success",
  "from": "USDT",
  "to": "IMC",
  "txHash": "0x...",
  "chainId": 11142220
}

Tokenize Airtime

Tokenize Airtime (Celo)

curl -X POST "http://localhost:8100/api/v1/tokenize/airtime" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -d '{
  "userId": 1,
  "amountBase": "10000000",
  "externalId": "airtime-001",
  "chain": "celo"
}'

Response200

{
  "status": "success",
  "asset": "IMC",
  "type": "airtime",
  "chain": "celo",
  "txHash": "0x..."
}

Authentication Headers

Header	Auth Method	Use For
X-API-Key + X-API-Secret	Per-tenant API key/secret	Every endpoint above except /admin/*
X-Service-Token	Service token (full access)	/admin/* platform-operator routes only

See Authentication → for details.

Error Responses

{
  "error": "human-readable message",
  "details": "optional sanitized detail"
}

Code	Meaning
400	Bad request / missing fields
401	Auth required or invalid credentials
404	Wallet, tenant, or asset not found
500	Internal error
502	On-chain operation failed