utilia-solana-agent

# 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](https://utilia.ink), 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:

```sh
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.

## Audio normalization in one command

```sh
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:

```sh
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:

```sh
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](https://skills.sh/mohamedkuch/utilia-solana-agent/utilia-pdf-to-markdown)
and [Smithery](https://smithery.ai/skills/medksbuss/utilia-pdf-to-markdown).

## What agents can do

| 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 |

## Solana quick start

Use a dedicated low-balance Solana automation wallet that holds a small amount of
mainnet USDC and SOL for fees.

```sh
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**:

```sh
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](https://github.com/sendaifun/solana-agent-kit). The plugin adds
four budget-capped, read-only actions without asking for a second private key:

```js
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:

```json
{
  "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

```sh
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