List Escrows

List escrows with filters and keyset pagination via GET /escrows.

Headers

Name	Value
Content-Type	application/json
x-api-key	<token>

Open API

GET /escrows

The main listing endpoint. Returns escrows the caller can see, filtered and keyset-paginated.

Scope

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

Filters

All filters are AND-combined.

Name	Type	Description
status	string	Lifecycle status (exact match)
contractType	string	Contract flavor (exact match)
engagementId	string	Your own correlation id (exact match)
contractIds	string[]	Only these addresses. Repeat the param
participant	string	Wallet (G…) that is an on-chain participant
role	string	Combined with participant: "wallet X acting as role Y"
platformId	string	Escrows attributed to this platform (tenant-scoped)
subjectId	string	Escrows attributed to this subject (tenant-scoped)
createdAfter / createdBefore	ISO 8601	Creation window
includeSnapshot	boolean	false drops the heavy snapshot field

Pagination

Name	Type	Description
limit	number	1–200, default 50
cursor	string	From the previous page's nextCursor
sort	createdAt | updatedAt	Default updatedAt
order	asc | desc	Default desc

What this Endpoint returns?

Always the paginated envelope — never a bare array:

{ "data": [ /* escrow summaries */ ], "hasMore": true, "nextCursor": "eyJ..." }

Keep sort and order identical across pages, or the cursor is rejected with INVALID_CURSOR.

Use Example:

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 params = new URLSearchParams({
    scope: "mine",
    limit: "20",
    sort: "updatedAt",
    order: "desc",
  });

  const { data } = await http.get(`/escrows?${params.toString()}`);
  return data; // { data, hasMore, nextCursor }
}

Paging through everything

export const listAll = async () => {
  const all = [];
  let cursor = null;

  do {
    const params = new URLSearchParams({ limit: "100" });
    if (cursor) params.append("cursor", cursor);

    const { data } = await http.get(`/escrows?${params.toString()}`);
    all.push(...data.data);
    cursor = data.hasMore ? data.nextCursor : null;
  } while (cursor);

  return all;
}

Filtering by a platformId or subjectId you do not own returns 403 ESCROW_FILTER_FORBIDDEN. Filtering by participant has no such restriction — on-chain participation is public.

These reads come from the read-model, which is eventually consistent. Right after submitting a transaction a 404 usually means "not projected yet", not "does not exist" — poll briefly instead of treating it as an error.