> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trusset.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Settlement

> Read one settlement and the trades it covers

Returns a settlement with its trades, in any state. Unlike [List Pending Settlements](/endpoints/external-securities-trading/list-pending-settlements), this resolves confirmed and failed settlements too, which makes it the read for reconciliation and for explaining a failure after the fact.

Only settlements belonging to your instance resolve, and only ones whose trades sit on external securities books. Both the public `settlementId` and the internal row ID are accepted.

## Path Parameters

<ParamField path="settlementId" type="string" required>Settlement ID.</ParamField>

## Response Fields

<ResponseField name="data" type="object">
  <Expandable>
    <ResponseField name="id" type="string">Internal row ID.</ResponseField>
    <ResponseField name="settlementId" type="string">Public settlement ID.</ResponseField>
    <ResponseField name="instanceId" type="string">Instance that owns the book the settlement belongs to.</ResponseField>
    <ResponseField name="status" type="string">`PENDING`, `PROCESSING`, `CONFIRMED` or `FAILED`.</ResponseField>
    <ResponseField name="txHash" type="string">Settlement transaction, or `null`.</ResponseField>
    <ResponseField name="blockNumber" type="integer">Block the transaction landed in, or `null`.</ResponseField>
    <ResponseField name="gasUsed" type="string">Gas consumed, or `null`.</ResponseField>
    <ResponseField name="error" type="string">Why the settlement failed, or `null`.</ResponseField>
    <ResponseField name="settledAt" type="string">ISO 8601 timestamp of confirmation, or `null`.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601 timestamp.</ResponseField>
    <ResponseField name="updatedAt" type="string">ISO 8601 timestamp.</ResponseField>

    <ResponseField name="trades" type="array">
      Every trade the settlement covers, each with its own `settlementStatus` and `settlementError`.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  A `FAILED` settlement on this venue is terminal and already unwound: its trades were reversed and both sides' reservations released. There is nothing to retry, and the orders behind it are free to be signed again with a fresh salt.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.trusset.org/orderbooks/external-securities/api/settlements/0f7c2a19-64b8-4d02-9e51-73ab0c5d6f18" \
    -H "X-API-Key: trusset_your_key_here"
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(
    `https://api.trusset.org/orderbooks/external-securities/api/settlements/${settlementId}`,
    { headers: { 'X-API-Key': 'trusset_your_key_here' } }
  );
  const { data } = await res.json();
  console.log(data.status, data.txHash ?? data.error);
  ```
</RequestExample>

<ResponseExample>
  ```json Response - Confirmed theme={null}
  {
    "success": true,
    "data": {
      "id": "clx_settle_77",
      "settlementId": "0f7c2a19-64b8-4d02-9e51-73ab0c5d6f18",
      "instanceId": "inst_abc123",
      "status": "CONFIRMED",
      "txHash": "0x9f2c41d8b7e05a3164c2870fbd935e1a4c7802db6135ea9048f7c21b5d3ea41b",
      "blockNumber": 6412901,
      "gasUsed": "241880",
      "error": null,
      "settledAt": "2025-06-15T12:00:41.000Z",
      "createdAt": "2025-06-15T12:00:01.000Z",
      "updatedAt": "2025-06-15T12:00:41.000Z",
      "trades": [
        {
          "tradeId": "5b3c19e0-7a42-4d86-91f5-2c0e8d47b613",
          "price": "104200000",
          "quantity": "10000000",
          "settlementStatus": "CONFIRMED",
          "settlementError": null
        }
      ]
    }
  }
  ```

  ```json Response - Failed and Unwound theme={null}
  {
    "success": true,
    "data": {
      "settlementId": "3a17f0c8-52d9-41b6-8e04-9c7b25a1f0d3",
      "status": "FAILED",
      "txHash": null,
      "error": "A signed order in this settlement was cancelled on chain. The trade has been reversed and both reservations released.",
      "settledAt": null,
      "trades": [
        {
          "tradeId": "d92a4c11-6f38-4b70-a5e2-81c0f37d4b96",
          "settlementStatus": "FAILED",
          "settlementError": "A signed order in this settlement was cancelled on chain. The trade has been reversed and both reservations released."
        }
      ]
    }
  }
  ```
</ResponseExample>

## Error Codes

| Code                   | HTTP  | Cause                                                                                       |
| ---------------------- | ----- | ------------------------------------------------------------------------------------------- |
| `SETTLEMENT_NOT_FOUND` | `404` | No settlement with that ID on your instance, or it is not an external securities settlement |
| `SERVICE_NOT_ENABLED`  | `403` | The Trading service is not enabled on this instance                                         |