MiHashport Backend

The API and orchestration layer behind MiHashport — send, receive, swap, and deploy Stellar/Soroban contracts, all from inside a WhatsApp chat.

Part of MiHashport

MiHashport is split across three repositories:

• Backend (this repo) — the API that talks to WhatsApp and to Stellar
• Frontend — companion web app
• Contract — the Soroban smart contracts deployed on Stellar

This repo is standalone: you can clone, install, build, and test it without checking out the other two.

What is MiHashport?

Chat. Build. Pay. On Stellar.

Most people will never install a wallet app, memorize a seed phrase, or learn what a trustline is — but almost everyone already has WhatsApp open. MiHashport puts a Stellar wallet behind a phone number: users send, receive, and swap assets, and even deploy and invoke Soroban contracts, by chatting with a bot. The backend is what turns "send 10 XLM to +1555..." into a signed, submitted Stellar transaction and a reply back in the same chat thread.

What this repo contains

This is the backend service: a NestJS API that

• links a WhatsApp phone number to a custodial Stellar wallet,
• receives and parses inbound WhatsApp messages via the Meta Cloud API webhook,
• builds, signs, and submits Stellar payments, swaps, and Soroban contract operations, and
• sends replies and confirmations back to the user's WhatsApp thread.

It is the system's brain: the Frontend and Contract repos are optional companions, but every Stellar operation a user triggers passes through here.

Why open source

A custodial bridge between a messaging app and a public blockchain has to be trustworthy, and the fastest way to earn that trust is to let anyone read the code that touches funds. Open-sourcing this repo also invites contributors who already know one half of the stack — NestJS backend engineers, or Stellar/Soroban developers — to help build out the other half, without needing an invitation or NDA to start.

Why it benefits the Soroban/Stellar ecosystem

• A reusable custodial-wallet pattern. Generating, encrypting, and managing Stellar keypairs behind a chat interface is a pattern other "Stellar for non-crypto-native users" projects can lift directly from modules/wallet and modules/stellar.
• A real-world Soroban invocation client. modules/contracts is a working example of building, simulating, and submitting InvokeHostFunction operations from a plain TypeScript backend, using @stellar/stellar-sdk's rpc.Server — useful reference for teams integrating Soroban outside of the CLI.
• Lower onboarding cost for new Soroban builders. Because the messaging layer, config, and database plumbing are already solved here, a contributor can add a new contract integration (see docs/PLAN.md, Phase 6) without first building an entire backend from scratch.
• Exercises Horizon and Soroban RPC together: account loading, path payments, and contract simulation/submission all live side by side in one codebase, which is a useful reference for anyone building a similar bridge.

Tech stack

• NestJS 11 (TypeScript, strict mode)
• TypeORM + PostgreSQL
• @stellar/stellar-sdk (Horizon + Soroban RPC)
• @nestjs/axios for outbound HTTP (WhatsApp Cloud API)
• Jest for unit tests

Getting started

Prerequisites

• Node.js 24.x (see .nvmrc)
• npm 11+
• A PostgreSQL instance (local or hosted) for DATABASE_URL

Install

npm install

Configure environment

cp .env.example .env
# then fill in DATABASE_URL, STELLAR_*, WALLET_ENCRYPTION_KEY, WHATSAPP_* as needed

Run (development)

npm run start:dev

Build

npm run build

Test

npm run test

Project structure

src/
  main.ts                  # app bootstrap
  app.module.ts
  common/                  # global filters, interceptors
  config/                  # typed + validated configuration
  database/                # TypeORM data source + migrations
  modules/
    health/                # GET /health
    users/                 # WhatsApp phone number -> user record
    wallet/                # custodial Stellar keypair generation/storage
    stellar/              # Horizon: accounts, payments, swaps
    contracts/            # Soroban RPC: deploy/invoke
    whatsapp/             # inbound webhook + outbound messages

Learn more / contribute

• docs/PLAN.md — the 6-phase implementation roadmap
• CONTRIBUTING.md — how to pick up an issue and submit a PR
• AGENTS.md — rules for AI coding agents contributing here

License

MIT — see LICENSE.