ALalfredpay
Quotes

Price a currency pair

Changed on

One endpoint with one job: price an FX pair. That price becomes the LP_EXECUTION leg of whatever consumes it.

A quote isn't a transaction type. What you do with it decides that:

  • POST /v1/customers/{customerId}/conversions, where both sides are the customer's own balances, makes it a CONVERSION.
  • POST /v1/customers/{customerId}/payouts/fiat, where value leaves, makes it a PAY_OUT with the FX running as a leg inside it.
  • A pay-in never consumes a quote. The deposit intent's indicativeRate is its price.

Setting the amount. Set fromAmount to fix what's debited, or toAmount to fix what lands. Sending both is a conflict, not a constraint.

Conditional fields. chain is required when either side is a stablecoin and must be omitted otherwise. rail is required when either side is fiat and must be omitted otherwise. Supplying a field the pair shape forbids is an error rather than an ignored value.

Why the rail is part of the price. (rail, currency) names the route being priced. (ACH, BOB) and (ACH, CLP) price separately, and (CHATS, USD) means USD delivered in Hong Kong. A quote that didn't know the rail could only return an average.

Par pairs, USD against USDC or USDT, are quotable at a rate of 1 with the fee table itemized, but a quote is never required for them.

A pair whose route isn't LIVE in GET /v1/countries/{country} fails with route_unsupported before anything is locked. Execute inside expiresAt, and re-quote rather than retry an expired one.

post/v1/customers/{customerId}/quotes

Request

  • Base URL
    https://api.sandbox.alfredpay.io
  • URL
    https://api.sandbox.alfredpay.io/v1/customers/{customerId}/quotes
  • Auth
    • HTTP bearer
    • or API key in header api-key and API key in header api-secret

Headers

Idempotency-Keystring uuid required

Required on every state-changing POST, simulators included; the only exempt POST is …/verifications/preflight. Replay (same key, same body) returns the original response with Idempotent-Replayed: true; same key with a different body → 409 idempotency_conflict. Keys are UUIDs, scoped to the API key, retained for 24 hours.

Request body

fromCurrency'USD' | 'HKD' | 'CNY' | 'MXN' | 'DOP' | 'COP' | 'BRL' | 'ARS' | 'CLP' | 'PEN' | 'BOB' | 'PYG' | 'USDC' | 'USDT' required

Fourteen members, reconciled to the countries a customer can be onboarded in. USDC and USDT are stablecoins and require chain.

toCurrency'USD' | 'HKD' | 'CNY' | 'MXN' | 'DOP' | 'COP' | 'BRL' | 'ARS' | 'CLP' | 'PEN' | 'BOB' | 'PYG' | 'USDC' | 'USDT' required

Fourteen members, reconciled to the countries a customer can be onboarded in. USDC and USDT are stablecoins and require chain.

fromAmountstring

Set this or toAmount, never both.

toAmountstring
chain'SOL' | 'ETH' | 'MATIC' | 'BASE' | 'ARB' | 'OP' | 'AVAX' | 'BNB' | 'TRX' | 'XLM' | 'CELO'
rail'ACH' | 'WIRE' | 'SPEI' | 'PIX' | 'COELSA' | 'FPS' | 'CHATS'

The Rail values a fiat quote may carry, so every rail except WALLET.

metadataMetadata

Client-supplied key–value pairs, echoed on the object and every event about it.

Response

Created

idstring
customerIdstring
fromCurrency'USD' | 'HKD' | 'CNY' | 'MXN' | 'DOP' | 'COP' | 'BRL' | 'ARS' | 'CLP' | 'PEN' | 'BOB' | 'PYG' | 'USDC' | 'USDT'

Fourteen members, reconciled to the countries a customer can be onboarded in. USDC and USDT are stablecoins and require chain.

toCurrency'USD' | 'HKD' | 'CNY' | 'MXN' | 'DOP' | 'COP' | 'BRL' | 'ARS' | 'CLP' | 'PEN' | 'BOB' | 'PYG' | 'USDC' | 'USDT'

Fourteen members, reconciled to the countries a customer can be onboarded in. USDC and USDT are stablecoins and require chain.

fromAmountstring
toAmountstring
chainstring nullable
railstring nullable
ratestring
rateLockedAtstring date-time
expiresAtstring date-time

Typically ~2 minutes. Execute before this or re-quote.

status'active' | 'expired' | 'consumed'

Changes