> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.finrock.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Network Fees and API Rate Limits — Finrock Reference

> Network fee units per blockchain, fee rate and estimate endpoints, and Finrock API rate limits — including rate limit headers and 429 handling.

Two operational constraints you need to account for in every Finrock integration are network fees — the on-chain costs paid to miners or validators to process a transaction — and API rate limits, which govern how many requests your application can make per minute. This page covers both, including how to query current fee rates, how fee units differ by blockchain type, and how to read the rate limit headers returned on every API response.

***

## Network Fees

Finrock exposes two endpoints for working with network fees: one to retrieve the current fee rates for any supported asset, and one to estimate the total fee for a specific transaction before you submit it.

### Fee Rate Units by Blockchain

Every blockchain family uses a different unit to express fee rates. Provide values in the correct unit when calling fee-related endpoints:

| Blockchain | Example Assets                 | Fee Rate Unit |
| ---------- | ------------------------------ | ------------- |
| UTXO       | BTC, LTC, DASH, DOGE, BCH      | Sat/Byte      |
| EVM        | ETH, BSC, POL, BASE, ARB, AVAX | GWei          |
| Tron       | TRX                            | Sun           |
| Ripple     | XRP                            | Drop          |
| Stellar    | XLM                            | Stroop        |
| Cardano    | ADA                            | Lovelace      |
| Solana     | SOL                            | Lamport       |

### Get Current Fee Rates

Use the fee rates endpoint to retrieve the current network fee rates for a given asset. This is useful for building a fee selection UI or for pre-flight checks before submitting high-value transactions.

```text theme={null}
GET https://api.finrock.io/dac/v1/network-fee-rates/{asset}
```

Replace `{asset}` with the asset ticker (e.g., `BTC`, `USDT_ETH`). This endpoint requires authentication.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
       --url https://api.finrock.io/dac/v1/network-fee-rates/BTC \
       --header 'Authorization: Token {JWT}' \
       --header 'accept: application/json' \
       --header 'x-api-key: YOUR_API_KEY'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.finrock.io/dac/v1/network-fee-rates/BTC',
    {
      method: 'GET',
      headers: {
        'Authorization': 'Token YOUR_JWT',
        'x-api-key': 'YOUR_API_KEY',
        'accept': 'application/json',
      },
    }
  );

  const feeRates = await response.json();
  console.log(feeRates);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.finrock.io/dac/v1/network-fee-rates/BTC',
      headers={
          'Authorization': 'Token YOUR_JWT',
          'x-api-key': 'YOUR_API_KEY',
          'accept': 'application/json',
      }
  )

  print(response.json())
  ```
</CodeGroup>

### Estimate Transaction Fee

Before submitting a transaction, you can call the fee estimate endpoint to calculate the total network fee for a given asset, amount (required for UTXO chains), and your chosen fee rate.

```text theme={null}
POST https://api.finrock.io/dac/v1/estimate-fee
```

**Request body parameters:**

<ParamField body="asset" type="string" required>
  The asset ticker as returned by the `/assets` endpoint (e.g., `BTC`, `USDT_ETH`).
</ParamField>

<ParamField body="fee_rate" type="float" required>
  The fee rate in the unit appropriate for the asset's blockchain (see the table above).
</ParamField>

<ParamField body="amount" type="double">
  The transfer amount. Required for UTXO-based chains (BTC, LTC, DASH, DOGE, BCH) because the fee depends on transaction size, which varies with the number of inputs and the amount.
</ParamField>

<CodeGroup>
  ```bash cURL (BTC example) theme={null}
  curl --request POST \
       --url https://api.finrock.io/dac/v1/estimate-fee \
       --header 'Authorization: Token {JWT}' \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --header 'x-api-key: YOUR_API_KEY' \
       --data '{
         "asset": "BTC",
         "amount": 0.5,
         "fee_rate": 25
       }'
  ```

  ```bash cURL (ETH example) theme={null}
  curl --request POST \
       --url https://api.finrock.io/dac/v1/estimate-fee \
       --header 'Authorization: Token {JWT}' \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --header 'x-api-key: YOUR_API_KEY' \
       --data '{
         "asset": "ETH",
         "fee_rate": 30
       }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.finrock.io/dac/v1/estimate-fee',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Token YOUR_JWT',
        'x-api-key': 'YOUR_API_KEY',
        'accept': 'application/json',
        'content-type': 'application/json',
      },
      body: JSON.stringify({
        asset: 'BTC',
        amount: 0.5,
        fee_rate: 25,
      }),
    }
  );

  const estimate = await response.json();
  console.log(estimate);
  ```
</CodeGroup>

<Tip>
  For UTXO chains, always include the `amount` field when calling `estimate-fee`. The fee depends on how many unspent outputs (UTXOs) the platform needs to consolidate to fund the transfer — omitting the amount will result in an inaccurate estimate.
</Tip>

***

## API Rate Limits

The Finrock API enforces rate limits on a **per-minute, per-API-key** basis. Rate limits apply globally across all endpoints associated with your API key. If your application exceeds the allowed number of requests within a one-minute window, the API returns an `HTTP 429 Too Many Requests` response. The limit automatically resets at the start of the next minute.

<Note>
  Rate limits are enforced per API key. If you need a higher limit for a production workload, contact [support@finrock.io](mailto:support@finrock.io) to request an increase.
</Note>

### Rate Limit Response Headers

Every API response includes rate limit headers so your application can proactively monitor its usage and back off before hitting the limit. Read these headers on every response:

| Header                   | Type    | Description                                                                                    |
| ------------------------ | ------- | ---------------------------------------------------------------------------------------------- |
| `x-rate-limit-remaining` | integer | The number of requests remaining in the current one-minute window for this endpoint.           |
| `x-ratelimit-limit`      | string  | The total request allowance for this endpoint and time window (e.g., `1m` denotes one minute). |
| `x-rate-limit-reset`     | string  | The ISO 8601 timestamp at which your rate limit window resets.                                 |

### Example Rate Limit Header Response

The following shows what the response headers look like when you call an endpoint with the `-i` flag in cURL to inspect them:

```bash theme={null}
# Use the -i flag to print response headers
curl -i 'https://api.finrock.io/dac/v1/supported-assets'

HTTP/2 200
date: Sat, 27 Aug 2022 18:22:48 GMT
content-type: application/json; charset=utf-8
content-length: 3026
x-frame-options: SAMEORIGIN
x-content-type-options: nosniff
x-xss-protection: 1; mode=block
strict-transport-security: max-age=31536000; includeSubDomains; preload
permissions-policy: geolocation=(self), microphone=()
referrer-policy: no-referrer
x-node-id: f1d758ba
x-rate-limit-limit: 1m
x-rate-limit-remaining: 999
x-rate-limit-reset: 2022-08-27T18:23:48.8071879Z
```

In this example, `x-rate-limit-remaining: 999` shows there are 999 requests left in the current minute window, and the limit will reset at `2022-08-27T18:23:48Z`.

### Handling a 429 Response

When your application receives an `HTTP 429`, implement a back-off and retry strategy:

1. Read the `x-rate-limit-reset` header to determine exactly when the window resets.
2. Pause requests until that timestamp is reached.
3. Resume sending requests at the start of the new window.

<Warning>
  Do not retry a `429` response immediately in a tight loop — doing so will not succeed and will consume retries that could be used for legitimate requests. Always wait until the `x-rate-limit-reset` timestamp before resuming.
</Warning>