---
title: "Settle a guard"
method: POST
path: "/api-regulated/v1/guards/{guardId}/settle-guard"
tags: ["GuardSettlement"]
---

# Settle a guard

`POST /api-regulated/v1/guards/{guardId}/settle-guard`

## Request

- Base URL: `https://api.currencyguard.com`
- URL: `https://api.currencyguard.com/api-regulated/v1/guards/{guardId}/settle-guard`
- Auth: OAuth 2 (implicit, authorization URL `https://auth.currencyguard.com/oauth2/authorize`, scopes: `regulated.risk-management.canSettleGuard`)

Initiates guard settlement for a regulated entity.

**Required entitlement:** `regulated.risk-management.canSettleGuard`  
_Entitles the regulated user to settle existing guard positions for their customers_

## Path parameters

- `guardId` string, required

## Request body

- SettleGuardRequestDTO
  - `foreignAmount` number, required
  - `foreignCurrency` string, required
  - `guardCurrency` string, required
  - `conversionRate` number, required
  - `clientConversionAmount` number, required: What this tranche would cost the client at their own all-in rate. Required on every settlement.
  - `customerId` string, uuid

## Response `201`

Guard settlement created

- GuardSettlementDTO: Schema for representing a GuardSettlement
  - `id` string: Reference for this settlement, appended to the Guard generation it settled.
  - `regulatedEntityId` string, uuid: ID of the regulated entity associated with this guard
  - `introducingBrokerId` string, uuid: ID of the introducing broker for this guard settlement (denormalized from guard)
  - `regulatedUserId` string, uuid: ID of the regulated user who booked this guard settlement
  - `salesUserId` string, uuid: ID of the sales user who sold this guard
  - `companyId` string, uuid: ID of the company associated with this payment
  - `customerId` string, uuid: ID of the customer who owns this guard
  - `settlementDate` string: Settlement date of this guard settlement, when the FX conversion occurs
  - `paymentDate` string: Payment date, calculated as settlement_date + 2 business days. The date when funds are actually transferred
  - `guardPeriodFrom` string: Start period date of this guard, also the purchase date
  - `guardFeeDate` string: Guard fee payment date, calculated as guard_period_from + 2 business days. Corresponds to the premium payment date on the back-to-back hedge.
  - `settlementWindowFrom` string: Start settlement window of this guard, typically two weeks due date of the final payment
  - `settlementWindowTo` string: End settlement window of this guard, typically the due date of the final payment
  - `guardPeriodTo` string: End period date of this guard, typically one day after the due date of the final payment
  - `guardPeriodToValueDate` string: Settlement date of the guard, calculated as guard_period_to + 2 business days. Must match the settlement date on the back-to-back hedge.
  - `guardSettlementStatus` 'AWAITING_FUNDING' | 'EXECUTION_PENDING' | 'FUNDING_LAPSED' | 'FUNDING_CANCELLED' | 'SETTLEMENT_PENDING' | 'SETTLEMENT_EXECUTED' | 'SETTLEMENT_REJECTED' | 'EXTENSION_PENDING' | 'EXTENSION_EXECUTED' | 'CANCELLATION_PENDING' | 'CANCELLATION_EXECUTED' | 'VOID_EXECUTED': Status of this settlement
  - `batchId` string: Settlement batch this row was requested as part of, if any
  - `payReceive` 'PAY' | 'RECEIVE': Indicates whether the settlement is for the payment or receipt of foreign currency
  - `guardCurrency` string: Guard currency, the currency in which the cost or receivable is being protected.
  - `foreignCurrency` string: Foreign currency of the settlement, matches the invoice or bill currency
  - `foreignAmount` number: Foreign amount the customer paid or received in the foreign currency for this settlement
  - `guardRate` number: Guard rate from the original guard contract
  - `guardAmount` number: Protected amount in guard currency - what the customer is guaranteed to receive/pay at the guard rate (foreign_amount ÷ guard_rate)
  - `deliveredAmount` number: Amount CGL delivers to the client at settlement, in delivered_currency. Pay: the invoice in foreign currency. Receive: the floor or the all-in in guard currency.
  - `deliveredCurrency` string: Currency of delivered_amount. Guard-Pay: foreign currency. Guard-Receive: guard currency.
  - `shortfallAmount` number: Amount the guard pays out when market moves unfavorably. For Guard-Receive: in guard currency (guard_amount - conversion_amount). For Guard-Pay: in foreign currency (foreign_amount × (guard_rate - conversion_rate) / guard_rate). Zero or positive when guard provides protection.
  - `shortfallCurrency` string: Currency of the shortfall amount. Guard-Receive: guard currency. Guard-Pay: foreign currency.
  - `savingsRebateAmount` number: Savings-zone rebate owed to the client on a funded settlement, in the funding currency
  - `savingsRebateCurrency` string: Currency of the savings rebate
  - `spotFxBid` number: Spot FX bid rate at the time of settlement
  - `spotFxAsk` number: Spot FX ask rate at the time of settlement
  - `conversionRate` number: Actual market FX rate at settlement time used for the conversion
  - `conversionAmount` number: What the tranche costs/yields the client at their own all-in rate (mid plus the declared payment margin). Above the guard amount means the Guard is protecting.
  - `executedConversionRate` number: The rate CGL actually converted at with the regulated entity at execution, versus conversion_rate which is the mid.
  - `conversionProceeds` number: Proceeds CGL received from the execution conversion, in the bought currency.
  - `reFxMarginAmount` number: The regulated entity's FX margin earned on CGL's execution conversion, in guard currency. Feeds the month-end true-up.
  - `declaredMarginPct` number: Client payment margin declared at settlement, as a decimal (0.016 = 1.6%)
  - `trueUpAmount` number: Signed CGL/RE margin true-up in the guard currency. Positive means the regulated entity owes CurrencyGuard; negative means CurrencyGuard owes the regulated entity.
  - `settlementZone` 'PROTECTION' | 'SAVINGS' | 'NOT_APPLICABLE' | 'UNKNOWN': Whether the Guard paid out on this tranche. PROTECTION: the client's own cost is above the cap, CGL funds the shortfall. SAVINGS: it is below, the client settles at market and CGL is not involved. NOT_APPLICABLE: a cancellation or void, where nothing was converted.
  - `refundAmount` number: Refund amount returned to client for guard cancellation in guard currency. Only populated for cancellation settlements.
  - `refundCalculation` GuardSettlementDTORefundCalculation: **Extensible JSONB field** - Full refund calculation including schedule config and per-component breakdown, snapshotted at the time of cancellation. Only populated for cancellation settlements. This field accepts any valid JSON structure and can be extended with additional properties as needed. Note: While the structure is extensible, known fields shown in the example are subject to application validation.
  - `salesMarginAmount` number: Sales margin amount applied to the conversion rate as a rate (e.g. 0.01 = 1%). Positive means sales took margin, negative means customer got better than market rate.
  - `totalForeignAmountSettled` number: Total foreign amount settled on the guard BEFORE this settlement (cumulative from previous settlements)
  - `totalGuardAmountSettled` number: Total guard amount settled on the guard BEFORE this settlement (cumulative from previous settlements)
  - `guardId` string: ID of the guard associated with this payment
  - `originalGuardId` string: ID of the original guard at the start of the lifecycle. Remains constant through extensions and other lifecycle changes.
  - `versionNumber` integer: Strictly monotonically increasing version number for this record
  - `updatedBy` string: Username of the person or entity that updated this record
  - `updatedAt` string: Timestamp of the last update in UTC
  - `createdAt` string: Timestamp of creation in UTC
  - `creditorReference` string: RF creditor reference to quote when funding this settlement
  - `fundingCurrency` string: Currency the client sends to fund this settlement
  - `fundingAmount` number: Amount the client sends to fund this settlement

