name	vulcan-error-recovery
version	1.0.0
description	Error category routing, tx_failed recovery, and network error handling for Vulcan.
metadata	{"openclawd":{"category":"finance"},"requires":{"bins":["vulcan"]}}

vulcan-error-recovery

Use this skill for:

Routing errors by category
Recovering from failed on-chain transactions
Handling network and rate limit errors

Error Envelope Format

{
  "ok": false,
  "error": {
    "category": "validation",
    "code": "UNKNOWN_MARKET",
    "message": "Market not found",
    "retryable": false
  }
}

Category Routing Table

Category	Exit	Retryable	Action
`validation`	1	No	Fix the input. Common: UNKNOWN_MARKET, MISSING_ARG, INVALID_INTERVAL
`auth`	2	No	Check wallet exists and password is correct. Run `vulcan wallet list`
`config`	3	No	Run `vulcan setup` to recreate config
`api`	4	No	Phoenix API issue. Check `vulcan status` for connectivity
`network`	5	Yes	Transient. Retry with exponential backoff (1s, 2s, 4s)
`rate_limit`	6	Yes	Wait 5s and retry. Reduce request frequency
`tx_failed`	7	No	Critical: verify state before retrying. See below
`io`	8	Yes	File permission issue. Check `~/.vulcan/` permissions
`dangerous_gate`	9	No	Add `acknowledged: true` to the tool call
`internal`	10	No	Bug in vulcan. Report it

tx_failed Recovery (Critical)

On-chain transactions can fail in complex ways. Never blind-retry.

Check position state first:

vulcan_position_list → {}
vulcan_margin_status → {}

Common causes:
- Blockhash expired — transaction took too long. Safe to retry with fresh state.
- Insufficient SOL for fees — check vulcan_wallet_balance.
- Account state changed — another transaction modified the account between build and send.
- Slippage exceeded — market moved. Re-check price and retry.

Recovery pattern:

1. vulcan_position_list → {}           # did the original tx partially succeed?
2. vulcan_margin_status → {}           # is collateral state as expected?
3. vulcan_wallet_balance → {}          # enough SOL for fees?
4. vulcan_market_ticker → { symbol }   # has price moved significantly?
5. Re-attempt the operation if state is clean

Network Error Recovery

1. Wait 1 second
2. Retry the same call
3. If still failing, wait 2 seconds and retry
4. After 3 failures, check connectivity: vulcan_status → {}
5. Report to user if API is down

Common Error Codes and Fixes

Code	Fix
`UNKNOWN_MARKET`	Run `vulcan_market_list` to see available symbols
`MISSING_ARG`	Check tool schema for required fields
`NO_POSITION`	No open position. Check `vulcan_position_list`
`ISOLATED_ONLY_MARKET`	Re-run with `isolated: true, collateral: <amount>`
`NO_DEFAULT_WALLET`	Run `vulcan wallet set-default <name>`
`DECRYPT_FAILED`	Wrong password. Check `VULCAN_WALLET_PASSWORD`
`NO_TRADER_ACCOUNT`	Register with `vulcan_account_register`
`BUILD_TPSL_FAILED`	TP/SL only works when opening/extending a position. Same-call TP/SL is supported on market orders and cross-margin limit orders; use post-hoc TP/SL tools for isolated limit orders.

Más de este repositorio

mismo repositorio

clawd-code-skill

Solizardking/solana-clawd

Development conventions and architecture guide for the Clawd Code CLI repository — a Solana-native AI coding agent with perps trading, image generation, voice, and x402 payments.

2026-07-030

agent-registry

Solizardking/solana-clawd

Register, discover, and hire autonomous AI agents on Solana. On-chain identity via Metaplex Core NFTs (8004-solana SDK or REST API). Search by capability, check reputation backed by $CLAWD payment proofs, browse the service catalog, and get machine-readable hiring instructions. Supports Google A2A agent-card.json and Anthropic MCP server-card.json. No EVM — Solana only.

2026-06-170

solana-rpc

Solizardking/solana-clawd

