---
title: "Create a guard quote"
method: POST
path: "/api-regulated/v1/guard-quotes/quote-guard"
tags: ["GuardQuote"]
---

# Create a guard quote

`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`)

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_

## Request body

- RegulatedGuardQuoteDTO: Schema for representing a GuardQuote
  - `introducingBrokerId` string, uuid, required: ID of the introducing broker for this guard quote (denormalized from company)
  - `salesUserId` string, 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.
  - `companyId` string, uuid, required: ID of the company associated with this guard
  - `customerId` string, uuid: ID of the customer who requested this quote
  - `externalRef` string: 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.
  - `invoiceExternalRef` string: 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.
  - `guardCurrency` string, required: The Guard currency is the currency in which the cost or receivable is being protected typically the corporate base currency
  - `foreignCurrency` string, required: Foreign currency of this guard, matching the invoice or bill currency
  - `currencyPair` string: 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
  - `foreignAmount` number: Amount of the guard in the foreign currency
  - `paymentMarginAtInception` number: Client payment margin inside the guard rate, as a decimal (0.015 = 1.5%). 0 = the guard rate is CGL's mid.
  - `midAtInception` number, required: The market mid the caller observed and priced against. Checked against CurrencyGuard's own feed; a mid outside tolerance is refused.
  - `salesMarginRate` number: 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.
  - `guardSettlementWindowTo` string, required: End settlement window of this guard in ISO 8601 format, typically the due date of the final payment
  - `targetGuardAmountToSeekNetFees` number: Amount of the guard in the guard currency to seek for net of fees
  - `salesMarginAmount` number: Sales margin amount incorporated into the guard fee and expressed in guard currency
  - `reason` string: Reason for the guard quote request
  - `payLater` boolean: Flag indicating whether fees should be paid later. Defaults to false if not specified.
  - `requestedGuardAmount` number: 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.

## Response `201`

Guard quote created

