> 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/api-rest/escrows.md).

# Escrows

{% hint style="warning" %}
**This section replaced the old "Indexer" flow.**

Previously you had to sign a transaction externally and then POST its `txHash` to `indexer/update-from-txHash` for the escrow to be recorded. **That flow no longer exists.** There is no endpoint to call and nothing for you to push.
{% endhint %}

### How reads work now

The API is two cooperating halves:

* The **write side** (`/escrow/**`, `/stellar/send-transaction`) builds unsigned transactions and submits the ones you sign.
* The **read side** (`/escrows/**` and GraphQL) serves a queryable copy of on-chain escrow state, kept current automatically.

You never connect the two. Submit a transaction, and the read-model reflects it a few seconds later on its own.

***

### Eventual consistency

The read-model is **eventually consistent** and is **never the authority** — the chain is.

For anything where being briefly stale matters (a final settlement check, a balance you are about to act on), read the chain. For everything else — lists, dashboards, history — the read-model is what you want, and it is far faster to query.

After submitting a transaction, do not assume the read-model is instantly current. Poll briefly rather than treating a momentary `404` or a stale `balance` as an error.

{% hint style="info" %}
If `POST /stellar/send-transaction` returns `code: "STELLAR_TX_SUBMITTED_INDEXER_LAGGING"`, that is a **success**: the transaction is in the ledger and the projection is catching up. Keep the `txHash`, show a pending state, and poll.
{% endhint %}

***

### Identifiers

An escrow's public identifier is its **`contractId`** — the on-chain `C…` address. It is the same value `deploy` predicts and `send-transaction` confirms, so a single key tracks an escrow from creation onward. No internal UUIDs are exposed anywhere.

***

### Who can read what

Reads require the `ESCROW_MANAGER` role. Beyond that they are **open**: any authenticated caller with that role can read any escrow on the network. Escrow state is public on-chain, so gating a mirror of public data adds friction without adding privacy.

Your identity affects exactly one thing — the `scope` parameter on the list endpoint:

| Value            | Returns                                                                                |
| ---------------- | -------------------------------------------------------------------------------------- |
| `mine` (default) | Escrows your verified wallets participate in, plus escrows attributed to your platform |
| `all`            | Every escrow on the network                                                            |

***

### The endpoints

| Endpoint                               | Use it for                                             |
| -------------------------------------- | ------------------------------------------------------ |
| `GET /escrows`                         | List with filters and keyset pagination                |
| `GET /escrows/{contractId}`            | Full detail: state, snapshot, timeline, deposits       |
| `GET /escrows/details`                 | Batch detail, up to 50 ids                             |
| `GET /escrows/{contractId}/events`     | Paged event timeline                                   |
| `GET /escrows/{contractId}/milestones` | Milestones of one escrow                               |
| `GET /escrows/milestones`              | Milestones of a batch                                  |
| `GET /escrows/financial`               | Fee, deposited, released, pending, balance for a batch |
| `POST /graphql`                        | The same data with field selection                     |

***

### Migration reference

| Old endpoint                              | Replacement                                        |
| ----------------------------------------- | -------------------------------------------------- |
| `GET /helper/get-escrow-by-contract-ids`  | `GET /escrows/details?contractIds=…`               |
| `GET /helper/get-escrows-by-signer`       | `GET /escrows?participant=G…`                      |
| `GET /helper/get-escrows-by-role`         | `GET /escrows?participant=G…&role=…`               |
| `GET /helper/get-multiple-escrow-balance` | `GET /escrows/financial?contractIds=…`             |
| `POST /indexer/update-from-txHash`        | *Nothing — escrow state is recorded automatically* |


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.trustlesswork.com/trustless-work/v2-en/api-rest/escrows.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.