primecli 0.2.7

Agent-friendly CLI tools for the DeltaPrime (Avalanche) and DegenPrime (Base) lending and leverage protocols. Preview-by-default; no Etherscan key required.

primecli

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

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.

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.

Install

pip install primecli

Requires Python 3.10+. Step-by-step install + first-use walkthroughs:

• Humans new to Python CLI tools: docs/install-humans.md.
• AI agents integrating the tool: docs/install-agents.md.

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

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

From a local clone (development):

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.

# 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.

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 (24h delayed lender flow, step 1), withdrawal-requests, execute-withdrawal-request --pool X [--index N], cancel-withdrawal-request --pool X --index N, 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] (⚠️ --via paraswap blocked upstream, see issue #2), swap-debt --from S --to S --amount N [--slippage P] (⚠️ also blocked upstream — same allowlist)
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. Per-capability build spec: docs/deltaprime-capabilities.md.

degenprime (Base)

Group	Commands
Lending core	pool-info [--json], my-positions, deposit, withdraw (24h delayed lender flow, step 1), withdrawal-requests, execute-withdrawal-request --pool X [--index N], cancel-withdrawal-request --pool X --index N, borrow, repay, fund
Degen Account	create-account, summary [--json], 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. Per-capability build spec: 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.

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: protocol model, addresses, facet map, RedStone integration, full command table, GMX / LB / PRIME flows.
• DeltaPrime capabilities: per-command build spec with function signatures, parameter encoding, approve targets, slippage / oracle / exec-fee requirements.
• DegenPrime reference: Base-side equivalent.
• DegenPrime capabilities: Base-side per-command build spec.
• Security model: 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.

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.

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.

Health Math (0-100% Scale)

The protocol's health meter runs from 0% (liquidation) to 100% (no debt). The tool reports health_ratio from the SolvencyFacet (1.0 = liquidation line), but the frontend-friendly 0-100% scale is computed as:

equity = total_supplied_usd - total_debt_usd
max_debt = equity * (tier - 1)    # PREMIUM=10, BASIC=5
health_pct = (max_debt - debt) / max_debt * 100

Key insight: LP tokens (GMX, LB, Aerodrome CL) don't count as full-rate collateral. Using gross supplied_usd as the borrowing base inflates max_debt and overstates health. The formula above uses equity only, which matches the protocol's cross-margin calculation within ~3pp.

Rebalancing

Auto-rebalance within a configurable range (e.g. 30-70%) by borrowing more (deploy into existing position) or repaying debt. A 1h cooldown prevents frequent toggling. Below 20% the cooldown is bypassed and the agent is escalated.

Stop Loss (Equity Drawdown)

Track a baseline equity (recorded at position open) and trigger a full close if equity drops X% below that baseline. Withdraw from the position, swap to USDC, repay all debt. See examples/health-monitoring/ for a reference implementation.

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.

Acknowledgements

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