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

# Circle Wallets Power Retempo Settlement Execution

> Retempo uses Circle Developer-Controlled Wallets to submit Arc settlements. Learn what Circle provides and what the settlement response contains.

Retempo's production environment uses **Circle Developer-Controlled Wallets** to submit settlement transactions on the Arc blockchain. When you call `POST /api/v1/settlements`, Retempo's backend handles the full wallet operation — including signing and broadcasting the Arc transaction — through Circle's infrastructure. You interact only with the Retempo API and receive Circle transaction details alongside the Arc confirmation in the settlement response.

## What Circle does in Retempo

Circle provides the wallet layer that holds the authorized operator credentials used to call `recordSettlement()` on the RetempoSettlement contract. Retempo manages all Circle configuration internally: wallet provisioning, transaction signing, and state polling. You do not need a Circle account, a Circle API key, or any direct integration with Circle's platform to use Retempo.

From your perspective, the flow is straightforward: you submit a settlement to the Retempo API, and Retempo returns a confirmed Arc transaction hash once the onchain record is verified. Circle is the engine behind that confirmation, but it operates entirely within Retempo's infrastructure.

<Note>
  You do not need to interact with Circle directly. Retempo handles all wallet operations. The `circleTransactionId` is provided for your records only.
</Note>

## Circle fields in the settlement response

Every settlement response includes a `chain` object that surfaces both the Arc-level confirmation details and the Circle transaction details that produced them.

```json theme={null}
{
  "chain": {
    "transactionHash": "0xabc123...def456",
    "receiptStatus": "success",
    "eventObserved": true,
    "executor": "circle",
    "circleTransactionId": "ctxn_01j9k2m...",
    "circleTransactionState": "CONFIRMED"
  }
}
```

| Field                    | Type      | Description                                                                                                          |
| ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------- |
| `transactionHash`        | `string`  | The Arc transaction hash for the `recordSettlement()` call — use this to verify the settlement on the Arc explorer   |
| `receiptStatus`          | `string`  | Arc transaction receipt status: `"success"` means the transaction was mined without reverting                        |
| `eventObserved`          | `boolean` | `true` when Retempo confirmed the `SettlementRecorded` event is present in the Arc receipt                           |
| `executor`               | `string`  | The execution engine used to submit the transaction — `"circle"` when Circle Developer-Controlled Wallets are active |
| `circleTransactionId`    | `string`  | Circle's internal identifier for the wallet transaction                                                              |
| `circleTransactionState` | `string`  | The settlement state as reported by Circle at confirmation time                                                      |

<Tip>
  The `transactionHash` is the most useful field for independent verification. Take it to the Arc Testnet explorer to confirm the `SettlementRecorded` event and the settlement parameters onchain — no Circle access required.
</Tip>

## Settlement confirmation

Retempo applies a two-part confirmation gate before it marks a settlement **CONFIRMED** and the associated invoice **PAID**.

<Steps>
  <Step title="Arc receipt status must be 'success'">
    Retempo waits for the Arc transaction to be mined and inspects the receipt status. A status of `"reverted"` or a missing receipt means the settlement is **not** confirmed, regardless of what Circle reports.
  </Step>

  <Step title="SettlementRecorded event must be observed">
    Retempo scans the transaction receipt logs for a `SettlementRecorded` event emitted by the RetempoSettlement contract. If the event is absent, the settlement is **not** confirmed.
  </Step>
</Steps>

Both conditions must be true simultaneously. The `circleTransactionId` returned in the response is the Circle-side identifier for the transaction that produced the verified Arc receipt. Retempo cross-references the Circle transaction hash against the Arc RPC to ensure the two records agree before setting `eventObserved: true`.

<Warning>
  A settlement with `receiptStatus: "success"` but `eventObserved: false` indicates an unexpected contract state. Contact Retempo support with the `transactionHash` and `circleTransactionId` if you encounter this combination.
</Warning>