API Reference

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

▸API ConfigurationNot configured

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)
Tokenization
POST	/tokenize/airtime	Mint airtime-backed asset
GET	/tokenize/status/:id	Check status
AMM (Swaps)
GET	/swap/quote	Get swap price quote
POST	/swap/tokens	Execute token swap
GET	/swap/pools	List pools + reserves
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-Service-Token: YOUR_TOKEN_HERE"

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-Service-Token: YOUR_TOKEN_HERE"

Response200

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

Create Wallet

Create Wallet

curl -X POST "http://localhost:8100/api/v1/wallets/create" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE" \
  -d '{"userId": 1}'

Response200

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

Mint IMC

Mint IMC

curl -X POST "http://localhost:8100/api/v1/assets/imc/mint" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE" \
  -d '{"userId": 1, "amountBase": 10000000, "externalId": "mint-001"}'

Response200

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

Check IMC Balance

IMC Balance

curl -X GET "http://localhost:8100/api/v1/assets/imc/balance?userId=1&tenantSlug=comet" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE"

Response200

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

Burn IMC (Holder)

Burn IMC

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

Response200

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

Token Swap Quote

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-Service-Token: YOUR_TOKEN_HERE"

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-Service-Token: YOUR_TOKEN_HERE" \
  -d '{"userId": 1, "from": "USDT", "to": "IMC", "amountIn": "1000000"}'

Response200

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

Tokenize Airtime

Tokenize Airtime

curl -X POST "http://localhost:8100/api/v1/tokenize/airtime" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE" \
  -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
X-API-Key + X-API-Secret	Per-tenant API key/secret
X-Service-Token	Service token (full access)

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