Trustless Work | Documentation

Agency Escrow Template

A milestone-based escrow workflow for agencies, consultants, freelancers, and product studios to secure client funds upfront, deliver work in clear increments, and release payment only after approval.

Agencies stop chasing invoices. Clients only release funds when work is delivered.

Built on Trustless Work — Escrow-as-a-Service on Stellar/Soroban — this template is a reference implementation you can fork, adapt, and dogfood for real client engagements.

The problem

Agency work breaks when delivery, scope, and payment live in separate tools. Clients hesitate to pay large retainers blindly; agencies hesitate to start without secured funds. This template adds a neutral, programmable payment layer: funds are locked before work begins and released when the client approves delivery.

Core workflow

Step	Actor	Action
1	Agency	Creates a one-milestone escrow and sends a funding link to the client
2	Client	Reviews terms and funds the escrow (stablecoin on Stellar)
3	Agency	Delivers work and marks the milestone as submitted
4	Client	Reviews deliverables and approves the milestone
5	Client	Releases funds to the agency; platform fee is routed automatically
6	Both	View escrow status and event timeline in the dashboard

Default role mapping (MVP)

Trustless Work role	Template meaning	Default actor
Creator	Initiates the commercial proposal	Agency
Funder	Deposits funds into escrow	Client
Receiver	Receives payment after approval	Agency
Milestone Marker	Marks work as submitted	Agency
Approver	Confirms milestone acceptance	Client
Release Signer	Triggers fund release	Client
Platform Address	Receives infrastructure fee	Trustless Work / platform

MVP scope

In scope

• One milestone per escrow
• Create escrow, assign roles, define amount and acceptance criteria
• Client funding, agency submission, client approval, fund release
• Platform fee routing and escrow status viewer for both parties

Out of scope (future versions)

• Multi-milestone contracts, disputes, partial releases, subscriptions, fiat, CRM, or full project management

For full product requirements, user flows, state machine, and acceptance criteria, see the docs/ folder:

Document	Purpose
docs/PRODUCT-BRIEF.md	Executive summary and example milestones
docs/PRD.md	Full PRD: personas, functional requirements, UX, data model
docs/FULL-USER-FLOW_ESCROW-ROLE-MAPPING.md	Step-by-step flows, role mapping, state machine

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-agency-escrow-template.git
cd trustlesswork-agency-escrow-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!