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

# Gas Prices

> Get current and historical gas prices for supported blockchains

## GET /leokit/gas-price/\[asset]

Get current or historical gas prices for a specific chain.

### Request

```http theme={null}
GET /leokit/gas-price/ETH
```

OR

```http theme={null}
GET /leokit/gas-price/BTC.BTC
```

**Path Parameter:** Chain name or asset identifier (e.g., "ETH", "BTC", "BTC.BTC")

## Response Formats

The API returns different response formats based on the chain's pricing model.

## Fixed Price Chains (Cosmos)

For Cosmos-based chains with fixed gas prices.

### Response

**Status Code:** `200 OK`

```json theme={null}
{
  "type": "fixed",
  "units": "rune",
  "gas_prices": 0.02
}
```

### Fixed Price Chains

| Chain | Token | Gas Price |
| ----- | ----- | --------- |
| THOR  | RUNE  | 0.02      |
| MAYA  | CACAO | 0.02      |
| GAIA  | ATOM  | 0.025     |
| KUJI  | KUJI  | 0.00119   |

### Response Fields

| Field        | Type   | Description                               |
| ------------ | ------ | ----------------------------------------- |
| `type`       | string | Always "fixed" for Cosmos chains          |
| `units`      | string | Token denomination (e.g., "rune", "atom") |
| `gas_prices` | number | Fixed gas price per transaction           |

## Dynamic Price Chains (EVM, UTXO)

For chains with variable gas prices.

### Response

**Status Code:** `200 OK`

```json theme={null}
{
  "type": "dynamic",
  "units": "gwei",
  "gas_prices": [
    [50.5, 1705324800],
    [48.2, 1705324740],
    [52.1, 1705324680],
    [49.8, 1705324620]
  ]
}
```

### Response Fields

| Field        | Type   | Description                                         |
| ------------ | ------ | --------------------------------------------------- |
| `type`       | string | Always "dynamic" for EVM and UTXO chains            |
| `units`      | string | Unit of measurement (e.g., "gwei", "satoshi/vbyte") |
| `gas_prices` | array  | Array of \[price, timestamp] tuples                 |

### Gas Prices Array Format

Each entry in the `gas_prices` array is a tuple:

```javascript theme={null}
[price, timestamp]
```

* **price** (number): Gas price in specified units
* **timestamp** (number): Unix timestamp
* **ordering**: Descending by timestamp (most recent first)
* **limit**: Last 200 entries

### Units by Chain

Different chains use different units for gas pricing:

**EVM Chains (gwei):**

* ETH (Ethereum)
* ARB (Arbitrum)
* AVAX (Avalanche)
* BSC (Binance Smart Chain)
* BASE (Base)
* POLYGON (Polygon)
* OPTIMISM (Optimism)
* FANTOM (Fantom)

**UTXO Chains:**

* **Bitcoin**: `satoshi/vbyte`
* **Litecoin**: `satoshi/vbyte`
* **Dogecoin**: `shibes/vbyte`

## Example Responses

### Ethereum (Dynamic)

```json theme={null}
{
  "type": "dynamic",
  "units": "gwei",
  "gas_prices": [
    [45.2, 1705324800],
    [47.8, 1705324740],
    [44.5, 1705324680],
    [46.1, 1705324620],
    [48.9, 1705324560]
  ]
}
```

### Bitcoin (Dynamic)

```json theme={null}
{
  "type": "dynamic",
  "units": "satoshi/vbyte",
  "gas_prices": [
    [25, 1705324800],
    [23, 1705324740],
    [26, 1705324680],
    [24, 1705324620],
    [22, 1705324560]
  ]
}
```

### THORChain (Fixed)

```json theme={null}
{
  "type": "fixed",
  "units": "rune",
  "gas_prices": 0.02
}
```

### Cosmos Hub (Fixed)

```json theme={null}
{
  "type": "fixed",
  "units": "atom",
  "gas_prices": 0.025
}
```

## Data Source

* **Database:** Fetched from `gas_prices` table
* **Updates:** Periodically updated by background workers
* **Historical Data:** Available for trend analysis and prediction
* **Retention:** Last 200 data points per chain

## Use Cases

### Estimating Transaction Costs

Use gas prices to calculate estimated transaction fees before initiating a swap:

```javascript theme={null}
// Fetch current gas price
const response = await fetch('/leokit/gas-price/ETH', {
  headers: {
    'Api-Key': 'your_api_key'
  }
});

const data = await response.json();

if (data.type === 'dynamic') {
  // Get most recent price (first in array)
  const currentGasPrice = data.gas_prices[0][0];
  console.log(`Current ETH gas price: ${currentGasPrice} ${data.units}`);

  // Calculate estimated fee (example: standard ETH transfer uses ~21000 gas)
  const gasLimit = 21000;
  const estimatedFeeGwei = currentGasPrice * gasLimit;
  const estimatedFeeETH = estimatedFeeGwei / 1e9;

  console.log(`Estimated transaction fee: ${estimatedFeeETH} ETH`);
} else if (data.type === 'fixed') {
  console.log(`Fixed gas price: ${data.gas_prices} ${data.units}`);
}
```

### Gas Price Trends

Analyze historical gas prices to recommend optimal transaction timing:

```javascript theme={null}
const response = await fetch('/leokit/gas-price/ETH', {
  headers: {
    'Api-Key': 'your_api_key'
  }
});

const data = await response.json();

if (data.type === 'dynamic') {
  const prices = data.gas_prices.map(entry => entry[0]);

  // Calculate average
  const average = prices.reduce((a, b) => a + b, 0) / prices.length;

  // Get current price
  const current = prices[0];

  // Determine if now is a good time to transact
  if (current < average * 0.9) {
    console.log('Gas prices are below average - good time to transact!');
  } else if (current > average * 1.1) {
    console.log('Gas prices are above average - consider waiting');
  } else {
    console.log('Gas prices are near average');
  }
}
```

### Chart Visualization

Display gas price trends over time:

```javascript theme={null}
const response = await fetch('/leokit/gas-price/BTC', {
  headers: {
    'Api-Key': 'your_api_key'
  }
});

const data = await response.json();

if (data.type === 'dynamic') {
  // Prepare data for charting library
  const chartData = data.gas_prices.map(([price, timestamp]) => ({
    x: new Date(timestamp * 1000), // Convert to milliseconds
    y: price
  }));

  // chartData is now ready for use with Chart.js, D3, etc.
  console.log('Chart data points:', chartData.length);
}
```

## Best Practices

1. **Cache Responses**: Gas prices don't change every second - cache for 10-30 seconds
2. **Handle Both Types**: Always check the `type` field and handle both "fixed" and "dynamic" responses
3. **Current Price**: For dynamic prices, the first array entry `gas_prices[0][0]` is the most recent
4. **Error Handling**: Implement fallback values if the endpoint is unavailable
5. **Display Units**: Always show the `units` field to users for clarity

## Error Responses

**Unsupported Chain (404)**

```json theme={null}
{
  "error": "Gas price data not available for this chain",
  "status": 404
}
```

**Invalid API Key (403)**

```json theme={null}
{
  "error": "Unknown Api-Key",
  "status": 403,
  "code": "CLIENT_CONFIG_IS_NOT_SET"
}
```