> 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/escrows/graphql.md).

# GraphQL

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.

{% hint style="info" %}
GraphQL opens no door that REST does not. It exists to save round trips, not to expose more data.
{% endhint %}

### **Headers**

<table><thead><tr><th width="366">Name</th><th>Value</th></tr></thead><tbody><tr><td>Content-Type</td><td><code>application/json</code></td></tr><tr><td>x-api-key</td><td><code>&#x3C;token></code></td></tr></tbody></table>

### 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:

{% hint style="danger" %}
**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.
{% endhint %}

```json
{
  "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:

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

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

```typescript
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.


---

# 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/escrows/graphql.md?ask=<question>&goal=<endgoal>
```

`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.