1 of 100

English

Welcome

Our docs are optimized to be exported as context for any AI! You can also ask on the search bar!

Welcome to Trustless Work Documentation!

Trustless Work is the escrow infrastructure for the new economy — a developer-first platform to integrate programmable, milestone-based escrows into products.

AI optimized docs

Trustless Work documentation isn’t just written for humans. It’s structured for agents, copilots, and AI models to understand, remix, and build on top of.

Every page in our documentation is written for both:

Humans who want clarity, precision, and examples.
Machines that need structure, consistency, and semantics.

Why It Matters

The next generation of builders won’t just code — they’ll prompt. Trustless Work is optimized for that. Our docs follow an AI-ready format, meaning you can:

Export any page in Markdown or PDF for training datasets.
Feed it directly into your custom copilot or LLM memory.
Let your AI agents read the docs, reason through flows, and even execute API calls using your keys and roles.

🧠 Our goal: make the documentation itself a building block for automation.

Export & Train

You can export any section of this documentation into:

PDF – for reference and onboarding manuals
Markdown (.md) – for AI ingestion or context injection
Prompt blocks – pre-formatted snippets that can be pasted into GPT, Cursor, or v0.dev

💡 Use the SDK subpage under VibeCoding to see live examples of AI prompts generating, debugging, and deploying escrow flows automatically.

Ask the Docs

The docs themselves are AI-trained and search-optimized. That means the search bar understands natural language and intent — not just keywords.

Try prompts like:

The system will reformat your question into a structured query, returning optimized snippets, SDK calls, or workflow examples.

Why Escrows Matter

Escrows are a great way to solve for trust.
Escrows are neutral way to hold funds while specific conditions are met. Most people tend to think about Real Estate when I mention escrows, and they are right! we DO use escrows for Real Estate and high value transactions!

But Escrows are useful for so many things, for example, marketplaces like Upwork and Ebay use them:

Ebay and Upwork can afford to build their own escrow infrastructure. Well, sort of... Ebay actually uses Escrow.com, a huge legacy escrow company that takes between (3% - 8%) , Upwork, built Upwork Escrow inc. But thats not the reality of most businesses...

Who Should Use This

Trustless Work is built for developers, platforms, and agents who want more control and automation over when funds are released.

🧱 Platforms Using Stablecoins

Examples:

Gig and freelance platforms (e.g. milestone payments)
B2B tools using USDC for global payouts
Rental and booking platforms (security deposits)

Value:

Reduce fraud, automate disbursements, lower cost

🧑‍💻 Builders & Product Teams

Examples:

Solo devs or teams prototyping dApps
DAO tools, donation platforms, web3 marketplaces

Value:

Plug-and-play escrow logic
Start on testnet, go live without audit headaches

🏢 Enterprise Use

Examples:

Platforms with escrow-like flows (but no infrastructure)
Projects looking to replace costly custodial services

Value:

Save time and legal risk by using programmable, auditable escrows

Escrow Design

We don’t hold your money—we hold the logic.

Trustless Work escrows are role-based. It is important to understand the roles to be able to correctly configure the escrows. Updates to the contract status have to be signed by addresses, and only the addresses which have a role assigned can perfom the functions that only that role can sign.

Roles

Every escrow includes a roles object. These are the available roles:

Escrow products Mix & Match Guide

From idea to escrow in one day.

Designing an escrow is only half the battle. The real question is: How do you go from schema to a working product without burning months on contracts, audits, and ops flows?

That’s why Trustless Work offers a modular product suite — tools you can combine like building blocks to launch escrow-powered workflows today.

The Product Suite

