Step 1 of 3 — quote paying PIX with crypto
lunium_quote_crypto_saleRequires an API key. Pay a PIX key or PIX copy-and-paste charge with crypto. Choose ONE mode: amount + pix_key (sell that crypto amount); brl_amount + pix_key (quote for a target BRL amount); or br_code alone (the charge determines amount and recipient). br_code supports USDT/USDC only, on currently available catalog networks. Key payments use supported catalog assets/networks; never promise every cryptocurrency works. Use the complete, exact copy-and-paste string. If the user provides only an image, use a compatible QR decoder; never reconstruct the code with AI. If a charge is refused, do not extract its PIX key and pay it directly: that would be a different payment. Returns amount (crypto to deposit), brl_amount (what the recipient receives), expires_at, an order id and a confirmation_token. No money moves and no deposit address is issued here — nothing is committed until lunium_confirm_crypto_sale.
Always show the user amount, asset, network, brl_amount and the destination PIX key or merchant_name plus original br_code before confirming. This is the last step where a wrong destination is still free to fix.
For brl_amount, rounding/routing can affect the effective quoted BRL: approve and report the returned amount, not an assumed exact result. For br_code, the returned crypto amount already includes any copia_e_cola_buffer_usd; do not add it again.
Rules that prevent expensive mistakes: send amount as a decimal STRING ("50", "12.5"), never a JSON number — floats lose precision in transit. brl_amount is a decimal string in REAIS, with at most two decimals ("100.00" means R$100, not cents). With br_code omit amount, brl_amount, pix_key and pix_key_type. pix_key_type is required for ambiguous 11-digit keys; other types can be inferred by the API. Always send your own external_id: it makes the call idempotent, so repeating it returns the same order instead of creating a second one, and it is how you recover after a timeout or a crash. Read expires_at from the response instead of assuming a window.
Do not call it in a loop to "watch the price" — every call is an order. Do not quote an amount you are not ready to send. Do not quote an asset or network you have not confirmed with lunium_list_settlement_options(direction=deposit). Follow pagination and current availability. A catalog listing is not a guarantee that a quote will be accepted; show live limits/fees/expiry.
Errors: acao=corrigir with a limits object → the value is outside a current per-operation or daily limit. Read limits.min_amount / limits.max_amount from that response — never use a hard-coded range — and use one of those numbers instead of guessing. A refusal on the network means it is not settling at this moment: offer another network instead of retrying. acao=esperar → quota. acao=repetir → retry with the SAME external_id. erro="external_id_divergente" (acao=corrigir) → this external_id already exists with different parameters; inspect cashout_id/recovery_endpoint before any new intent. external_id_nao_verificavel means the legacy order cannot be compared safely; recover that original order instead of creating another payment.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| asset | Yes | Ticker from lunium_list_settlement_options(direction=deposit). br_code supports USDT/USDC only. | |
| amount | No | Positive crypto amount as a decimal STRING. Use with pix_key; omit when brl_amount or br_code is present. | |
| br_code | No | Exact PIX copy-and-paste from the user (never abbreviated). Amount and recipient come from it. USDT/USDC only; omit amount, brl_amount, pix_key and pix_key_type. | |
| network | Yes | Current network id from the deposit catalog. Confirmation requirements and provider timing vary; do not promise a fixed settlement time. | |
| pix_key | No | PIX key receiving the reais. Required unless br_code is used. Must come from your user or your own configuration. | |
| brl_amount | No | Positive target PIX value in REAIS, decimal STRING (100.00 = R$100). Approve the effective returned quote. Use with pix_key, never amount or br_code. | |
| external_id | Yes | Your stable id for this user intent. Generate it once per intent, not once per attempt, and reuse it on every retry. | |
| pix_key_type | No | Usually omit it: the type is inferred from the key itself for e-mail, CNPJ, random keys and phones written with the +55 country code. Only required when the key is 11 bare digits, because a CPF and a phone number are the same length and guessing would pay the wrong person. Send it explicitly when you know it — an explicit type always wins over inference. | |
| token_address | No | Contract address or mint. Only for catalog-supported long-tail tokens with ambiguous tickers; omit for USDT/USDC. |