Metadata-Version: 2.4
Name: hyperd-ai
Version: 0.1.0
Summary: Python SDK for hyperD — pay-per-call DeFi APIs for AI agents over x402. 20 paid endpoints on Base USDC, no API key, no signup.
Project-URL: Homepage, https://hyperd.ai
Project-URL: Documentation, https://github.com/hyperd-ai/hyperd-py
Project-URL: Repository, https://github.com/hyperd-ai/hyperd-py
Project-URL: Bug Tracker, https://github.com/hyperd-ai/hyperd-py/issues
Project-URL: x402 protocol, https://x402.org
Author-email: Thomas Potter <hi@hyperd.ai>
License: MIT
License-File: LICENSE
Keywords: agent-tools,ai-agents,base,defi,eip-3009,hyperd,langchain,usdc,x402
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: eth-account>=0.10.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3.0; extra == 'langchain'
Description-Content-Type: text/markdown

# hyperd-ai — Python SDK

> Pay-per-call DeFi APIs for AI agents on Base. 20 paid x402 endpoints, USDC settlement in ~2s, no API key, no signup. The signed EIP-3009 payment is the auth.

[![PyPI](https://img.shields.io/pypi/v/hyperd-ai.svg)](https://pypi.org/project/hyperd-ai/)
[![Python](https://img.shields.io/pypi/pyversions/hyperd-ai.svg)](https://pypi.org/project/hyperd-ai/)
[![License](https://img.shields.io/pypi/l/hyperd-ai.svg)](./LICENSE)

## Install

```bash
pip install hyperd-ai
```

For LangChain Tool wrappers:

```bash
pip install 'hyperd-ai[langchain]'
```

## Quick start

```python
from hyperd import HyperD

# private_key can be passed explicitly or read from HYPERD_WALLET_PRIVATE_KEY env
client = HyperD(private_key="0x...")

# Cost: $0.10 USDC — auto-signed and settled
risk = client.wallet_risk("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")
print(risk["sanctioned"], risk["risk_tier"], risk["categories"])

# Cost: $0.05
pnl = client.wallet_pnl("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", chain="base")
print(f"Total P&L: ${pnl['total_pnl_usd']:.2f}")
```

## Fund the wallet

The wallet at `private_key` must hold USDC on Base. Typical agent runs cost a few cents — **~$5 of USDC is enough for hundreds of decision cycles.**

- Buy USDC directly on Base via Coinbase / Coinbase Wallet
- Bridge from Ethereum via [Across](https://across.to) or [Hop](https://hop.exchange)
- Get a test wallet at any Ethereum wallet generator (don't use your primary)

## Endpoints

### Marquee (the agent decision loop — $0.32 total)

| Method | Cost | What it answers |
|---|---|---|
| `client.wallet_risk(address)` | $0.10 | Is this address OFAC-sanctioned or otherwise risky? |
| `client.token_security(contract, chain)` | $0.05 | Is this token a scam? (GoPlus 0-100 score) |
| `client.liquidation_risk(address, chain)` | $0.10 | Cross-protocol health across Aave V3 / Compound v3 / Spark / Morpho |
| `client.wallet_pnl(address, chain)` | $0.05 | Realized + unrealized P&L, per-token breakdown |
| `client.dex_quote(from_token, to_token, amount, chain)` | $0.02 | Best swap route (Paraswap + 0x) |

### Secondary

| Method | Cost |
|---|---|
| `client.balance(address, chain)` | $0.01 |
| `client.token_info(query)` | $0.01 |
| `client.yield_recommend(amount, risk)` | $0.05 |
| `client.protocol_tvl(slug)` | $0.01 |
| `client.gas_estimate(chain)` | $0.005 |
| `client.wallet_persona(address)` | $0.10 |
| `client.contract_audit(contract, chain)` | $0.10 |
| `client.governance_summarize(proposal_url)` | $0.10 |
| `client.sentiment_token(token, window)` | $0.05 |
| `client.wallet_anomaly(address, chain, window)` | $0.10 |
| `client.budget_guardian(address)` | $0.01 |
| `client.bundle(calls)` | $0.20 fixed (up to 10 calls bundled) |

### Free (no payment)

| Method | What |
|---|---|
| `client.health()` | Liveness + version |
| `client.catalog()` | Full machine-readable catalog of every endpoint + price |

## LangChain

```python
from hyperd.langchain import get_tools
from langchain.agents import create_react_agent
from langchain_openai import ChatOpenAI

tools = get_tools(private_key="0x...")  # 5 marquee endpoints as StructuredTools
llm = ChatOpenAI(model="gpt-4o-mini")
agent = create_react_agent(llm, tools)

result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "Is 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 safe to send funds to?",
    }],
})
```

The agent will pick `hyperd_wallet_risk` from the tool list, sign + settle the payment, and return the result to the LLM for synthesis.

## Safety: the per-call USDC cap

Every paid method respects `max_usdc_per_call` (default $0.25). If the server's 402 challenge requests more than that, the SDK throws `HyperdPaymentRefused` BEFORE signing — your wallet can't be drained even by a misbehaving or compromised server.

To raise the cap (e.g. for the $3 watch.create endpoint):

```python
client = HyperD(private_key="0x...", max_usdc_per_call=5.0)
```

## How the x402 payment works

1. The SDK makes a normal HTTP GET to the paid endpoint.
2. The server responds with HTTP 402 Payment Required and a machine-readable payment-required header.
3. The SDK decodes the header, signs an EIP-3009 USDC transfer authorization on Base, and retries with the signed payment in the `X-Payment` header.
4. Coinbase's x402 facilitator verifies the signature, submits the transfer on-chain, and unblocks the response. ~2 seconds end-to-end.

There's no key store to rotate, no rate-limit form to fill out, no signup. The signature is the auth.

## Errors

| Exception | When |
|---|---|
| `HyperdPaymentRefused` | Server requested more USDC than `max_usdc_per_call` |
| `HyperdHttpError` | Server returned a non-2xx after the payment retry |
| `HyperdError` | Malformed 402 challenge, missing EIP-712 domain fields, or signing error |

All three inherit from `HyperdError` so you can catch the umbrella class.

## Links

- **Production API**: https://api.hyperd.ai
- **Endpoint catalog**: https://api.hyperd.ai/api/catalog
- **ElizaOS plugin**: [`@hyperd-ai/plugin-hyperd`](https://www.npmjs.com/package/@hyperd-ai/plugin-hyperd) (TypeScript)
- **MCP server**: [`hyperd-mcp`](https://www.npmjs.com/package/hyperd-mcp) (stdio for Claude Desktop / Cursor / Cline / Zed)
- **Glama listing**: https://glama.ai/mcp/servers/hyperd-ai/hyperd-mcp
- **x402 protocol**: https://x402.org

## License

MIT. Built for agents that pay their own way.