Escrow API – The programmable core. Create, fund, update, approve, and release escrows. Maximum control, minimal friction.
Next.js SDK – React-friendly wrapper for interacting with escrows directly from your frontend.
Escrow Blocks – Pre-built React UI components. The fastest way to launch a user-facing escrow flow.
Back Office dApp (Open Source) – Ops-friendly control panel for deploying and managing escrows. Ideal for dispute resolution, MVP pilots, and non-technical teams. Use it, clone it.
Demo Lab dApp – Developer sandbox to test flows before pushing to production.
Escrow Viewer (Open Source) – Public, read-only explorer of escrow configs, milestones, and balances. Essential for transparency and compliance.

Integration Models

Think of these as playbooks for how to mix & match the suite:

Full API/SDK Integration → For teams with dev capacity and UX control needs. Your UI + our escrow logic.
Escrow Blocks: → Import template UI components to launch faster, with minimal custom frontend work.
Hybrid Back Office → Your users stay in your UI, but ops/disputes handled in the Back Office.
Back Office First → Launch this week. Manage flows directly in our Back Office while validating.

Stellar Network

Escrows need rails. Trustless Work runs on Stellar, a blockchain optimized for stablecoins, payments, and smart contracts.

This section explains the infrastructure behind Trustless Work — the network, assets, and tools that make escrows fast, cheap, and globally accessible.

🌐 Why Stellar?

Fast → Transactions settle in 5 seconds

Trustlines

On Stellar, accounts must explicitly opt in to hold and use assets. This opt-in is called a trustline.

What Are Trustlines in Stellar?

A trustline is an explicit opt-in setup by a Stellar account that authorizes it to hold, receive, and transact with a non‑native asset (i.e. anything other than XLM), issued by a specific issuer

Stellar Wallets

A Comprehensive Developer's Guide to Stellar Wallet Integrations

Introduction to Stellar Wallets

Stellar wallets are essential tools for interacting with the Stellar blockchain, enabling developers and users to securely manage, send, and receive digital assets. This section covers the setup and integration of popular Stellar wallets:

Developer Guide

🚀Developer Quickstart Escrow products Mix & Match Guide Trustless Work API Stellar Wallets

Dapp:

Authentication

In order to get registered, you have to connect with a Stellar wallet. If you do not yet have one, or have never used one, there is more information in the following section:

To authenticate you will need to login to our Dapp with a Stellar Wallet and Request an API key. Here are the steps to achieve that:

Coming: We are figuring out how this can work with passkeys and send to addresses with Memo. WE do this in the open, so feel free to crontribute.

Architecture

Step-by-step instructions to help you connect your product with Trustless Work smoothly and efficiently.

Overview

The purpose of this document is to provide a comprehensive guide on implementing best practices within the development team. It covers essential methodologies, tools, and strategies that can enhance productivity and ensure high-quality outcomes.

Basic Flow

Most common flow in the dApps.

Services - Endpoints

Flow that must always be executed at each Endpoint except Get Balances & Get Escrow

The document describes the essential execution flow for service endpoints, with exceptions for Get Balances and Get Escrow, ensuring uniformity in implementation.

Types

All the entities that you'll need.

Overview

In this document, we explore the structure and functionality of key escrow-related types and interfaces used in the system, including the Escrow and Escrow Response entities. These entities are crucial for handling escrow operations such as initializing, updating, and responding to requests regarding escrow contracts.

Our React library includes all these types. Simply import them.

Basic

Status, baseURL and HttpMethos

/**
 * The base URL for the Trustless Work API
 */
export type baseURL =
  | "https://api.trustlesswork.com"
  | "https://dev.api.trustlesswork.com";

/**
 * Escrow Type
 */
export type EscrowType = "single-release" | "multi-release";

/**
 * Http Method
 */
export type HttpMethod = "get" | "post" | "put" | "delete";

/**
 * Unique possible statuses for a Trustless Work request
 */
export type Status = "SUCCESS" | "FAILED";

/**
 * Date
 */
export type Date = {
  _seconds: number;
  _nanoseconds: number;
};

Fund Escrow

Single & Multi Release

Approve Milestone

Single & Multi Release

