Trustless Work | Documentation

Payment Widget Template

A reusable payment widget that lets any app accept stablecoin payments into Trustless Work escrow, holding funds until delivery, approval, or release conditions are met.

Add escrow-protected payments to your app in minutes.

Built on Trustless Work — Escrow-as-a-Service on Stellar/Soroban — this template ships an embeddable payment component, a demo app, mock mode for UI testing, and integration docs you can fork and adapt for marketplaces, freelance platforms, e-commerce, bounties, and service deposits.

The problem

Most payment widgets send funds directly to the seller. That works for low-trust-risk purchases, but not when delivery happens later, work must be reviewed, or both parties need protection before release. The missing primitive is pay now, release later — and Trustless Work provides that through programmable escrow.

Core workflow

Step	Actor	Action
1	Buyer / payer	Starts payment; escrow is created for the order
2	Buyer / payer	Deposits stablecoin into escrow on Stellar
3	Seller / receiver	Sees funds secured and marks delivery or completion
4	Buyer / approver	Reviews and approves delivery
5	Release signer	Releases funds to the seller; platform fee is routed automatically
6	All parties	View payment status and timeline in the widget or demo app

Default role mapping (v1)

Trustless Work role	Widget meaning	Default actor
Payer	Buyer / client	Buyer
Receiver	Seller / service provider	Seller
Milestone Marker	Marks delivered or completed	Seller
Milestone Approver	Approves delivery	Buyer
Release Signer	Triggers fund release	Buyer (platform-controlled release optional)
Platform Address	Receives platform fee	Platform

MVP scope

In scope (v1)

• Embeddable payment widget with create, existing-escrow, and read-only status modes
• Single escrow payment flow: create → deposit → deliver → approve → release
• Status tracker, fee breakdown, and role mapping (payer, receiver, approver, release signer, platform)
• Mock mode (UI without real API) and real API mode (Trustless Work)
• Demo app and setup documentation

Out of scope (future versions)

• Multi-item cart, multi-seller checkout, full disputes, full refund flows, fiat card payments, inventory, user accounts, messaging, or notifications

For product concept, widget API, state machine, UX, and demo screens, see docs/PRODUCT-BRIEF.md.

Tech stack

• Next.js 16 (App Router) + React 19 + TypeScript
• Tailwind CSS v4
• Trustless Work SDK — @trustless-work/escrow and/or @trustless-work/blocks (to be integrated)
• Stellar Wallets Kit + Freighter (testnet for development)

---

Local installation

Prerequisites

• Node.js 20+ and pnpm
• A Trustless Work API key
• Freighter (or another Stellar wallet supported by Wallets Kit) on Stellar testnet
• Testnet USDC (or your chosen escrow asset) and a trustline to the asset issuer (G… address, not the contract C… address)

Setup

# Clone the repository
git clone https://github.com/Trustless-Work/trustlesswork-payment-widget-template.git
cd trustlesswork-payment-widget-template

# Install dependencies
pnpm install

# Copy environment variables and fill in your values
cp .env.local.example .env.local   # create this file — see below

Create .env.local in the project root (never commit this file):

# Trustless Work API (required once SDK/blocks are wired)
NEXT_PUBLIC_API_KEY=your_trustless_work_api_key

When integrating the SDK or Blocks, you will also configure role addresses, asset issuer, and provider nesting. See Trustless Work React SDK and the bundled agent skill at .agents/skills/trustless-work/.

Run locally

pnpm dev

Open http://localhost:3000. The page hot-reloads as you edit files under src/.

Other scripts:

Command	Description
pnpm build	Production build
pnpm start	Serve production build
pnpm lint	Run ESLint

---

Trustless Work resources & AI tools

Platform documentation

Resource	Link
Documentation home	docs.trustlesswork.com/trustless-work
REST API	API reference
React SDK (@trustless-work/escrow)	SDK guides
UI Blocks (@trustless-work/blocks)	Blocks guides
Documentation index (LLMs)	llms.txt

Template-specific behavior (roles, screens, MVP boundaries) lives in this repo’s docs/ folder. Platform mechanics (XDR signing, trustlines, API payloads) live in Trustless Work docs.

AI Skill (Skills.sh)

Install the official Trustless Work skill so your AI assistant understands escrow lifecycle, XDR signing, trustlines, provider setup, and common integration mistakes:

npx skills add trustless-work/trustless-work-dev-skill

Update installed skills later:

npx skills update

Registry: skills.sh/trustless-work

This repository also ships a local copy at .agents/skills/trustless-work/ for Cursor and compatible agents.

Learn more: Trustless Work Skill

MCP (Cursor & compatible editors)

Connect your editor to Trustless Work documentation and escrow tools via MCP. Use both servers together:

• trustlesswork-docs — read docs and generate integrations
• trustlesswork — escrow actions and live operations

Add to your project mcp.json (project root) or Cursor Settings → MCP:

{
  "mcpServers": {
    "trustlesswork-docs": {
      "type": "streamable-http",
      "url": "https://docs.trustlesswork.com/trustless-work/~gitbook/mcp",
      "headers": {}
    },
    "trustlesswork": {
      "type": "streamable-http",
      "url": "https://mcp.trustlesswork.com/mcp",
      "headers": {}
    }
  }
}

After saving, reload Cursor and confirm both servers show Connected under Settings → MCP. Use Agent Mode and prompts such as:

• Create a multi-release escrow with the SDK.
• Generate code to call the changeMilestoneStatus endpoint.
• Show me how to sign a transaction for releaseFunds.

Setup guide: Trustless Work MCP

---

Maintainers | Telegram

Tech Rebel | Product Manager techrebelgit Telegram

Joel Vargas | Frontend Developer JoelVR17 Telegram

Armando Murillo | Full Stack Developer armandocodecr Telegram

Caleb Loría | Smart Contract Developer zkCaleb-dev Telegram

---

Thanks to all the contributors who have made this project possible!