GraphQL

Read the same escrow data with field selection over a single POST endpoint.

The same escrow data available over REST is also queryable through a single GraphQL endpoint, with the same authentication, the same roles, and the same visibility rules.

GraphQL opens no door that REST does not. It exists to save round trips, not to expose more data.

Headers

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

Open API

POST /graphql

Always POST, always the same path — including for queries.

---

When to use it instead of REST

Use GraphQL when a screen needs several related things at once. Over REST, an escrow detail view with milestones, financials and recent events is four requests. In GraphQL it is one, returning only the fields you name.

Use REST when you want one specific thing, or when a simple cache layer matters more than round trips.

---

Queries

Query	Returns
escrows(filters…)	A paginated EscrowPage
escrow(contractId)	A single escrow
ping	Liveness check

The filter vocabulary matches GET /escrows exactly, and the page envelope is the same { data, hasMore, nextCursor }.

---

What this Endpoint returns?

A standard GraphQL envelope. Note the error behaviour:

GraphQL always returns HTTP 200, even on failure. Check body.errors before reading body.data. The extensions.code values are the same vocabulary as REST Problem Details.

{
  "data": { "escrow": { } },
  "errors": [
    { "message": "…", "extensions": { "code": "ESCROW_NOT_FOUND" } }
  ]
}

---

Limits

Guardrail	Value
Maximum query depth	8
Maximum complexity	1000 fields
Introspection	Disabled in production
Mutations	None — GraphQL is read-only. Every write stays on REST.

---

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,
  },
});

const GET_ESCROW = `
  query GetEscrow($contractId: String!) {
    escrow(contractId: $contractId) {
      contractId
      status
      balance
      asset { name decimals }
      financial {
        totalDeposited
        totalReleased
        pendingRelease
      }
      milestones {
        description
        status
        approvals { target approvalCount }
      }
      events(limit: 10) {
        type
        ledger
        txHash
      }
    }
  }
`;

export const useExample = async (contractId: string) => {
  const response = await http.post("/graphql", {
    query: GET_ESCROW,
    variables: { contractId },
  });

  // GraphQL reports failures in the body, not the HTTP status.
  if (response.data.errors?.length) {
    throw new Error(response.data.errors[0].extensions?.code ?? "GRAPHQL_ERROR");
  }

  return response.data.data.escrow;
};

Listing with pagination

const LIST_ESCROWS = `
  query ListEscrows($participant: String, $limit: Int, $cursor: String) {
    escrows(participant: $participant, limit: $limit, cursor: $cursor) {
      data { contractId status balance updatedAt }
      hasMore
      nextCursor
    }
  }
`;

The same cursor rules as REST apply: keep the sort and order stable while paging.