utilia-solana-agent

Normalize public audio to a bounded MP3, convert a PDF to agent-ready Markdown, or give a Solana bot a live priority-fee signal in one command. 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.

Fastest wallet-managed proof

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. Agents that prefer native Solana settlement can use the guarded client below.

Related MCP server: ntriq-agentshop

Audio normalization in one command

export SOLANA_KEYPAIR_PATH=/absolute/path/to/automation-wallet.json
npx -y utilia-solana-agent@0.5.7 doctor
npx -y utilia-solana-agent@0.5.7 audio-normalize \
  https://example.com/voice-note.wav --output voice-note-normalized.mp3

The call costs exactly $0.01 USDC. It normalizes to -16 integrated LUFS by default, returns loudness evidence and content digests, verifies the output locally, and writes a 128 kbps MP3 without overwriting an existing file. Use --target-lufs -18 or --max-seconds 90 when needed.

PDF to Markdown in one command

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.7 doctor
npx -y utilia-solana-agent@0.5.7 pdf-to-markdown https://example.com/document.pdf

Each conversion costs exactly $0.0025 USDC and returns page-delimited Markdown, metadata, and a source SHA-256 digest. Limit extraction with --max-pages 20.

Install as an agent skill

Install the dedicated PDF skill 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-pdf-to-markdown -g -y

Then ask the agent to use $utilia-pdf-to-markdown on a public PDF. Install utilia-audio-normalization for audio workflows or utilia-solana-preflight for Solana transaction workflows. The PDF skill is also browsable on skills.sh and Smithery.

What agents can do

Solana quick start

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.

Solana Agent Kit plugin

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 it to an MCP client

Add this stdio server to any MCP client that supports an executable command:

{
  "mcpServers": {
    "utilia": {
      "command": "npx",
      "args": ["-y", "utilia-solana-agent@0.5.7", "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.

CLI

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.7 audio-normalize <public-https-audio-url> [--output normalized.mp3] [--target-lufs -16] [--max-seconds 180]
npx -y utilia-solana-agent@0.5.7 pdf <public-https-pdf-url> [max-pages]
npx -y utilia-solana-agent@0.5.7 pdf-to-markdown <public-https-pdf-url> [--max-pages 50]
npx -y utilia-solana-agent call <tool-name> '<json-arguments>'

Payment guardrails

The package will only approve a payment when every field matches:

• network: Solana mainnet

• asset: official Solana mainnet USDC

• receiver: Utilia's published wallet

• maximum: 10,000 atomic USDC, or $0.01, per tool call

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.

Machine-readable endpoints

• Remote MCP: https://api.utilia.ink/mcp

• OpenAPI: https://api.utilia.ink/openapi.json

• x402 discovery: https://api.utilia.ink/.well-known/x402

• MCP registry package: ink.utilia/solana-preflight

License

MIT