# mPerp and Position-Fee API

Use these endpoints to show mPerp mark-price gaps and position fees. All timestamps are Unix milliseconds. All rates and USD values are decimal strings.

Use the HTTP and Archive API hosts for your environment from [API Hosts](/protocol-reference/api-hosts).

## List Mark-Price Gaps

```http
GET /v1/product/mark-price-gap
```

Required query parameters:

| Parameter    | Description                                |
| ------------ | ------------------------------------------ |
| `productIds` | One or more comma-separated product UUIDs. |
| `startTime`  | Start of the requested time range.         |
| `endTime`    | End of the requested time range.           |

Optional pagination parameters are `limit`, `order`, `orderBy`, and `cursor`.

```bash
curl 'https://api.meridiantest.net/v1/product/mark-price-gap?productIds=PRODUCT_UUID&startTime=1785542400000&endTime=1786147200000&order=asc'
```

```json
{
  "data": [
    {
      "productId": "PRODUCT_UUID",
      "startTime": 1785592800000,
      "endTime": 1785614400000
    }
  ],
  "hasNext": false
}
```

A gap is a window in which Meridian uses a frozen mark for the product.

## Get Projected Position Fees

```http
GET /v1/position-fee/projected-rate
```

Send one or more comma-separated product UUIDs in `productIds`.

```bash
curl 'https://api.meridiantest.net/v1/position-fee/projected-rate?productIds=PRODUCT_UUID'
```

```json
{
  "data": [
    {
      "productId": "PRODUCT_UUID",
      "scheduledAt": 1785593700000,
      "cadenceMinutes": 15,
      "positionFeeRate": "0.000064213"
    }
  ],
  "hasNext": false
}
```

The rate is a projection. It can change before `scheduledAt`.

## List Applied Product Charges

```http
GET /v1/position-fee
```

Required query parameters are `productId`, `startTime`, and `endTime`.

```bash
curl 'https://api.meridiantest.net/v1/position-fee?productId=PRODUCT_UUID&startTime=1785592800000&endTime=1785614400000&order=asc'
```

```json
{
  "data": [
    {
      "chargedAt": 1785593700000,
      "cadenceMinutes": 15,
      "positionFeeRate": "0.000064213",
      "chargePerUnitUsd": "0.5"
    }
  ],
  "hasNext": false
}
```

## Get Subaccount Position-Fee History

Use the Archive API:

```http
GET /v1/subaccount/position-fee
```

Required query parameters are `subaccountId` and `startTime`. `endTime`, `positionIds`, and `productIds` are optional filters.

The response includes:

* `time` and `settledAt`.
* `productId` and `productTicker`.
* `positionId`, `positionSide`, and `positionQuantity`.
* `rate` and `referencePrice`.
* `chargePerUnitUsd` and `positionFeeCharge`.

## Integration Notes

* Refresh gaps instead of storing a permanent market-hours table.
* Treat projected fees as estimates.
* Use applied charges for accounting.
* Include `positionFeeUsd` when you display current position equity.
* Use cursor pagination for history.
* Keep decimal strings as exact decimal or integer values.

See [Position Fees](/trading/perpetual-futures/position-fees) for user-facing behavior.