Metadata-Version: 2.4
Name: primecli
Version: 0.2.0
Summary: Agent-friendly CLI tools for the DeltaPrime (Avalanche) and DegenPrime (Base) lending and leverage protocols. Preview-by-default; no Etherscan key required.
Author: Mnemosyne-quest contributors
License: MIT
Project-URL: Homepage, https://github.com/Mnemosyne-quest/primecli
Project-URL: Issues, https://github.com/Mnemosyne-quest/primecli/issues
Project-URL: Documentation, https://github.com/Mnemosyne-quest/primecli/tree/main/docs
Keywords: defi,deltaprime,degenprime,avalanche,base,lending,leverage,ethereum,web3,agent,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: web3<8,>=7.0
Requires-Dist: eth-account>=0.13
Requires-Dist: eth-keys>=0.5
Requires-Dist: eth-abi>=5.0
Requires-Dist: requests>=2.31
Dynamic: license-file

# primecli

> Command-line tools for the **DeltaPrime** (Avalanche C-chain) and **DegenPrime** (Base) lending and leverage protocols.

[![PyPI](https://img.shields.io/pypi/v/primecli.svg)](https://pypi.org/project/primecli/)
[![Python](https://img.shields.io/pypi/pyversions/primecli.svg)](https://pypi.org/project/primecli/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

`primecli` installs two console commands, `deltaprime` and `degenprime`, that drive the lending and leverage protocols built by the DeltaPrimeLabs team on Avalanche C-chain and Base respectively. Both share a per-user smart-account architecture (EIP-2535 diamond) and are operated through the same CLI shape: savings pools, per-user Prime / Degen Accounts, borrow / repay / fund, swaps, debt refinancing, delayed collateral withdrawals. The Avalanche side additionally exposes GMX V2 LP (GM and GM+), TraderJoe V2 LB, sJOE staking, PRIME leverage tiers, and a leveraged-long zap macro. The Base side ships a read-only Aerodrome position inventory; write paths are deferred to v2.

Built for agent use:

- Preview by default. Every state-changing command prints the plan and stops unless you pass `--execute`.
- Predictable stdout. Read-only commands emit fixed-format tables or JSON.
- No Etherscan, Snowtrace, or Basescan API key required. Hand-curated ABIs, proxy reads via the EIP-1967 storage slot.
- RedStone-signed solvency math handled internally, with a regression test pinning the half-boundary `toFixed(8)` encoding.
- ParaSwap calldata validated client-side against the on-chain executor allowlist before broadcast.

**Current version:** 0.1.2. The 0.x line is pre-1.0, so breaking changes are possible. See [Releases](https://github.com/Mnemosyne-quest/primecli/releases).

## Security and trust

**This tool moves real on-chain funds.** Read before using.

- You manage your own private key. The tool reads it from `DELTAPRIME_PRIVATE_KEY` or `DEGENPRIME_PRIVATE_KEY` (or a file path you point at via `*_KEY_FILE`, or a one-shot `--key` flag). It never writes the key anywhere.
- Every state-changing command **previews by default**. You must pass `--execute` to broadcast. Don't pass `--execute` until you have read the preview and understand what it is about to do.
- The RedStone payload, ParaSwap executor allowlist, and facet ABIs are pinned to specific on-chain state at the dates noted in the source. If DeltaPrime or DegenPrime upgrade their diamonds, the tool may need updating. Open an issue.
- The DeltaPrimeLabs team is not affiliated with this project. This is community-maintained tooling.

Full threat model and trust assumptions: [docs/security.md](docs/security.md).

## Install

Requires Python 3.10+.

```bash
pip install primecli
```

From the latest `main` (ahead of the most recent release):

```bash
pip install git+https://github.com/Mnemosyne-quest/primecli.git
```

From a local clone (development):

```bash
git clone https://github.com/Mnemosyne-quest/primecli.git
cd primecli
pip install -e .
```

## Quickstart

Read-only commands work with no key configured. Set the key when you want to broadcast.

```bash
# Read live pool state, no key needed.
deltaprime pool-info usdc

# Configure the key (or pass --key on each command for one-off use).
export DELTAPRIME_PRIVATE_KEY=0xabc...

# Preview a deposit. Prints the plan, broadcasts nothing.
deltaprime deposit --pool usdc --amount 100

# Broadcast.
deltaprime deposit --pool usdc --amount 100 --execute
```

Same shape on Base. The same EVM key works on both chains, and `DEGENPRIME_PRIVATE_KEY` falls back to `DELTAPRIME_PRIVATE_KEY` if unset.

```bash
export DEGENPRIME_PRIVATE_KEY=0xabc...   # optional; falls back to DELTAPRIME_PRIVATE_KEY

degenprime pool-info usdc
degenprime my-positions
```

## Commands

State-changing commands preview by default. Add `--execute` to broadcast.

### `deltaprime` (Avalanche C-chain)

| Group | Commands |
|-------|----------|
| Lending core | `pool-info [--json]`, `my-positions`, `deposit`, `withdraw`, `borrow`, `repay`, `fund` |
| Prime Account | `create-prime-account` (alias `create-account`), `prime-summary`, `defi --json`, `withdraw-collateral`, `withdrawal-intents`, `execute-withdrawal` |
| Swaps | `swap --from S --to S --amount N [--via yak\|paraswap] [--slippage P]`, `swap-debt --from S --to S --amount N [--slippage P]` |
| GMX V2 LP (async, keeper-executed) | `gmx-positions`, `gmx-deposit --market M --amount N [--side long\|short]`, `gmx-withdraw --market M --amount N` |
| TraderJoe V2 LB | `lb-positions`, `lb-add --pair P --amount-x N --amount-y N [--shape spot\|curve\|bidask] [--range R]`, `lb-remove --pair P` |
| sJOE staking | `sjoe-position`, `sjoe-stake --amount N`, `sjoe-unstake --amount N`, `sjoe-claim` |
| PRIME leverage tiers | `prime-tier`, `prime-needed --borrow X [--tier premium\|basic]`, `prime-deposit --amount N`, `prime-activate [--amount N]`, `prime-deactivate [--withdraw]`, `prime-unstake --amount N`, `prime-repay --amount N` |
| Zaps (multi-tx macro) | `zap --market M --collateral P --collateral-amount N --borrow-amount N --deposit-amount N [--side long\|short] [--swap]` |

Pools: `usdc`, `wavax`, `weth`, `btc`, `usdt`. GM markets: `avax-usdc`, `btc-usdc`, `eth-usdc` (two-sided GM); `avax+`, `btc+`, `eth+` (single-sided GM+). LB pairs: `avax-usdc`, `avax-usdc-20`, `btc-usdc`, `eth-avax`, `btc-avax`, `avax-btc`, `eurc-usdc`, `usdt-usdc`, `joe-avax`.

`defi --json` emits a full positions snapshot in a DeBank-like shape — `null`, empty-list, and empty-dict fields are stripped, and the decorative `url` key is dropped (numeric `0` and boolean `false` are preserved, since they carry real information). `pool-info --json` emits a single JSON object for a named pool, or a `{name: {...}}` dict for `all`. `zap` composes `fund` → `borrow` → optional `swap` → `gmx-deposit` into one preview-and-execute flow, stopping on the first failure.

Full per-command reference: [docs/deltaprime-reference.md](docs/deltaprime-reference.md). Per-capability build spec: [docs/deltaprime-capabilities.md](docs/deltaprime-capabilities.md).

### `degenprime` (Base)

| Group | Commands |
|-------|----------|
| Lending core | `pool-info [--json]`, `my-positions`, `deposit`, `withdraw`, `borrow`, `repay`, `fund` |
| Degen Account | `create-account`, `summary`, `withdraw-collateral`, `withdrawal-intents`, `execute-withdrawal`, `cancel-withdrawal` |
| Swaps | `swap --from S --to S --amount N [--slippage P]` (ParaSwap v6), `swap-debt --from S --to S --amount N` |
| Aerodrome (read-only in v1) | `aerodrome-positions` |

Pools (v1): `usdc`, `weth`, `cbbtc`, `aero`, `brett`, `kaito`, `cbdoge`, `cbxrp`. Beyond the lendable pools, the on-chain TokenManager exposes 32 collateral symbols (memecoins, LSTs, blue-chips) usable for `swap` / `swap-debt`.

`aerodrome-positions` lists owned and staked Aerodrome NFT tokenIds. Composition decoding and write paths (claim, decrease, add, stake) are deferred to v2.

Full per-command reference: [docs/degenprime-reference.md](docs/degenprime-reference.md). Per-capability build spec: [docs/degenprime-capabilities.md](docs/degenprime-capabilities.md).

## Configuration

| Env var | Default | Purpose |
|---|---|---|
| `DELTAPRIME_PRIVATE_KEY` | — | Your Avalanche signing key. Raw `0x...` hex. |
| `DELTAPRIME_KEY_FILE` | — | Path to a file containing the key. Use this if you don't want the key in process env. |
| `DELTAPRIME_RPC` | `https://api.avax.network/ext/bc/C/rpc` | Avalanche C-chain RPC. Override with a paid Alchemy / QuickNode / Infura endpoint for high-throughput use. |
| `DEGENPRIME_PRIVATE_KEY` | falls back to `DELTAPRIME_PRIVATE_KEY` | Your Base signing key. Same EVM key works on both chains. |
| `DEGENPRIME_KEY_FILE` | falls back to `DELTAPRIME_KEY_FILE` | Path to key file for Base. |
| `DEGENPRIME_RPC` | `https://base.publicnode.com` | Base RPC. |

The CLI also accepts a per-command `--key <0xhex>` override that takes precedence over all env vars. Handy for one-off operations from a shell where you don't want to persist the key.

A copy-paste template is at [examples/env.example](examples/env.example).

## What's covered

### `deltaprime` (Avalanche C-chain)

| Area | Status |
|------|--------|
| Savings pools (USDC, WAVAX, WETH, BTC, USDT) | full read + write |
| Prime Account creation and funding | full |
| Borrow / repay / fund / withdraw-collateral | full |
| Solvency views (health ratio, total value, debt, solvent flag) | full (RedStone-gated reads) |
| Swap (YieldYak + ParaSwap) | full |
| Swap-debt (debt refinancing) | full |
| GMX V2 LP (GM + GM+, 6 markets) | full (async, account freezes until keeper callback) |
| TraderJoe V2 LB (9 whitelisted pairs) | full (max 80 bins per account) |
| sJOE staking | full |
| PRIME leverage tiers (BASIC / PREMIUM) | full |
| Leveraged-long zap macro | full (GM-terminal) |
| Wombat / GLP / Pangolin LP | not yet (specced in docs) |

### `degenprime` (Base)

| Area | Status |
|------|--------|
| Savings pools (8 v1 pools) | full read + write |
| Degen Account creation and funding | full |
| Borrow / repay / fund | full |
| Universal 24h delayed collateral withdrawal | full (3-step create / list / execute, plus cancel) |
| Solvency views | full (RedStone-gated reads, with BaseOracle TWAP fallback for non-RedStone symbols) |
| Swap (ParaSwap v6) | full |
| Swap-debt | full (both legs must have RedStone feeds) |
| Aerodrome positions | read-only (tokenId inventory) |
| Aerodrome write paths (claim, decrease, add, stake) | deferred to v2 |
| `$DgP` staking | not deployed on-chain yet |

## Documentation

- [DeltaPrime reference](docs/deltaprime-reference.md): protocol model, addresses, facet map, RedStone integration, full command table, GMX / LB / PRIME flows.
- [DeltaPrime capabilities](docs/deltaprime-capabilities.md): per-command build spec with function signatures, parameter encoding, approve targets, slippage / oracle / exec-fee requirements.
- [DegenPrime reference](docs/degenprime-reference.md): Base-side equivalent.
- [DegenPrime capabilities](docs/degenprime-capabilities.md): Base-side per-command build spec.
- [Security model](docs/security.md): key handling, preview-by-default, ParaSwap executor allowlist, RedStone trust model, threat model.

## Using from an AI agent

`primecli` is built for autonomous and semi-autonomous use. Three properties matter:

1. **Preview by default.** Every state-changing command prints a structured preview and stops unless `--execute` is passed. An agent can call any command speculatively, parse the preview, decide whether to broadcast, then re-run with `--execute`.
2. **Predictable, parseable stdout.** Read-only commands (`pool-info` (also `--json`), `my-positions`, `prime-summary`, `summary`, `withdrawal-intents`, `lb-positions`, `gmx-positions`, `aerodrome-positions`, `sjoe-position`, `prime-tier`, `defi --json`) emit fixed-format tables or JSON. `defi --json` is a one-shot full positions snapshot.
3. **Clean failure modes.** Configuration errors do not print stack traces. A missing key prints `deltaprime: No signing key found. Set DELTAPRIME_PRIVATE_KEY ...` to stderr and exits 1.

Full agent integration guide (Claude Code skill template, MCP notes, recommended guardrails): [docs/agent-integration.md](docs/agent-integration.md).

### Drop-in patterns

**Shell-tooled agents** (Claude Code, Cursor agent mode, Aider, OpenAI Codex CLI, custom bash-using agents). Install with `pip install primecli`, set the env var, and the agent calls `deltaprime` / `degenprime` as normal CLI commands. No further wiring.

**Claude Code skills.** Drop a `SKILL.md` into `.claude/skills/deltaprime/` (or `degenprime/`) describing when to invoke the tool and which commands are read-only vs state-changing. Starter template in [docs/agent-integration.md](docs/agent-integration.md).

**MCP server.** Not shipped in v0.1. If you have a use case, file an issue. The wrapper is a few hundred lines of FastMCP.

### Recommended guardrails

- Never store `--execute` in a model-controlled string. Treat it as a separate authorisation step the operator (or a deliberate policy layer) attaches after seeing the preview.
- Cap daily spend with an external budget check. The tool has no built-in caps; that is the operator's responsibility.
- Log the preview before broadcasting. If the agent decided to swap 100 USDC and the preview says 100,000 USDC, the operator needs to see that.

## Troubleshooting

Common failure modes and their fixes:

- **`No signing key found`.** Set `DELTAPRIME_PRIVATE_KEY` (or `DEGENPRIME_PRIVATE_KEY`), or point `*_KEY_FILE` at a file holding the key, or pass `--key 0x...` for a one-off command.
- **RPC rate-limited (429 or stalls).** The default public RPCs are fine for occasional reads. For sustained or write-heavy use, point `DELTAPRIME_RPC` / `DEGENPRIME_RPC` at a paid endpoint (Alchemy, QuickNode, Infura, your own node).
- **`RedStone gateway unreachable` on a read.** `prime-summary` / `summary` fall back to balances-only when the RedStone gateway is down. On `--execute` of a solvency-gated write, the call cannot proceed without a payload; wait and retry, or try the alternate gateway via the env override.
- **Swap fails on-chain with `InvalidExecutor`.** ParaSwap rotated an executor that is not in the tool's mirror of the on-chain allowlist. The tool patches to a known-good fallback automatically; if reverts persist, the on-chain allowlist itself has likely rotated. Open an issue.
- **GMX deposit reverts `InsufficientNumberOfUniqueSigners(0,3)`.** A required RedStone feed was missing from the appended payload. This was the load-bearing fix on the GMX path (24-05-2026). If you hit it on a current build, capture the tx hash and open an issue.
- **GMX deposit accepted but no GM minted.** The execution fee was below the keeper's threshold and the request expired (refund without mint). Re-run; the tool floors gas at 25 gwei in the fee estimator to clear the keeper's bar.
- **`createLoan` succeeded but `getLoansForOwner` returns empty.** The factory's owner→loans map lags a beat behind the receipt. The tool polls for up to 12s; rerun `my-positions` shortly after if it timed out.

If your failure is not on this list and the on-chain revert reason is opaque, capture the tx hash, the exact CLI invocation, and the preview output, and file an issue.

## Versions and releases

`primecli` is on a 0.x line. **Breaking changes are possible** between minor versions until 1.0. Once the on-chain surface stabilises and the v2 work (DegenPrime Aerodrome writes, Wombat / GLP on DeltaPrime) is in, the project will commit to semver.

- Latest version on PyPI: <https://pypi.org/project/primecli/>.
- Per-version release notes: <https://github.com/Mnemosyne-quest/primecli/releases>.
- The `main` branch may be ahead of the latest tagged release; install from git if you need the bleeding edge.

## Contributing

PRs welcome. Open an issue first if you are planning anything non-trivial (new facet support, new chain, write paths for Aerodrome). Pinning ABIs and verifying on-chain shapes takes a real probe pass, and it is worth aligning before doing the work.

## License

MIT. See [LICENSE](LICENSE).

## Acknowledgements

Built on the work of the [DeltaPrimeLabs team](https://www.deltaprime.io/) (DeltaPrime + DegenPrime) and the broader DeFi tooling ecosystem: web3.py, eth-account, RedStone, ParaSwap (Velora), YieldYak, TraderJoe (LFJ), GMX, Aerodrome.
