Quote

Price a BRL to asset conversion, with the full fee breakdown, before you run an on-ramp or off-ramp.

POST /api/quote

Returns an indicative conversion price and fee breakdown. Re-quote before executing and show the final amount returned by the operation. Quotes expire within two minutes and do not lock a rate.

For a Pix payout with a locked quote, use POST /api/wallet/payout/beneficiary and pass its quoteId to Wallet Payout.

Request

curl --request POST \
  --url https://api.hodle.com.br/api/quote \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "inputCurrency": "BRL",
    "inputPaymentMethod": "PIX",
    "outputCurrency": "USDC",
    "outputPaymentMethod": "BASE",
    "inputAmount": "100.00"
  }'
const res = await fetch('https://api.hodle.com.br/api/quote', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HODLE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    inputCurrency: 'BRL',
    inputPaymentMethod: 'PIX',
    outputCurrency: 'USDC',
    outputPaymentMethod: 'BASE',
    inputAmount: '100.00',
  }),
})
const data = await res.json()
import os, requests

res = requests.post(
    "https://api.hodle.com.br/api/quote",
    headers={
        "Authorization": f"Bearer {os.environ['HODLE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "inputCurrency": "BRL",
        "inputPaymentMethod": "PIX",
        "outputCurrency": "USDC",
        "outputPaymentMethod": "BASE",
        "inputAmount": "100.00",
    },
)
data = res.json()

Parameters

FieldTypeRequiredDescription
inputCurrencystringYesBRL, USDT, USDC, USDB, LBTC, BTC, BRS.
inputPaymentMethodstringYesPIX, POLYGON, BASE, TRON, LIQUID, LIGHTNING, SOLANA, SPARK.
outputCurrencystringYesSame set as inputCurrency.
outputPaymentMethodstringYesSame set as inputPaymentMethod.
inputAmountstringYes (or outputAmount)Amount in inputCurrency. Decimal string.
outputAmountstringYes (or inputAmount)Amount in outputCurrency. Use this for exact-out quotes.
outputBrCodestringNoPIX BR Code used to price a known recipient. Third-party operations must be enabled separately.
addressstringNoBRL → BRS destination. External Solana delivery adds deliveryFee and requires account enablement. On Base, use an address owned by the account.

Pass exactly one of inputAmount or outputAmount.

Response

200 OK
{
  "success": true,
  "data": {
    "quoteToken": "qt_8f3a4b...",
    "pairName": "BRL-USDC",
    "basePrice": "0.18634",
    "inputCurrency": "BRL",
    "outputCurrency": "USDC",
    "inputAmount": "100.00",
    "outputAmount": "18.41",
    "appliedFees": [
      { "type": "MARKUP",        "amount": "0.20", "currency": "USDC" },
      { "type": "INPUT_FIXED",   "amount": "0.50", "currency": "BRL"  },
      { "type": "OUTPUT_FIXED",  "amount": "0.05", "currency": "USDC" }
    ],
    "expiresAt": "2026-05-09T22:02:00.000Z"
  }
}
FieldTypeDescription
data.quoteTokenstringReference for traceability; not accepted as input by other endpoints.
data.basePricestringQuoted exchange rate for the pair.
data.outputAmountstringIndicative amount after fees; Solana delivery costs are excluded.
data.inputAmountSatsintegerBTC sats required for a BTC → BRL exact-out quote. Present only for this route.
data.outputAmountSatsintegerBTC sats delivered by a BRL → BTC quote. Present only for this route.
data.feeInCentsintegerTotal fee for BRS and BTC quotes, using your account’s pricing.
data.appliedFeesarrayItemised — your UI can render each line.
data.expiresAtstringISO timestamp; after this, re-quote.
data.settlementobjectRoute details for Solana, BRS and BTC quotes.

Solana quotes

SOLANA supports USDT, USDC and BRS. Use BRS for BRL-pegged tokens on Solana.

BRS

BRS is quoted against BRL over Pix in both directions, at basePrice 1:

