Escrow Information

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

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