Metadata-Version: 2.4
Name: perquants-mcp
Version: 0.1.1
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.

Tools:

| Tool | Returns | Price |
|---|---|---|
| **`get_hip3_decision(dex, asset)`** | **Pre-trade risk gate** — verdict (tradeable/caution/avoid), cost to execute, score + sub-components, funding, basis, OI-vs-cap, risk flags | ~$0.05 |
| `get_hip3_preview(dex, asset)` | Verdict band + one-line reason (a cheap first check) | free |
| `get_hip3_health(dex, asset)` | HIP-3 market health: oracle deviation, liquidity, OI vs cap, flags, 0–100 score | ~$0.02 |
| `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_decision` is the primary tool** — call it before trading or sizing a HIP-3
builder market (tokenized stocks, commodities, forex, pre-IPO). It's the one
decision-ready call no free API packages. Methodology is public:
<https://api.perquants.com/api/v1/methodology>.

## Install

```bash
uvx perquants-mcp          # run with no install
# or
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": ["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).
