User-Facing API

Direct endpoints for mobile app integration. Authentication via Authorization: Bearer <jwt> or X-Service-Token header.

▸API ConfigurationNot configured

All user endpoints are prefixed with /api/v1/u/ and automatically resolve the user from the JWT token.

---

Wallet Endpoints

Create Wallet

Creates or returns existing custodial wallet for the authenticated user.

Create Wallet

curl -X POST "http://localhost:8100/api/v1/u/wallet/create" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE" \
  -d '{"chain": "celo"}'

Response200

{ "address": "0xe3f53fe54f8e1b5e8c86f070e4c9c2c7fa641d0d", "chainId": 11142220, "chains": ["celo", "ethereum", "base"] }

Get Wallet

Returns the user's custodial wallet.

Get Wallet

curl -X GET "http://localhost:8100/api/v1/u/wallet" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE"

Response200

{ "address": "0xe3f53fe54f8e1b5e8c86f070e4c9c2c7fa641d0d", "chainId": 11142220 }

Wallet Balance

Returns native + token balances for the user's wallet.

Wallet Balance

curl -X GET "http://localhost:8100/api/v1/u/wallet/balance" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE"

Response200

{ "address": "0xe3f53fe54f8e1b5e8c86f070e4c9c2c7fa641d0d", "chainId": 11142220, "balances": { "native": "0.5", "USDT": { "balance": "10000000", "decimals": 6, "humanAmount": 10.0 }, "IMC": { "balance": "447000000", "decimals": 6, "humanAmount": 447.0 } } }

All Balances (Multi-Chain)

Returns balances across all configured chains.

All Balances

curl -X GET "http://localhost:8100/api/v1/u/wallet/balances" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE"

Response200

{ "balances": [{ "chain": "celo", "address": "0xe3f53fe54f8e1b5e8c86f070e4c9c2c7fa641d0d", "native": "0.5", "tokens": { "USDT": { "balance": "10000000", "decimals": 6, "humanAmount": 10.0 }, "IMC": { "balance": "447000000", "decimals": 6, "humanAmount": 447.0 } } }], "count": 1 }

---

Token Endpoints

Mint Token

Mints tokens to the user's wallet.

Mint Token

curl -X POST "http://localhost:8100/api/v1/u/token/mint" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE" \
  -d '{"symbol": "USDT", "chain": "celo", "amountBase": 10000000, "externalId": "deposit-001"}'

Response200

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

Send Token

Transfers tokens from the user's wallet.

Send Token

curl -X POST "http://localhost:8100/api/v1/u/token/send" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE" \
  -d '{"symbol": "USDT", "chain": "celo", "to": "0xRecipientAddress", "amountBase": 5000000}'

Response200

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

Burn Token

Burns tokens from the user's wallet (requires prior approval).

Burn Token

curl -X POST "http://localhost:8100/api/v1/u/token/burn" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE" \
  -d '{"symbol": "USDT", "chain": "celo", "amountBase": 5000000, "externalId": "withdrawal-001"}'

Response200

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

Token Balance

Returns balance for a specific token.

Token Balance

curl -X GET "http://localhost:8100/api/v1/u/token/balance?symbol=USDT&chain=celo" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE"

Response200

{ "symbol": "USDT", "chain": "celo", "balance": "10000000", "decimals": 6, "humanAmount": 10.0 }

IMC Balance

IMC Balance

curl -X GET "http://localhost:8100/api/v1/u/token/balance?symbol=IMC&chain=celo" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE"

Response200

{ "symbol": "IMC", "chain": "celo", "balance": "447000000", "decimals": 6, "humanAmount": 447.0 }

---

Swap Endpoints

Swap Quote

Get a price quote for a token swap.

Swap Quote

curl -X GET "http://localhost:8100/api/v1/u/swap/quote?from=USDT&to=IMC&amount=10.0&chain=celo" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE"

Response200

{ "from": "USDT", "to": "IMC", "amountIn": 10.0, "amountOut": 9.98, "rate": 0.998, "path": ["0x...", "0x..."], "router": "0x..." }

Execute Swap

Execute a token swap via AMM.

Execute Swap

curl -X POST "http://localhost:8100/api/v1/u/swap" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE" \
  -d '{"from": "USDT", "to": "IMC", "amountIn": 10.0, "minAmountOut": 9.9, "chain": "celo"}'

Response200

{ "txHash": "0x...", "from": "USDT", "to": "IMC", "amountIn": 10.0, "amountOut": 9.98, "chain": "celo" }

---

Airtime Deposit (Proxy)

These endpoints delegate to app-core-backend for airtime tokenization.

Submit Airtime Deposit

Submit Deposit

curl -X POST "http://localhost:8100/api/v1/u/airtime/deposit" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE" \
  -d '{"carrier": "safaricom", "phone": "+254712345678", "amountKES": 500, "screenshotUrl": "https://..."}'

Response200

{ "depositId": "dep-001", "status": "pending", "amountKES": 500 }

List Airtime Deposits

List Deposits

curl -X GET "http://localhost:8100/api/v1/u/airtime/deposits?status=pending&limit=10" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE"

Response200

{ "deposits": [{ "depositId": "dep-001", "status": "pending", "amountKES": 500, "createdAt": "2026-08-30T12:00:00Z" }], "count": 1 }

Get Deposit Status

Deposit Status

curl -X GET "http://localhost:8100/api/v1/u/airtime/deposit/dep-001" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE"

Response200

{ "depositId": "dep-001", "status": "completed", "amountKES": 500, "tokenMinted": "5000000", "txHash": "0x..." }