Perpetual Swap Funding Rate Data and Its Metadata
Summary
This document defines a funding-rate update record for a perpetual swap instrument. It identifies the instrument and rate, and may include the funding interval and next scheduled funding timestamp when supplied by the venue. Event and initialization timestamps are also part of the record, supporting the distinction between when the update occurred and when it was initialized in a data system.
The update is cached by instrument, while equality and hashing are based on the instrument, rate, interval, and next funding time. The document stresses that a funding-rate update is reference data: receiving it does not mean that a funding payment has been applied. Interval and next-funding fields may be absent, so consumers should treat them as optional and only rely on them when the venue provides them. Examples illustrate the record in Rust and Python, but the page does not discuss how rates are calculated or settled.
Key ideas
- A funding-rate update associates a current rate with a perpetual swap instrument.
- Funding interval and next funding time are optional venue-provided metadata.
- Event and initialization timestamps record timing information for the update.
- Receiving a rate update does not indicate that a funding payment has occurred.
- The record is cached by instrument, and its equality and hashing use its identifying funding fields.
Tags
Full text
# FundingRateUpdate
# FundingRateUpdate
`FundingRateUpdate` represents the funding rate for a perpetual swap instrument. It can also include
the funding interval and next funding timestamp when the venue publishes them.
## Fields
| Field | Rust type | Python type | Required/default | Notes |
| ----------------- | ------------------- | -------------- | ---------------- | ---------------------------------------- |
| `instrument_id` | `InstrumentId` | `InstrumentId` | Required | Perpetual instrument for the rate. |
| `rate` | `Decimal` | `Decimal` | Required | Current funding rate. |
| `interval` | `Option<u16>` | `int \| None` | `None` | Funding interval in minutes. |
| `next_funding_ns` | `Option<UnixNanos>` | `int \| None` | `None` | Next funding timestamp in nanoseconds. |
| `ts_event` | `UnixNanos` | `int` | Required | Event timestamp in nanoseconds. |
| `ts_init` | `UnixNanos` | `int` | Required | Initialization timestamp in nanoseconds. |
## Behavior
- Funding rates are cached by instrument when received.
- Equality and hashing use instrument ID, rate, interval, and next funding time.
- Funding rates are reference data and do not imply a payment was applied.
- Use `interval` and `next_funding_ns` only when the venue publishes them.
## Example
```rust tab="Rust"
use nautilus_core::UnixNanos;
use nautilus_model::{data::FundingRateUpdate, identifiers::InstrumentId};
use rust_decimal::Decimal;
let funding = FundingRateUpdate::new(
InstrumentId::from("BTCUSDT-PERP.BINANCE"),
Decimal::new(1, 4),
Some(480),
Some(UnixNanos::from(1_000_008_000)),
UnixNanos::from(1_000_000_000),
UnixNanos::from(1_000_000_100),
);
```
```python tab="Python"
from decimal import Decimal
from nautilus_trader.model import FundingRateUpdate
from nautilus_trader.model import InstrumentId
funding = FundingRateUpdate(
instrument_id=InstrumentId.from_str("BTCUSDT-PERP.BINANCE"),
rate=Decimal("0.0001"),
ts_event=1_000_000_000,
ts_init=1_000_000_100,
interval=480,
next_funding_ns=1_000_008_000,
)
```
## Related guides
- [MarkPriceUpdate](mark_price_update.md) covers mark prices for derivatives.
- [IndexPriceUpdate](index_price_update.md) covers index reference prices.
- [Python API reference](/docs/python-api-latest/model/data.html) lists Python members.Shown in full with attribution under the source's licence. Licence: LGPL-3.0
This summary was written by Stratmill's research agent from the original; it is not a copy of the source.