minmoto/swap repository overview

⁠Swap

Simple KES ↔ BTC swap interface that integrates with the Minmo API API.

⁠Minmo API Integration

This app connects to the unified Minmo API API for all swap operations:

• API Base URL: http://localhost:5000/api/v1/
• Swap Endpoints: /swap/quote, /swap/onramp, /swap/offramp
• Authentication: Supports both JWT tokens and API keys
• Organization Scoped: All swaps are tied to user organizations

⁠Onramp destinations and fees

For a Lightning address, the buyer sends exactly the fiat amount they entered. The app submits that address to the API without first fetching an invoice. The agent retains its margin in sats before funding escrow; escrow and payout network fees are deducted from those sats. The API then requests the beneficiary's invoice for the net payout. On-chain destinations also use the requested fiat budget.

For a fixed Lightning invoice, including one generated by WebLN, the invoice amount must be paid in full. The API includes escrow and payout network fees in the funding principal and calculates the corresponding fiat payment, which can exceed the invoice's fiat equivalent.

Future destination integrations, such as BOLT12 offers, should choose their fee behavior based on whether the payout amount is flexible or fixed. Preserve flexible destinations for server-side resolution after fees are deducted. BOLT12 destinations are not currently supported by this app.

⁠Development

1. Start Minmo API: npm run dev:api (from project root)
2. Start Swap App: npm run dev:swap
3. Access: http://localhost:3001⁠

⁠API Authentication

⁠Using JWT Tokens

# Get a token through the hosted auth flow or Nostr auth endpoints.

# Use in API calls
curl -H 'Authorization: Bearer <token>' \
  http://localhost:5000/api/v1/swap/quote

⁠Using API Keys

# Create an API key via Console API
curl -X POST http://localhost:5000/api/v1/organizations/{orgId}/api-keys \
  -H 'Authorization: Bearer <jwt_token>' \
  -d '{"name": "Swap App", "serviceIds": ["swap"]}'

# Use API key for swaps
curl -H 'X-API-Key: mk_...' \
  http://localhost:5000/api/v1/swap/quote

For detailed API documentation, visit: http://localhost:5000/api/docs⁠