Escrows

The read endpoints: list, detail, events, milestones, financial and GraphQL.

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.

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.

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.

---

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