opencode-venice-balance

An OpenCode TUI plugin for displaying your Venice.ai balance

Prerequisites

• OpenCode v1.17.0 or later
• Venice.ai account with Admin API key
• Environment variable: VENICE_ADMIN_API_KEY

Note: This plugin requires an Admin API key, not a regular API key. Admin keys have access to billing endpoints that regular keys cannot access. You can generate an Admin API key from your Venice.ai account settings.

Installation

The one-step path — installs the package and registers it in tui.jsonc for you:

opencode plugin --global @jcyamo/opencode-venice-balance

Registering manually

If you'd rather wire it up yourself, install the package:

pnpm add @jcyamo/opencode-venice-balance
# or: npm install @jcyamo/opencode-venice-balance

Then register it. OpenCode TUI sidebar plugins go in tui.jsonc — project .opencode/tui.jsonc or global ~/.config/opencode/tui.jsonc — not opencode.jsonc:

{
	"plugin": ["@jcyamo/opencode-venice-balance/tui"],
}

From a local checkout (for development), point at the source entry with an absolute path instead:

{
	"plugin": ["/absolute/path/to/opencode-venice-balance/src/tui.tsx"],
}

Setting the environment variable

Add to your shell configuration (e.g., ~/.bashrc, ~/.zshrc):

export VENICE_ADMIN_API_KEY="your-admin-api-key-here"

Or set it inline when running OpenCode:

VENICE_ADMIN_API_KEY="your-key" opencode

Features

• Real-time DIEM Balance - Displays your current DIEM balance and percentage of epoch allocation remaining
• Visual Status Indicators - Color-coded indicators for balance status (low, exhausted, using USD fallback)
• Automatic Updates - Balance refreshes automatically during your OpenCode session
• Manual Refresh - Press <leader>v to manually refresh your balance
• Error Handling - User-friendly error messages with actionable solutions

Keybinding

| Key | Action | | ----------- | --------------- | | <leader>v | Refresh balance |

Error States

| Error | Display | Cause | Solution | | -------------- | ----------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------- | | no_key | "Set VENICE_ADMIN_API_KEY" | Environment variable not set | Set VENICE_ADMIN_API_KEY in your shell configuration or export it before running OpenCode | | invalid_key | "invalid or not an Admin key" | API key is invalid or is a regular key | Verify your key is an Admin API key from your Venice.ai account settings | | fetch_failed | "Failed to fetch" | Network error or API unavailable | Check your internet connection and try again; the Venice.ai API may be temporarily down | | not_staking | "Not staking DIEM" | Account is not currently staking DIEM | Enable staking in your Venice.ai account to earn DIEM allocations | | exhausted | "Exhausted" | DIEM balance fully consumed | Your DIEM allocation is depleted; wait for the next epoch or add funds | | usd_fallback | "Using USD reserve" | DIEM exhausted, using USD balance | Add more DIEM to your staking balance or the account will consume from USD reserve |

Troubleshooting

Balance not showing

1. Verify VENICE_ADMIN_API_KEY is set: echo $VENICE_ADMIN_API_KEY
2. Ensure you're using an Admin API key, not a regular API key
3. Check the OpenCode logs for errors
4. Try refreshing manually with <leader>v

Shows "Not staking"

Your Venice.ai account does not have an active staking position. To stake DIEM:

1. Log into your Venice.ai account
2. Navigate to the staking section
3. Stake tokens to receive DIEM allocations

Shows incorrect value

1. The balance reflects your current DIEM allocation, not total balance
2. Balance updates periodically; use <leader>v to force refresh
3. If persistent, verify your API key has access to billing endpoints

License

GPL-3.0-or-later