Guard

Calculate a guard extension quote

Calculates the cost of extending the guard based on current rates and extension parameters, and provides it as a quote with a time-to-live.

Required entitlement: regulated.risk-management.canExtendGuard
Entitles the regulated user to extend guard position expiration dates for their customers

post/api-regulated/v1/guards/{guardId}/quote-guard-extension

Request

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

Path parameters

guardIdstring required

Request body

extendToDatestring required

New end date for the guard extension in ISO 8601 format

reasonstring

Reason for the guard extension

salesMarginRatenumber

Sales margin rate as a decimal (e.g. 0.007 = 0.7%). If only salesMarginRate is provided, salesMarginAmount is calculated. If only salesMarginAmount is provided, salesMarginRate is calculated. If both are provided, they must match within a tolerance of 0.01 or the request is rejected with 400 Bad Request. If neither provided, defaults to zero.

salesMarginAmountnumber

Sales margin amount in guard currency. If only salesMarginAmount is provided, salesMarginRate is calculated. If only salesMarginRate is provided, salesMarginAmount is calculated. If both are provided, they must match within a tolerance of 0.01 or the request is rejected with 400 Bad Request. If neither provided, defaults to zero.

customerIdstring

Customer ID (optional). If not provided, inherits customer from original guard. Allows changing customer during extension.

Example request

{
  "extendToDate": "2024-12-31T23:59:59Z",
  "reason": "Contract renewal",
  "salesMarginRate": 0.007,
  "salesMarginAmount": 350,
  "customerId": "123e4567-e89b-12d3-a456-426614174000"
}

Response

Guard extension quote calculated

validboolean required

Whether the price data is currently valid (true) or in an error/degraded state (false). When false, the value may still be present (stale/approximate data).

errorMessagesstring[]

List of error messages explaining why the state is invalid. Empty/null when valid=true. Can contain multiple accumulated errors from different sources.

valueTimestampstring required

ISO 8601 timestamp indicating when the underlying data was produced at the source (business time). This represents the data's original timestamp.

emissionTimestampstring required

ISO 8601 timestamp indicating when our system emitted this state (system/processing time). This represents when the wrapper was created.

subscriptionSourcestring

Market data subscription channel identifier. Used for debugging and monitoring data flows.

emissionSourcestring

Identifier of the market data provider or internal pricing engine that produced this data. Diagnostic detail for internal use only — omitted from responses to non-internal callers.

infoMessagesstring[]

Informational messages providing context about the price state (e.g., validation details, reference source checks). Do not affect validity. Diagnostic detail for internal use only — omitted from responses to non-internal callers.

Example response

{
  "valid": true,
  "errorMessages": [
    "Market data feed delayed by 30 seconds",
    "Volatility surface is stale"
  ],
  "valueTimestamp": "2024-03-01T14:30:15.123Z",
  "emissionTimestamp": "2024-03-01T14:30:16.456Z",
  "subscriptionSource": "DEFAULT",
  "value": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "regulatedEntityId": "9e107d9d-372d-4add-ae2d-f3d1d41fd1d7",
    "introducingBrokerId": "eeeeeeee-ee55-4001-8000-000000000000",
    "regulatedUserId": "9e107d9d-372d-4add-ae2d-f3d1d41fd1d7",
    "salesUserId": "9e107d9d-372d-4add-ae2d-f3d1d41fd1d7",
    "companyId": "9e107d9d-372d-4add-ae2d-f3d1d41fd1d7",
    "customerId": "9e107d9d-372d-4add-ae2d-f3d1d41fd1d7",
    "validationStatus": "VALID",
    "validationErrors": "FX vol surface exceeded TTL; Interest rate curve is stale",
    "quoteStatus": "OPEN",
    "marketStatus": "OPEN",
    "marketReason": "Trading hours",
    "previousGuardId": "GSP1000104",
    "externalRef": "BEN-90210",
    "invoiceExternalRef": "INV-2024-001",
    "guardPeriodFrom": "2024-01-16",
    "settlementWindowFrom": "2024-01-16",
    "settlementWindowTo": "2024-04-15",
    "guardPeriodTo": "2024-04-15",
    "guardCurrency": "GBP",
    "foreignCurrency": "USD",
    "currencyPair": "GBPUSD",
    "payReceive": "PAY",
    "foreignAmount": 50000,
    "guardRate": 1.312,
    "paymentMarginAtInception": 0.015,
    "midAtInception": 1.34,
    "quoteTimeToLiveInSeconds": 60,
    "guardAmount": 38109.75,
    "guardFee": 512,
    "effectiveRate": 1.2946,
    "payLaterCreditFee": 12,
    "guardMarginRate": 0.007,
    "guardMargin": 296.02,
    "volSpreadMultiplier": 2,
    "valuationStrike": 1.34,
    "valuationNotional": 101500,
    "salesMarginRate": 0.007,
    "salesMargin": 296.02,
    "quoteTimestamp": "2024-10-18T12:30:40Z",
    "spotBidPrice": 1.2345,
    "spotAskPrice": 1.2347,
    "historicVolatility": 0.1234,
    "riskIndex": 0.5678,
    "versionNumber": 1,
    "updatedBy": "jbloggs24",
    "updatedAt": "2024-10-18T12:30:40Z",
    "createdAt": "2024-10-18T12:30:40Z",
    "guardSettlementWindowTo": "2024-04-15T00:00:00Z",
    "targetGuardAmountToSeekNetFees": 60000,
    "salesMarginAmount": 296.02,
    "reason": "Invoice protection for Q1 2024",
    "requestedGuardAmount": 136010
  }
}

Changes

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