/**
 * Approve Milestone Payload, this can be a single-release or multi-release
 */
export type ApproveMilestonePayload = {
  /**
   * ID (address) that identifies the escrow contract
   */
  contractId: string;

  /**
   * Index of the milestone to be updated
   */
  milestoneIndex: string;

  /**
   * New evidence of work performed by the service provider.
   */
  newEvidence?: string;

  /**
   * Address of the entity requiring the service.
   */
  approver: string;
};

Change Milestone Status

Single & Multi Release

/**
 * Change Milestone Status Payload, this can be a single-release or multi-release
 */
export type ChangeMilestoneStatusPayload = {
  /**
   * ID (address) that identifies the escrow contract
   */
  contractId: string;

  /**
   * Index of the milestone to be updated
   */
  milestoneIndex: string;

  /**
   * New status of the milestone
   */
  newStatus: string;

  /**
   * New evidence of work performed by the service provider.
   */
  newEvidence?: string;

  /**
   * Address of the entity providing the service.
   */
  serviceProvider: string;
};

Release Funds

Single Release

/**
 * Single Release Release Funds Payload
 */
export type SingleReleaseReleaseFundsPayload = {
  /**
   * ID (address) that identifies the escrow contract
   */
  contractId: string;

  /**
   * Address of the user in charge of releasing the escrow funds to the service provider.
   */
  releaseSigner: string;
};

Multi Release

/**
 * Multi Release Release Funds Payload
 */
export type MultiReleaseReleaseFundsPayload = {
  /**
   * ID (address) that identifies the escrow contract
   */
  contractId: string;

  /**
   * Address of the user in charge of releasing the escrow funds to the service provider.
   */
  releaseSigner: string;

  /**
   * Index of the milestone to be released
   */
  milestoneIndex: string;
};

Start Dispute

Single Release

/**
 * Single Release Start Dispute Payload. This starts a dispute for the entire escrow.
 */
export type SingleReleaseStartDisputePayload = {
  /**
   * ID (address) that identifies the escrow contract
   */
  contractId: string;

  /**
   * Address of the user signing the contract transaction
   */
  signer: string;
};

Multi Release

/**
 * Multi Release Start Dispute Payload. This starts a dispute for a specific milestone.
 */
export type MultiReleaseStartDisputePayload = {
  /**
   * ID (address) that identifies the escrow contract
   */
  contractId: string;

  /**
   * Address of the user signing the contract transaction
   */
  signer: string;

  /**
   * Index of the milestone to be disputed
   */
  milestoneIndex: string;
};

Resolve Dispute

Single Release

/**
 * Resolve Dispute Payload
 */
export type SingleReleaseResolveDisputePayload = {
  /**
   * ID (address) that identifies the escrow contract
   */
  contractId: string;

  /**
   * Address in charge of resolving disputes within the escrow.
   */
  disputeResolver: string;

  /**
   * Distributions of the escrow amount to the receivers.
   */
  distributions: [
    {
      /**
       * Address of the receiver
       */
      address: string;
      /**
       * Amount to be transferred to the receiver. All the amount must be equal to the total amount of the escrow.
       */
      amount: number;
    },
  ];
};

Multi Release

Withdraw Remaining Funds

Multi Release Only

Get Balances

Params

Get Escrows by Contract ID

Params

Get Escrows by Signer

Params

/**
 * Get Escrows From Indexer By Signer Params
 */