## Other responses

- `400`: Invalid request data — [`http/malformed-request`](/problems/http/malformed-request/)
- `401`: Not authenticated — [`security/authentication-failed`](/problems/security/authentication-failed/)
- `403`: Not authorized — [`security/insufficient-permissions`](/problems/security/insufficient-permissions/)
- `404`: Guard not found — [`http/resource-not-found`](/problems/http/resource-not-found/)
- `409`: Guard is not in a settleable status **Problem types returned by this endpoint** | Type | Meaning | |---|---| | [`guard/invalid-state-transition`](/problems/guard/invalid-state-transition/) | Operation cannot be performed in the current resource state |
- `422`: Settlement rejected by a business rule **Problem types returned by this endpoint** | Type | Meaning | |---|---| | [`guard-settlement/outside-settlement-window`](/problems/guard-settlement/outside-settlement-window/) | Settlement was attempted outside the Guard's permitted settlement (drawdown) window | | [`guard-settlement/settlement-exceeds-remaining`](/problems/guard-settlement/settlement-exceeds-remaining/) | The requested settlement amount is greater than the Guard's unsettled balance | | [`guard-settlement/residual-below-minimum`](/problems/guard-settlement/residual-below-minimum/) | The settlement would leave a residual balance below the permitted minimum; settle less, or settle in full | | [`guard/sales-margin-exceeded`](/problems/guard/sales-margin-exceeded/) | The sales margin on the request exceeds the maximum permitted for the applicable zone or refund | | [`guard-settlement/conversion-rate-crosses-guard-rate`](/problems/guard-settlement/conversion-rate-crosses-guard-rate/) | In the savings zone the conversion rate may not cross the guard rate, which would move the client from savings into protection | | [`guard-settlement/client-rate-required`](/problems/guard-settlement/client-rate-required/) | A Guard settlement requires a client conversion amount, so the RE can declare its own margin for this tranche | | [`guard-settlement/implied-margin-out-of-band`](/problems/guard-settlement/implied-margin-out-of-band/) | The supplied client conversion amount implies a payment margin outside the permitted band |
- `500`: Server error — [`server/internal-error`](/problems/server/internal-error/)

---

[API](https://skmtc.dev/currencyguard/apis/currencyguard-trading-system-api-external.md) · [All operations](https://skmtc.dev/currencyguard/apis/currencyguard-trading-system-api-external/llms.txt) · [OpenAPI document](https://skmtc.dev/currencyguard/apis/currencyguard-trading-system-api-external/revisions/a1f3f854190d?raw)