{
  "markdown": "# utilia-solana-agent\n\nTurn a failed Solana signature into a support-ready answer: what landed, what\nchanged, why it failed, and what is safe to try next. The package connects to\n[Utilia](https://utilia.ink/solana-transaction-support), handles x402 payments\nlocally, and can run as a guarded CLI, a budget-capped fee watcher, or a standard\nstdio MCP server.\n\nNo Utilia account, API key, or subscription is required. Calls cost between $0.002\nand $0.01 in USDC on Solana or Base.\n\n## Copy-paste buyer fixtures\n\nFour guarded examples cover automatic x402 v2 payment and retry over Base MCP,\nSolana MCP, Base HTTP, and Solana HTTP. Each fixture pins the host, network, asset,\nreceiver, resource, timeout, per-call maximum, one-call total budget, and exact\ntool before a wallet may sign.\n\nSee [examples/buyers/README.md](examples/buyers/README.md). Fixture output is\nexplicitly labeled as an operator compatibility test, not customer demand.\n\nFor a single public, machine-verifiable Base artifact, use the stricter\n[compatibility fixture](examples/compatibility/README.md):\n\n```sh\nBASE_PRIVATE_KEY=0xYOUR_32_BYTE_LOW_BALANCE_KEY npm run --silent compatibility:base -- --source your_runtime_fixture\n```\n\nIt caps the payment at $0.002, reuses one request ID across challenge and retry,\nprints a response SHA-256 and settlement evidence, and ships with a public JSON\nSchema plus an offline verifier.\n\n## Diagnose one failed transaction\n\nUse a dedicated low-balance Solana automation wallet that holds a small amount of\nmainnet USDC and SOL for fees:\n\n```sh\nexport SOLANA_KEYPAIR_PATH=/absolute/path/to/automation-wallet.json\nnpx -y utilia-solana-agent@0.5.8 doctor\nnpx -y utilia-solana-agent@0.5.8 transaction <signature>\n```\n\nThe diagnosis costs exactly **$0.004 USDC** and returns confirmation state, fee,\ncompute use, SOL and token deltas, program logs, a stable failure class, and a\nretry-aware suggested action.\n\n## Run a budget-capped priority-fee feed\n\n```sh\nexport SOLANA_KEYPAIR_PATH=/absolute/path/to/automation-wallet.json\nnpx -y utilia-solana-agent@0.5.8 watch-fees \\\n  --every 12m \\\n  --max-calls 25\n```\n\nThe first JSONL result is immediate, then one result is emitted every 12 minutes:\nfive calls per hour for **$0.01**, with an automatic **$0.05** maximum. Each line\nincludes the observation time, fee quantiles, paid amount, and settlement\ntransaction. Add `--accounts account1,account2` to localize the estimate to the\nwritable accounts in a transaction.\n\n## Fastest wallet-managed proof\n\nAgents that already use AgentCash can make the lowest-cost live call without\nhandling a private key directly:\n\n```sh\nnpx -y agentcash@latest balance\nnpx -y agentcash@latest fetch \\\n  https://api.utilia.ink/base/v1/fees/priority --yes\n```\n\nThis route returns live Solana priority-fee data and settles the exact **$0.002\nUSDC** payment on Base. AgentCash creates and manages its own wallet on first\nuse; `balance` reports its available funds and funding accounts. Utilia never\nreceives or controls the payer's key.\n\n## Install the Solana evidence skill\n\nInstall the transaction workflow into Codex, Claude Code, OpenClaw, Cursor, or any\nother agent supported by the open Skills CLI:\n\n```sh\nnpx skills add mohamedkuch/utilia-solana-agent \\\n  --skill utilia-solana-transaction-diagnosis -g -y\n```\n\nThen ask the agent to use `$utilia-solana-transaction-diagnosis` to explain a\nfailed signature. The broader `$utilia-solana-preflight` skill also covers live\npriority fees, token risk, and pre-broadcast simulation.\n\n## What agents can do\n\n| Tool                          | Result                                                      |   Price |\n| ----------------------------- | ----------------------------------------------------------- | ------: |\n| `solana_priority_fees`        | Recent priority-fee quantiles                               |  $0.002 |\n| `solana_transaction_analysis` | Confirmed transaction, deltas, logs, failure guidance       |  $0.004 |\n| `solana_token_analysis`       | Authorities, Token-2022 controls, concentration, risk flags |  $0.006 |\n| `solana_transaction_simulate` | Pre-broadcast simulation and failure classification         |  $0.008 |\n| `pdf_to_markdown`             | Page-delimited Markdown, metadata, and a source digest      | $0.0025 |\n| `normalize_audio`             | Bounded normalized MP3, loudness measurements, and digests  |   $0.01 |\n\n## PDF and audio utility transforms\n\nThe same guarded client also exposes two bounded non-Solana transforms:\n\n```sh\nnpx -y utilia-solana-agent@0.5.8 pdf-to-markdown \\\n  https://example.com/document.pdf --max-pages 20\nnpx -y utilia-solana-agent@0.5.8 audio-normalize \\\n  https://example.com/voice-note.wav --output voice-note-normalized.mp3\n```\n\nPDF conversion costs **$0.0025 USDC** and returns page-delimited Markdown,\nmetadata, and a source digest. Audio normalization costs **$0.01 USDC**, targets\n-16 integrated LUFS by default, verifies the saved MP3 locally, and returns\nloudness evidence plus content digests.\n\nDedicated skills are available as `utilia-pdf-to-markdown` and\n`utilia-audio-normalization`.\n\n## Solana quick start\n\nUse a dedicated low-balance Solana automation wallet that holds a small amount of\nmainnet USDC and SOL for fees.\n\n```sh\nexport SOLANA_KEYPAIR_PATH=/absolute/path/to/automation-wallet.json\nnpx -y utilia-solana-agent doctor\nnpx -y utilia-solana-agent fees\n```\n\nFor a JSONL fee feed at five calls per hour, capped at 25 calls and **$0.05 total**:\n\n```sh\nnpx -y utilia-solana-agent watch-fees --every 12m --max-calls 25\n```\n\nThe first result is immediate, then one result is emitted every 12 minutes. The\nprocess stops after 25 calls; `Ctrl-C` stops it sooner. Localize estimates to the\nwritable accounts used by your transaction builder with\n`--accounts account1,account2`.\n\nYou can alternatively set `SOLANA_PRIVATE_KEY` to a base58-encoded 64-byte private\nkey. Environment variables are inherited by the local process; the private key is\nnever sent to Utilia.\n\n## Solana Agent Kit plugin\n\nUse the same wallet already attached to\n[Solana Agent Kit](https://github.com/sendaifun/solana-agent-kit). The plugin adds\nfour budget-capped, read-only actions without asking for a second private key:\n\n```js\nimport { SolanaAgentKit } from \"solana-agent-kit\";\nimport { createUtiliaPlugin } from \"utilia-solana-agent\";\n\nconst agent = new SolanaAgentKit(wallet, rpcUrl, {}).use(createUtiliaPlugin());\n\nconst fees = await agent.methods.utiliaPriorityFees(agent, {\n  accounts: writableAccounts,\n});\n```\n\nThe registered agent actions are `UTILIA_PRIORITY_FEES`,\n`UTILIA_SIMULATE_TRANSACTION`, `UTILIA_ANALYZE_TRANSACTION`, and\n`UTILIA_ANALYZE_TOKEN`. Payments are signed by the Agent Kit wallet only after the\nsame receiver, asset, network, and per-call maximum checks described below pass.\nThe wallet must implement Agent Kit's `signMessage()` method and hold a small amount\nof Solana mainnet USDC; the facilitator pays the transaction fee.\n\n## Add it to an MCP client\n\nAdd this stdio server to any MCP client that supports an executable command:\n\n```json\n{\n  \"mcpServers\": {\n    \"utilia\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"utilia-solana-agent@0.5.8\", \"mcp\"],\n      \"env\": {\n        \"SOLANA_KEYPAIR_PATH\": \"/absolute/path/to/automation-wallet.json\"\n      }\n    }\n  }\n}\n```\n\nThe local bridge advertises all six Utilia tools without loading or transmitting a\nwallet. When the agent calls one, the bridge loads the configured wallet locally,\nverifies the payment request, signs the exact USDC payment, and returns the paid\nresult. A wallet is therefore required for tool execution, not for MCP initialization\nor `tools/list`.\n\n## CLI\n\n```sh\nnpx -y utilia-solana-agent fees [account1,account2]\nnpx -y utilia-solana-agent watch-fees [--every 12m] [--max-calls 25] [--accounts account1,account2]\nnpx -y utilia-solana-agent transaction <signature>\nnpx -y utilia-solana-agent simulate <serialized-transaction> [base64|base58]\nnpx -y utilia-solana-agent token <mint>\nnpx -y utilia-solana-agent@0.5.8 audio-normalize <public-https-audio-url> [--output normalized.mp3] [--target-lufs -16] [--max-seconds 180]\nnpx -y utilia-solana-agent@0.5.8 pdf <public-https-pdf-url> [max-pages]\nnpx -y utilia-solana-agent@0.5.8 pdf-to-markdown <public-https-pdf-url> [--max-pages 50]\nnpx -y utilia-solana-agent call <tool-name> '<json-arguments>'\n```\n\n## Payment guardrails\n\nThe package will only approve a payment when every field matches:\n\n- network: Solana mainnet\n- asset: official Solana mainnet USDC\n- receiver: Utilia's published wallet\n- maximum: 10,000 atomic USDC, or $0.01, per tool call\n\nA changed receiver, asset, network, zero amount, malformed amount, or higher amount is\nrejected before signing. The package has no withdrawal, swap, token-launch, or\narbitrary-transaction capability.\n\n## Machine-readable endpoints\n\n- Remote MCP: `https://api.utilia.ink/mcp`\n- OpenAPI: `https://api.utilia.ink/openapi.json`\n- x402 discovery: `https://api.utilia.ink/.well-known/x402`\n- MCP registry package: `ink.utilia/solana-preflight`\n\n## License\n\nMIT\n",
  "bytes": 9044,
  "sha": "3812acf76f4269d86c9fd72abd30c1509ded9e2b80cbff04a4d37e37bc8da77a",
  "repo_slug": "mohamedkuch/utilia-solana-agent",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ink_utilia_solana_preflight_d8d532b6/readme"
}