Solana RPC data toolkit — 8-command CLI for live on-chain data: SOL balance + SPL token portfolio with USD values, transaction detail with balance changes, SPL token metadata + top holders, recent activity history, NFT portfolio (SPL + cNFT via Helius DAS), whale detector, network stats (TPS/epoch/price), and quick price lookup. Pure Python stdlib, no extra packages. Optional HELIUS_API_KEY for compressed NFT detection.

2026-06-150

clawd-guard-secrets

Solizardking/solana-clawd

Clawd Guard — the sovereign secrets sentinel. Mandatory reading for every Solana developer before they push a single commit. Use when: setting up a new repo, reviewing a .gitignore, onboarding a dev, or after any "oops I committed my private key" incident. Covers every secrets pattern that must never touch git: wallet JSON files, keypairs, .env files, private keys, API tokens, service account credentials, and IDE/OS junk. Built by Clawd to stop you from becoming a cautionary tale.

2026-06-080

greptile

Solizardking/solana-clawd

AI code reviews via Greptile — trigger PR reviews, run local CLI reviews, query codebase graphs, apply auto-fixes, manage custom rules, and analyze review analytics. Use for code review, PR feedback, issue triage, and codebase exploration.

2026-06-080

clawd-tui

Solizardking/solana-clawd

Clawd TUI perps screen integration. Use when the user asks about the Clawd terminal UI, the Phoenix perps screen inside the TUI, paper trading from the TUI, or how the TUI drives Vulcan.

2026-06-080

vulcan-error-recovery

Use this skill for:

Routing errors by category

Recovering from failed on-chain transactions

Handling network and rate limit errors

Error Envelope Format

{ "ok": false, "error": { "category": "validation", "code": "UNKNOWN_MARKET", "message": "Market not found", "retryable": false } }

Category Routing Table

Category

Exit

Retryable

Action

validation

Fix the input. Common: UNKNOWN_MARKET, MISSING_ARG, INVALID_INTERVAL

auth

Check wallet exists and password is correct. Run vulcan wallet list

config

Run vulcan setup to recreate config

api

Phoenix API issue. Check vulcan status for connectivity

network

Yes

Transient. Retry with exponential backoff (1s, 2s, 4s)

rate_limit

Yes

Wait 5s and retry. Reduce request frequency

tx_failed

Critical: verify state before retrying. See below

io

Yes

File permission issue. Check ~/.vulcan/ permissions

dangerous_gate

Add acknowledged: true to the tool call

internal

Bug in vulcan. Report it

tx_failed Recovery (Critical)

On-chain transactions can fail in complex ways. Never blind-retry.

Check position state first:

vulcan_position_list → {}
vulcan_margin_status → {}

Common causes:

Blockhash expired — transaction took too long. Safe to retry with fresh state.
Insufficient SOL for fees — check vulcan_wallet_balance.
Account state changed — another transaction modified the account between build and send.
Slippage exceeded — market moved. Re-check price and retry.

Recovery pattern:

1. vulcan_position_list → {}           # did the original tx partially succeed?
2. vulcan_margin_status → {}           # is collateral state as expected?
3. vulcan_wallet_balance → {}          # enough SOL for fees?
4. vulcan_market_ticker → { symbol }   # has price moved significantly?
5. Re-attempt the operation if state is clean

Network Error Recovery

1. Wait 1 second 2. Retry the same call 3. If still failing, wait 2 seconds and retry 4. After 3 failures, check connectivity: vulcan_status → {} 5. Report to user if API is down

Common Error Codes and Fixes

Code

Fix

UNKNOWN_MARKET

Run vulcan_market_list to see available symbols

MISSING_ARG

Check tool schema for required fields

NO_POSITION

No open position. Check vulcan_position_list

ISOLATED_ONLY_MARKET

Re-run with isolated: true, collateral: <amount>

NO_DEFAULT_WALLET

Run vulcan wallet set-default <name>

DECRYPT_FAILED

Wrong password. Check VULCAN_WALLET_PASSWORD

NO_TRADER_ACCOUNT

BUILD_TPSL_FAILED

TP/SL only works when opening/extending a position. Same-call TP/SL is supported on market orders and cross-margin limit orders; use post-hoc TP/SL tools for isolated limit orders.