Skill: bifrost-io/bifrost-slpx (version 0.1.3)

--- name: bifrost-slpx description: | Bifrost SLPx liquid staking via @bifrostio/slpx-cli: exchange rates, APY (with optional DeFiLlama LP pools), TVL, holders, protocol info; vETH balances, redemption queue, mint ETH/WETH→vETH, redeem vETH, claim ETH. Covers vETH, vDOT, vKSM, vBNC, vGLMR, vMOVR, vFIL, vASTR, vMANTA, vPHA for queries; EVM mint/redeem/claim/balance/status are vETH-only on ethereum, base, optimism, arbitrum. Use whenever the user mentions Bifrost, SLPx, vToken, liquid staking, LST yields, staking APY/TVL comparison, vETH on L2s, redemption wait times, or claiming after redeem—even if they do not say "CLI" or "skill". keywords: - bifrost - vETH - vDOT - vToken - liquid-staking - DeFi - staking - mint - redeem - APY metadata: author: bifrost.io version: "0.1.3" pattern: tool-wrapper composed_patterns: - pipeline - inversion --- # Bifrost SLPx CLI You operate the Bifrost liquid-staking CLI. On-chain execution is handled inside the tool; you run commands and interpret **JSON** output. ## Grounding — no extra narrative - Answer **only** from fields present in the CLI **`--json`** you just received. Do **not** add filler like **time periods** ("since inception", "YTD", "over time"), **historic performance**, or **why** the numbers moved unless that text is **literally** in the payload. - **`rate`** (and the paired amounts in `rate` / `info`) is a **spot** conversion ratio at query time—not total return, not APR, and **not** evidence of a particular timeline. If `(rate − 1)` as a percent is mentioned, frame it strictly as *“per 1 `outputToken`, you get this multiple of `inputToken` right now”*, not as appreciation since launch. - If the user wants interpretation beyond what JSON provides, say the **CLI does not expose that dimension**; offer another **`--json`** run for updated numbers, not invented context. ## Progressive disclosure — what to load | Task | Read first | | ------------------------------------- | ------------------------------------------------------------------------ | | rate / apy / info only | `references/commands.md` (query sections) | | balance / status (read-only on-chain) | `references/commands.md` + `references/tokens-and-chains.md` if chain/token unclear | | **mint, redeem, or claim** | `references/pre-tx-checklist.md`, then `references/commands.md` | | signing key unset / how to configure it | `references/private-key-env.md` | Do **not** skip `pre-tx-checklist.md` before any transaction that could broadcast. ## Pre-flight ```bash npx -y @bifrostio/slpx-cli --version ``` If the published package uses a non-`latest` dist-tag (e.g. prerelease on `next`), pin it: `npx -y @bifrostio/slpx-cli@next --version`. ## On-chain pipeline (do not skip steps) For **mint**, **redeem**, and **claim**: 1. Complete the **inversion** prompts below if anything is ambiguous. 2. Read `references/pre-tx-checklist.md`. 3. Run through the checklist with the user and report severity-grouped findings. 4. **Stop** until the user explicitly approves broadcasting. 5. Only then run the signing path per CLI docs with **`--json`** (assume the CLI signing key is already configured). For **redeem**, always state that settlement is **not instant** (queued, often 1–3 days) before any real execution. ## Inversion — gather before acting Before mint/redeem/claim, resolve (ask the user if missing): - **Chain** (`ethereum` | `base` | `optimism` | `arbitrum` for vETH on-chain). - **Amount** and whether mint uses **native ETH** or **`--weth`**. - **Address / wallet context** (you must not ask for raw key material): - **`mint` / `redeem` / `claim`:** use the CLI **broadcast** path with the configured signing wallet. - **`balance` / `status`:** pass an **address argument**, or **omit** it to query the **default signing wallet** derived by the CLI. Batch `balance` still needs explicit comma-separated addresses. Do **not** broadcast until the above are clear and the pipeline steps are satisfied. ## Signing key not configured Read `references/private-key-env.md` and follow it end-to-end. ## Commands, options, and examples See `references/commands.md`. ## Tokens, chains, contracts See `references/tokens-and-chains.md`. ## Errors CLI returns JSON with `error`, `code`, `message`. Full table: `references/errors.md`. ## Notes - Always prefer **`--json`** for agent-driven calls. - Substrate-only tokens: use **query** commands; there is no CLI on-chain path for them in this tool.

