Quick Start

Get from zero to on-chain token swap in under 5 minutes.

▸API ConfigurationNot configured

---

Prerequisites

• A running Comet Engine instance (see Architecture)
• Celo testnet RPC access

---

Step 1 — Health Check

Verify the engine is running:

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"] }

---

Step 2 — Authenticate

Get a JWT for your user:

# Login via your app backend (this is an example)
curl -X POST http://localhost:8092/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "your-password"}'

Or use the service token directly — all API examples use X-Service-Token for simplicity.

---

Step 3 — Create a 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": 123}'

Response200

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

The wallet works on ALL configured EVM chains — same address, same key.

---

Step 4 — Check Balances

Wallet Balance

curl -X GET "http://localhost:8100/api/v1/wallets/balance?userId=123" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE"

Response200

{ "address": "0xe3f53fe54f8e1b5e8c86f070e4c9c2c7fa641d0d", "nativeWei": "500000000000000000", "usdtBaseUnits": "10000000" }

---

Step 5 — Mint Tokens

Mint 10 USDT to the user:

Mint USDT

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

Response200

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

---

Step 6 — Tokenize Airtime

Mint the chain's airtime-backed asset (IMC):

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": 123, "amountBase": "10000000", "externalId": "airtime-001", "chain": "celo"}'

Response200

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

---

Step 7 — Check Asset Balance

Verify IMC balance:

IMC Balance

curl -X GET "http://localhost:8100/api/v1/assets/imc/balance?userId=123&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 }

---

Step 8 — Swap Tokens

Get a 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", "1998000"] }

Execute the 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": 123, "from": "USDT", "to": "IMC", "amountIn": "1000000"}'

Response200

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

---

Step 9 — Burn on Redemption

When airtime is delivered, burn the on-chain mirror:

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": 123, "amountBase": 3000000, "externalId": "airtime-001"}'

Response200

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

---

What You Can Build

Use Case	Flow	Engine Endpoints
Buy airtime	User pays KES → mint IMC → deliver airtime → burn IMC	tokenize/airtime → burn-by-holder
Sell ARTM	User sells ARTM → swap IMC → USDT → withdraw KES	swap/tokens → backend withdraw
Buy ARTM	User deposits KES → USDT → swap → IMC	assets/usdt/mint → swap/tokens
Cross-border payments	Deposit KES → USDC → send → recipient redeems NGN	assets/usdc/mint → send → burn-from
Tokenize deposits	User deposits fiat → receive stablecoin on-chain	assets/:symbol/mint
Loyalty rewards	Register token → mint to users → burn on redemption	admin/assets/register → mint → burn-by-holder
Token swaps	Swap any registered pair via on-chain AMM	swap/quote → swap/tokens