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

# Funding

> Perp funding per coin as an APR, ranked against every perp in the market, plus market temperature and funding alerts.

Funding is what perp longs and shorts pay each other to hold a position. Shumi turns each coin's rate into a yearly APR, ranks it against every perp it tracks, and gives the whole market a temperature.

## Get funding for one coin or the market

<Tabs>
  <Tab title="Terminal">
    ```bash theme={"dark"}
    shumi funding momentum --symbol BTC
    shumi funding momentum
    ```

    Bare `shumi funding` prints help only.
  </Tab>

  <Tab title="API">
    ```bash theme={"dark"}
    curl "https://api.shumi.ai/api/cli/funding/momentum?symbol=BTC" \
      -H "Authorization: Bearer shumi_sk_your_key_here"
    ```
  </Tab>

  <Tab title="AI agent">
    Connect the [MCP server](/agents/mcp) and call `get_funding_momentum`, with `symbol` for one coin.
  </Tab>
</Tabs>

## Read one coin

```json theme={"dark"}
{"symbol":"BTC","apr":11,"ratePct":0.0013,"intervalH":1,"source":"hyperliquid","tier":"neutral","percentile":0.65}
```

| Field | Meaning |
| - | - |
| `apr` | Funding as a yearly rate, in percent. `11` means 11% a year |
| `ratePct` | The raw rate per funding interval, in percent |
| `intervalH` | Hours between funding payments on the source venue |
| `source` | The venue the rate came from |
| `percentile` | Where this APR sits among every perp in the snapshot (616 in the example). `0.65` means higher than 65% of them |
| `tier` | The percentile as a label |

The tier uses the exact percentile; the response shows it rounded to two decimals, so a displayed `0.80` can still be `neutral`.

| Percentile | Tier |
| - | - |
| 0.90 and above | `hot` |
| 0.80 to 0.89 | `warm` |
| 0.21 to 0.79 | `neutral` |
| 0.11 to 0.20 | `cool` |
| 0.10 and below | `cold` |

`--symbol` answers for any perp in the snapshot. The market-wide call returns:

* a fixed watch list of large coins, 43 in the example, sorted by APR
* `market`: the market `temperature`, such as `neutral`, and the median APR it is read from
* `distribution`: `p10` to `p90`, `min`, `max` and `totalAssets`

## Read the market temperature

`market.temperature` reads the median perp's funding against the resting rate. Hyperliquid and Variational charge a fixed interest component, so about 10.95% APR is what a perp pays with no crowding at all. Only funding above or below that is positioning. `medianPremiumApr` is that difference:

| `medianPremiumApr` | Temperature |
| - | - |
| 20 or more | `hot` |
| 5 to 20 | `warm` |
| -5 to 5 | `neutral` |
| -20 to -5 | `cool` |
| below -20 | `cold` |

For example: `"temperature":"neutral","medianApr":11,"medianPremiumApr":0`. `positive`, `negative` and `total` count the coins on the watch list. Quote `medianApr` as the market level, not `avgApr`: one broken market can pull the average anywhere.

## What positive and negative funding cost you

Positive funding: longs pay, shorts receive. Negative funding: shorts pay, longs receive. `shumi coin risk BTC` spells it out for the coin in `funding_paying_side`, `carry_if_long` and `carry_if_short`, for example "Long perpetual positions pay funding at +11.0% APR."

<Note>
  Funding applies to perpetual positions only. A spot position pays and receives nothing.
</Note>

Funding tells you who is crowded and what a held position costs. For timing, pair it with the trend in a [signal](/trade-decisions/signals).

## See funding alerts

```bash theme={"dark"}
shumi funding alerts
```

API: `GET /api/cli/funding/alerts`. Agent tool: `get_funding_alerts`.

| Field | Meaning |
| - | - |
| `asset` | The coin |
| `triggerZone` | The zone funding entered, for example `negative` |
| `fundingAtTrigger`, `fundingIntervalH` | The rate when it fired, and the funding interval in hours |
| `source` | The exchange |
| `firedAt` | When it fired |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.