> 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       |
| `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"
    },
    "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"
    },
    "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"
    },
    "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)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.orda.network/developers/api/on-ramps/requesting-a-quote.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.