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.
activeOnly	When true, restrict results to currently active 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",
  "activeOnly": true
}

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

Evaluate quote options

The response has two top-level arrays:

• options contains executable quote options
• 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
• path, including each provider leg
• policyApplied and the policy version identifiers

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.

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.

Store the right identifiers

Persist the quote request id for traceability and the selected quote option id for transfer creation. Do not persist provider credentials, quote internals outside the public response, or assumptions derived from a provider's position in the returned array.

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