wayfinder-paths 0.1.23__tar.gz → 0.1.24__tar.gz

wayfinder_paths-0.1.24/PKG-INFO

@@ -0,0 +1,378 @@
+Metadata-Version: 2.3
+Name: wayfinder-paths
+Version: 0.1.24
+Summary: Wayfinder Path: strategies and adapters
+Author: Wayfinder
+Author-email: dev@wayfinder.ai
+Requires-Python: >=3.12,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: aiocache (>=0.12.3,<0.13.0)
+Requires-Dist: aiohttp (>=3.13.0,<4.0.0)
+Requires-Dist: eth-account (>=0.13.7,<0.14.0)
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: hyperliquid-felix
+Requires-Dist: loguru (>=0.7.3,<0.8.0)
+Requires-Dist: numpy (>=1.26.0,<2.0.0)
+Requires-Dist: pandas (>=2.2.0,<3.0.0)
+Requires-Dist: pydantic (>=2.11.9,<3.0.0)
+Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
+Requires-Dist: web3 (>=7.13.0,<8.0.0)
+Description-Content-Type: text/markdown
+
+# Wayfinder Paths SDK
+
+[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/wayfinder-paths.svg)](https://pypi.org/project/wayfinder-paths/)
+[![Discord](https://img.shields.io/badge/discord-join-7289da.svg)](https://discord.gg/fUVwGMXjm3)
+
+**An open-source SDK for building and managing automated DeFi strategies.** Use it locally to deposit into, monitor, rebalance, and exit strategies across multiple chains and protocols. Powered by the [Wayfinder API](https://wayfinder.ai).
+
+## What is Wayfinder Paths?
+
+Wayfinder Paths is an SDK that lets you:
+
+- **Enter and exit DeFi strategies** - Deposit funds, let strategies auto-rebalance, withdraw when ready
+- **Build custom trading paths** - Create your own adapters and strategies for any protocol
+- **Use Claude as your DeFi co-pilot** - With MCP (Model Context Protocol) integration, Claude can execute swaps, check balances, place perp orders, and manage your positions conversationally
+
+Think of it as programmable DeFi infrastructure that connects your wallets to yield strategies, perpetual exchanges, lending protocols, and cross-chain bridges.
+
+## Getting Your Wayfinder API Key
+
+**You need a Wayfinder API key to use this SDK.** The API provides token resolution, cross-chain routing, balance queries, and more.
+
+1. Go to [wayfinder.ai](https://wayfinder.ai)
+2. Create an account or log in
+3. Navigate to your account settings to generate an API key
+4. Add it to your `config.json` under `system.api_key`
+
+## Quick Start
+
+```bash
+# Clone the repository
+git clone https://github.com/WayfinderFoundation/wayfinder-paths.git
+cd wayfinder-paths
+
+# One-command setup (installs Poetry + deps, prompts for your Wayfinder API key, updates .mcp.json)
+python3 scripts/setup.py
+
+# Optional: create a strategy-specific wallet
+poetry run python scripts/make_wallets.py --label stablecoin_yield_strategy
+
+# Check strategy status
+poetry run python wayfinder_paths/run_strategy.py stablecoin_yield_strategy --action status --config config.json
+
+# Deposit into a strategy
+poetry run python wayfinder_paths/run_strategy.py stablecoin_yield_strategy --action deposit \
+    --main-token-amount 100 --gas-token-amount 0.01 --config config.json
+```
+
+## Claude MCP Integration
+
+**Turn Claude into an on-chain trading and DeFi engine.** The SDK includes an MCP server that gives Claude direct access to:
+
+- **Wallet balances** across all supported chains
+- **Token swaps** via the BRAP cross-chain router
+- **Hyperliquid perpetuals** - market data, orders, leverage, withdrawals
+- **Strategy management** - analyze, snapshot, and query any strategy
+- **Script execution** - run custom Python scripts from `.wayfinder_runs/`
+
+### Setting Up MCP with Claude Code
+
+This repo includes a project-scoped Claude Code MCP config at `.mcp.json` (you'll be prompted to enable it).
+If you prefer a global config instead, add:
+
+```json
+{
+  "mcpServers": {
+    "wayfinder": {
+      "command": "poetry",
+      "args": ["run", "python", "-m", "wayfinder_paths.mcp.server"],
+      "cwd": "/path/to/wayfinder-paths"
+    }
+  }
+}
+```
+
+### Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `discover` | List available adapters and strategies |
+| `describe` | Get detailed info about any adapter or strategy |
+| `wallets` | List or create local wallets |
+| `tokens` | Resolve token metadata by ID or address |
+| `balances` | Query token/pool balances across chains |
+| `quote_swap` | Get swap quotes without executing |
+| `execute` | Execute swaps, sends, and Hyperliquid deposits |
+| `hyperliquid` | Read-only perp market data and user state |
+| `hyperliquid_execute` | Place orders, update leverage, withdraw |
+| `run_strategy` | Analyze strategies, get snapshots and policies |
+| `run_script` | Execute local Python scripts safely |
+
+### Example Conversation with Claude
+
+```
+You: What's my balance on Arbitrum?
+
+Claude: [Uses balances tool to query your wallet]
+Your Arbitrum wallet (0x81830...) holds:
+- 1,245.32 USDC ($1,245.32)
+- 0.42 ETH ($1,512.00)
+- 15,000 ARB ($8,250.00)
+
+You: Swap 500 USDC to ETH
+
+Claude: [Uses quote_swap, then execute with your approval]
+Swapped 500 USDC for 0.139 ETH via Uniswap V3
+TX: 0xabc123...
+
+You: Open a 2x long on BTC with $1000
+
+Claude: [Uses hyperliquid_execute to place the order]
+Opened BTC-PERP long position:
+- Size: 0.0234 BTC (~$1,000 notional)
+- Leverage: 2x
+- Entry: $42,735.50
+```
+
+## Available Strategies
+
+| Strategy | Description | Chain | Risk |
+|----------|-------------|-------|------|
+| **Stablecoin Yield** | USDC yield optimization across Base pools | Base | Low |
+| **HyperLend Stable Yield** | Stablecoin rotation on HyperLend | HyperEVM | Medium |
+| **Moonwell wstETH Loop** | Leveraged LST carry trade | Base | High |
+| **Basis Trading** | Delta-neutral funding rate capture | Hyperliquid | High |
+| **Boros HYPE** | Multi-leg HYPE yield with rate locking | Multi-chain | High |
+
+### Strategy Lifecycle
+
+```python
+from wayfinder_paths.core.strategies.Strategy import Strategy, StatusDict, StatusTuple
+
+class MyStrategy(Strategy):
+    name = "My Strategy"
+
+    def __init__(self, config=None, **kwargs):
+        super().__init__(config, **kwargs)
+        balance_adapter = BalanceAdapter(config, **kwargs)
+        self.balance_adapter = balance_adapter
+
+    async def deposit(self, main_token_amount=0.0, gas_token_amount=0.0) -> StatusTuple:
+        """Move funds from main wallet into strategy wallet."""
+        return (True, "Deposited successfully")
+
+    async def update(self) -> StatusTuple:
+        """Rebalance or optimize positions."""
+        return (True, "Updated successfully")
+
+    async def exit(self, **kwargs) -> StatusTuple:
+        """Transfer funds from strategy wallet back to main wallet."""
+        return (True, "Exited successfully")
+
+    async def _status(self) -> StatusDict:
+        """Report current state."""
+        return {
+            "portfolio_value": 0.0,
+            "net_deposit": 0.0,
+            "strategy_status": {"message": "healthy"},
+            "gas_available": 0.0,
+            "gassed_up": True,
+        }
+```
+
+## Available Adapters
+
+| Adapter | Purpose | External Protocol |
+|---------|---------|-------------------|
+| **BalanceAdapter** | Wallet balances, cross-wallet transfers | - |
+| **BRAPAdapter** | Cross-chain swaps and bridges | Wayfinder BRAP Router |
+| **BorosAdapter** | Fixed-rate lending positions | Boros Protocol |
+| **HyperliquidAdapter** | Perps, spot, deposits, withdrawals | Hyperliquid DEX |
+| **HyperlendAdapter** | Stablecoin lending | HyperLend Protocol |
+| **MoonwellAdapter** | Lending/borrowing on Base | Moonwell Protocol |
+| **PendleAdapter** | PT/YT discovery + Hosted SDK convert (swap/mint/roll/LP) | Pendle Protocol |
+| **MulticallAdapter** | Batch contract calls | Multicall3 |
+| **LedgerAdapter** | Transaction recording | - |
+| **TokenAdapter** | Token metadata and prices | Wayfinder API |
+| **PoolAdapter** | DeFi pool analytics | DeFi Llama |
+
+## Configuration
+
+Create `config.json` in the project root:
+
+```json
+{
+  "system": {
+    "api_base_url": "https://api.wayfinder.ai",
+    "api_key": "wk_your_api_key_here"
+  },
+  "strategy": {
+    "rpc_urls": {
+      "1": "https://eth.llamarpc.com",
+      "8453": "https://mainnet.base.org",
+      "42161": "https://arb1.arbitrum.io/rpc",
+      "999": "https://rpc.hyperliquid.xyz"
+    }
+  },
+  "wallets": [
+    {
+      "label": "main",
+      "address": "0x...",
+      "private_key_hex": "..."
+    }
+  ]
+}
+```
+
+### Supported Chains
+
+| Chain | ID | Code |
+|-------|-----|------|
+| Ethereum | 1 | `ethereum` |
+| Base | 8453 | `base` |
+| Arbitrum | 42161 | `arbitrum` |
+| Polygon | 137 | `polygon` |
+| BSC | 56 | `bsc` |
+| HyperEVM | 999 | `hyperevm` |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Claude + MCP Server                      │
+│  "Swap 100 USDC to ETH" → execute tool → transaction        │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Strategy Layer                            │
+│  Strategies orchestrate adapters to capture yield            │
+│  (deposit → update → update → ... → exit)                    │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Adapter Layer                             │
+│  Protocol integrations: Hyperliquid, Moonwell, Boros, etc.  │
+│  All methods return (success: bool, data: Any) tuples       │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Client Layer                              │
+│  TokenClient, BRAPClient, LedgerClient                       │
+│  Authenticated via X-API-KEY header                          │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Network Layer                             │
+│  Wayfinder API • Chain RPCs • Protocol APIs                 │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## CLI Reference
+
+```bash
+# Check strategy status
+poetry run python wayfinder_paths/run_strategy.py <strategy> --action status
+
+# Deposit funds into strategy
+poetry run python wayfinder_paths/run_strategy.py <strategy> --action deposit \
+    --main-token-amount 100 --gas-token-amount 0.01
+
+# Run strategy update cycle
+poetry run python wayfinder_paths/run_strategy.py <strategy> --action update
+
+# Withdraw funds
+poetry run python wayfinder_paths/run_strategy.py <strategy> --action withdraw
+
+# Exit strategy (return all funds to main wallet)
+poetry run python wayfinder_paths/run_strategy.py <strategy> --action exit
+
+# Run continuously
+poetry run python wayfinder_paths/run_strategy.py <strategy> --action run
+
+# Partial liquidation
+poetry run python wayfinder_paths/run_strategy.py <strategy> --action partial-liquidate --amount 50
+```
+
+## Contributing
+
+We welcome contributions! You can add your own strategies and adapters to the SDK.
+
+### Adding a New Strategy
+
+```bash
+# Use the convenience command
+just create-strategy "My Strategy Name"
+
+# Or copy the template manually
+cp -r wayfinder_paths/templates/strategy wayfinder_paths/strategies/my_strategy
+```
+
+Implement the required methods:
+- `deposit()` - Move funds from main wallet to strategy
+- `update()` - Rebalance/optimize positions
+- `exit()` - Return funds to main wallet
+- `_status()` - Report current state
+
+### Adding a New Adapter
+
+```bash
+cp -r wayfinder_paths/templates/adapter wayfinder_paths/adapters/my_adapter
+```
+
+Implement protocol-specific methods, returning `(success, data)` tuples.
+
+### Contribution Process
+
+The process for contributing new paths to the official SDK is still being defined. For now:
+
+1. Fork the repository
+2. Create your adapter or strategy
+3. Add tests
+4. Open a PR with a description of what your path does
+
+Join our [Discord](https://discord.gg/fUVwGMXjm3) to discuss ideas and get help.
+
+## Testing
+
+```bash
+# Generate test wallets
+just create-wallets
+
+# Run all tests
+poetry run pytest -v
+
+# Run smoke tests
+poetry run pytest -k smoke -v
+
+# Run adapter tests
+poetry run pytest wayfinder_paths/adapters/ -v
+
+# Run with coverage
+poetry run pytest --cov=wayfinder_paths -v
+```
+
+## Security
+
+- **Never commit `config.json`** - it contains private keys
+- **Use test wallets** for development
+- **DRY_RUN mode** - Set `DRY_RUN=1` env var to simulate executions
+- **Idempotency** - MCP tools use idempotency keys to prevent duplicate transactions
+
+## Community
+
+- [Discord](https://discord.gg/fUVwGMXjm3) - Get help, share strategies, discuss DeFi
+- [GitHub Issues](https://github.com/WayfinderFoundation/wayfinder-paths/issues) - Report bugs, request features
+- [Wayfinder](https://wayfinder.ai) - Get your API key
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+