export type GetEscrowsFromIndexerBySignerParams = {
  /**
   * Page number. Pagination
   */
  page?: number;

  /**
   * Sorting direction. Sorting
   */
  orderDirection?: "asc" | "desc";

  /**
   * Order by property. Sorting
   */
  orderBy?: "createdAt" | "updatedAt" | "amount";

  /**
   * Created at = start date. Filtering
   */
  startDate?: string;

  /**
   * Created at = end date. Filtering
   */
  endDate?: string;

  /**
   * Max amount. Filtering
   */
  maxAmount?: number;

  /**
   * Min amount. Filtering
   */
  minAmount?: number;

  /**
   * Is active. Filtering
   */
  isActive?: boolean;

  /**
   * Escrow that you are looking for. Filtering
   */
  title?: string;

  /**
   * Engagement ID. Filtering
   */
  engagementId?: string;

  /**
   * Status of the single-release escrow. Filtering
   */
  status?: SingleReleaseEscrowStatus;

  /**
   * Type of the escrow. Filtering
   */
  type?: "single-release" | "multi-release";

  /**
   * If true, the escrows will be validated on the blockchain to ensure data consistency.
   * This performs an additional verification step to confirm that the escrow data
   * returned from the indexer matches the current state on the blockchain.
   * Use this when you need to ensure the most up-to-date and accurate escrow information.
   * If you active this param, your request will take longer to complete.
   */
  validateOnChain?: boolean;

  /**
   * Address of the user signing the contract transaction.
   */
  signer: string;
};

Errors

Errors Entity

Introduction

How to get started in Trustless Work API REST

Base URL

Mainnet API

https://api.trustlesswork.com

Testnet API

https://dev.api.trustlesswork.com

Warning!

You'll have 50 as a request rate limit per client in the API every 60 seconds.

GitHub Repository

API Swagger

Single Release Escrow

Single-Release Escrow is a type in which all your funds are released only once, either with the resolution of a dispute or by completing all the milestones defined for it.

The Deploy endpoints allow users to deploy escrows efficiently. These endpoints provide the way to initialize escrows in the Stellar's Blockchain.

Key Components

Initial Fund Lockup: Upon contract initiation, the escrow amoun plus the platform fee (“platformFee”) is deposited into an escrow account.
Flags: The escrow status is interpreted by means of these flags: (approved, dispute, released, resolved).
Primary Roles:
- Service Provider: Delivers the deliverable corresponding to each milestone.
- Approver: Verifies and approves a milestone before authorizing the release of funds.
- Dispute Resolver: Intervenes in case of disagreement and decides whether to release or refund the locked amount.

Brief Workflow

An escrow is initialized by defining all the necessary escrow properties.
The Service Provider completes a milestone and requests approval.
The approver reviews the deliverable; if approved, signs a transaction that releases the amount allocated as escrow reward (minus the platform and Trustless Work fee).
The Stellar network executes the transaction and transfers the payment to the Service Provider or the configured Receiver.

Get Multiple Escrow Balance

Get the balance of multiple escrows.

Headers

Name

Value

Content-Type

application/json

x-api-key

<token>

Open API

Use Example:

Get Escrows By Contract Ids

Returns all the information of a security deposit requested through one or more requested contract ids.

Headers

Name

Value

Content-Type

application/json

x-api-key

Open API

Use Example:

Get Escrows By Signer

Returns all the information of an escrow requested through the signer.

Headers

Name

Value

Get Escrows By Role

Returns all the information of an escrow requested through the role.

Headers

Name

Value

Content-Type

application/json

x-api-key

Open API

Use Example:

Indexer

This endpoint facilitates the recovery and proper storage in Firebase of escrow-related information submitted to the Stellar Blockchain via external applications, bypassing the standard application.

Key Components

External Transaction: This endpoint handles cases where the XDR generated by any endpoint of our REST API is signed and sent directly by external applications.

Update From Tx Hash

This endpoint allows you to change the properties of an escrow as long as a series of requirements are met, which will be mentioned in this section.

Requirements for Use:

You must have the valid txHash generated from a transaction sent directly to the Stellar network.

Trustless Work SDK

Overview

Welcome to the our React Library Reference. This documentation provides details on how to interact with our API by using our library in the simplest way.

Links

import { EscrowType, SingleReleaseEscrowStatus } from "./types";
import { MultiReleaseEscrow, Role, SingleReleaseEscrow } from "./types.entity";

