io.github.pelazas/carrydesk

carrydesk

Cross-sectional funding-carry rankings for Hyperliquid perpetuals, sold per call in USDC.

Every hour, rank the liquid Hyperliquid perp universe by trailing 14-day mean funding. The most negative names pay you to hold them long; the most positive pay you to short them. The spread between those two legs is the carry — a structural risk premium, not a prediction.

This is the same signal a live market-neutral book trades, published as an API.

Endpoints

Paid endpoints are metered with x402: the server answers 402 with payment requirements, your client pays USDC on Base, retries, and gets the data. No account, no API key, no invoice.

Quick start

curl -s https://carry.pelazas.com/v1/free/carry | jq

{
  "carry_spread_annualized": 0.3901,
  "carry_spread_annualized_trimmed": 0.2231,
  "carry_spread_annualized_median": 0.0955,
  "headline_vs_typical": 4.09,
  "outlier_dominated": true,
  "longs":  [{"coin": "PENGU", "mean_funding_annualized": -0.0636}, ...],
  "shorts": [{"coin": "SAGA",  "mean_funding_annualized":  1.9886}, ...]
}

Three spread numbers, always, plus two that say how far apart they are. The headline mean is what an equal-weighted book earns; the median is what a typical coin pays. headline_vs_typical is the multiple between them — about 4 in the sample above, and around 4 in practice — and outlier_dominated fires when the median drops below half the mean. On the reading above, SAGA alone accounts for most of the gap — that is exactly the kind of thing a single number would hide.

MCP

claude mcp add carrydesk -- uvx --from carrydesk carrydesk-mcp

No clone, no virtualenv — uvx fetches and runs it.

Six tools: carry_snapshot, carry_method, carry_health (free) and carry_rankings, carry_history, carry_universe (paid). It talks to https://carry.pelazas.com by default — override with CARRYDESK_API_BASE.

Set CARRYDESK_PRIVATE_KEY to let the agent pay automatically. Without it the free tools work and paid tools return the price instead of failing, so a wallet-less install is still useful.

Local development

uv venv --python 3.12 && uv pip install -e ".[dev]"
.venv/bin/python -m uvicorn carrydesk.api:app --reload   # open, no paywall
.venv/bin/python -m pytest -q                            # full suite, no network

With X402_PAY_TO unset the service runs fully open — that is the dev default. Set it to turn the paywall on. See .env.example.

For agents and crawlers

/llms.txt describes the whole service in plain text. /openapi.json is the full spec, /archive is every snapshot ever published, and the public page carries schema.org Dataset markup. Crawlers are explicitly welcome — the free tier exists to be read, indexed and quoted.

Honest limitations

• The carry spread can and does go negative. This is compensation for absorbing crowded leverage, not a forecast.
• All figures are gross of fees, slippage and borrow. Taker fees alone can erase the edge; the reference book is maker-only for that reason.
• Funding is Hyperliquid's own, with no cross-venue reconciliation yet.
• Illiquid names dominate the headline spread more often than not. Read the trimmed and median variants before sizing anything.
• Informational only. Not investment advice.

Repo docs