PairAmount fieldMeaning
BRL/PIX → BRS/SOLANA or BASEinputAmountThe Pix charge; outputAmount is the BRS minted after fees.
BRS/SOLANA → BRL/PIXoutputAmountThe Pix payout; inputAmount is the BRS debited, fee included.

BRS must be enabled on your account (ask support). Solana buys and payouts have a R$1.00 minimum; Base buys require at least R$5.00 after fees. Deposits default to your Hodle wallet. To preview external Solana delivery, send address; deliveryFee is paid separately in BRS from your Hodle wallet. Quoting does not debit it. See external BRS delivery.

If a BRS quote returns 202 with status: "PENDING" and pricingPending: true, retry the same quote after one or two seconds.

200 OK — BRL → BRS to an external address (excerpt)
{
  "success": true,
  "data": {
    "pairName": "BRLBRS",
    "inputAmount": "100.00",
    "outputAmount": "100.00",
    "feeInCents": 0,
    "settlement": {
      "deliveryNetwork": "SOLANA",
      "destination": "EXTERNAL_SOLANA_WALLET"
    },
    "deliveryFee": {
      "feeCents": 144,
      "recipientHasTokenAccount": false,
      "paidIn": "BRS",
      "paidFrom": "OWN_HODLE_SOLANA_WALLET"
    }
  }
}

USDC and USDT quotes for Solana exclude delivery costs:

200 OK — BRL → USDC on Solana (excerpt)
{
  "success": true,
  "data": {
    "outputAmount": "18.41",
    "settlement": {
      "quotedNetwork": "BASE",
      "deliveryNetwork": "SOLANA",
      "bridgeFeeIncluded": false
    }
  }
}

With bridgeFeeIncluded: false, the delivered amount is below outputAmount. Use the completed deposit’s amount for reconciliation.

BRL ↔ BTC quotes

BTC quotes use your account’s fees.

  • BRL → BTC is an exact-input quote: send inputAmount in BRL with PIX → LIGHTNING or SPARK. The response returns outputAmountSats.
  • BTC → BRL is an exact-output quote: send outputAmount in BRL with LIGHTNING or SPARK → PIX. The response returns inputAmountSats, the exact invoice amount to request from the payer.
BRL → BTC — supported deposit-sized quote
{
  "inputCurrency": "BRL",
  "inputPaymentMethod": "PIX",
  "outputCurrency": "BTC",
  "outputPaymentMethod": "LIGHTNING",
  "inputAmount": "21.00"
}

inputAmount is the gross Pix amount, matching deposit/asset.value. The quoted sats use the amount after feeInCents. Depending on your account’s route, the minimum BTC purchase is R$20.00.

BTC → BRL exact output
{
  "inputCurrency": "BTC",
  "inputPaymentMethod": "LIGHTNING",
  "outputCurrency": "BRL",
  "outputPaymentMethod": "PIX",
  "outputAmount": "100.00"
}

Errors

StatusWhen
400Invalid fields, unsupported pair, wrong amount direction, or amount below the route’s minimum. BRL input must be at least R$1.00. BTC buys may require R$20.00; BRS on Base requires at least R$5.00 after fees.
401Missing or invalid API key.
403BRS or external delivery is not enabled, or the Base destination is not your own wallet.
503The external BRS delivery fee cannot be priced. Retry later.
400 — pair not supported
{ "success": false, "error": "No route for BRL-USDC at this time" }
400 — amount below minimum
{ "success": false, "error": "inputAmount must be at least 1.00 BRL" }

Common quote shapes

Use caseInputOutput
BRL → USDC (Base) on-rampBRL / PIXUSDC / BASE
BRL → USDT (Polygon) on-rampBRL / PIXUSDT / POLYGON
BRL → USDC (Solana) on-rampBRL / PIXUSDC / SOLANA
USDC (Solana) → BRL off-rampUSDC / SOLANABRL / PIX
USDT (Tron) → BRL off-rampUSDT / TRONBRL / PIX
BRL → BTC (Lightning) on-rampBRL / PIXBTC / LIGHTNING
Lightning → BRL off-rampBTC / LIGHTNINGBRL / PIX
Lightning → USDB (Spark)BTC / LIGHTNINGUSDB / SPARK