/**
 * Documentation: https://docs.trustlesswork.com/trustless-work/developer-resources/quickstart/integration-demo-project/entities
 */

// ----------------- Milestone Payloads -----------------
/**
 * Single Release Milestone Payload
 */
export type SingleReleaseMilestonePayload = {
  /**
   * Text describing the function of the milestone
   */
  description: string;
};

/**
 * Multi Release Milestone Payload
 */
export type MultiReleaseMilestonePayload = {
  /**
   * Text describing the function of the milestone
   */
  description: string;
  /**
   * Amount to be transferred upon completion of this milestone
   */
  amount: number;
  /**
   * Address where milestone proceeds will be sent to
   */
  receiver: string;
};

// ----------------- Initialize Escrow -----------------
/**
 * Single Release Initialize Escrow Payload
 */
export type InitializeSingleReleaseEscrowPayload = Omit<
  SingleReleaseEscrow,
  "contractId" | "balance" | "milestones"
> & {
  /**
   * Objectives to be completed to define the escrow as completed
   */
  milestones: SingleReleaseMilestonePayload[];
};

/**
 * Multi Release Initialize Escrow Payload
 */
export type InitializeMultiReleaseEscrowPayload = Omit<
  MultiReleaseEscrow,
  "contractId" | "balance" | "milestones"
> & {
  /**
   * Objectives to be completed to define the escrow as completed
   */
  milestones: MultiReleaseMilestonePayload[];
};

// ----------------- Update Escrow -----------------
/**
 * Single Release Update Escrow Payload
 */
export type UpdateSingleReleaseEscrowPayload = {
  /**
   * ID (address) that identifies the escrow contract
   */
  contractId: string;

  /**
   * Escrow data
   */
  escrow: Omit<SingleReleaseEscrow, "contractId" | "signer" | "balance"> & {
    /**
     * Whether the escrow is active. This comes from DB, not from the blockchain.
     */
    isActive?: boolean;
  };

  /**
   * Address of the user signing the contract transaction
   */
  signer: string;
};

/**
 * Multi Release Update Escrow Payload
 */
export type UpdateMultiReleaseEscrowPayload = {
  /**
   * ID (address) that identifies the escrow contract
   */
  contractId: string;

  /**
   * Escrow data
   */
  escrow: Omit<MultiReleaseEscrow, "contractId" | "signer" | "balance"> & {
    /**
     * Whether the escrow is active. This comes from DB, not from the blockchain.
     */
    isActive?: boolean;
  };

  /**
   * Address of the user signing the contract transaction
   */
  signer: string;
};

// ----------------- Change Milestone Status -----------------
/**
 * Change Milestone Status Payload, this can be a single-release or multi-release
 */
export type ChangeMilestoneStatusPayload = {
  /**
   * ID (address) that identifies the escrow contract
   */
  contractId: string;

  /**
   * Index of the milestone to be updated
   */
  milestoneIndex: string;

  /**
   * New status of the milestone
   */
  newStatus: string;

  /**
   * New evidence of work performed by the service provider.
   */
  newEvidence?: string;

  /**
   * Address of the entity providing the service.
   */
  serviceProvider: string;
};

// ----------------- Approve Milestone -----------------
/**
 * Approve Milestone Payload, this can be a single-release or multi-release
 */
export type ApproveMilestonePayload = Omit<
  ChangeMilestoneStatusPayload,
  "serviceProvider" | "newStatus"
> & {
  /**
   * Address of the entity requiring the service.
   */
  approver: string;
};

// ----------------- Start Dispute -----------------
/**
 * Single Release Start Dispute Payload. This starts a dispute for the entire escrow.
 */
export type SingleReleaseStartDisputePayload = {
  /**
   * ID (address) that identifies the escrow contract
   */
  contractId: string;

  /**
   * Address of the user signing the contract transaction
   */
  signer: string;
};

/**
 * Multi Release Start Dispute Payload. This starts a dispute for a specific milestone.
 */
export type MultiReleaseStartDisputePayload =
  SingleReleaseStartDisputePayload & {
    /**
     * Index of the milestone to be disputed
     */
    milestoneIndex: string;
  };

// ----------------- Resolve Dispute -----------------
/**
 * Resolve Dispute Payload
 */
export type SingleReleaseResolveDisputePayload = {
  /**
   * ID (address) that identifies the escrow contract
   */
  contractId: string;

  /**
   * Address in charge of resolving disputes within the escrow.
   */
  disputeResolver: string;

  /**
   * Distributions of the escrow amount to the receivers.
   */
  distributions: [
    {
      /**
       * Address of the receiver
       */
      address: string;
      /**
       * Amount to be transferred to the receiver. All the amount must be equal to the total amount of the escrow.
       */
      amount: number;
    },
  ];
};

/**
 * Multi Release Resolve Dispute Payload
 */
export type MultiReleaseResolveDisputePayload =
  SingleReleaseResolveDisputePayload & {
    /**
     * Index of the milestone to be resolved
     */
    milestoneIndex: string;
  };

// ----------------- Withdraw Remaining Funds -----------------
/**
 * Withdraw remaining funds
 */
export type WithdrawRemainingFundsPayload = SingleReleaseResolveDisputePayload;

// ----------------- Fund Escrow -----------------
/**
 * Fund Escrow Payload, this can be a single-release or multi-release
 */
export type FundEscrowPayload = {
  /**
   * Amount to be transferred upon completion of escrow milestones
   */
  amount: number;

  /**
   * ID (address) that identifies the escrow contract
   */
  contractId: string;

  /**
   * Address of the user signing the contract transaction
   */
  signer: string;
};

// ----------------- Get Escrows From Indexer -----------------
/**
 * Get Escrows From Indexer Params
 */
export type GetEscrowsFromIndexerParams = {
  /**
   * Page number. Pagination
   */
  page?: number;

  /**
   * Sorting direction. Sorting
   */
  orderDirection?: "asc" | "desc";

  /**
   * Order by property. Sorting
   */
  orderBy?: "createdAt" | "updatedAt" | "amount";

  /**
   * Created at = start date. Filtering
   */
  startDate?: string;

  /**
   * Created at = end date. Filtering
   */
  endDate?: string;

  /**
   * Max amount. Filtering
   */
  maxAmount?: number;

  /**
   * Min amount. Filtering
   */
  minAmount?: number;

  /**
   * Is active. Filtering
   */
  isActive?: boolean;

  /**
   * Escrow that you are looking for. Filtering
   */
  title?: string;

  /**
   * Engagement ID. Filtering
   */
  engagementId?: string;

  /**
   * Status of the single-release escrow. Filtering
   */
  status?: SingleReleaseEscrowStatus;

  /**
   * Type of the escrow. Filtering
   */
  type?: EscrowType;

  /**
   * If true, the escrows will be validated on the blockchain to ensure data consistency.
   * This performs an additional verification step to confirm that the escrow data
   * returned from the indexer matches the current state on the blockchain.
   * Use this when you need to ensure the most up-to-date and accurate escrow information.
   * If you active this param, your request will take longer to complete.
   */
  validateOnChain?: boolean;
};

export type GetEscrowsFromIndexerBySignerParams =
  GetEscrowsFromIndexerParams & {
    /**
     * Address of the user signing the contract transaction.
     */
    signer: string;
  };

export type GetEscrowsFromIndexerByRoleParams = GetEscrowsFromIndexerParams & {
  /**
   * Role of the user. Required
   */
  role: Role;

  /**
   * Address of the owner of the escrows. If you want to get all escrows from a specific role, you can use this parameter. But with this parameter, you can't use the signer parameter.
   */
  roleAddress: string;
};

export type GetEscrowFromIndexerByContractIdsParams = {
  /**
   * IDs (addresses) that identifies the escrow contracts.
   */
  contractIds: string[];

  /**
   * If true, the escrows will be validated on the blockchain to ensure data consistency.
   * This performs an additional verification step to confirm that the escrow data
   * returned from the indexer matches the current state on the blockchain.
   * Use this when you need to ensure the most up-to-date and accurate escrow information.
   * If you active this param, your request will take longer to complete.
   */
  validateOnChain?: boolean;
};

// ----------------- Release Funds -----------------
/**
 * Single Release Release Funds Payload
 */
export type SingleReleaseReleaseFundsPayload = {
  /**
   * ID (address) that identifies the escrow contract
   */
  contractId: string;

  /**
   * Address of the user in charge of releasing the escrow funds to the service provider.
   */
  releaseSigner: string;
};

/**
 * Multi Release Release Funds Payload
 */
export type MultiReleaseReleaseFundsPayload =
  SingleReleaseReleaseFundsPayload & {
    /**
     * Index of the milestone to be released
     */
    milestoneIndex: string;
  };

// ----------------- Get Balance -----------------
/**
 * Get Balance Params
 */
export type GetBalanceParams = {
  /**
   * Addresses of the escrows to get the balance
   */
  addresses: string[];
};

// ----------------- Update From Transaction Hash -----------------
/**
 * Payload for updating escrow data from a transaction hash.
 */
export type UpdateFromTxHashPayload = {
  /**
   * Transaction hash to be used for the update.
   */
  txHash: string;
};

Vibe Coding - Blocks

⚡ VibeCoding Guide — Escrow Blocks (Single-File AI Context)

This page is engineered for bytecoders/agent workflows. You can export to PDF or Markdown and feed it to your copilot, Cursor, or fine-tuning pipelines. Our docs are explicitly optimized to be exported as AI context and can be queried via the docs search bar in natural language.

0) What this file is

Purpose: Give an AI (or a very fast human) all the context needed to install, wire, and use Trustless Work Escrow Blocks with Next.js.
Scope: Installation, required providers (order matters), commands to add blocks, example pages, dependency rules, actions, and troubleshooting.
Audience: Builders, PMs, and AIs doing codegen for single-release and multi-release escrow UIs.

1) Quick mental model

Escrow Blocks = prebuilt React components + hooks that talk to the Trustless Work API/SDK for escrow lifecycles.
Providers must wrap your app in a specific order (React Query → TW → Wallet → Escrow → Dialogs → Amount). Do not reorder.
Listings (by role / by signer) show escrows and open detail dialogs with context-aware actions. Some actions ship commented; enable the version matching your escrow type (single or multi).

2) Project bootstrap (Next.js + Blocks)

2.1 Create the app

2.2 Install Escrow Blocks

2.3 Run the CLI (recommended)

What it does (summary):

Installs deps (@tanstack/react-query, forms/validation libs, shadcn/ui).
Generates .twblocks.json.
Offers to wire providers in app/layout.tsx for you.

You can also add modules incrementally with npx trustless-work add <module>.

3) Environment

Create .env.local (reads can work without a key; write flows need it):

Get your API key in the dApp when ready to move beyond read-only dev flows. (Docs index + dApp flow referenced elsewhere.)

4) Provider stack (order is critical)

If you skipped CLI wiring, add these providers in this exact order.

Why it matters: The blocks depend on React Query + Trustless Work context + wallet + escrow state + dialogs/amount contexts. Reordering breaks hooks and UI flows.

5) Add modules & blocks (CLI)

Run these once per project:

6) Your first page (wallet + init + listings)

What you’ll see: wallet connect, “Initialize Escrow” (single-release), and a cards grid filtered by role (actions are role/state-aware).

7) Actions area: enabling the right buttons

Inside listings’ detail dialog, some actions are commented so you can enable only what you need per escrow type:

