---
name: yugen
description: Interact with Yūgen (幽玄) — a negative-rebase ERC-20 token on Base. Use when the user wants to buy or sell YGN, stake YGN to escape the hourly rebase, unstake (starts a 7-day decaying drip), claim dripped tokens, become a Witness (permanent burn for a yield-earning NFT), claim Witness yield, or read protocol state (price, supply, burn, staking ratio, next rebase). Yugen's API builds the unsigned transaction; Bankr's Wallet Submit API signs and broadcasts it. Base mainnet (chain 8453) only.
metadata:
  {
    "clawdbot":
      {
        "emoji": "幽",
        "homepage": "https://yugen.fun",
        "requires": { "bins": ["curl", "jq"] },
      },
  }
---

# Yūgen (幽玄)

A negative-rebase token on Base. **One-sentence pitch: your tokens shrink unless you stake them.**

Every hour, all liquid YGN (in wallets, in pools, in most contracts) loses 0.4% to a rebase — the supply is burned. The only escape is the staking contract. Unstaking starts a 7-day drip during which tokens are liquid and keep decaying. This skill lets an agent read protocol state and execute every protocol action through Bankr.

## How it works

Yugen exposes a transaction-builder API at `https://www.yugen.fun/api/action`. You **never hand-encode calldata**: you POST an intent (e.g. `{"action":"buy","ethAmount":"0.1"}`), Yugen returns an unsigned transaction `{to, data, value, gas}`, and you forward that to **Bankr's Wallet Submit API** to sign and broadcast from the user's Bankr wallet.

```
intent → POST https://www.yugen.fun/api/action → unsigned tx → POST https://api.bankr.bot/wallet/submit → tx hash
```

> **Host note:** use the canonical `https://www.yugen.fun` for all API calls. The apex `yugen.fun` issues a 307 redirect to `www`, so a bare `curl` (no `-L`) will fail. Either call `www.yugen.fun` directly or pass `curl -L`.

If a write action needs an ERC-20 approval first, the Yugen response includes an `approveFirst` tx object. **Submit `approveFirst` and wait for confirmation before submitting the main `tx`.**

## Prerequisites

### Bankr API key (write access)

On-chain actions go through the Bankr Wallet API, which needs a key with **write access** (`walletApiEnabled`, not `readOnly`).

```bash
# CLI login (recommended)
bankr login email user@example.com
bankr login email user@example.com --code 123456 --accept-terms --key-name "Yugen" --read-write
```

