Comet Engine

Appearance

User-Facing API ​

Direct endpoints for mobile app integration — typically called by your own backend on the end user's behalf. Same authentication as every other tenant-facing route on this site: X-API-Key + X-API-Secret (see Authentication).

▸API ConfigurationNot configured
Every endpoint, payload, and response on this page follows this choice.

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 (Celo)
curl -X POST "http://localhost:8100/api/v1/u/wallet/create" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -d '{
  "chain": "celo"
}'
Response200
{
  "address": "0xe3f53fe54f8e1b5e8c86f070e4c9c2c7fa641d0d",
  "chainId": 11142220,
  "chains": [
    "celo",
    "ethereum",
    "base"
  ]
}

Get Wallet ​

Returns the user's custodial wallet.

Get Wallet (Celo)
curl -X GET "http://localhost:8100/api/v1/u/wallet" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
Response200
{
  "address": "0xe3f53fe54f8e1b5e8c86f070e4c9c2c7fa641d0d",
  "chainId": 11142220
}

Wallet Balance ​

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

Wallet Balance (Celo)
curl -X GET "http://localhost:8100/api/v1/u/wallet/balance" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
Response200
{
  "address": "0xe3f53fe54f8e1b5e8c86f070e4c9c2c7fa641d0d",
  "chainId": 11142220,
  "balances": {
    "native": "0.5",
    "USDT": {
      "balance": "10000000",
      "decimals": 6,
      "humanAmount": 10
    },
    "IMC": {
      "balance": "447000000",
      "decimals": 6,
      "humanAmount": 447
    }
  }
}

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-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
Response200
{
  "balances": [
    {
      "chain": "celo",
      "address": "0xe3f53fe54f8e1b5e8c86f070e4c9c2c7fa641d0d",
      "native": "0.5",
      "tokens": {
        "USDT": {
          "balance": "10000000",
          "decimals": 6,
          "humanAmount": 10
        },
        "IMC": {
          "balance": "447000000",
          "decimals": 6,
          "humanAmount": 447
        }
      }
    }
  ],
  "count": 1
}

Token Endpoints ​

Mint Token ​

Mints tokens to the user's wallet.

Mint Token (Celo)
curl -X POST "http://localhost:8100/api/v1/u/token/mint" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -d '{
  "symbol": "USDT",
  "chain": "celo",
  "amountBase": 10000000,
  "externalId": "deposit-001"
}'
Response200
{
  "txHash": "0x...",
  "chain": "celo",
  "symbol": "USDT",
  "amount": 10
}

Send Token ​

Transfers tokens from the user's wallet.

Send Token (Celo)
curl -X POST "http://localhost:8100/api/v1/u/token/send" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -d '{
  "symbol": "USDT",
  "chain": "celo",
  "to": "0xe3f53fe54f8e1b5e8c86f070e4c9c2c7fa641d0d",
  "amountBase": 5000000
}'
Response200
{
  "txHash": "0x...",
  "chain": "celo",
  "symbol": "USDT",
  "amount": 5
}

Burn Token ​

Burns tokens from the user's wallet (requires prior approval on EVM chains — see Approve Spender. Stellar has no allowance concept; use Burn (Holder) semantics there instead, which this proxy endpoint applies automatically per chain).

Burn Token (Celo)
curl -X POST "http://localhost:8100/api/v1/u/token/burn" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -d '{
  "symbol": "USDT",
  "chain": "celo",
  "amountBase": 5000000,
  "externalId": "withdrawal-001"
}'
Response200
{
  "txHash": "0x...",
  "chain": "celo",
  "symbol": "USDT",
  "amount": 5
}

Token Balance ​

Returns balance for a specific token.

Token Balance (Celo)
curl -X GET "http://localhost:8100/api/v1/u/token/balance?symbol=USDT&chain=celo" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
Response200
{
  "symbol": "USDT",
  "chain": "celo",
  "balance": "10000000",
  "decimals": 6,
  "humanAmount": 10
}

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-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
Response200
{
  "symbol": "IMC",
  "chain": "celo",
  "balance": "447000000",
  "decimals": 6,
  "humanAmount": 447
}

IMC itself is a Celo asset — no toggle here; use the generic Token Balance endpoint above with your own Stellar asset's symbol instead.

Swap Endpoints ​

These proxy the Celo Uniswap V2 AMM specifically (note the path/router response fields) — no chain toggle here, since Stellar's AMM is a separate native mechanism with no equivalent mobile proxy today. For a chain-agnostic swap, see IMM instead.

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-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
Response200
{
  "from": "USDT",
  "to": "IMC",
  "amountIn": 10,
  "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-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -d '{
  "from": "USDT",
  "to": "IMC",
  "amountIn": 10,
  "minAmountOut": 9.9,
  "chain": "celo"
}'
Response200
{
  "txHash": "0x...",
  "from": "USDT",
  "to": "IMC",
  "amountIn": 10,
  "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-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -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-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
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-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
Response200
{
  "depositId": "dep-001",
  "status": "completed",
  "amountKES": 500,
  "tokenMinted": "5000000",
  "txHash": "0x..."
}

Released under the MIT License.

Copyright © 2024 FusionFi