When ready, import & enable:

Rule of thumb: Use single-release actions for single escrows; use multi- components for multi escrows. Listings are shared, funding/approve/status are shared via single-multi-release.

8) Dependency rules (practical)

Listings (by role / by signer) need:

wallet-kit, providers, tanstack, helpers, handle-errors, plus lifecycle blocks for the actions you’ll expose.

Single-release or Multi-release actions need:

wallet-kit, providers, tanstack, helpers (+ handle-errors), and the corresponding block set(s).

Provider order must match section 4.

9) Usage flow (testnet demo path)

Connect wallet (Freighter).
Initialize escrow (single or multi).
Fund the escrow (shared dialogs/buttons).
Change milestone status, approve, and then release (release-all for single; release milestone

Tip: Listings filter by role; the visible actions depend on your role + escrow state. Add the USDC trustline in Freighter to interact smoothly.

10) Troubleshooting (fast fixes)

Buttons do nothing / disabled: Your account doesn’t have the required role, the escrow state doesn’t allow that action, or the escrow isn’t funded/approved yet.
Hooks failing / context error: Provider order is wrong. Compare with the canonical order here.
Client vs server error: Add "use client" to pages/components that consume hooks.

11) Minimal “Blocks Gallery” pattern (optional)

A local gallery lets teammates see every block live:

Dev server: pnpm dev → open /blocks
Wire the global providers (as above)
Add pages:

12) VibeCoding: prompt scaffolds (copy-paste)

A) System prompt (one-time context)

B) Task prompt (generate page + wiring)

C) Debug prompt (when things break)

13) Notes for AIs (indexing hints)

Important keywords: Trustless Work, Escrow Blocks, single-release, multi-release, providers, WalletProvider, ReactQueryClientProvider, role-based actions, FundEscrowDialog, ApproveMilestoneDialog, ChangeMilestoneStatusDialog, ReleaseEscrowButton, ReleaseMilestoneButton, InitializeEscrowDialog.
Do not reorder providers. Quote this rule when suggesting edits.
Docs are AI-exportable; searching the docs in natural language is supported.

14) Appendix — canonical provider order (snippet)

Source reference for order requirement.

License to remix

Use, copy, embed, and ship. If your agent needs more, point it at the full docs hub and API reference. The overall documentation explicitly supports AI export & semantic search.

English

Welcome

Welcome to Trustless Work Documentation!

AI optimized docs

Why It Matters

Export & Train

Ask the Docs

Why Escrows Matter

Who Should Use This

🧱 Platforms Using Stablecoins

🧑‍💻 Builders & Product Teams

🏢 Enterprise Use

Links

🧭 Core Docs

🛠️ Tools

🌐 External Links

Escrow Design

Roles

Escrow products Mix & Match Guide

The Product Suite

Integration Models

Stellar Network

🌐 Why Stellar?

Trustlines

What Are Trustlines in Stellar?

Stellar Wallets

Introduction to Stellar Wallets

Developer Guide

Authentication

Architecture

Overview

Basic Flow

Services - Endpoints

Types

Overview

Basic

Status, baseURL and HttpMethos

Fund Escrow

Single & Multi Release

Approve Milestone

Single & Multi Release

Change Milestone Status

Single & Multi Release

Release Funds

Single Release

Multi Release

Start Dispute

Single Release

Multi Release

Resolve Dispute

Single Release

Multi Release

Withdraw Remaining Funds

Multi Release Only

Get Balances

Params

Get Escrows by Contract ID

Params

Get Escrows by Signer

Params

Errors

Errors Entity

Introduction

Base URL

Warning!

GitHub Repository

API Swagger

Single Release Escrow

Fund Escrow

Headers

Approve Milestone

Headers

Dispute Milestone

Headers

Resolve Milestone Dispute

Headers

Helpers

Introduction

Get Multiple Escrow Balance

Headers