SafeSwap: A Stellar-Based Escrow Marketplace for P2P USDC Transfers

What SafeSwap Tries to Solve

SafeSwap addresses a specific pain point: two strangers who want to exchange USDC on the Stellar network without trusting each other or a central intermediary. The README describes a marketplace where users browse listings of buyers and sellers, match with a counterpart, and then execute a transfer through an escrow contract. The escrow holds funds until both parties confirm, and a dispute mechanism exists if something goes wrong. The target user is a developer building a P2P exchange on Stellar who does not want to implement escrow logic from scratch. The project leans on the Trustless Work API to handle escrow creation, funding, completion, and disputes, which means the actual smart contract logic lives outside this repository. That is the core trade-off: you get speed and simplicity, but you surrender control over the most safety-critical part of the system.

Architecture and Data Flow

The repository is a monorepo with one application, p2p-safe-swap, built on Next.js 16 and Tailwind CSS v4. The README mentions a legacy backend using NestJS, GraphQL, and Prisma, but the current app folder only lists the Next.js frontend. The data flow starts in the UI, where users see listings stored in Supabase, a PostgreSQL-backed database. When two parties agree on a trade, the frontend calls the Trustless Work API to create an escrow contract on Stellar. The sender then funds that contract with USDC. Once both parties confirm, the API triggers a release to the recipient's wallet. The README states that disputes are handled by the escrow contract, but it does not explain how a dispute is opened, who arbitrates, or what happens to the funds during that period. That is a meaningful gap for a project whose entire value proposition is trust.

Getting It Running: Commands and Configuration

The README gives a clear starting point. You need Node.js 20 or higher and npm 10.9.2 or higher. The installation steps are straightforward: clone the repo, run npm install, and copy an environment file. The exact command is cp p2p-safe-swap/.env.local p2p-safe-swap/.env.local, which looks like a typo because it copies a file onto itself. Presumably the intended source is .env.example, but the README does not say that. The required environment variables are NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY, and TRUSTLESS_WORK_API_KEY. The first two are client-side, the latter two are server-side only. For local development, the repo includes Supabase CLI configuration in supabase/config.toml, migrations in supabase/migrations/, and a seed file. You start the local stack with supabase start and apply migrations with supabase db reset, or from the app folder with npm run db:reset. To push to a remote project, use supabase db push. The root package.json exposes npm run dev and npm run build for all apps. The documentation points to docs/SUPABASE-SETUP.md for full setup, but that file is not included in the provided material, so you are left to guess at the details.

The Trustless Work API Dependency

The entire escrow mechanism depends on the Trustless Work API, which is an external service. The README lists it as a key part of the stack, but it does not specify the API version, endpoint, or authentication method beyond an API key. This creates a single point of failure. If the API changes its contract, goes offline, or shuts down, SafeSwap stops working. The project does not include any fallback or local smart contract implementation. For a platform that claims to be trustless, relying on a third-party API is a contradiction. The trust is shifted from a central marketplace operator to the API provider. The README's phrase 'no central authority controls the process' is only true if the Trustless Work API itself is decentralized, which is not stated. This is a critical distinction for anyone evaluating the project for real use.

Limitations and Failure Modes

The most obvious limitation is the incomplete documentation. The .env copy command is wrong, the Supabase setup doc is referenced but not provided, and there is no mention of how to handle errors from the Trustless Work API. The README also says the UI is 'intentionally minimal', which is fine for a prototype but not for a production marketplace. There is no mention of identity verification, reputation systems, or fraud prevention beyond the escrow. A buyer and seller could still collude to submit false confirmations, or one party could simply refuse to confirm, leaving funds locked indefinitely. The dispute resolution process is described in one line: 'either party can open a dispute handled by the escrow contract'. That is not enough to understand the timeout rules, the arbitration process, or the cost. Another failure mode is the lack of a release mechanism for the escrow if the Trustless Work API is down. The README does not describe any fallback path, so a transaction could stall mid-way.

Alternative Approaches on Stellar

The main alternative is to build directly on Stellar's native escrow capabilities. Stellar supports time-bounded escrow accounts and multi-signature transactions, which you can implement using the Stellar SDK without an external API. That approach gives you full control over the contract logic, but it requires writing more code and managing the escrow accounts yourself. Another option is to use a Stellar-based DEX like StellarX or a protocol like StellarTerm, which already handle order matching and settlement. Those are centralized platforms, though, so they do not offer the same peer-to-peer trustlessness. The key difference with SafeSwap is that it abstracts away the escrow mechanics entirely, trading control for convenience. If you need to customize the dispute process or add regulatory compliance, you will likely hit a wall with the Trustless Work API.

Maintenance and License Considerations

The repository is archived: no, but the last push date is unknown and there are no recent releases. That makes it hard to judge activity. The codebase uses Next.js 16, which is a recent version, but the legacy backend mention suggests the project may be in transition. The license is MIT, which means you can use, modify, and distribute the code freely, including in commercial products, as long as you include the original copyright notice. There is no copyleft obligation. However, the MIT license does not cover the Trustless Work API, which has its own terms of service. You need to review those separately. The maintenance cost is low if you only use the frontend, but it rises if you need to fix bugs in the escrow flow, because you cannot modify the API behavior. You are dependent on the API provider's roadmap and uptime.

Editorial conclusion

SafeSwap fits developers who already build on Stellar and want a working escrow flow without writing smart contracts from scratch, especially if they are comfortable with the Trustless Work API as a dependency. It is not suitable for production use today: the docs are incomplete, the setup steps are contradictory, and there is no evidence of dispute resolution logic beyond a mention. Before adopting it, verify that the Trustless Work API is still active, confirm the escrow contract actually enforces release conditions, and reconcile the .env.example copy command with the real file layout. If those checks pass, it can serve as a scaffold for a prototype. If they do not, you are better off building directly on Stellar's own escrow primitives.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository