> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/rest-api/market-data/fundingpayments.md).

# fundingPayments

### Overview

The fundingPayments endpoint returns all funding payments from the most recent funding hour across every market and user on Hyperliquid. Data is grouped by coin and compressed using msgpack + zstd.

There are two endpoints:

1. **Metadata Endpoint (Fast)**: Check the current snapshot timestamp and event count
2. **Snapshot Endpoint (Heavy)**: Download the full funding payment data

### Funding Payment Metadata (Fast)

* **Endpoint**: `POST /info`
* **Purpose**: Check the current snapshot timestamp and size without downloading data

#### Request

```json
{
  "type": "fundingPaymentTimestamp"
}
```

#### Response

```json
{
  "time": 1709251200000,
  "count": 198432
}
```

| Field   | Description                            |
| ------- | -------------------------------------- |
| `time`  | Funding hour timestamp in milliseconds |
| `count` | Total number of funding payment events |

### Funding Payments Snapshot (Heavy)

* **Endpoint**: `POST /info`
* **Purpose**: Download the full funding payment snapshot
* **Response**: zstd-compressed msgpack binary

#### Request

```json
{
  "type": "fundingPayments"
}
```

#### Response Headers

| Header             | Value                       |
| ------------------ | --------------------------- |
| `Content-Type`     | `application/zstd`          |
| `x-payload-format` | `msgpack`                   |
| `x-snapshot-time`  | Funding hour timestamp (ms) |
| `x-snapshot-count` | Total event count           |

### Data Format

The response body is a zstd-compressed msgpack binary. After decompressing (zstd) and decoding (msgpack), the payload is an array:

```json
[
  1709251200000,
  [
    ["BTC", "0.0001", ["0xabc...", "0xdef..."], ["12.345", "-5.678"], ["1.5", "-0.8"]],
    ["ETH", "-0.00005", ["0x123..."], ["-2.1"], ["10.0"]]
  ]
]
```

| Index      | Description                                                    |
| ---------- | -------------------------------------------------------------- |
| `[0]`      | Funding hour timestamp in milliseconds                         |
| `[1]`      | Array of per-coin funding data                                 |
| `[1][][0]` | Coin name (e.g., "BTC", "ETH")                                 |
| `[1][][1]` | Funding rate for this coin (string, same for all users)        |
| `[1][][2]` | User addresses (parallel array)                                |
| `[1][][3]` | Funding payment amounts per user (string, parallel with `[2]`) |
| `[1][][4]` | Position sizes per user (string, parallel with `[2]`)          |

All numeric values (rate, amounts, sizes) are decimal strings for exact precision.

### Implementation Examples

**Note**: Set **HYDROMANCER\_API\_KEY** in your .env file.

{% tabs %}
{% tab title="Python" %}

```python
import asyncio
import io
import aiohttp
import zstandard as zstd
import msgpack
import os
from dotenv import load_dotenv

load_dotenv()


async def get_funding_payments():
    base_url = os.getenv("HYDROMANCER_API_URL", "https://api.hydromancer.xyz")
    api_key = os.getenv("HYDROMANCER_API_KEY")
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}",
    }

    async with aiohttp.ClientSession() as session:
        # 1. Check metadata first
        async with session.post(
            f"{base_url}/info",
            json={"type": "fundingPaymentTimestamp"},
            headers=headers,
        ) as resp:
            meta = await resp.json()
            print(f"Snapshot time: {meta['time']}, events: {meta['count']}")

        # 2. Download snapshot
        async with session.post(
            f"{base_url}/info",
            json={"type": "fundingPayments"},
            headers=headers,
        ) as resp:
            compressed = await resp.read()
            print(f"Downloaded {len(compressed)} bytes")

            # Decompress and decode
            dctx = zstd.ZstdDecompressor()
            raw = dctx.stream_reader(io.BytesIO(compressed)).read()
            data = msgpack.unpackb(raw, raw=False)

            timestamp, markets = data[0], data[1]
            print(f"Funding hour: {timestamp}")
            print(f"Markets: {len(markets)}")

            for market in markets:
                coin, rate, addresses, amounts, sizes = market
                print(f"  {coin}: rate={rate}, users={len(addresses)}")


asyncio.run(get_funding_payments())
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');
const { decompress } = require('@mongodb-js/zstd');
const msgpack = require('msgpack-lite');
require('dotenv').config();

async function getFundingPayments() {
    const baseUrl = process.env.HYDROMANCER_API_URL || 'https://api.hydromancer.xyz';
    const apiKey = process.env.HYDROMANCER_API_KEY;
    const headers = {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`
    };

    // 1. Check metadata first
    const metaResp = await axios.post(
        `${baseUrl}/info`,
        { type: 'fundingPaymentTimestamp' },
        { headers }
    );
    console.log(`Snapshot time: ${metaResp.data.time}, events: ${metaResp.data.count}`);

    // 2. Download snapshot
    const resp = await axios.post(
        `${baseUrl}/info`,
        { type: 'fundingPayments' },
        { headers, responseType: 'arraybuffer' }
    );

    const compressed = Buffer.from(resp.data);
    console.log(`Downloaded ${compressed.length} bytes`);

    // Decompress and decode
    const raw = await decompress(compressed);
    const data = msgpack.decode(raw);

    const [timestamp, markets] = data;
    console.log(`Funding hour: ${timestamp}`);
    console.log(`Markets: ${markets.length}`);

    for (const [coin, rate, addresses, amounts, sizes] of markets) {
        console.log(`  ${coin}: rate=${rate}, users=${addresses.length}`);
    }
}

getFundingPayments().catch(console.error);
```

{% endtab %}
{% endtabs %}