Introduction

Base URLs, the build-sign-submit loop, and the conventions every endpoint follows.

What is the Trustless Work API?

The Trustless Work REST API lets you create and manage decentralized escrow contracts on Stellar using Soroban smart contracts.

Use it to deploy escrows, fund them, track milestones, and release funds.

---

Base URL

Beta (Testnet)

Base URL

https://beta.api.trustlesswork.com

This version of the documentation describes the new Core API, currently running on Stellar Testnet at beta.api.trustlesswork.com.

The previous backend — documented under Version 1 — remains available at api.trustlesswork.com (mainnet) and dev.api.trustlesswork.com (testnet). The two are not interchangeable: credentials, read endpoints and error shapes all differ.

---

The one thing to understand first

The API never signs anything. Every endpoint that changes on-chain state returns an unsigned transaction. Your wallet signs it. You submit it.

1. BUILD    POST /escrow/<family>/<version>/<action>  →  { unsignedXdr, txHash, … }
2. SIGN     your wallet signs unsignedXdr locally     →  signedXdr
3. SUBMIT   POST /stellar/send-transaction { signedXdr }

Once you internalise this loop, every escrow action — fund, approve, dispute, release — is the same call with a different body.

Reads are separate and much simpler: plain GET requests against the read-model. See Reading Escrow Data.

---

Core capabilities

• Deploy escrows with roles, milestones, and conditions.

• Fund escrows using Stellar assets (for example USDC).

• Approve / update milestones to drive releases.

• Dispute and resolution flows, at escrow or milestone level.

• Release funds only when conditions are met.

• Query status for escrows, milestones, events and balances.

---

Escrow types

1. Single-release escrow

   • One release action for the full amount.

2. Multi-release escrow

   • Multiple milestone payouts.

   • Each milestone can be approved, disputed, and released independently.

Both come in a v1 and a v2 contract flavour. New integrations should use v2, which adds pluralised roles (up to 5 addresses each), an admin role, batch milestone operations, and manage_milestones.

---

Authentication

Every request carries either an API key or a wallet-session token:

x-api-key: <id>.<secret>

Authorization: Bearer <jwt>

See Authentication for how to obtain either one.

---

Conventions

Convention	Detail
Identifiers	An escrow is addressed by its on-chain contractId (C…). No internal UUIDs are exposed.
Casing	Every field is camelCase, including the snapshot object.
Pagination	Keyset, never offset. Responses are { data, hasMore, nextCursor } — never a bare array.
Errors	RFC 9457 Problem Details. Switch on code. See Errors.
Amounts	Decimal strings in read responses. Parse with a decimal library if you do arithmetic.
Consistency	The read-model is eventually consistent; the chain is authoritative.