A mobile wallet connecting Stellar payments with cash in Mexico.
Status: Active development. Stellar Testnet; mainnet deployment pending.
MicoPay helps people send and receive digital assets, find nearby cash providers, and coordinate cash deposits and withdrawals in Mexican pesos. The app combines a Stellar wallet, a provider map, chat, and Soroban escrow.
This repository contains the MicoPay mobile app and its supporting backend. ZK, AI-agent, x402, Bazaar, atomic-swap, and cross-chain work lives in MicoPay Bridge. Its code and product documentation are intentionally not duplicated here.
Connecting the app's cash network to AI assistants, bots, or paid APIs is a possible future development direction. The related x402, ZK, atomic-swap, and cross-chain work lives in MicoPay Bridge. The combined agent-to-cash experience is not fully implemented or available end to end in these early stages of the app. Individual prototypes or components do not establish that the complete integration works with the mobile wallet and real cash providers.
For example, an assistant could eventually help a user request MXN cash, discover a provider, and follow an escrow-backed exchange. This is an illustrative scenario, not a currently supported single API call. Provider names, distances, reputation scores, and transaction counts in earlier examples were illustrative, not evidence of a live network or verified on-chain reputation. Cross-chain funding and automated coordination would require further integration and validation. Escrow also cannot guarantee that neither participant can cheat during physical cash handover.
| Area | Current scope |
|---|---|
| Wallet | Account access, balances, transaction history, and wallet backup flows. |
| Payments | Send and receive Stellar assets, including QR-based payment flows. |
| Cash deposits and withdrawals | Choose an amount and nearby provider, review the operation, coordinate through chat, and follow escrow and QR confirmation steps. |
| Provider network | Join the network, configure availability and offers, and manage incoming operations. “Agent” here means a cash provider. |
| Identity verification | Didit integration with verification levels and backend controls for operations and monthly volume. Enforcement depends on backend configuration. |
| Bank withdrawals | SPEI integration through Etherfuse: identity requirements, bank-account registration, quotes, and order status. Availability depends on the build and provider configuration and approval. |
- Choose a cash deposit or withdrawal and enter the amount in MXN.
- Select an available provider on the map.
- Review the amount, asset, and fees before confirming.
- Coordinate the meeting through the operation's chat.
- Follow the escrow and QR steps for the selected direction of exchange.
- Review the result in the operation history.
The escrow tracks the digital-asset side of the exchange. Physical cash handover still depends on participants following the confirmation process; the contract does not independently verify that cash changed hands.
MicoPay is under active development. Code being present does not mean a feature is enabled in every APK or ready for unrestricted mainnet use.
- Stellar Testnet: used for app testing. Testnet assets are not real funds. A Testnet APK can still connect to the shared backend and identity providers; this network setting does not isolate every service.
- SPEI / Etherfuse: requires the appropriate build flags, backend credentials, provider onboarding, KYC, and environment configuration.
- CETES: exploration and integration code exists, but trading is gated. The backend's CETES purchase endpoint is disabled outside Testnet/mock mode.
- Blend: supply and borrow flows are simulated and intended for internal testing.
- Release validation: builds and API health checks do not replace testing the complete flow on Android with two participants.
Feature visibility is defined in
features.ts:
| Build flag | Controls |
|---|---|
VITE_ENABLE_DEFI_TRADING |
Internal CETES and Blend screens. |
VITE_ENABLE_SPEI_RAMP |
Etherfuse SPEI ramp screens. |
VITE_ENABLE_BANK_WITHDRAW |
Bank withdrawal flow. |
MicoPay does not take custody of user funds in the wallet or the cash network.
- Keys: each user's key is generated and stored on their device, and users sign their own transactions.
- Funds: during a cash exchange, the asset sits in the Soroban escrow. The contract can only pay the buyer and the platform fee on release, or return the funds to the seller. Its admin has no function to withdraw them.
- Backend: it stores the secret of each escrow encrypted, to coordinate the QR step. The contract still decides where funds can go, but the exchange flow depends on the backend being available.
| Path | Purpose |
|---|---|
micopay/frontend/ |
React, TypeScript, and Vite app; Android packaging with Capacitor. |
micopay/backend/ |
Fastify API for authentication, trades, providers, payments, KYC, and integrations. |
micopay/contracts/ |
App escrow contract and network deployment notes. |
micopay/sql/ |
PostgreSQL schema and migrations. |
micopay/scripts/ |
App development and operational utilities. |
docs/ |
Indexed product, architecture, operations, audit, and historical documentation. |
The backend runs on AWS ECS, with images in ECR, PostgreSQL in RDS, and runtime secrets in SSM Parameter Store. Older Render deployment references and dated planning documents are historical.
This repository has no protocol/x402 workspace. The removed apps/api, SDK,
ZK circuits, verifier, Bazaar, and agent-facing skill are maintained in
MicoPay Bridge. “Agent” inside this
repository means a human cash provider, not an autonomous AI agent.
Use Node.js 22, npm, and PostgreSQL for the app stack. Android builds also require the Android SDK and a compatible JDK; the Windows build workflow uses Android Studio's bundled JDK.
From micopay/backend, run npm ci. Create a local .env using .env.example
as a reference and configure the database, JWT secret, and a 64-character
hexadecimal SECRET_ENCRYPTION_KEY. Example values are placeholders.
For actual Testnet transactions, configure the Stellar keys, RPC, contract, and
MOCK_STELLAR=false. External integrations require their own configuration.
npm run devThe example backend port is 3000. MOCK_STELLAR=true simulates blockchain
behavior and does not validate a real escrow transaction.
From micopay/frontend:
npm ci
npm run devSet VITE_API_URL to your local backend. The development server uses port 5181.
Check the applicable environment mode files: Testnet, Play, and mainnet builds
have different settings.
From micopay/frontend:
npm run build:testnet
npx cap sync android
cd androidRun gradlew.bat assembleDebug on Windows or ./gradlew assembleDebug on
macOS/Linux. The output is app/build/outputs/apk/debug/app-debug.apk.
The debug ID is com.micopay.app.debug, separate from release ID com.micopay.app.
It does not share the release app's stored session. Updating a release installation
while preserving its data requires the same application ID, compatible version
code, and signing identity.
See the APK release checklist. Never commit signing keys, wallet secrets, or environment credentials.
Focus on wallet access, payments, cash operations, provider onboarding, identity verification, and bank withdrawals.
- Start with a scoped issue and describe the user-visible problem.
- Distinguish simulated behavior from real integrations in UI and documentation.
- Include reproduction steps and validation notes with behavior changes.
- Keep credentials, identity documents, and private wallet data out of issues and PRs.
- Treat dated roadmaps and audits as historical context; check the current code and issue before assuming a milestone is still pending.
Useful references:
MicoPay began at Código Alebrije in Mexico City and has participated in Stellar Drips and the PULSO Hackathon. Stellar Drips Wave 10 has been completed. For new contributions, start with CONTRIBUTING.md and the current issues rather than the historical Wave 6 audit. The current focus is making the mobile wallet and cash exchange experience usable and reliable.
See LICENSE.