> For the complete documentation index, see [llms.txt](https://docs.nexusglobalpayments.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexusglobalpayments.org/apis/quotes.md).

# Quotes

## FX Quote Retrieval & Selection

> Source PSP retrieves FX quotes from Nexus for a given corridor and amount. Includes improved rates for PSP, improved rates for the amount, and checks Maximum Source and Destination IPS amounts for the currencies. Service used when Source PSP uses third-party FXP.

```json
{"openapi":"3.1.0","info":{"title":"Nexus API","version":"v1"},"tags":[{"name":"Quotes","description":"FX quotes for a corridor and amount."}],"servers":[{"url":"http://localhost:8080","description":"Local simulator (make run / make docker-run)"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Deployed simulator (Cloud Run, asia-southeast1) - indicative, not authoritative"}],"security":[{"nexusOAuth":["quotes.read"]}],"components":{"securitySchemes":{"nexusOAuth":{"type":"oauth2","description":"OAuth2 client credentials token issued per participant.","flows":{"clientCredentials":{"tokenUrl":"https://auth.nexus.net/realms/nexus/protocol/openid-connect/token","scopes":{"countries.read":"Read country and currency reference data","address.read":"Read address types and input definitions","institutions.read":"Read the financial institution directory","quotes.read":"Retrieve FX quotes for a corridor and amount","quote.read":"Compute fees and settlement amounts from a PSP supplied rate","fees.read":"Retrieve the Destination Agent fee formula","payment.process":"Submit and receive ISO 20022 payment messages","admin.downtime.notify":"Submit admi.004 downtime notifications for a Direct Participant IPS","fxp.payment.read":"Query the FXP's own completed payments","rates.read":"Read FXP rate records.","rates.write":"Create or withdraw FXP rate records.","tiers.read":"Read FXP tier records.","tiers.write":"Create or withdraw FXP tier records.","relationships.read":"Read FXP–PSP relationship records.","relationships.write":"Create, update, or delete FXP–PSP relationship records."}}}}},"schemas":{"QuoteResponse":{"type":"object","description":"FX quote response with quote details.","properties":{"quoteRequestId":{"type":"string","description":"Quote request identifier."},"sourceCountry":{"type":"string","description":"The ISO 3166 alpha-2 country code","maxLength":2,"minLength":2,"pattern":"^[A-Z]{2}$"},"sourceCurrency":{"type":"string","description":"The ISO 4217 alpha-3 currency code","maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$"},"destinationCountry":{"type":"string","description":"ISO 3166-1 alpha-2 destination country code.","maxLength":2,"minLength":2,"pattern":"^[A-Z]{2}$"},"destinationCurrency":{"type":"string","description":"ISO 4217 destination currency code.","maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$"},"amountCurrency":{"type":"string","description":"Currency for the amount.","maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$"},"amount":{"type":"number","description":"Amount value."},"quotes":{"type":"array","description":"Quote detail list.","items":{"$ref":"#/components/schemas/QuoteDetail"}}},"required":["amount","amountCurrency","destinationCountry","destinationCurrency","quoteRequestId","quotes","sourceCountry","sourceCurrency"]},"QuoteDetail":{"type":"object","description":"Individual quote detail.","properties":{"quoteId":{"type":"string","description":"Quote identifier."},"issuedDateTime":{"type":"string","format":"date-time","description":"Quote issue timestamp (ISO-8601)."},"expiryDateTime":{"type":"string","format":"date-time","description":"Quote expiry timestamp (ISO-8601)."},"fxpFinInstIdType":{"type":"string","description":"FXP financial institution id type."},"fxpFinInstId":{"type":"string","description":"FXP financial institution id."},"exchangeRate":{"type":"number","description":"FX rate applied to the quote."},"debtorAgent":{"$ref":"#/components/schemas/DebtorAgent","description":"Debtor agent amounts."},"intermediaryAgent1":{"$ref":"#/components/schemas/IntermediaryAgent","description":"First intermediary agent."},"intermediaryAgent1Account":{"$ref":"#/components/schemas/IntermediaryAgentAccount","description":"First intermediary agent account."},"intermediaryAgent2":{"$ref":"#/components/schemas/IntermediaryAgent","description":"Second intermediary agent."},"intermediaryAgent2Account":{"$ref":"#/components/schemas/IntermediaryAgentAccount","description":"Second intermediary agent account."},"creditorAgent":{"$ref":"#/components/schemas/CreditorAgent","description":"Creditor agent amounts."}}},"DebtorAgent":{"type":"object","description":"Debtor agent amounts for a quote.","properties":{"interbankSettlementAmount":{"$ref":"#/components/schemas/InterbankAmount","description":"Interbank settlement amount."}}},"InterbankAmount":{"type":"object","description":"Interbank settlement amount with cap indicator.","properties":{"currency":{"type":"string","description":"The ISO 4217 alpha-3 currency code","maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$"},"amount":{"type":"number","description":"Amount value."},"cappedToMaxAmount":{"type":"boolean","description":"Whether the amount was capped by IPS limits."}}},"IntermediaryAgent":{"type":"object","description":"Intermediary agent details.","properties":{"finInstId":{"$ref":"#/components/schemas/IntermediaryFinInstId","description":"Financial institution identifier."}}},"IntermediaryFinInstId":{"type":"object","description":"Financial institution identifiers for an intermediary agent.","properties":{"name":{"type":"string","description":"Financial institution name."},"BICFI":{"type":"string","description":"BICFI identifier."},"LEI":{"type":"string","description":"LEI identifier."},"clearingSystemMemberId":{"$ref":"#/components/schemas/ClearingSystemMemberId","description":"Clearing system member identifier."},"other":{"$ref":"#/components/schemas/OtherId","description":"Other identifier."}}},"ClearingSystemMemberId":{"type":"object","description":"Clearing system member identifier.","properties":{"clearingSystemId":{"type":"string","description":"Clearing system identifier."},"memberId":{"type":"string","description":"Member identifier."}}},"OtherId":{"type":"object","description":"Generic identifier wrapper.","properties":{"id":{"type":"string","description":"Identifier value."}}},"IntermediaryAgentAccount":{"type":"object","description":"Intermediary agent account identifier.","properties":{"id":{"type":"string","description":"Account identifier."}}},"CreditorAgent":{"type":"object","description":"Creditor agent amounts for a quote.","properties":{"interbankSettlementAmount":{"$ref":"#/components/schemas/InterbankAmount","description":"Interbank settlement amount."},"chargesAmount":{"$ref":"#/components/schemas/AmountDto","description":"Charges amount."},"creditorAccountAmount":{"type":"number","description":"Net amount credited to the creditor account."}}},"AmountDto":{"type":"object","description":"Monetary amount with currency code.","properties":{"amount":{"type":"number","description":"Fixed nominal fee amount in Destination Currency. Omitted when the formula has no fixed component."},"currency":{"type":"string","description":"ISO-4217 currency code for the fee. Always the Destination Currency. Omitted when nominalFee is omitted.","maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$"}}},"ErrorApiResponse":{"type":"object","description":"Standard structured rejection body. Returned for all non-2xx responses produced by the auth sidecar or the application. Gateway level errors (405, 409, 413, 429, 502, 503, 504) do NOT carry this body.","properties":{"statusCode":{"type":"string","description":"Business-level status code. Always RJCT (Rejected) — the structured error body is only returned for rejection cases. Successful responses use HTTP status alone (200 OK for sync, 202 Accepted for async ingress) with no structured statusCode body.","enum":["RJCT"],"maxLength":4},"reasonCode":{"type":"string","description":"Categorised reason code. Three families: TE (Technical Error, e.g. TE001/TE002/TE099), AE (Authentication / Authorization Error, e.g. AE001–AE004, sidecar-enforced), BE (Business Error). BE001–BE020 are raised by the Payments endpoints; BE021–BE027 are raised by the FXP endpoints.","enum":["AE001","AE002","AE003","AE004","BE001","BE002","BE005","BE006","BE007","BE008","BE009","BE011","BE012","BE016","BE017","BE018","BE019","BE020","BE021","BE022","BE023","BE024","BE025","BE026","BE027","TE001","TE002","TE099"],"maxLength":5,"pattern":"[A-Z]{2}[0-9]{3}"},"name":{"type":"string","description":"Machine-readable business error name from the reason code catalogue.","maxLength":50,"pattern":"[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*"},"description":{"type":"string","description":"Human-readable error description. MUST NOT contain PII (CD-INV-09).","maxLength":500}},"required":["description","name","reasonCode","statusCode"]}}},"paths":{"/v1/quotes":{"get":{"tags":["Quotes"],"summary":"FX Quote Retrieval & Selection","description":"Source PSP retrieves FX quotes from Nexus for a given corridor and amount. Includes improved rates for PSP, improved rates for the amount, and checks Maximum Source and Destination IPS amounts for the currencies. Service used when Source PSP uses third-party FXP.","operationId":"createQuote","parameters":[{"name":"Accept","in":"header","description":"application/json","required":true,"schema":{"type":"string","default":"application/json"}},{"name":"sourceCountry","in":"query","description":"ISO‑3166 alpha‑2 country code of the Source Country.","required":true,"schema":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Z]{2}$"}},{"name":"sourceCurrency","in":"query","description":"ISO‑4217 3‑letter code of the Source Currency.","required":true,"schema":{"type":"string","maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$"}},{"name":"destinationCountry","in":"query","description":"ISO‑3166 alpha‑2 country code of the Destination Country.","required":true,"schema":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Z]{2}$"}},{"name":"destinationCurrency","in":"query","description":"ISO‑4217 3‑letter code of the Destination Currency.","required":true,"schema":{"type":"string","maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$"}},{"name":"amountCurrency","in":"query","description":"   ISO‑4217 3‑letter currency code of `amount`. Equals `sourceCurrency` if Sender defined `DebtorAccountAmount`,\n   or `destinationCurrency` if Sender defined `CreditorAccountAmount`.\n","required":true,"schema":{"type":"string","maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$"}},{"name":"amount","in":"query","description":"  Amount specified by Sender. If Sender chose `DebtorAccountAmount`,\n  this is `DebtorAccountAmount` minus `Source PSP Deducted Fee` (Source Currency).\n  If Sender chose `CreditorAccountAmount`, this is `CreditorAccountAmount` (Destination Currency).\n","required":true,"schema":{"type":"number","minimum":0}},{"name":"finInstIdType","in":"query","description":"  Type ID of the Source PSP. Used together with `finInstId` to identify the Source PSP for FXP eligibility and rate improvement lookups.\n  The originating Source IPS is resolved separately from the authenticated caller context.\n","required":true,"schema":{"type":"string","minLength":1}},{"name":"finInstId","in":"query","description":"ID of the Source PSP.","required":true,"schema":{"type":"string","minLength":1}},{"name":"destFinInstIdType","in":"query","description":"  Type ID of the Destination PSP. Required when the destination country operates multiple IPSes.\n  Used to resolve which Destination IPS(s) the Destination PSP is connected to,\n  constraining eligible FXPs to those with Destination-side access on the same IPS(s).\n","required":false,"schema":{"type":"string"}},{"name":"destFinInstId","in":"query","description":"  ID of the Destination PSP. Required when the destination country operates multiple IPSes.\n  If absent in a multi-IPS destination country, Nexus rejects the request with `BE008 QUOTE_DESTINATION_PSP_REQUIRED`\n","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Quote created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"401":{"description":"Authentication Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"403":{"description":"Authorization Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"405":{"description":"Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.","headers":{"Allow":{"description":"Permitted HTTP methods for this endpoint","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.","headers":{"Retry-After":{"description":"Duration after which the caller may retry","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"502":{"description":"Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate."},"503":{"description":"Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff."},"504":{"description":"Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff."}}}}}}
```