- GuardQuoteStateDTO: Container for guard quote data with state information. The 'value' field contains quote details and can be present even when valid=false (stale/approximate data).
  - `valid` boolean, 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).
  - `errorMessages` string[]: List of error messages explaining why the state is invalid. Empty/null when valid=true. Can contain multiple accumulated errors from different sources.
  - `valueTimestamp` string, required: ISO 8601 timestamp indicating when the underlying data was produced at the source (business time). This represents the data's original timestamp.
  - `emissionTimestamp` string, required: ISO 8601 timestamp indicating when our system emitted this state (system/processing time). This represents when the wrapper was created.
  - `subscriptionSource` string: Market data subscription channel identifier. Used for debugging and monitoring data flows.
  - `emissionSource` string: 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.
  - `infoMessages` string[]: 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.
  - `value` InternalGuardQuoteDTO: Schema for representing a GuardQuote
    - `id` string, uuid: ID for this guard quote
    - `regulatedEntityId` string, uuid: ID of the regulated entity associated with this guard
    - `introducingBrokerId` string, uuid: ID of the introducing broker for this guard quote (denormalized from company)
    - `regulatedUserId` string, uuid: ID of the regulated user who created this quote
    - `salesUserId` string, uuid: ID of the sales user on whose behalf this quote is being created. Must belong to an introducing broker within the regulated entity.
    - `companyId` string, uuid, required: ID of the company associated with this guard
    - `customerId` string, uuid: ID of the customer who requested this quote
    - `validationStatus` 'VALID' | 'ERROR': Validation status of the market data used to price this quote
    - `validationErrors` string: Validation error messages if market data was stale or invalid when quote was priced. Semicolon-separated list of errors.
    - `quoteStatus` 'OPEN' | 'TRADED': Lifecycle status of the quote
    - `marketStatus` 'OPEN' | 'CLOSED': Market status at the time the quote was generated
    - `marketReason` string: Reason for the market status at the time the quote was generated
    - `previousGuardId` string: Id of the Guard being extended by this quote
    - `externalRef` string: 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.
    - `invoiceExternalRef` string: 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.
    - `guardPeriodFrom` string: Start period date of this guard, also the purchase date
    - `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
    - `guardCurrency` string, required: The Guard currency is the currency in which the cost or receivable is being protected typically the corporate base currency
    - `foreignCurrency` string, required: Foreign currency of this guard, matching the invoice or bill currency
    - `currencyPair` string: 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
    - `foreignAmount` number: Amount of the guard in the foreign currency
    - `guardRate` number: Guard rate of exchange
    - `paymentMarginAtInception` number: Client payment margin inside the guard rate, as a decimal (0.015 = 1.5%). 0 = the guard rate is CGL's mid.
    - `midAtInception` number, required: The market mid the caller observed and priced against. Checked against CurrencyGuard's own feed; a mid outside tolerance is refused.
    - `quoteTimeToLiveInSeconds` integer: Time to live for the quote in seconds
    - `guardAmount` number: GuardQuote amount in the guard currency, derived from the foreign amount and guard rate
    - `guardFee` number: Fee paid for the guard in the guard currency
    - `effectiveRate` number: Net rate to client after costs
    - `payLaterCreditFee` number: Pay later Credit Fee paid for the guard in the guard currency. This fee is calculated when payLater=true is specified in the quote request, otherwise defaults to 0.00
    - `guardMarginRate` number: GuardQuote margin rate as a percentage
    - `guardMargin` number: GuardQuote margin amount incorporated into the guard fee and expressed in guard currency
    - `volSpreadMultiplier` number: Vol spread multiplier applied to the market vol bid/ask when this quote was priced. 1.0 = unadjusted market spread.
    - `valuationStrike` number: Valuation rate this quote was priced against: the mid rounded to 0.0005 in CGL's favour
    - `valuationNotional` number: Valuation notional in the foreign currency: guard amount divided by the valuation rate
    - `salesMarginRate` number: 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.
    - `salesMargin` number: Sales margin amount incorporated into the guard fee and expressed in guard currency. If only salesMargin is provided, salesMarginRate is calculated. If only salesMarginRate is provided, salesMargin amount is calculated. If both are provided, they must match within a tolerance of 0.01 or the request is rejected with 400 Bad Request.
    - `priceExplain` string: Price explain for this guard - this is used for internal testing only and will be removed from the API in future releases.
    - `quoteTimestamp` string: Timestamp when the quote was generated
    - `spotBidPrice` number: Spot bid price for FX at time of quote
    - `spotAskPrice` number: Spot ask price for FX at time of quote
    - `historicVolatility` number: Historic volatility used in pricing calculation
    - `riskIndex` number: Risk index calculated for this quote
    - `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
    - `guardSettlementWindowTo` string, required: End settlement window of this guard in ISO 8601 format, typically the due date of the final payment
    - `targetGuardAmountToSeekNetFees` number: Amount of the guard in the guard currency to seek for net of fees
    - `salesMarginAmount` number: Sales margin amount incorporated into the guard fee and expressed in guard currency
    - `reason` string: Reason for the guard quote request
    - `payLater` boolean: Flag indicating whether fees should be paid later. Defaults to false if not specified.
    - `requestedGuardAmount` number: 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.

## 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/)
- `422`: Quote rejected by a business rule **Problem types returned by this endpoint** | Type | Meaning | |---|---| | [`guard/supplied-mid-off-market`](/problems/guard/supplied-mid-off-market/) | The supplied market mid deviates from CurrencyGuard's mid by more than the configured tolerance | | [`guard/pair-not-configured`](/problems/guard/pair-not-configured/) | The currency pair lacks configuration required to price or validate the request | | [`guard/guard-duration-out-of-range`](/problems/guard/guard-duration-out-of-range/) | The requested Guard duration is outside the permitted minimum and maximum tenor | | [`guard/sales-margin-mismatch`](/problems/guard/sales-margin-mismatch/) | A sales margin rate and a sales margin amount were both supplied and they do not agree within tolerance |
- `500`: Server error — [`server/internal-error`](/problems/server/internal-error/)
- `503`: Market data required to price the quote is not currently available. Retryable; nothing about the request needs to change. **Problem types returned by this endpoint** | Type | Meaning | |---|---| | [`market-data/market-data-unavailable`](/problems/market-data/market-data-unavailable/) | The market data required to price or book the request is not currently available |

---

[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)