GuardSettlement

Settle a guard

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

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)

Path parameters

guardIdstring required

Request body

foreignAmountnumber required
foreignCurrencystring required
guardCurrencystring required
conversionRatenumber required
clientConversionAmountnumber required

What this tranche would cost the client at their own all-in rate. Required on every settlement.

customerIdstring uuid

Response

Guard settlement created

idstring

Reference for this settlement, appended to the Guard generation it settled.

regulatedEntityIdstring uuid

ID of the regulated entity associated with this guard

introducingBrokerIdstring uuid

ID of the introducing broker for this guard settlement (denormalized from guard)

regulatedUserIdstring uuid

ID of the regulated user who booked this guard settlement

salesUserIdstring uuid

ID of the sales user who sold this guard

companyIdstring uuid

ID of the company associated with this payment

customerIdstring uuid

ID of the customer who owns this guard

settlementDatestring

Settlement date of this guard settlement, when the FX conversion occurs

paymentDatestring

Payment date, calculated as settlement_date + 2 business days. The date when funds are actually transferred

guardPeriodFromstring

Start period date of this guard, also the purchase date

guardFeeDatestring

Guard fee payment date, calculated as guard_period_from + 2 business days. Corresponds to the premium payment date on the back-to-back hedge.

settlementWindowFromstring

Start settlement window of this guard, typically two weeks due date of the final payment

settlementWindowTostring

End settlement window of this guard, typically the due date of the final payment

guardPeriodTostring

End period date of this guard, typically one day after the due date of the final payment

guardPeriodToValueDatestring

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

batchIdstring

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

guardCurrencystring

Guard currency, the currency in which the cost or receivable is being protected.

foreignCurrencystring

Foreign currency of the settlement, matches the invoice or bill currency

foreignAmountnumber

Foreign amount the customer paid or received in the foreign currency for this settlement

guardRatenumber

Guard rate from the original guard contract

guardAmountnumber

Protected amount in guard currency - what the customer is guaranteed to receive/pay at the guard rate (foreign_amount ÷ guard_rate)

deliveredAmountnumber

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.

deliveredCurrencystring

Currency of delivered_amount. Guard-Pay: foreign currency. Guard-Receive: guard currency.

shortfallAmountnumber

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.

shortfallCurrencystring

Currency of the shortfall amount. Guard-Receive: guard currency. Guard-Pay: foreign currency.

savingsRebateAmountnumber

Savings-zone rebate owed to the client on a funded settlement, in the funding currency

savingsRebateCurrencystring

Currency of the savings rebate

spotFxBidnumber

Spot FX bid rate at the time of settlement

spotFxAsknumber

Spot FX ask rate at the time of settlement

conversionRatenumber

Actual market FX rate at settlement time used for the conversion

conversionAmountnumber

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.

executedConversionRatenumber

The rate CGL actually converted at with the regulated entity at execution, versus conversion_rate which is the mid.

conversionProceedsnumber

Proceeds CGL received from the execution conversion, in the bought currency.

reFxMarginAmountnumber

The regulated entity's FX margin earned on CGL's execution conversion, in guard currency. Feeds the month-end true-up.

declaredMarginPctnumber

Client payment margin declared at settlement, as a decimal (0.016 = 1.6%)

trueUpAmountnumber

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.

refundAmountnumber

Refund amount returned to client for guard cancellation in guard currency. Only populated for cancellation settlements.

refundCalculationGuardSettlementDTORefundCalculation

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.

salesMarginAmountnumber

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.

totalForeignAmountSettlednumber

Total foreign amount settled on the guard BEFORE this settlement (cumulative from previous settlements)

totalGuardAmountSettlednumber

Total guard amount settled on the guard BEFORE this settlement (cumulative from previous settlements)

guardIdstring

ID of the guard associated with this payment

originalGuardIdstring

ID of the original guard at the start of the lifecycle. Remains constant through extensions and other lifecycle changes.

versionNumberinteger

Strictly monotonically increasing version number for this record

updatedBystring

Username of the person or entity that updated this record

updatedAtstring

Timestamp of the last update in UTC

createdAtstring

Timestamp of creation in UTC

creditorReferencestring

RF creditor reference to quote when funding this settlement

fundingCurrencystring

Currency the client sends to fund this settlement

fundingAmountnumber

Amount the client sends to fund this settlement

Example response

{
  "id": "GSP1000104-E01-S02",
  "regulatedEntityId": "9e107d9d-372d-4add-ae2d-f3d1d41fd1d7",
  "introducingBrokerId": "eeeeeeee-ee55-4001-8000-000000000000",
  "regulatedUserId": "9e107d9d-372d-4add-ae2d-f3d1d41fd1d7",
  "salesUserId": "9e107d9d-372d-4add-ae2d-f3d1d41fd1d7",
  "customerId": "9e107d9d-372d-4add-ae2d-f3d1d41fd1d7",
  "settlementDate": "2024-04-09",
  "paymentDate": "2024-04-11",
  "guardPeriodFrom": "2024-01-16",
  "guardFeeDate": "2024-01-18",
  "settlementWindowFrom": "2024-01-16",
  "settlementWindowTo": "2024-04-15",
  "guardPeriodTo": "2024-04-15",
  "guardPeriodToValueDate": "2024-04-17",
  "guardSettlementStatus": "SETTLEMENT_EXECUTED",
  "batchId": "BSP0000042",
  "payReceive": "PAY",
  "guardCurrency": "GBP",
  "foreignCurrency": "EUR",
  "foreignAmount": 75000,
  "guardRate": 1.1405,
  "guardAmount": 65760.63,
  "deliveredAmount": 100000,
  "deliveredCurrency": "GBP",
  "shortfallAmount": 2147.4,
  "shortfallCurrency": "GBP",
  "savingsRebateAmount": 1660.12,
  "savingsRebateCurrency": "USD",
  "spotFxBid": 1.17895,
  "spotFxAsk": 1.17905,
  "conversionRate": 1.179,
  "conversionAmount": 139055,
  "executedConversionRate": 1.3670475,
  "conversionProceeds": 99491.79,
  "reFxMarginAmount": 203.76,
  "declaredMarginPct": 0.016,
  "trueUpAmount": 685,
  "settlementZone": "PROTECTION",
  "refundAmount": 334,
  "salesMarginAmount": 0.0025,
  "totalForeignAmountSettled": 20000,
  "totalGuardAmountSettled": 15243.9,
  "guardId": "1b6453892-e5e1-4fad-9e9b-4fa4e60f6c2b",
  "originalGuardId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "versionNumber": 1,
  "updatedBy": "jbloggs24",
  "updatedAt": "2024-10-18T12:30:40Z",
  "createdAt": "2024-10-18T12:30:40Z",
  "creditorReference": "RF13GIX0000001S01",
  "fundingCurrency": "USD",
  "fundingAmount": 20000
}

Changes

No recorded changes to this operation across all 1 revision of this API.