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

List escrows (paginated) — the caller’s by default

get

With scope=mine (the default) returns the escrows that concern the caller: participation via verified wallets and platform attribution. With scope=all returns every escrow on this network. Filter with status, type, engagementId, contractIds (batch), participant, role, platformId, subjectId; page with limit + opaque cursor (keyset). The platformId/subjectId filters are tenant-scoped: they require the caller to be (or own) that platform — 403 ESCROW_FILTER_FORBIDDEN otherwise.

Authorizations

x-api-keystringRequired

Query parameters

scopestring · enumOptional

Listing reach. mine (default) returns only the escrows that concern the caller: participation via their verified wallets and escrows attributed to their platform. all returns every escrow on this network (escrow state is public on-chain).

Default: minePossible values:

limitnumber · min: 1 · max: 200Optional

Page size. 1–200, defaults to 50.

Default: 50Example: 50

cursorstringOptional

Opaque cursor from the previous page’s nextCursor. Omit for page one.

includeSnapshotbooleanOptional

Set to false to receive rows WITHOUT the full contract snapshot (served as null) — a much lighter page when only the typed summary is needed. Defaults to true.

Default: true

sortstring · enumOptional

Sort column. Defaults to updatedAt.

Default: updatedAtPossible values:

orderstring · enumOptional

Sort direction. Defaults to desc.

Default: descPossible values:

createdAfterstring · date-timeOptional

Only escrows created at/after this time (ISO 8601).

Example: 2026-01-01T00:00:00.000Z

createdBeforestring · date-timeOptional

Only escrows created at/before this time (ISO 8601).

Example: 2026-12-31T23:59:59.000Z

statusstringOptional

Filter by lifecycle status (exact match).

Example: active

typestringOptional

Filter by detected contract flavor (exact match). Matches the type field of the response rows.

Example: single-release

engagementIdstringOptional

Filter by engagement id (exact match).

Example: ENG-2026-01

contractIdsstring[] · min: 1 · max: 50Optional

Only these on-chain contract addresses (repeat the param: contractIds=C…&contractIds=C…, 1–50). Batch lookup within the caller’s accessible set — inaccessible or unknown ids are silently absent from the page.

Example: ["CAAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQC526"]

participantstringOptional

Filter to escrows where this wallet (G…) is an on-chain participant — within the caller’s accessible set. Lets a platform segment its escrows by end-user.

Example: GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN

rolestringOptional

Filter to escrows with a participant acting in this role (e.g. approver, receiver, platform). Combined with participant, both must match the same participant — "escrows where wallet X is an approver".

Example: approver

platformIdstringOptional

Filter to escrows attributed to this platform. Tenant-scoped: the caller must be (or own) that platform — 403 ESCROW_FILTER_FORBIDDEN otherwise. Useful for an account that owns several platforms.

Example: 8c1d9a44-5f27-4f0b-9a3e-71b0c2d5e604

subjectIdstringOptional

Filter to escrows attributed to this subject (the platform’s end-user). Subject id from the Subjects API. Tenant-scoped like platformId: the subject must belong to a platform the caller is or owns — 403 ESCROW_FILTER_FORBIDDEN otherwise.

Example: b7c4e210-6d83-4a1f-8e55-9f2a0c3d4b18

Responses

200Success

application/json

hasMorebooleanRequired

Whether more results exist after nextCursor.

Example: true

nextCursorstring · nullableOptional

Cursor to fetch the next page, or null if this is the last.

400

Request body or query params fail schema validation (wrong type, missing required field, unknown property).

application/json

401

Missing, malformed, expired, revoked or invalid API key.

application/json

403

API key is valid but does not have the role required for this operation.

application/json

422

Payload is well-formed but a business rule rejects it (e.g. amount out of range, role not allowed for this user).

application/json

get/escrows

GET /escrows HTTP/1.1
Host: beta.api.trustlesswork.com
x-api-key: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "network": "testnet",
      "contractId": "text",
      "type": "text",
      "apiVersion": "v1",
      "status": "text",
      "anomalies": [],
      "amount": "250.5",
      "balance": "250.5",
      "asset": {
        "name": "USDC",
        "address": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
        "contractId": "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA",
        "decimals": 7,
        "resolved": true
      },
      "lastLedgerSeq": "5512345",
      "createdAt": "text",
      "updatedAt": "text",
      "firstLedgerClosedAt": "text",
      "lastLedgerClosedAt": "text",
      "snapshot": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "hasMore": true,
  "nextCursor": "text"
}

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.