Or generate a write-enabled key at [bankr.bot/api](https://bankr.bot/api). Read-only keys can still read state (price/protocol/balances) but cannot trade, stake, or burn.

### ETH on Base

The Bankr wallet needs ETH on Base for gas (and for buys). Check with `bankr wallet portfolio`.

## Quick Start

### Check protocol state

```
What's the YGN price and staking ratio?
```

```bash
curl -s https://www.yugen.fun/api/protocol | jq '{price: .pool.price, supply: .token.totalSupply, burnedPct: .token.burnedPct, stakingRatio: .staking.stakingRatio, nextRebase: .rebase.nextRebaseTime, rebaseDue: .rebase.isRebaseDue}'
```

### Check a wallet's position

```bash
curl -s -X POST https://www.yugen.fun/api/action \
  -H "Content-Type: application/json" \
  -d '{"action":"balances","address":"0xWALLET"}' | jq .result
```

Returns `ygnBalance`, `stakedBalance`, `stakingShares`, `activeDrips`, `pendingDripYgn`, and `allowances`.

### Buy YGN with 0.1 ETH

```bash
# 1. Build the tx
TX=$(curl -s -X POST https://www.yugen.fun/api/action \
  -H "Content-Type: application/json" \
  -d '{"action":"buy","ethAmount":"0.1"}' | jq -c .tx)

# 2. Submit via Bankr
curl -s -X POST https://api.bankr.bot/wallet/submit \
  -H "X-API-Key: $BANKR_API_KEY" -H "Content-Type: application/json" \
  -d "{\"transaction\":$(echo $TX | jq '. + {chainId:8453}'),\"description\":\"Buy YGN with 0.1 ETH\",\"waitForConfirmation\":true}"
```

### Stake YGN (escape the rebase)

```bash
WALLET=$(curl -s https://api.bankr.bot/wallet/me -H "X-API-Key: $BANKR_API_KEY" | jq -r .address)

# Build stake intent ("max" needs address to read the on-chain balance)
RESP=$(curl -s -X POST https://www.yugen.fun/api/action \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"stake\",\"ygnAmount\":\"max\",\"address\":\"$WALLET\"}")

# If approveFirst present, submit it and WAIT, then submit the main tx (see Action Flow below)
```

## Action Reference

All write actions hit `POST https://www.yugen.fun/api/action` and return `{ "tx": {...} }`, optionally with `{ "approveFirst": {...} }`. Read actions return `{ "result": {...} }` directly.

| Intent | Body | Returns | Approval? |
|---|---|---|---|
| Buy YGN | `{"action":"buy","ethAmount":"0.1"}` | `tx` (has `value`) | no |
| Sell YGN | `{"action":"sell","ygnAmount":"1000000"}` or `"max"`+`address` | `tx` | yes (router) |
| Stake | `{"action":"stake","ygnAmount":"500000"}` or `"max"`+`address` | `tx` | yes (staking) |
| Unstake | `{"action":"unstake","shares":"500000"}` | `tx` | no |
| Claim drip | `{"action":"claimDrip","dripIndex":0}` | `tx` | no |
| Approve | `{"action":"approve","target":"router\|staking\|witness"}` | `tx` | — |
| Become Witness | `{"action":"becomeWitness","ygnAmount":"100000"}` | `tx` | yes (witness) |
| Claim yield | `{"action":"claimYield","tokenId":1}` | `tx` | no |
| Balances (read) | `{"action":"balances","address":"0x..."}` | `result` | — |

**Amount formats:** display units (`"500000"`), raw wei strings (`"500000000000000000000000"`), or `"max"` (requires an `"address"` field so the API can read the exact on-chain balance). Prefer raw wei or `"max"` to avoid float precision loss. YGN has **18 decimals**.

## Action Flow (with approval)

For `sell`, `stake`, and `becomeWitness` the response may include `approveFirst`. Sequence:

1. `POST /api/action` → response with `tx` and (maybe) `approveFirst`.
2. If `approveFirst` present: submit it to Bankr with `waitForConfirmation: true`, confirm `status: "success"`.
3. Submit the main `tx` to Bankr (add `chainId: 8453`).
4. Report the `transactionHash`.

Every tx Yugen returns is missing only `chainId` — always inject `chainId: 8453` before submitting.

## Bankr Submit API

**Endpoint:** `POST https://api.bankr.bot/wallet/submit`
**Headers:** `X-API-Key: bk_...`, `Content-Type: application/json`

```json
{
  "transaction": { "to": "0x...", "chainId": 8453, "value": "0", "data": "0x..." },
  "description": "Stake 500000 YGN on Yugen",
  "waitForConfirmation": true
}
```

Success → `{ "success": true, "transactionHash": "0x...", "status": "success", ... }`.
`status` can be `success`, `reverted`, or `pending`. Always pass a human-readable `description`. Use `waitForConfirmation: true` for anything sequential (approvals before the main call).

Wallet address: `GET https://api.bankr.bot/wallet/me` → `.address`.

## Read Endpoints (no key needed, CORS + cached)

| Endpoint | Returns |
|---|---|
| `GET /api/protocol` | Full snapshot: token supply/burn/scalingFactor, rebase timing & decay, pool reserves/price/fees, staking ratio, contract addresses |
| `GET /api/price` | `price` (ETH per YGN), `ygnPerEth`, reserves |
| `GET /api/candles` | 1-minute OHLCV history + recent trades with tx hashes |
| `GET /mcp.json` | Machine-readable MCP tool spec |

Base URL: `https://www.yugen.fun`.

## What every user MUST understand before acting

These are protocol mechanics, not slippage — surface them proactively:

- **Holding liquid YGN melts it.** ~0.4%/hour, ~9.2%/day, ~94.5%/month. Buying and sitting unstaked is a loss by design. The rational move after buying is usually to **stake**.
- **Unstaking is a 7-day drip, not instant.** Tokens return linearly over 7 days and are *liquid (decaying) the whole time* — roughly **~50% of the unstaked amount is lost to rebase** at the current 0.4% rate. There is no instant exit and no fee to avoid; the drip *is* the exit cost. Confirm the user accepts this before submitting an `unstake`.
- **Becoming a Witness is permanent and irreversible.** `becomeWitness` burns the YGN forever in exchange for a yield-earning NFT. There is no unburn. Confirm intent explicitly.
- **Rebase is permissionless.** Anyone can call `rebase()` when one is due (`rebase.isRebaseDue`). Pool reserves are `sync()`'d atomically in the same tx, so quotes from `/api/price` are fresh.
- **Decay halves over time.** 0.4%/rebase for the first ~104 days, then halves every 2,500 rebases down to a 0.01% floor — long-term disinflationary.

## Contracts (Base mainnet, chain 8453)

| Contract | Address |
|---|---|
| YGN Token | `0xf0e29fDD31f628B329309A274874EC23Ee777F60` |
| Staking | `0x0aD79F37C3B7C36ec5c745eFF5A9f810C4De73e7` |
| V4 Hook (AMM) | `0xa23246738365A73354BDd6d079Bcd80318Eb6A88` |
| Swap Router | `0x7625b04ae283230590C4Bb4b4a9d520bd639E991` |
| Witness NFT | `0x1a0120E8B65319dBB9791f571E69C0c80e206126` |
| Marketplace | `0x227cA4646A017010154c376Ca4FA5e3D5e931D46` |
| Pool Manager | `0x498581fF718922c3f8e6A244956aF099B2652b2b` |

Yugen also has deep liquidity on a Uniswap V2 ETH/YGN pair; the V4 hook pool above is the protocol-native venue the API routes through.

## Example conversations

**"Buy me $50 of YGN and stake it."**
1. Convert $50 → ETH (read ETH price, or let the user specify ETH directly).
2. `buy` → submit. Wait for confirmation.
3. `stake` with `ygnAmount:"max"` + the Bankr wallet address → if `approveFirst`, submit + wait, then submit `stake`.
4. Report both tx hashes and the staked amount. Note: staked YGN no longer rebases.

**"How much would I lose unstaking 1,000,000 YGN?"**
At the current 0.4%/hr rate over a 7-day linear drip, ~50% is lost (~500,000 YGN received). Quote the live decay via `GET /api/protocol → rebase.decayPct`; if it has halved, the loss is smaller. **Do not submit** — this is a question, not an order.

**"Claim my Witness yield for NFT #1."**
`{"action":"claimYield","tokenId":1}` → submit. Yield is paid in YGN.

**"What's the burn at?"**
`GET /api/protocol → token.burned`, `token.burnedPct`.

## Resources

- **App:** https://yugen.fun
- **Full agent spec:** https://www.yugen.fun/skill.md
- **MCP tool spec:** https://www.yugen.fun/mcp.json
- **Bankr Submit API:** https://docs.bankr.bot/wallet-api/overview