path: README.md
content: # bifrost-slpx

Agent skill for **Bifrost SLPx** (vTokens, vETH on-chain flows) using the [`@bifrostio/slpx-cli`](https://www.npmjs.com/package/@bifrostio/slpx-cli) CLI. Full agent behavior, pipelines, and guardrails are in **`SKILL.md`**.

## Install

```bash
npx skills add bifrost-io/skills --skill bifrost-slpx
```

### Agent install (non-interactive)

AI agents that need to **add this skill autonomously** without interactive prompts should run the same command with a target **`--agent`**, **`-g`** (install globally for that agent), and **`-y`** (assume yes):

```bash
npx skills add bifrost-io/skills --skill bifrost-slpx --agent <agentname> -g -y
```

Examples: `--agent cursor` or `--agent claude-code` (use the name your skills CLI expects for the host).

## What it does

- **Queries (all vTokens):** spot exchange `rate`, staking `apy` (optional `--lp` for DeFiLlama LP pool yields), and protocol `info` (TVL, holders, totals; vETH also contract / chains / paused).
- **vETH on EVM:** read `balance` and redemption `status`; write paths `mint` (ETH or WETH → vETH), `redeem` (queued, not instant), `claim` (ETH after redeem completes).
- **Coverage:** `vETH`, `vDOT`, `vKSM`, `vBNC`, `vGLMR`, `vMOVR`, `vFIL`, `vASTR`, `vMANTA`, `vPHA` for queries; **mint / redeem / claim / balance / status** are **vETH-only** on `ethereum`, `base`, `optimism`, `arbitrum`.

## Example user scenarios

| User intent                                                      | Typical CLI flow                                         |
| ---------------------------------------------------------------- | -------------------------------------------------------- |
| “What’s vDOT APY”                                                | `apy --token vDOT --json`                                |
| “Compare vETH vs vKSM staking yield”                             | `apy --token vETH --json` then `apy --token vKSM --json` |
| “vETH exchange rate for 10 ETH worth”                            | `rate 10 --json` (default token vETH)                    |
| “Protocol overview for vASTR”                                    | `info --token vASTR --json`                              |
| “How much vETH / ETH equivalent does this address have on Base?” | `balance 0x… --chain base --json`                        |
| “Stake 0.5 ETH on Arbitrum”                                      | `mint 0.5 --chain arbitrum --json`                       |

## Prerequisites

This skill assumes the **CLI signing key is already configured** for on-chain commands. If it is not, follow **`references/private-key-env.md`** in the skill. **Never** paste raw key material into chat.

## Contents

| Path                              | Purpose                                                          |
| --------------------------------- | ---------------------------------------------------------------- |
| `SKILL.md`                        | Entry point: when to use, pre-flight, mint/redeem/claim pipeline |
| `references/commands.md`          | CLI commands and flags                                           |
| `references/tokens-and-chains.md` | vToken matrix, vETH contract, WETH addresses                     |
| `references/errors.md`            | JSON error `code` values                                         |
| `references/pre-tx-checklist.md`  | Checks before broadcasting                                       |

The CLI package itself lives in a separate repo and does **not** ship these markdown files.


path: references/pre-tx-checklist.md
content: # Pre-broadcast checklist (mint / redeem / claim)

Use this **before** broadcasting **mint** / **redeem** / **claim**. Classify each item; if any **error** remains unresolved, do not broadcast.

## Checklist

| # | Check | Severity if failed |
|---|--------|-------------------|
| 1 | User explicitly confirmed chain, amount, and action (mint vs redeem vs claim) | error |
| 2 | For `redeem`: user acknowledged non-instant queue (typically 1–3 days) | error |
| 3 | Amount, chain, and action match user intent (recipient/contract, value, chain id where applicable) | error |
| 4 | Not advising user to paste private keys or secrets into chat | error |
| 5 | No private key material in command strings, logs, or echoed env | error |
| 6 | vETH contract / chain matches `tokens-and-chains.md` expectations | warning |

## Output format for the agent

Summarize results for the user:

- **Summary**: What transaction was checked and on which chain.
- **Findings**: Group by severity — **error** (must fix before send), **warning** (should address), **info** (optional).
- **Ready to broadcast**: yes / no — only **yes** if there are no errors.


path: references/commands.md
content: # Command reference

Always pass `--json` when invoking from an agent unless you intentionally need human-readable text.

Prefix: `npx -y @bifrostio/slpx-cli`

## Query commands (all vTokens)

### `rate [amount]`

Exchange rate. Default: 1 unit of base asset.

```bash
npx -y @bifrostio/slpx-cli rate --json
npx -y @bifrostio/slpx-cli rate 10 --json
npx -y @bifrostio/slpx-cli rate --token vDOT --json
npx -y @bifrostio/slpx-cli rate 100 --token vKSM --json
```

Output fields: `inputAmount`, `outputAmount`, `inputToken`, `outputToken`, `rate` (`tokenToBase`: `inputToken` per 1 `outputToken`), `source` (on-chain fallback also: `chain`)

**`rate` semantics (agents):** snapshot only—how many units of `inputToken` one `outputToken` commands **at request time**. The JSON has **no** inception date, **no** history, and **no** “cumulative return” label. Do **not** equate `(rate − 1)` with “appreciation since inception” or any other period; that is inferential, not in the data.

### `apy`

Staking APY (base + reward). Add `--lp` for LP pool yields from DeFiLlama.

```bash
npx -y @bifrostio/slpx-cli apy --json
npx -y @bifrostio/slpx-cli apy --token vDOT --json
npx -y @bifrostio/slpx-cli apy --token vMANTA --json
npx -y @bifrostio/slpx-cli apy --token vDOT --lp --json
```

Output fields: `token`, `totalApy`, `baseApy`, `rewardApy`, `rewardApyIncentiveAsset`

- `baseApy` — native staking yield on the underlying chain (Bifrost API: `apyBase`)
- `rewardApy` — Bifrost farming incentive component (Bifrost API: `apyReward`)
- `rewardApyIncentiveAsset` — **vDOT** for **vETH** only; **BNC** for every other vToken
- `totalApy` — `baseApy` + `rewardApy`

With `--lp`: adds `lpPools` — each entry: `symbol`, `project`, `chain`, `lpApy`, `tvl`

### `info`

Protocol overview: rate, APY, TVL, holders. vETH also: contract, chains, paused.

```bash
npx -y @bifrostio/slpx-cli info --json
npx -y @bifrostio/slpx-cli info --token vDOT --json
npx -y @bifrostio/slpx-cli info --token vASTR --json
```

Output fields: `protocol`, `inputAmount`, `outputAmount`, `inputToken`, `outputToken`, `rate` (`tokenToBase`), `totalApy`, `baseApy`, `rewardApy`, `tvl`, `totalStaked` (amount in `inputToken`), `totalSupply` (amount in `outputToken`), `holders`  
`rate` here matches **`rate` command** semantics: **spot** `tokenToBase`, **no** time dimension in the JSON.  
vETH extra: `contract`, `chains`, `paused`

## On-chain commands (vETH only)

### `balance [address]`

vETH balance and ETH equivalent. **Omit `address`** to query the CLI **default signing wallet**. Comma-separated addresses for batch.

```bash
npx -y @bifrostio/slpx-cli balance --json
npx -y @bifrostio/slpx-cli balance 0x742d...bD18 --json
npx -y @bifrostio/slpx-cli balance 0x742d...bD18 --chain base --json
npx -y @bifrostio/slpx-cli balance 0xAddr1,0xAddr2,0xAddr3 --json
```

Single: `address`, `vethBalance` (vETH, amount only), `ethValue` (ETH, amount only), `chain`  
Batch: `results` (`{address, vethBalance, ethValue}`), `chain`

### `status [address]`

Redemption queue status. Omit address to query the **default signing wallet** (same as `balance`).

```bash
npx -y @bifrostio/slpx-cli status --json
npx -y @bifrostio/slpx-cli status 0x742d...bD18 --json
```

Output: `address`, `claimableEth` (ETH, amount only), `pendingEthAmount` (ETH, amount only), `chain`, `hint` (time estimate when pending; may include units in prose)

### `mint <amount>`

Stake ETH → vETH. `--weth` uses WETH instead of native ETH.

```bash
npx -y @bifrostio/slpx-cli mint 0.1 --json
npx -y @bifrostio/slpx-cli mint 0.5 --chain base --json
npx -y @bifrostio/slpx-cli mint 0.1 --weth --json
npx -y @bifrostio/slpx-cli mint 0.5 --weth --chain arbitrum --json
```

Native ETH (unsigned preview): `action`, `inputAmount`, `inputToken` (`ETH`), `expectedAmount`, `expectedToken` (`vETH`), `mode`, `from` (signer/receiver when applicable), `unsigned.to`, `unsigned.value`, `unsigned.data`, `unsigned.chainId`  
WETH (unsigned preview): `action:mint-weth`, `inputAmount`, `inputToken` (`WETH`), `expectedAmount`, `expectedToken` (`vETH`), `mode`, `from`, `wethAddress`, `steps` (Approve, Deposit; deposit `receiver` aligns with `from` when using address-only flows)  
Signed: same amount/token fields plus `from`, `txHash`, `explorer`

WETH contract addresses: see `tokens-and-chains.md`.

### `redeem <amount>`

Redeem vETH — **not instant** (queue, often 1–3 days).

> Before broadcasting `redeem`, confirm with the user: amount, chain, and that redemption is queued (not instant).

```bash
npx -y @bifrostio/slpx-cli redeem 0.1 --json
```

### `claim`

Claim completed ETH after redemption.

```bash
npx -y @bifrostio/slpx-cli claim --json
```

## Global options

| Option | Description | Default |
|--------|-------------|---------|
| `--token <name>` | `vETH`, `vDOT`, `vKSM`, `vBNC`, `vGLMR`, `vMOVR`, `vFIL`, `vASTR`, `vMANTA`, `vPHA` | `vETH` |
| `--chain <name>` | `ethereum`, `base`, `optimism`, `arbitrum` (vETH on-chain only) | `ethereum` |
| `--rpc <url>` | Custom RPC | auto per chain |
| `--json` | JSON output | false |

## Transaction-related options

| Option | Description |
|--------|-------------|
| `--weth` | Mint from WETH (not native ETH) |
| `--lp` | LP yields on `apy` only |
| `--address <addr>` | **`balance` / `status`:** use the positional `[address]` (comma-separated batch for `balance`); omit to use the default signing wallet. **`mint` / `redeem` / `claim`:** optional when broadcasting (CLI uses the signing wallet); see CLI `--help` for edge cases. |

## Workflow examples

### Compare APYs (with LP)

```bash
npx -y @bifrostio/slpx-cli apy --token vDOT --lp --json
npx -y @bifrostio/slpx-cli apy --token vETH --lp --json
npx -y @bifrostio/slpx-cli apy --token vKSM --json
```

### Batch balances

```bash
npx -y @bifrostio/slpx-cli balance 0xAddr1,0xAddr2,0xAddr3 --json
```

### Research → stake (vETH)

```bash
npx -y @bifrostio/slpx-cli info --json
npx -y @bifrostio/slpx-cli rate 1 --json
npx -y @bifrostio/slpx-cli apy --json
npx -y @bifrostio/slpx-cli mint 0.5 --json
# Broadcast after pre-tx checklist + explicit user approval.
```

### Redeem → claim (vETH)

```bash
npx -y @bifrostio/slpx-cli balance 0x... --json
npx -y @bifrostio/slpx-cli redeem 1.0 --json
npx -y @bifrostio/slpx-cli status --json
npx -y @bifrostio/slpx-cli claim --json
```

## Operational notes

1. Query commands use the Bifrost API for all 10 vTokens.
2. On-chain commands are vETH-only on the listed EVM chains.
3. Redemption goes through Bifrost’s cross-chain queue — not immediate settlement.
4. **`mint` / `redeem` / `claim`:** broadcasting requires a configured signing key (default for this skill). See `references/errors.md` (`NO_PRIVATE_KEY`, `NO_PRIVATE_KEY_OR_ADDRESS`) and `references/private-key-env.md` if setup is missing.
5. **`balance` / `status`:** omitting the address uses the default signing wallet; otherwise pass an address. See `NO_ADDRESS_OR_PRIVATE_KEY` in `references/errors.md`.
6. RPC: CLI may fall back to backup endpoints if primary RPC fails.
7. `--weth` unsigned flow emits Approve + Deposit steps.
8. `--lp` on `apy` pulls DeFiLlama pool data for the selected vToken.


path: references/errors.md
content: # Error codes

All errors return structured JSON with `error`, `code`, and `message` fields.

Signing key env name and setup: **`references/private-key-env.md`** only.

| Code | Meaning |
|------|---------|
| `INVALID_TOKEN` | Unknown vToken name |
| `UNSUPPORTED_TOKEN` | Token not available for on-chain operations |
| `INVALID_ADDRESS` | Bad Ethereum address format |
| `INVALID_AMOUNT` | Amount must be a positive number |
| `INVALID_CHAIN` | Unknown EVM chain name |
| `INSUFFICIENT_BALANCE` | Not enough vETH |
| `CONTRACT_PAUSED` | vETH contract is paused |
| `NOTHING_TO_CLAIM` | No completed redemptions to claim |
| `NO_PRIVATE_KEY` | Signing key not configured or invalid — required to broadcast `mint` / `redeem` / `claim` |
| `NO_PRIVATE_KEY_OR_ADDRESS` | Unsigned transaction build for those commands requires a configured signing key or `--address` (see CLI) |
| `NO_ADDRESS_OR_PRIVATE_KEY` | `balance` or `status` with **no address argument** requires a valid signing key (CLI derives the queried address from it) |
| `RPC_ERROR` | RPC connection failed |
| `API_ERROR` | Bifrost API unavailable or timed out |
| `TX_ERROR` | Transaction execution failed |
| `CLI_ERROR` | Missing argument or invalid option |


path: references/private-key-env.md
content: # `BIFROST_SKILL_PRIVATEKEY` — missing env or “how do I configure the private key?”

When the CLI or workflow indicates the env var is unset, or the user asks how to set the key:

1. **Detect the user’s shell** (run in the environment where they will use the CLI), e.g.:
   - `echo $SHELL` (path suffix: `bash`, `zsh`, `fish`, …), and/or
   - `ps -p $$ -o comm=` (current process name, e.g. `-zsh`, `bash`).
2. **Tell them to end this agent session** before writing secrets to disk, so they do not paste a raw private key into the chat.
3. **Map shell → init file** (typical):
   - **bash** → `~/.bashrc` (on macOS login shells, `~/.bash_profile` is also common if `~/.bashrc` is not sourced—mention both if relevant).
   - **zsh** → `~/.zshrc`.
   - **fish** → `~/.config/fish/config.fish`.
   - **Other** (e.g. tcsh) → point them to that shell’s standard user config file.
4. **Simple local append** (they run this themselves in Terminal; **never** paste the real key into the agent):

   ```bash
   # zsh example — adjust the file for bash/fish as above
   echo 'export BIFROST_SKILL_PRIVATEKEY=0xYOUR_PRIVATE_KEY' >> ~/.zshrc
   ```

   For **fish**, use `set -Ux` or the fish-native export style in `config.fish` instead of POSIX `export` if they prefer.

5. After editing: **open a new terminal** (or `source` the file) so the variable is loaded, then start a **new** agent session if they still need help.

Remind them: keep the key out of version control, shared dotfiles repos, and screen recordings; rotating the key is recommended if it was ever exposed in chat or logs.


path: references/tokens-and-chains.md
content: # Supported tokens and chains

## Token matrix

| Token | Base Asset | Query (rate/apy/info) | On-chain (balance/mint/redeem/claim/status) |
|-------|-----------|----------------------|---------------------------------------------|
| vETH | ETH | Yes | Yes (Ethereum, Base, Optimism, Arbitrum) |
| vDOT | DOT | Yes | No (Substrate) |
| vKSM | KSM | Yes | No (Substrate) |
| vBNC | BNC | Yes | No (Substrate) |
| vGLMR | GLMR | Yes | No (Substrate) |
| vMOVR | MOVR | Yes | No (Substrate) |
| vFIL | FIL | Yes | No (Substrate) |
| vASTR | ASTR | Yes | No (Substrate) |
| vMANTA | MANTA | Yes | No (Substrate) |
| vPHA | PHA | Yes | No (Substrate) |

## vETH contract (EVM)

Same address on all supported EVM chains: [REDACTED_SECRET]

## WETH addresses (for `--weth` mint)

| Chain | WETH contract |
|-------|----------------|
| Ethereum | [REDACTED_SECRET] |
| Arbitrum | [REDACTED_SECRET] |
| Base / Optimism | `0x4200000000000000000000000000000000000006` |


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)