Quotes

A quote request asks Heron for the available execution options between two rails. Each option captures the quoted amounts, fees, ETA, execution path, applied policy, and expiry needed to create a transfer.

Before requesting a quote

Prepare the following:

• a source and destination returned by GET /v1/rails
• the amount and whether the source or destination side is fixed
• the entity whose provider readiness should be used, when applicable
• a saved fiat account or crypto wallet for destination-aware options

Some providers cannot return a usable option until the destination is known. Include destinationFiatAccountId or destinationCryptoWalletId when requesting a transfer-ready quote.

Request quotes

POST /v1/quotes

The main request fields are:

Field	Description
from	Source fiat or crypto rail.
to	Destination fiat or crypto rail.
amount	Positive decimal string for the fixed side.
fixedSide	FROM to fix the amount sent or TO to fix the amount received.
entityId	Entity used for provider eligibility and readiness.
destinationFiatAccountId	Saved fiat destination, when quoting to a bank account.
destinationCryptoWalletId	Saved wallet destination, when quoting to crypto.
policyId	Optional routing policy to apply.
includeIndicativeQuotes	Opt in to indicative quotes from eligible inactive providers.

Example request:

{
  "entityId": "00000000-0000-4000-8000-000000000001",
  "from": {
    "type": "FIAT",
    "country": "US",
    "currency": "USD",
    "method": "ACH"
  },
  "to": {
    "type": "FIAT",
    "country": "MX",
    "currency": "MXN",
    "method": "SPEI"
  },
  "amount": "1000.00",
  "fixedSide": "FROM",
  "destinationFiatAccountId": "00000000-0000-4000-8000-000000000002",
  "includeIndicativeQuotes": false
}

The example route is illustrative. Use the rail directory for current environment availability.

By default, Heron returns only quotes from providers that are active for the selected entity and can produce executable quotes. Set includeIndicativeQuotes to true only for discovery or comparison experiences. Those broader results can include providers the entity has not onboarded with and must not be assumed to be executable.

In production, the Desk currency picker shows rails supported by active providers for your organization and counts only those active providers. Sandbox keeps the broader catalog for indicative quote discovery. Rail availability is not a guarantee that every currency pair is supported; quotes still check eligibility for the selected entity and provider corridor.

Evaluate quote options

The response has two top-level arrays:

• options contains quote options; these are executable unless the request opted into indicative quotes
• advisories explains why additional options may be unavailable or require a destination

For each option, evaluate:

• totalInAmount and totalOutAmount
• fees, including amount, currency, and percentage when present
• eta
• quoteExpiresAt
• transferPurposeRequirement, when every provider leg in the route can accept at least one common canonical transfer purpose
• path, including each provider leg
• policyApplied and the policy version identifiers
• requiresFirstPartyDestination — when true, the payout provider on this option only pays accounts owned by the sending entity. Creating a transfer for this option with a third-party fiat account is rejected, so filter destination choices (or options) accordingly before creation. Always false for crypto-wallet destinations.

When transferPurposeRequirement.required is true, show the customer a choice from allowedValues and send the selected value unchanged when creating the transfer. Heron returns canonical values here rather than provider-specific purpose codes. An option is omitted when its route requires a purpose but its legs have no common supported value; the response includes a TRANSFER_PURPOSE_UNAVAILABLE advisory for that route.

If transferPurposeRequirement is null, request a new quote before transfer creation.

Do not assume the first option is best for every use case. Your selection logic can prioritize delivered amount, cost, speed, provider policy, or another product requirement.

Expiry and destination freshness

Create the transfer before quoteExpiresAt. If the option has expired, request a new quote instead of retrying transfer creation with the old id.

In the Desk review modal, Heron refreshes an expired quote that was not priced for a saved destination when you create the transfer. If the same route and terms are still available, creation continues automatically with your account, purpose, memo, and reference preserved. If the terms changed or the route is unavailable, you are asked to return to the Desk and review the latest quotes.

When a quote was created for a saved destination, Heron records that destination version. If the account or wallet changes before transfer creation, request a new quote. This prevents a quote from being executed against different instructions than the ones used during pricing and validation. The Desk requires a new review for expired destination-bound quotes because it cannot verify that the saved destination version is unchanged. The review modal cannot be closed while transfer submission is in progress, including during quote refresh.

Store the right identifiers

Persist the quote request id for traceability and the selected quote option id for transfer creation. Persist the selected canonical transfer purpose alongside your logical payment when the option requires one. Do not infer provider preference from the order of returned options.

Continue with Transfers to bind the selected option to its destination.

Destination approval notice

Quote options may include destinationApproval: { "status": "NOT_REGISTERED" } or another approval state when the final payout provider requires destination approval. null or an absent field means this requirement does not apply. APPROVED means Heron has recorded approval for the selected destination; it checks approval again before generating payment details.

This information does not change the quoted amounts or expiry. Browsing these quotes does not submit a destination registration to an approval-requiring provider. Register the selected bank account or wallet, with consent, in the transfer preparation step.

Routing policies

Heron can return direct and multi-provider options. Results are a selection of available routes, not an exhaustive comparison of every provider combination. A provider's temporary failure does not necessarily prevent another provider from returning an option.

Use allowedProviders, allowedChains and allowedTokens to restrict routing to selected values. Use the corresponding blockedProviders, blockedChains and blockedTokens to exclude values; exclusions take precedence. Allowed lists must be nonempty when supplied. A chain restriction does not require a fiat-only route to include a crypto step.

A transfer uses the policy associated with its selected quote. If its route violates that policy, the API returns invalid_request with details.reason: "routing_policy_violation". Invalid policy restrictions return details.reason: "routing_policy_invalid". Review the policy and request a new quote instead of repeatedly submitting the same incompatible route.