> For the complete documentation index, see [llms.txt](https://docs.trustlesswork.com/trustless-work/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/developer-resources.md). # Developer Guide Start building with Trustless Work V2 using the Core API, React SDK, JavaScript SDK, or Escrow Blocks on Stellar Testnet. Trustless Work is **non-custodial escrow infrastructure** for applications, platforms, and agents. Version 2 provides a rewritten developer stack built around: * Core API v2 * Single-Release and Multi-Release escrows * V2 smart contracts * React SDK * JavaScript SDK * Escrow Blocks * automatic chain indexing Your application controls the user experience. Trustless Work provides the escrow and settlement infrastructure underneath it. *** ## V2 beta status Trustless Work Version 2 is currently: * **Beta** * **Stellar Testnet only** * **Not yet externally audited** The V2 API host is: ``` https://beta.api.trustlesswork.com ``` Version 1 remains the current production/mainnet environment. Do not mix Version 1 API hosts, SDK behavior, or indexing flows into a V2 integration. *** ## How V2 works The normal write flow is: ``` Your application ↓ React SDK / JS SDK / REST ↓ Core API v2 ↓ Unsigned Stellar transaction ↓ Authorized wallet signs ↓ Transaction submitted ↓ Stellar / Soroban ↓ Escrow contract executes ``` Trustless Work does not hold your private keys and does not sign escrow actions for you. The Core API builds transactions. The wallet assigned to the relevant escrow role authorizes them. *** ## API access is not escrow authority These are separate concepts: ``` API key = access to Trustless Work developer infrastructure Wallet signature = authority to perform an escrow action ``` For example, your application may successfully authenticate with the API but still be unable to approve a milestone if the signing wallet is not configured as an Approver. The smart contract remains the final authority over escrow permissions. *** ## 1. Choose your integration path Start by deciding how your application should interact with Trustless Work. | Need | Recommended surface | | ------------------------------------------- | ------------------- | | React application | **React SDK** | | Node.js, scripts, agents, non-React JS | **JavaScript SDK** | | Non-JavaScript stack or direct HTTP control | **REST API** | | Reusable escrow UI | **Escrow Blocks** | | Operational pilot or internal workflow | **Backoffice** | | Read-only contract inspection | **Escrow Viewer** | You can combine these surfaces. For example: ``` Customer experience → React SDK Internal operations → Backoffice Independent verification → Escrow Viewer ``` [Choose Your Integration Path](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/smart-escrow-design) *** ## 2. Get API access Generate an API key through the Trustless Work Backoffice. Authenticated API-key requests use: ```http x-api-key: . ``` Keep the secret server-side. Do not expose API keys in: * frontend source code * browser bundles * public repositories * client-side environment variables [Get an API Key](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/developer-resources/request-api-key) *** ## 3. Set up wallet signing Most operations that change on-chain state produce an unsigned Stellar transaction. Your integration must: 1. request the transaction 2. present it to the correct wallet 3. collect the signature 4. submit the signed transaction The signer must hold the appropriate escrow role. Examples: | Action | Required authority | | ------------------------------------- | ------------------ | | Change milestone status | Service Provider | | Approve milestone | Approver | | Release funds | Release Signer | | Resolve dispute | Dispute Resolver | | Update permitted escrow configuration | Admin | The API does not replace these contract permissions. [Learn about Stellar Wallets](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/stellar-and-soroban-the-backbone-of-trustless-work/stellar-wallets) *** ## 4. Understand the escrow model Before implementing endpoints or SDK calls, understand the agreement you are creating. Start with: * escrow type * roles * milestones * approval thresholds * funding * release * dispute resolution [Review Escrow Design](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview) Then review the technical object model: [Review the V2 Schema](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/developer-resources/schema) *** ## 5. Choose the escrow type V2 supports two settlement models. ### Single Release Use Single Release when several conditions lead to **one final payout**. ``` Milestone 1 Milestone 2 Milestone 3 ↓ One settlement ``` ### Multi Release Use Multi Release when milestones should settle **independently**. ``` Milestone 1 → Payment 1 Milestone 2 → Payment 2 Milestone 3 → Payment 3 ``` [Compare Escrow Types](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-types) *** ## 6. Implement the lifecycle A typical escrow flow is: ``` Initialize ↓ Fund ↓ Update Milestones ↓ Approve ↓ Release ``` A dispute creates an alternative settlement path: ``` Dispute ↓ Resolve ``` These actions are intentionally separate. In particular: ``` Status ≠ Approval ≠ Release ``` Updating a milestone does not approve it. Approving a milestone does not automatically release funds. [Review the Escrow Lifecycle](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle) *** ## 7. Use the integration surface that fits your stack ### REST API Use the REST API when you want direct access to Core API v2. Good fit for: * custom backends * non-JavaScript stacks * custom SDKs * infrastructure services * direct HTTP integrations [Explore the V2 REST API](https://docs.trustlesswork.com/trustless-work/v2-en/api-rest) *** ### React SDK Package: ``` @trustless-work/escrow ``` Use it for React and TypeScript applications where escrow interactions should be embedded directly into your product. [Explore the Escrow React SDK](https://docs.trustlesswork.com/trustless-work/v2-en/escrow-react-sdk) *** ### JavaScript SDK Package: ``` @trustless-work/escrow-js ``` Use it for: * Node.js * backend services * scripts * non-React frontends * automation * agents [Explore the Escrow JS SDK](https://docs.trustlesswork.com/trustless-work/v2-en/escrow-js-sdk) *** ### Escrow Blocks Escrow Blocks provide reusable UI components built on the React integration stack. Use them when you want to accelerate development without designing every escrow interface from scratch. [Explore the Escrow Blocks SDK](https://docs.trustlesswork.com/trustless-work/v2-en/escrow-blocks-sdk) *** ## 8. Read escrow state Core API v2 automatically indexes supported escrow activity from the blockchain. You can query state through: * REST * GraphQL Applications no longer use the Version 1 manual: ``` indexer/update-from-txHash ``` flow. [Explore GraphQL](https://docs.trustlesswork.com/trustless-work/v2-en/api-rest/graphql) *** ## Expect eventual consistency The blockchain and the indexed read model are separate layers. After a transaction: ``` Transaction confirmed on Stellar ↓ Indexer processes chain activity ↓ Core API read model updates ``` There may be a short delay between transaction confirmation and the new state appearing in API reads. The chain is the authoritative execution layer. The Core API is the application-friendly indexed view. *** ## 9. Understand the Stellar prerequisites V2 currently runs on Stellar Testnet. You will need to understand: * Stellar wallets * Testnet XLM for transaction fees * supported testnet assets * token / trustline requirements * Soroban transaction signing Start here: [Stellar Network](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/stellar-and-soroban-the-backbone-of-trustless-work) [Testnet Tokens](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/stellar-and-soroban-the-backbone-of-trustless-work/testnet-tokens) [Trustlines](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/stellar-and-soroban-the-backbone-of-trustless-work/trustlines) [Stellar Wallets](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/stellar-and-soroban-the-backbone-of-trustless-work/stellar-wallets) *** ## 10. Use operational tools when useful You do not need to build every operational interface yourself. ### Backoffice Use Backoffice for: * API key management * pilots * testing * operational workflows * internal support [Explore Backoffice](https://docs.trustlesswork.com/trustless-work/v2-en/oss-dapps/backoffice) ### Escrow Viewer Use the Viewer for independent, read-only inspection of escrow contract state. [Explore the Escrow Viewer](https://docs.trustlesswork.com/trustless-work/v2-en/oss-dapps/escrow-viewer) *** ## Recommended implementation sequence For a new integration, use this order: #### Step 1 — Define the agreement Decide: * Single or Multi Release * roles * milestones * approval thresholds * Receivers * dispute authority #### Step 2 — Choose the integration surface Pick: * REST * React SDK * JS SDK * Blocks based on your application architecture. #### Step 3 — Get API access Create and securely store the API key. #### Step 4 — Implement wallet signing Make sure each action is signed by an address with the required contract role. #### Step 5 — Implement the happy path Build: ``` Initialize → Fund → Update → Approve → Release ``` #### Step 6 — Implement disputes Add: ``` Dispute → Resolve ``` Do not leave the exception path until after production design. #### Step 7 — Handle indexed reads Account for eventual consistency between successful on-chain execution and the API read model. #### Step 8 — Add operational tooling Decide whether Backoffice and Viewer can replace internal tooling you would otherwise need to build. *** ## Architecture principle Trustless Work works best when responsibilities remain separated. ``` Business workflow → Your application Transaction construction → Trustless Work SDK / Core API Authorization → Wallet signatures Settlement rules → Escrow smart contract Execution → Stellar / Soroban Queryable application state → Core API indexer ``` Do not put business-specific workflow into the contract unless it must affect economic authorization. Do not rely solely on application permissions for actions the escrow contract should enforce. [Review Architecture & Design Strategy](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/architecture-and-design-strategy) *** ## Where to go next If you are starting from zero: 1. [Escrow Design](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview) 2. [Choose Your Integration Path](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/smart-escrow-design) 3. [Get an API Key](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/developer-resources/request-api-key) 4. [V2 Schema](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/developer-resources/schema) 5. [REST API](https://docs.trustlesswork.com/trustless-work/v2-en/api-rest) 6. [React SDK](https://docs.trustlesswork.com/trustless-work/v2-en/escrow-react-sdk) 7. [JavaScript SDK](https://docs.trustlesswork.com/trustless-work/v2-en/escrow-js-sdk) 8. [Escrow Blocks](https://docs.trustlesswork.com/trustless-work/v2-en/escrow-blocks-sdk) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.trustlesswork.com/trustless-work/v2-en/introduction/developer-resources.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.