Are you the author? Sign in to claim
Guarded x402 client for Solana transaction diagnosis, simulation, token risk, and budget-capped live priority fees.
Turn a failed Solana signature into a support-ready answer: what landed, what changed, why it failed, and what is safe to try next. The package connects to Utilia, handles x402 payments locally, and can run as a guarded CLI, a budget-capped fee watcher, or a standard stdio MCP server.
No Utilia account, API key, or subscription is required. Calls cost between $0.002 and $0.01 in USDC on Solana or Base.
Use a dedicated low-balance Solana automation wallet that holds a small amount of mainnet USDC and SOL for fees:
export SOLANA_KEYPAIR_PATH=/absolute/path/to/automation-wallet.json
npx -y utilia-solana-agent@0.5.8 doctor
npx -y utilia-solana-agent@0.5.8 transaction <signature>
The diagnosis costs exactly $0.004 USDC and returns confirmation state, fee, compute use, SOL and token deltas, program logs, a stable failure class, and a retry-aware suggested action.
export SOLANA_KEYPAIR_PATH=/absolute/path/to/automation-wallet.json
npx -y utilia-solana-agent@0.5.8 watch-fees \
--every 12m \
--max-calls 25
The first JSONL result is immediate, then one result is emitted every 12 minutes:
five calls per hour for $0.01, with an automatic $0.05 maximum. Each line
includes the observation time, fee quantiles, paid amount, and settlement
transaction. Add --accounts account1,account2 to localize the estimate to the
writable accounts in a transaction.
Agents that already use AgentCash can make the lowest-cost live call without handling a private key directly:
npx -y agentcash@latest balance
npx -y agentcash@latest fetch \
https://api.utilia.ink/base/v1/fees/priority --yes
This route returns live Solana priority-fee data and settles the exact $0.002
USDC payment on Base. AgentCash creates and manages its own wallet on first
use; balance reports its available funds and funding accounts. Utilia never
receives or controls the payer's key.
Install the transaction workflow into Codex, Claude Code, OpenClaw, Cursor, or any other agent supported by the open Skills CLI:
npx skills add mohamedkuch/utilia-solana-agent \
--skill utilia-solana-transaction-diagnosis -g -y
Then ask the agent to use $utilia-solana-transaction-diagnosis to explain a
failed signature. The broader $utilia-solana-preflight skill also covers live
priority fees, token risk, and pre-broadcast simulation.
| Tool | Result | Price |
|---|---|---|
solana_priority_fees | Recent priority-fee quantiles | $0.002 |
solana_transaction_analysis | Confirmed transaction, deltas, logs, failure guidance | $0.004 |
solana_token_analysis | Authorities, Token-2022 controls, concentration, risk flags | $0.006 |
solana_transaction_simulate | Pre-broadcast simulation and failure classification | $0.008 |
pdf_to_markdown | Page-delimited Markdown, metadata, and a source digest | $0.0025 |
normalize_audio | Bounded normalized MP3, loudness measurements, and digests | $0.01 |
The same guarded client also exposes two bounded non-Solana transforms:
npx -y utilia-solana-agent@0.5.8 pdf-to-markdown \
https://example.com/document.pdf --max-pages 20
npx -y utilia-solana-agent@0.5.8 audio-normalize \
https://example.com/voice-note.wav --output voice-note-normalized.mp3
PDF conversion costs $0.0025 USDC and returns page-delimited Markdown, metadata, and a source digest. Audio normalization costs $0.01 USDC, targets -16 integrated LUFS by default, verifies the saved MP3 locally, and returns loudness evidence plus content digests.
Dedicated skills are available as utilia-pdf-to-markdown and
utilia-audio-normalization.
Use a dedicated low-balance Solana automation wallet that holds a small amount of mainnet USDC and SOL for fees.
export SOLANA_KEYPAIR_PATH=/absolute/path/to/automation-wallet.json
npx -y utilia-solana-agent doctor
npx -y utilia-solana-agent fees
For a JSONL fee feed at five calls per hour, capped at 25 calls and $0.05 total:
npx -y utilia-solana-agent watch-fees --every 12m --max-calls 25
The first result is immediate, then one result is emitted every 12 minutes. The
process stops after 25 calls; Ctrl-C stops it sooner. Localize estimates to the
writable accounts used by your transaction builder with
--accounts account1,account2.
You can alternatively set SOLANA_PRIVATE_KEY to a base58-encoded 64-byte private
key. Environment variables are inherited by the local process; the private key is
never sent to Utilia.
Use the same wallet already attached to Solana Agent Kit. The plugin adds four budget-capped, read-only actions without asking for a second private key:
import { SolanaAgentKit } from "solana-agent-kit";
import { createUtiliaPlugin } from "utilia-solana-agent";
const agent = new SolanaAgentKit(wallet, rpcUrl, {}).use(createUtiliaPlugin());
const fees = await agent.methods.utiliaPriorityFees(agent, {
accounts: writableAccounts,
});
The registered agent actions are UTILIA_PRIORITY_FEES,
UTILIA_SIMULATE_TRANSACTION, UTILIA_ANALYZE_TRANSACTION, and
UTILIA_ANALYZE_TOKEN. Payments are signed by the Agent Kit wallet only after the
same receiver, asset, network, and per-call maximum checks described below pass.
The wallet must implement Agent Kit's signMessage() method and hold a small amount
of Solana mainnet USDC; the facilitator pays the transaction fee.
Add this stdio server to any MCP client that supports an executable command:
{
"mcpServers": {
"utilia": {
"command": "npx",
"args": ["-y", "utilia-solana-agent@0.5.8", "mcp"],
"env": {
"SOLANA_KEYPAIR_PATH": "/absolute/path/to/automation-wallet.json"
}
}
}
}
The local bridge advertises all six Utilia tools without loading or transmitting a
wallet. When the agent calls one, the bridge loads the configured wallet locally,
verifies the payment request, signs the exact USDC payment, and returns the paid
result. A wallet is therefore required for tool execution, not for MCP initialization
or tools/list.
npx -y utilia-solana-agent fees [account1,account2]
npx -y utilia-solana-agent watch-fees [--every 12m] [--max-calls 25] [--accounts account1,account2]
npx -y utilia-solana-agent transaction <signature>
npx -y utilia-solana-agent simulate <serialized-transaction> [base64|base58]
npx -y utilia-solana-agent token <mint>
npx -y utilia-solana-agent@0.5.8 audio-normalize <public-https-audio-url> [--output normalized.mp3] [--target-lufs -16] [--max-seconds 180]
npx -y utilia-solana-agent@0.5.8 pdf <public-https-pdf-url> [max-pages]
npx -y utilia-solana-agent@0.5.8 pdf-to-markdown <public-https-pdf-url> [--max-pages 50]
npx -y utilia-solana-agent call <tool-name> '<json-arguments>'
The package will only approve a payment when every field matches:
A changed receiver, asset, network, zero amount, malformed amount, or higher amount is rejected before signing. The package has no withdrawal, swap, token-launch, or arbitrary-transaction capability.
https://api.utilia.ink/mcphttps://api.utilia.ink/openapi.jsonhttps://api.utilia.ink/.well-known/x402ink.utilia/solana-preflightMIT
Run Claude Code as an MCP server so any agent can delegate coding tasks to it
@microsoft✓ OfficialBrowser automation using accessibility snapshots instead of screenshots
@googleapis✓ OfficialGoogle's universal MCP server supporting PostgreSQL, MySQL, MongoDB, Redis, and 10+ databases
@github✓ OfficialOfficial GitHub integration for repos, issues, PRs, and CI/CD workflows