> For the complete documentation index, see [llms.txt](https://docs.orda.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.orda.network/developers/api/on-ramps/requesting-a-quote.md).

# Requesting a Quote

## Requesting a Fiat-to-Crypto Quote <a href="#requesting-a-fiat-to-crypto-quote" id="requesting-a-fiat-to-crypto-quote"></a>

### Overview <a href="#overview" id="overview"></a>

Request a quote to convert fiat currency into cryptocurrency. The quote endpoint provides real-time exchange rates and generates deposit instructions for the fiat payment.

### Endpoint <a href="#endpoint" id="endpoint"></a>

```
POST /v1/onramp/quote
```

### Authentication <a href="#authentication" id="authentication"></a>

Requires HMAC authentication headers:

* `x-client-id`: Your project's client ID
* `x-signature`: HMAC-SHA256 signature
* `x-timestamp`: Request timestamp (optional)

Check our [authentication](/developers/authentication.md) guide for more info.

### Request Parameters <a href="#request-parameters" id="request-parameters"></a>

#### Required Fields <a href="#required-fields" id="required-fields"></a>

| Parameter      | Type   | Description                                                                                                                |
| -------------- | ------ | -------------------------------------------------------------------------------------------------------------------------- |
| `fromCurrency` | string | Source fiat currency code (e.g., "BRL")                                                                                    |
| `intent`       | object | Defines the transaction amount and method                                                                                  |
| `taxId`        | string | Fiat payer's Brazilian tax ID: CPF (11 digits) or CNPJ (14 digits), digits only with no punctuation (e.g., "11144477735"). |
| `taxIdCountry` | string | ISO 3166-1 alpha-3 country code, uppercase (e.g., "BRA").                                                                  |
| `recipientId`  | string | UUID of the recipient to receive cryptocurrency                                                                            |

#### Intent Object <a href="#intent-object" id="intent-object"></a>

The intent object supports three methods to specify transaction amounts:

| Method       | Description                    | Value Format                                        | Example                                                                    |
| ------------ | ------------------------------ | --------------------------------------------------- | -------------------------------------------------------------------------- |
| `fromAmount` | Exact fiat amount to spend     | Decimal string representing fiat amount             | `{ "method": "fromAmount", "value": "500" }` means 500 BRL                 |
| `toAmount`   | Exact crypto amount to receive | String representing smallest units (wei-equivalent) | `{ "method": "toAmount", "value": "100000000000000000000" }` means 100 BRZ |
| `usd`        | USD value for conversion       | String representing smallest units (18 decimals)    | `{ "method": "usd", "value": "100000000000000000000" }` means $100 USD     |

**Important:**

* Fiat amounts (`fromAmount`) use standard decimal notation: `"500"` = 500 BRL
* Crypto amounts (`toAmount`) use smallest units based on token decimals: `"100000000000000000000"` = 100 tokens (18 decimals)
* USD amounts (`usd`) use 18 decimals like Ether: `"100000000000000000000"` = $100 USD

### Amount Formats <a href="#amount-formats" id="amount-formats"></a>

#### Understanding Smallest Units <a href="#understanding-smallest-units" id="understanding-smallest-units"></a>

Cryptocurrency amounts are represented in their smallest indivisible units (similar to wei for Ether):

**18-Decimal Tokens (BRZ on most chains):**

* 1 BRZ = 1000000000000000000 smallest units
* Formula: `smallest_units = amount × 10^18`

**6-Decimal Tokens (USDC, USDT):**

* 1 USDC = 1000000 smallest units
* Formula: `smallest_units = amount × 10^6`

#### Conversion Examples <a href="#conversion-examples" id="conversion-examples"></a>

{% tabs %}
{% tab title="Ethers" %}

```javascript
import { ethers } from 'ethers';

// For 18-decimal tokens (BRZ)
const toSmallestUnits = ethers.parseUnits("100", 18);  // "100000000000000000000"
const fromSmallestUnits = ethers.formatUnits("100000000000000000000", 18);  // "100.0"

// For USD values (always 18 decimals)
const usdInSmallestUnits = ethers.parseUnits("100", 18);  // "100000000000000000000"
```

{% endtab %}

{% tab title="  Web3.js" %}

```javascript
import Web3 from 'web3';
const web3 = new Web3();

// For 18-decimal tokens
const toSmallestUnits = web3.utils.toWei("100", "ether");  // "100000000000000000000"
const fromSmallestUnits = web3.utils.fromWei("100000000000000000000", "ether");  // "100"

// For 6-decimal tokens
const toSmallestUnits = web3.utils.toWei("100", "mwei");  // "100000000"
```

{% endtab %}
{% endtabs %}

### Request Examples <a href="#request-examples" id="request-examples"></a>

{% tabs %}
{% tab title="Fiat Amount (BRL)" %}

```bash
curl -X POST https://api.orda.network/v1/onramp/quote \
  -H "Content-Type: application/json" \
  -H "x-client-id: your-client-id" \
  -H "x-signature: your-signature" \
  -H "x-timestamp: 1234567890" \
  -d '{
    "fromCurrency": "BRL",
    "intent": {
      "method": "fromAmount",
      "value": "500"
    },
    "taxId": "11144477735",
    "taxIdCountry": "BRA",
    "recipientId": "123e4567-e89b-12d3-a456-426614174000"
  }'
```

{% endtab %}

{% tab title="Crypto Amount" %}

```bash
curl -X POST https://api.orda.network/v1/onramp/quote \
  -H "Content-Type: application/json" \
  -H "x-client-id: your-client-id" \
  -H "x-signature: your-signature" \
  -H "x-timestamp: 1234567890" \
  -d '{
    "fromCurrency": "BRL",
    "intent": {
      "method": "toAmount",
      "value": "100000000000000000000"
    },
    "taxId": "11144477735",
    "taxIdCountry": "BRA",
    "recipientId": "123e4567-e89b-12d3-a456-426614174000"
  }'
```

**Note:** The value `"100000000000000000000"` represents 100 BRZ in smallest units (18 decimals).
{% endtab %}

{% tab title="USD Value" %}

```bash
curl -X POST https://api.orda.network/v1/onramp/quote \
  -H "Content-Type: application/json" \
  -H "x-client-id: your-client-id" \
  -H "x-signature: your-signature" \
  -H "x-timestamp: 1234567890" \
  -d '{
    "fromCurrency": "BRL",
    "intent": {
      "method": "usd",
      "value": "100"
    },
    "taxId": "11144477735",
    "taxIdCountry": "BRA",
    "recipientId": "123e4567-e89b-12d3-a456-426614174000"
  }'
```

{% endtab %}
{% endtabs %}

### Implementation Notes <a href="#implementation-notes" id="implementation-notes"></a>

#### Recipient Requirements <a href="#recipient-requirements" id="recipient-requirements"></a>

* Recipient must exist and belong to your project
* Must have crypto settlement details configured:
  * `toChain`: Target blockchain ID
  * `toToken`: Token contract address
  * `toAddress`: Wallet address for delivery

#### Quote Expiration <a href="#quote-expiration" id="quote-expiration"></a>

* Quotes typically expire after 5-10 minutes
* Check `expiresAt` field for exact expiration time
* Execute deposit before expiration to lock in rate

#### Rate Calculation <a href="#rate-calculation" id="rate-calculation"></a>

* Exchange rates include all fees
* No hidden charges or additional fees
* Rate is guaranteed once deposit is made

#### Current Flow Limitation

At present, all BRL on-ramp flows are routed through **BRZ** as an intermediate step:

* **Now:** `BRL → BRZ → Target Asset (e.g. USDC, ETH, AUSD)`
* **Future:** `BRL → Target Asset` (direct)

This means:

* When configuring a recipient, you must first enable **BRZ** settlement.
* Additional conversions (BRZ → USDC, ETH, etc.) are handled automatically, but they add one extra step in the flow.

{% hint style="warning" %}
⚠️ **Note:** Direct BRL → asset settlement is in development. Once live, you’ll be able to on-ramp directly into USDC, ETH or other supported tokens with a single transaction.
{% endhint %}

### Next Steps <a href="#next-steps" id="next-steps"></a>

After receiving a quote:

1. Display deposit instructions to user
2. For PIX: Show QR code or copy PIX key
3. Monitor payment status
4. [Execute the quote](/developers/api/on-ramps/executing-a-quote.md) by completing deposit
5. [Track transaction status](/developers/api/on-ramps/monitoring-status.md)