> For the complete documentation index, see [llms.txt](https://docs.rozo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rozo.ai/integration/api-doc/bridge-api/get-fees.md).

# Get Fees

Use the `dryrun` parameter to preview the fee calculation without creating an actual payment.

**API Host**: `https://intentapiv4.rozo.ai/functions/v1`

**Endpoint:** `POST /payment-api/payments?dryrun=true`

## Request

Use the authenticated Node.js client in [Make Your First API Request](https://docs.rozo.ai/integration/api-doc/first-request.md), with the request body from the [Wallet quick start](https://docs.rozo.ai/integration/api-doc/bridge-api/api-quick-start.md) or [Merchant quick start](https://docs.rozo.ai/integration/api-doc/merchant-api/api-quick-start-merchant.md):

```bash
node payment.mjs quote
```

The client sends `POST /payments?dryrun=true` with your server-side `X-API-Key`. It does not create a payable order. Select the app and route you intend to use for the eventual payment.

## Response

Trimmed example for 100 USDC on Base to USDC on Stellar on the public default tier:

```json
{
  "status": "dryrun",
  "type": "exactIn",
  "source": {
    "chainId": "8453",
    "tokenSymbol": "USDC",
    "amount": "100.000000",
    "fee": "0.10"
  },
  "destination": {
    "chainId": "1500",
    "tokenSymbol": "USDC",
    "amount": "99.900000"
  },
  "provider": "rozo",
  "feeInfo": {
    "feePercentage": "0.1%",
    "minimumFee": "$0.01",
    "provider": "rozo"
  }
}
```

The Rozo fee is `source.fee`, in source token units.

> **Note**: The `dryrun=true` parameter returns fee details without creating a payment record.

## Which rail charged the fee

Dry-run and create responses also carry a `feeInfo` block that names the routing provider the fee belongs to, so you always know whether a quote is priced on Rozo's own rails or on NEAR Intents:

```json
"provider": "near",
"feeInfo": {
  "feePercentage": "0.3%",
  "minimumFee": "$0.01",
  "provider": "near",
  "feeTier": "near-routing"
}
```

| Provider | Rate                                                                                     |
| -------- | ---------------------------------------------------------------------------------------- |
| `rozo`   | your app tier (public default 0.1%, minimum $0.01); per-chain minimums apply (see below) |
| `near`   | flat 0.3% (minimum $0.01); the Solana payout minimum still applies                       |

Per-chain minimum fees on the public tiers:

* Paying out to Solana: $0.20 when the receiver does not hold the token account yet, $0.01 when it already does. This applies on both rails.
* Paying in from or paying out to Ethereum on `rozo`: $0.10.

A minimum replaces the percentage fee when it is higher; it is not added on top.

`feePercentage` is the **effective** rate: when a minimum fee applies to a small order it shows the real percentage, not the nominal one.

## Rate card without a dry run

`GET /payment-api/payments/supported` returns the schedule-level rate card for both rails together with the supported chain/token matrix:

```bash
curl 'https://intentapiv4.rozo.ai/functions/v1/payment-api/payments/supported'
```

```json
{
  "fees": {
    "rozo": { "feePercentage": "0.1%", "minimumFee": "$0.01" },
    "near": { "feePercentage": "0.3%", "minimumFee": "$0.01", "feeTier": "near-routing" }
  },
  "data": [ ... ]
}
```

These numbers are indicative. Read the dry-run `feeInfo` for the preview, then check the actual created order before paying. A dry-run does not lock a future price.

## TRON USDT to Stellar USDC quote (Beta)

The same dry run quotes the TRON USDT to Stellar USDC Beta route. Send `"provider": "rozo"`, `"type": "exactOut"`, source `{"chainId": "728126428", "tokenSymbol": "USDT"}` and destination USDC on Stellar (`1500`) with the net amount, and optionally the receiver and memo. A valid API key is required. Without a receiver the quote is priced but the receiver checks (trustline, approved receiver for a bound key) do not run; the receiver is required when you create the order.

The response keeps the usual `status: "dryrun"`, `source.amount` (gross USDT), `destination.amount` (net USDC) and `feeInfo`, and adds a `paymentOption` block:

* `priceLocked: false` and `amountIsEstimate: true`: the quote reserves nothing, and the final amount to pay can be slightly higher.
* `available` and `availabilityReason`: whether a payment option can be created right now, and why not.
* `limits.minGrossUsd`, `limits.maxGrossUsd`: current limits on the gross amount.
* `fees`: Rozo fee amount and basis points, whether the 0.30 USD minimum applied, and the partner fee. The Rozo fee is dynamic with a 0.20% floor and a 0.30 USD minimum; the partner fee is separate. On this route `feeInfo.feePercentage` shows that rate, not an effective rate, even when the 0.30 USD minimum applies; read `paymentOption.fees.rozoFeeUsd` and `minimumFeeApplied` for the actual fee.
* `source.amount` is the gross rounded up to 0.01 USDT; limits are checked on that amount. When the request cannot be priced (route off, app not eligible, receiver malformed or not allowed), `source.amount`, `feeInfo` and `fees` are `null`.
* A dependency that cannot be read returns HTTP 503 `serviceUnavailable`; retry later. A request without an API key is rejected with HTTP 400.

Creating the order is a separate two-step flow; a successful quote does not mean `POST /payments` accepts a TRON source. See [TRON USDT pay-in, settle in Stellar USDC](https://docs.rozo.ai/start/supported-tokens-and-chains/usdt-tron-to-usdc-stellar.md) for request and response examples. Apart from this route and TRON USDT to Base USDC below, any other request with a TRON source, including TRX, is still rejected.

## TRON USDT to Base USDC quote (Beta)

The same dry run quotes TRON USDT to Base USDC. Send the same body with destination USDC on Base:

```json
{
  "type": "exactOut",
  "provider": "rozo",
  "source": { "chainId": "728126428", "tokenSymbol": "USDT" },
  "destination": {
    "chainId": "8453",
    "tokenSymbol": "USDC",
    "amount": "100.00",
    "receiverAddress": "<your user Base address>"
  }
}
```

The response has the same `paymentOption` block, with `route` set to `tron_usdt_to_base_usdc`; fees and limits follow the same rules as the Stellar route (dynamic rate with a 0.20% floor, 0.30 USD minimum), but the fee is calculated for this route, so read it from the quote. `receiverAddress` is optional on the quote, and `receiverMemo` is not accepted. A non-200 answer, or a 200 without `paymentOption.route`, means the route is not available to your app right now. See [TRON USDT pay-in, settle in Base USDC](https://docs.rozo.ai/start/supported-tokens-and-chains/usdt-tron-to-usdc-base.md).

## Errors specific to NEAR-routed quotes

| Error code                        | Meaning                                                                                |
| --------------------------------- | -------------------------------------------------------------------------------------- |
| `ROUTE_NOT_SUPPORTED_BY_PROVIDER` | You asked for `provider: "near"` on a route it cannot serve.                           |
| `AMOUNT_TOO_SMALL`                | Below the route's minimum; the response includes `data.minimumSourceAmount`.           |
| `NEGATIVE_ROUTE_ECONOMICS`        | The amount is too small to cover the network cost of this route; send a larger amount. |

## Error responses

Errors from this endpoint use `error.code` and `error.message`, plus a `requestId` you can share with support. Route-specific details, when present, are in the top-level `data` object: read `data.errorCode`, not `error.details.errorCode`. Some errors have no `data` object.

The examples below use illustrative inputs. They show the full JSON shape, not captured customer responses. Amounts are examples, not fixed route minimums; the placeholder `requestId` is replaced by a generated ID in real responses. These examples are not an exhaustive error catalog.

All five examples return **HTTP 400 Bad Request** with **Content-Type: application/json**.

### Unsupported NEAR route

For example, requesting `provider: "near"` for Base USDC to HyperEVM USDC is rejected by the provider route check.

```json
{
  "error": {
    "code": "invalidRequest",
    "message": "This route is not supported by provider \"near\". Retry with provider \"rozo\" (or omit provider to use auto)."
  },
  "requestId": "00000000-0000-4000-8000-000000000001",
  "data": {
    "errorCode": "ROUTE_NOT_SUPPORTED_BY_PROVIDER",
    "provider": "near",
    "reason": "destination_not_settleable",
    "sourceChainId": "8453",
    "sourceTokenSymbol": "USDC",
    "destinationChainId": "999",
    "destinationTokenSymbol": "USDC",
    "supportedProviders": [
      "rozo"
    ]
  }
}
```

Check the supported routes. If `data.supportedProviders` includes `"rozo"`, retry with `provider: "rozo"` or omit `provider` to use automatic routing. Otherwise, select another supported route. Additional request validation still applies.

### Amount below the route minimum

This example requests 3 source tokens when the provider quote requires at least 5.

```json
{
  "error": {
    "code": "amountTooLow",
    "message": "Amount is below the minimum for this route. Minimum pay-in is 5 (you requested 3)."
  },
  "requestId": "00000000-0000-4000-8000-000000000001",
  "data": {
    "errorCode": "AMOUNT_TOO_SMALL",
    "provider": "near",
    "minimumSourceAmount": 5,
    "requestedSourceAmount": 3
  }
}
```

`data.minimumSourceAmount` and `data.requestedSourceAmount` are numbers in source-token units, not smallest units. Increase the source amount to at least the returned minimum and request a fresh dry-run quote; other route checks may still reject it.

### Amount cannot cover the route cost

The quote cannot cover the requested destination amount after route costs.

```json
{
  "error": {
    "code": "amountTooLow",
    "message": "Amount is too low to cover the network cost of this route (short by 0.024365). Please send a larger amount."
  },
  "requestId": "00000000-0000-4000-8000-000000000001",
  "data": {
    "errorCode": "NEGATIVE_ROUTE_ECONOMICS",
    "provider": "near",
    "deliverable": 19.915635,
    "expectedDeliverable": 19.975562,
    "promised": 19.94,
    "shortfall": 0.024365
  }
}
```

Increase the amount and request a fresh quote. `deliverable`, `expectedDeliverable`, `promised`, and `shortfall` are numbers in destination-token units. `deliverable` is the guaranteed quote floor when available, while `expectedDeliverable` is the expected output. A numeric or null `withdrawFee` may also appear if the provider supplies that field. These values vary with the quote.

### NEAR does not support anyAmount

Setting `provider: "near"` together with `type: "anyAmount"` returns this error.

```json
{
  "error": {
    "code": "invalidRequest",
    "message": "provider \"near\" does not support type \"anyAmount\". Use provider \"rozo\" or \"auto\"."
  },
  "requestId": "00000000-0000-4000-8000-000000000001",
  "data": {
    "errorCode": "PROVIDER_TYPE_NOT_SUPPORTED",
    "provider": "near",
    "type": "anyAmount"
  }
}
```

For `anyAmount`, use `provider: "rozo"` or `"auto"`. To request a NEAR quote, use a supported fixed-amount type (`exactIn` or `exactOut`) and provide its required fields.

### Invalid request body

A malformed JSON body or a body that is not a JSON object returns this error.

```json
{
  "error": {
    "code": "invalidRequest",
    "message": "Body must be valid JSON object"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}
```

Send a valid JSON object with `Content-Type: application/json`. This example has no `data` object, so clients must handle that field as optional.

For client-side handling, check the HTTP status first, then `data.errorCode` when available, otherwise `error.code`. Do not match the full `error.message` string: it can contain dynamic amounts or provider guidance. Correct these request errors before retrying the same request.
