GuardQuote

Create a guard quote

Creates a new guard quote for the regulated entity and persists it to the database.

Required entitlement: regulated.risk-management.canBuyGuard
Entitles the regulated user to enter guard trades for their customers

post/api-regulated/v1/guard-quotes/quote-guard

Request

  • Base URL: https://api.currencyguard.com
  • URL: https://api.currencyguard.com/api-regulated/v1/guard-quotes/quote-guard
  • Auth: OAuth 2 (implicit, authorization URL https://auth.currencyguard.com/oauth2/authorize, scopes: regulated.risk-management.canBuyGuard)

Request body

introducingBrokerIdstring uuid required

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

salesUserIdstring uuid required

ID of the sales user on whose behalf this quote is being created. Must belong to an introducing broker within the regulated entity.

companyIdstring uuid required

ID of the company associated with this guard

customerIdstring uuid

ID of the customer who requested this quote

externalRefstring

External reference for the guard quote. Could be the beneficiary identifier or a foreign key in the PSP platform. Avoid using Personally Identifiable Information in this field.

invoiceExternalRefstring

External reference of the customer invoice this guard quote protects. Carried onto the guard when the quote is purchased. Avoid using Personally Identifiable Information in this field.

guardCurrencystring required

The Guard currency is the currency in which the cost or receivable is being protected typically the corporate base currency

foreignCurrencystring required

Foreign currency of this guard, matching the invoice or bill currency

currencyPairstring

The traded currency pair this guard is booked on, in CurrencyPair convention. The guard currency may be either leg of this pair.

payReceive'PAY' | 'RECEIVE' required

Indicates whether the guard will pay or receive foreign currency

foreignAmountnumber

Amount of the guard in the foreign currency

paymentMarginAtInceptionnumber

Client payment margin inside the guard rate, as a decimal (0.015 = 1.5%). 0 = the guard rate is CGL's mid.

midAtInceptionnumber required

The market mid the caller observed and priced against. Checked against CurrencyGuard's own feed; a mid outside tolerance is refused.

salesMarginRatenumber

Sales margin rate as a decimal (e.g. 0.007 = 0.7%). If only salesMarginRate is provided, salesMargin amount is calculated. If only salesMargin 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.

guardSettlementWindowTostring required

End settlement window of this guard in ISO 8601 format, typically the due date of the final payment

targetGuardAmountToSeekNetFeesnumber

Amount of the guard in the guard currency to seek for net of fees

salesMarginAmountnumber

Sales margin amount incorporated into the guard fee and expressed in guard currency

reasonstring

Reason for the guard quote request

payLaterboolean

Flag indicating whether fees should be paid later. Defaults to false if not specified.

requestedGuardAmountnumber

The funding requirement in the guard currency: the cap (Guard-Pay) or floor (Guard-Receive) the client is protected to, before fees. This is the client's own all-in price for the invoice, so the payment margin and the guard rate are DERIVED from it rather than sent -- amounts are exact to the cent, rates are 5dp roundings. Absent: CGL prices off its own mid with no payment margin, which is the pre-client-rate behaviour.

Example request

{
  "introducingBrokerId": "eeeeeeee-ee55-4001-8000-000000000000",
  "salesUserId": "9e107d9d-372d-4add-ae2d-f3d1d41fd1d7",
  "companyId": "9e107d9d-372d-4add-ae2d-f3d1d41fd1d7",
  "customerId": "9e107d9d-372d-4add-ae2d-f3d1d41fd1d7",
  "externalRef": "BEN-90210",
  "invoiceExternalRef": "INV-2024-001",
  "guardCurrency": "GBP",
  "foreignCurrency": "USD",
  "currencyPair": "GBPUSD",
  "payReceive": "PAY",
  "foreignAmount": 50000,
  "paymentMarginAtInception": 0.015,
  "midAtInception": 1.34,
  "salesMarginRate": 0.007,
  "guardSettlementWindowTo": "2024-04-15T00:00:00Z",
  "targetGuardAmountToSeekNetFees": 60000,
  "salesMarginAmount": 296.02,
  "reason": "Invoice protection for Q1 2024",
  "requestedGuardAmount": 136010
}

Response

Guard quote created

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.