> 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/escrow-information/get-escrow-by-contract-ids.md).
# Get Escrows Details
Batch-read the full state of up to 50 escrows via GET /escrows/details.
{% hint style="info" %}
This endpoint replaces `GET /helper/get-escrow-by-contract-ids`. The old path no longer exists.
{% endhint %}
### **Headers**
| Name | Value |
|---|
| Content-Type | application/json |
| x-api-key | <token> |
### Open API
## Read the full detail of a batch of escrows
> Bulk companion of \`GET /escrows/:contractId\`: pass up to 50 contract addresses (\`contractIds=Cā¦\&contractIds=Cā¦\`) and get, for each known escrow, its full state (snapshot included) plus the deposit trail. The per-escrow timeline is excluded ā page it at \`GET /escrows/:contractId/events\`. Unknown ids are silently absent from the response.
```json
{"openapi":"3.0.0","info":{"title":"šš¼ Trustless Work Core API ā All Endpoints (Unified)","version":"1.0"},"servers":[{"url":"https://beta.api.trustlesswork.com"}],"security":[{}],"paths":{"/escrows/details":{"get":{"description":"Bulk companion of `GET /escrows/:contractId`: pass up to 50 contract addresses (`contractIds=Cā¦&contractIds=Cā¦`) and get, for each known escrow, its full state (snapshot included) plus the deposit trail. The per-escrow timeline is excluded ā page it at `GET /escrows/:contractId/events`. Unknown ids are silently absent from the response.","operationId":"EscrowQueryController_detailsBatch","parameters":[{"name":"contractIds","required":true,"in":"query","description":"On-chain contract addresses (repeat the param: `contractIds=Cā¦&contractIds=Cā¦`, 1ā50). Inaccessible or unknown ids are silently absent from the response.","schema":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EscrowDetailsListResponse"}}}},"400":{"description":"Request body or query params fail schema validation (wrong type, missing required field, unknown property).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsResponseDto"}}}},"401":{"description":"Missing, malformed, expired, revoked or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsResponseDto"}}}},"403":{"description":"API key is valid but does not have the role required for this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsResponseDto"}}}},"422":{"description":"Payload is well-formed but a business rule rejects it (e.g. amount out of range, role not allowed for this user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsResponseDto"}}}}},"summary":"Read the full detail of a batch of escrows","tags":["Escrows"]}}},"components":{"schemas":{"EscrowDetailsListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EscrowBatchDetailResponse"}}},"required":["data"]},"EscrowBatchDetailResponse":{"type":"object","properties":{"escrow":{"$ref":"#/components/schemas/EscrowSummaryResponse"},"deposits":{"description":"First page of the fund trail, newest first (up to 200 rows). Page the rest at `GET /escrows/:contractId/deposits`.","type":"array","items":{"$ref":"#/components/schemas/EscrowDepositResponse"}},"depositsHasMore":{"type":"boolean","description":"True when the trail holds more rows than the embedded page ā page the rest at `GET /escrows/:contractId/deposits`."},"depositsTotal":{"type":"number","description":"Total deposit-row count across every page."}},"required":["escrow","deposits","depositsHasMore","depositsTotal"]},"EscrowSummaryResponse":{"type":"object","properties":{"network":{"type":"string","description":"Stellar network."},"contractId":{"type":"string","description":"On-chain escrow contract (C...)."},"type":{"type":"object","description":"Detected contract flavor. Null until the first state.","nullable":true},"status":{"type":"object","nullable":true,"description":"Lifecycle status."},"anomalies":{"description":"TW invariant violations visible in the projected state (empty = compliant). The factory is a public contract, so an escrow can be deployed outside this API with trap parameters (e.g. a platform fee above the ceiling locks every deposit); a non-empty list means DO NOT treat this escrow as a compliant TW escrow.","type":"array","items":{"type":"string"}},"totalAmount":{"type":"object","nullable":true,"description":"Multi-release only: sum of the milestone amounts, in token units (decimal string; null until the first state is projected). Single-release rows OMIT this key ā the amount lives in `snapshot.amount`, and `GET /escrows/financial` always carries the figure for both flavors."},"balance":{"type":"string","description":"Projected balance (total deposited ā total released), derived from the read-model deposit trail; eventually consistent with the on-chain token balance. Always present (decimal string), \"0\" when nothing is deposited."},"asset":{"nullable":true,"description":"The trustline asset funding this escrow. Null until the first state is projected.","type":"object","allOf":[{"$ref":"#/components/schemas/EscrowAssetResponse"}]},"lastLedgerSeq":{"type":"string","description":"Highest ledger applied to this row (BigInt as string)."},"createdAt":{"type":"string","description":"Row creation timestamp (ISO 8601)."},"updatedAt":{"type":"string","description":"Last update timestamp (ISO 8601)."},"firstLedgerClosedAt":{"type":"object","nullable":true,"description":"Chain clock: close time of the first ledger whose state was projected (ISO 8601). Unlike createdAt (ingestion wall-clock), it survives replays and rebuilds. Null until a state carries it."},"lastLedgerClosedAt":{"type":"object","nullable":true,"description":"Chain clock: close time of the latest ledger applied to this row (ISO 8601). Null until a state carries it."},"snapshot":{"type":"object","nullable":true,"description":"Full contract state (camelCased for the wire; amounts in token units, platformFee as percent).","additionalProperties":true}},"required":["network","contractId","anomalies","balance","lastLedgerSeq","createdAt","updatedAt"]},"EscrowAssetResponse":{"type":"object","properties":{"name":{"type":"object","nullable":true,"description":"Asset code / SEP-41 symbol. Null while unresolved."},"address":{"type":"object","nullable":true,"description":"Issuer account (G...) of the wrapped classic asset. Null for pure Soroban tokens or while unresolved."},"contractId":{"type":"object","nullable":true,"description":"Soroban token contract (C...) from the escrow trustline."},"decimals":{"type":"number","description":"Decimals every amount in this payload was scaled with. Falls back to 7 (Stellar classic) while the token metadata is unresolved ā check `resolved`."},"resolved":{"type":"boolean","description":"False while the token metadata is unresolved: `decimals` is then the 7-decimal fallback, so amounts of a custom token may be scaled wrong until the cache self-heals. Re-scale client-side or hold rendering while false."}},"required":["decimals","resolved"]},"EscrowDepositResponse":{"type":"object","properties":{"fromAddress":{"type":"string","description":"Sender wallet (G...)."},"assetInfo":{"nullable":true,"description":"The deposited asset, resolved (same shape as the escrow-root `asset` object; `contractId` is the emitting token contract of the SAC transfer). Null only when the raw asset id is unusable.","type":"object","allOf":[{"$ref":"#/components/schemas/EscrowAssetResponse"}]},"amount":{"type":"string","description":"Amount in token units (decimal string)."},"txHash":{"type":"object","nullable":true,"description":"Transaction hash."},"ledgerSeq":{"type":"string","description":"Ledger sequence (BigInt as string)."},"ledgerClosedAt":{"type":"string","description":"Ledger close time (ISO 8601)."}},"required":["fromAddress","amount","ledgerSeq","ledgerClosedAt"]},"ProblemDetailsResponseDto":{"type":"object","properties":{"type":{"type":"string","description":"Stable URI identifying the error type. Hash-link points to the docs."},"title":{"type":"string","description":"Short human-readable summary of the problem."},"status":{"type":"number","description":"HTTP status code, repeated here for typed clients."},"code":{"type":"string","description":"Machine-readable error code. Stable across versions; safe to switch on."},"detail":{"type":"string","description":"Human-readable explanation specific to this occurrence."},"instance":{"type":"string","description":"URI of the request that triggered the error."},"traceId":{"type":"string","description":"Correlation id propagated from the `X-Trace-Id` header (or generated). Use it when contacting support to reference a specific request."},"extensions":{"type":"object","description":"Optional structured context. Shape depends on the error code; documented per-endpoint when relevant.","additionalProperties":true}},"required":["type","title","status","code","detail"]}}}}
```
## GET /escrows/details
Returns the full state and deposits of up to 50 escrows in one request. No event timeline ā use `GET /escrows/{contractId}/events` for that.
### Query parameters
| Name | Type | Description |
| ----------- | ---------------- | --------------------------------------------------------------------- |
| contractIds | string\[] (1ā50) | Contract addresses (`Cā¦`) to fetch. Repeat the parameter once per id. |
{% hint style="warning" %}
Unknown ids are **silently absent** from the response rather than raising an error. Always check which ids came back before assuming an escrow exists.
{% endhint %}
### **What this Endpoint returns?**
An array of escrow objects, each containing the current state, the camelCase `snapshot`, the resolved `asset`, and the recorded `deposits`. Every amount is a decimal string.
Because the request itself is bounded at 50 ids, this endpoint is **not paginated**.
### Use Example:
```typescript
import axios from "axios";
const http = axios.create({
baseURL: "https://beta.api.trustlesswork.com",
timeout: 10000,
headers: {
"Content-Type": "application/json",
"x-api-key": your_api_key,
},
});
export const useExample = async () => {
const contractIds = [
"CCR6HLU3LQMXOESNA6TOS2RZKGEBWQG3EN5FMZNC43RVXZWTTDCZ...",
"CCA7WTCVCQ5JPKNIFSHPSJLJ3FJ3GKPNEVAIHP6T..."
];
const params = new URLSearchParams();
contractIds.forEach(id => params.append("contractIds", id));
const response = await http.get(`/escrows/details?${params.toString()}`);
return response.data;
}
```
{% hint style="info" %}
The old endpoint took a `validateOnChain` flag to re-check data against the chain. There is no equivalent here: escrow state is recorded from on-chain events automatically, so there is nothing to reconcile. When you need chain-authoritative truth, read the chain.
{% endhint %}
---
# 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/escrow-information/get-escrow-by-contract-ids.md?ask=&goal=
```
`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.