Metadata-Version: 2.4
Name: perquants-mcp
Version: 0.1.0
Summary: MCP connector for perquants — pay-per-call Hyperliquid derivatives data (funding, basis, HIP-3 health) over x402.
Project-URL: Homepage, https://api.perquants.com
Project-URL: Source, https://github.com/CarlosTejeiro/perquants-mcp
Author: perquants
License: MIT
License-File: LICENSE
Keywords: agents,basis,defi,funding,hip3,hyperliquid,mcp,perpetuals,x402
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: eth-account>=0.13
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.2
Requires-Dist: x402[evm]>=2.12
Description-Content-Type: text/markdown

# perquants-mcp

MCP connector for **[perquants](https://api.perquants.com)** — specialized Hyperliquid
derivatives data for AI agents, **pay-per-call over [x402](https://x402.org)** (USDC on
Base). No account, no API key — your agent pays a few cents per call from its own wallet.

Three tools:

| Tool | Returns | Price |
|---|---|---|
| `get_funding(coin)` | Funding rate: latest, annualized, 24h/7d means, sign streaks | ~$0.01 |
| `get_basis(coin)` | Spot-perp premium (basis) in bps + means, streaks, churn | ~$0.01 |
| `get_hip3_health(dex, asset)` | HIP-3 builder-market health: oracle deviation, liquidity, OI vs cap, risk flags, 0–100 score | ~$0.02 |

`get_hip3_health` is the differentiator — risk analytics for builder-deployed perps
(tokenized stocks, commodities, forex, pre-IPO) that no free API packages.

## Install

Run it with no install via `uvx` straight from the repo:

```bash
uvx --from git+https://github.com/CarlosTejeiro/perquants-mcp perquants-mcp
```

Or install into an environment:

```bash
pip install git+https://github.com/CarlosTejeiro/perquants-mcp
```

> Once published to PyPI this becomes simply `uvx perquants-mcp` / `pip install perquants-mcp`.

## Configure your wallet

Paid calls are settled on **Base mainnet in USDC**, so the connector needs a wallet
private key with a little USDC (and a few cents of ETH for nothing — x402 settlement is
gasless for the buyer). Use a **dedicated, low-balance wallet**, never your main one.

```bash
export PERQUANTS_BUYER_KEY=0x<private key of a Base wallet funded with USDC>
```

Without `PERQUANTS_BUYER_KEY`, the tools return a clear "payment required" error.

## Use in Claude Desktop / Cursor

Add to your MCP config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "perquants": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/CarlosTejeiro/perquants-mcp", "perquants-mcp"],
      "env": { "PERQUANTS_BUYER_KEY": "0x<your Base wallet private key>" }
    }
  }
}
```

Then ask your agent things like *"what's the funding on HYPE?"* or *"is the xyz:NVDA
HIP-3 market healthy?"* and it calls the tools (paying per call).

## Use from Python

```python
from perquants_mcp import PerquantsClient

client = PerquantsClient(buyer_key="0x...")   # omit to only read free/402 responses
print(client.get_json("/api/v1/hip3/xyz/NVDA"))
```

## How it works

The connector is a thin client: it `GET`s the hosted perquants API, and on a
`402 Payment Required` it signs an x402 USDC payment with your wallet and retries. It
holds no funds and runs locally — your key never leaves your machine.

- Service & live docs: https://api.perquants.com
- Discoverable in the x402 Bazaar (search *"Hyperliquid funding"*).

Returns data/metrics, **not financial advice**.

## License

MIT — see [LICENSE](LICENSE).
