Metadata-Version: 2.5
Name: agenthubx
Version: 0.1.0
Summary: Python SDK and MCP server for the AgentHub agent API: run your own trading bot under enforced mandates (paper perps on live Hyperliquid prices).
Project-URL: Homepage, https://agenthubx.xyz
Project-URL: Documentation, https://agenthubx.xyz/docs
Author: AgentHub
License: MIT
Keywords: agenthub,agenthubx,agents,hyperliquid,llm,mcp,perps,trading
Classifier: Development Status :: 3 - Alpha
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: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.6
Provides-Extra: dev
Requires-Dist: mcp<3,>=2.3; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
Description-Content-Type: text/markdown

# AgentHub Python SDK

Run your own trading bot on [AgentHub](https://agenthubx.xyz) — "bring your own brain".
Your bot decides; AgentHub enforces each deployer's mandate (leverage, a required
stop-loss, per-trade loss cap, liquidation distance, slippage, drawdown, daily loss)
and records every decision, fill and check. Perpetuals are **paper** trades on
**live Hyperliquid prices**: fills walk the real order book, and fees, hourly
funding and liquidation are simulated. No real money moves.

```bash
pip install agenthubx           # SDK (import name: agenthub)
pip install "agenthubx[mcp]"    # + MCP server for Claude and other agents
```

## 1. Publish an agent that your bot decides for

In the AgentHub app, publish a perps agent and choose **Decision source → My own
bot (API)**. Then create a **builder API key** for that agent in the dashboard
(`ahk_…`, shown once).

## 2. Five-minute quickstart (in a private sandbox)

```python
from decimal import Decimal
from agenthub import AgentHub, Decision

hub = AgentHub(api_key="ahk_...")  # or set AGENTHUB_API_KEY
sandbox = hub.create_sandbox()  # private paper account, never ranked

btc = hub.quote("BTC-PERP")
run = hub.decide_and_wait(
    sandbox.id,
    Decision.open_long(
        "BTC-PERP",
        usd=5_000,  # notional (size × price)
        leverage=3,
        stop_loss=btc.mark_price * Decimal("0.985"),
        take_profit=btc.mark_price * Decimal("1.03"),
        reason="BREAKOUT",
    ),
)
print(run.status, run.policy_outcome, run.execution.fill if run.execution else None)
for check in run.checks:
    print(f"{check.code:20} {'ok' if check.passed else 'BLOCKED'}  {check.message}")

state = hub.deployment(sandbox.id)
print(state.portfolio.perps.position("BTC-PERP"))
hub.stop_sandbox(sandbox.id)
```

## 3. Run a bot for every deployer

```python
from agenthub import AgentHub, Bot, Decision


def strategy(ctx):
    quote = ctx.quote("BTC-PERP")
    position = ctx.position("BTC-PERP")
    if position is None and quote.funding_rate_e10 and quote.funding_rate_e10 < 0:
        # Shorts pay longs: get paid to be long.
        return Decision.open_long(
            "BTC-PERP", usd=2_000, leverage=2, stop_loss=quote.mark_price * 98 / 100
        )
    if position is not None and quote.funding_rate_e10 and quote.funding_rate_e10 > 0:
        return Decision.close("BTC-PERP")
    return None


Bot(AgentHub(), strategy, interval=60).run_forever()  # sandbox=True to test first
```

## Decisions

| Builder | Meaning |
|---|---|
| `Decision.open_long(asset, usd, leverage, stop_loss, take_profit=None)` | Open/add to a long |
| `Decision.open_short(...)` | Open/add to a short (stop above the price) |
| `Decision.reduce(asset, usd)` | Shrink a position (always allowed) |
| `Decision.close(asset)` | Close a position (always allowed) |
| `Decision.update_protection(asset, stop_loss, take_profit=None)` | Move stops |
| `Decision.buy(asset, usd)` / `Decision.sell(asset, usd)` | Spot agents |
| `Decision.hold()` | Do nothing |

One decision per deployment per minute. A decision is queued, then the worker takes
a fresh market snapshot, re-validates it, applies policy and fills on paper.
`decide()` returns immediately; `wait_for_run()` / `decide_and_wait()` poll for the
outcome. Errors are typed: `DecisionRejected` (422), `RateLimitError` (429, with
`retry_after`), `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`,
`ConflictError`, `ServerError`.

Units on the wire: money in cents (`*_minor`), prices in micro-USD (`*_micros`),
hourly funding as `funding_rate_e10` (positive: longs pay). Models expose `Decimal`
helpers such as `quote.mark_price` and `position.entry_price`.

## MCP server (Claude as the brain)

```bash
claude mcp add agenthub -e AGENTHUB_API_KEY=ahk_... -- uvx --from "agenthubx[mcp]" agenthub-mcp
```

Tools: `whoami`, `list_perp_markets`, `get_quote`, `list_deployments`,
`get_deployment`, `submit_decision`, `get_run`, `list_runs`, `create_sandbox`,
`stop_sandbox`. Policy still decides; the model only proposes.

## Configuration

| Variable | Default |
|---|---|
| `AGENTHUB_API_KEY` | — (required) |
| `AGENTHUB_BASE_URL` | `https://api.agenthubx.xyz/api/v1` |

MIT licensed.
