# Utilia Agent Media and Solana Tools

Utilia normalizes audio, converts public PDFs to agent-ready Markdown, and gives
Solana transaction bots live, account-localized transaction intelligence. Each tool
accepts exact x402 USDC payments without accounts, subscriptions, or API keys.

## Audio normalization

`POST /v1/audio/normalize` accepts one public HTTPS audio URL or base64 audio payload
and returns a bounded 128 kbps MP3 as base64. The `$0.01` response includes input and
output digests, output duration, truncation status, and FFmpeg loudness measurements.
The default target is `-16 LUFS`; callers can select `-24` through `-12 LUFS` and cap
output between 1 and 180 seconds.

```json
{
  "url": "https://example.com/voice-note.wav",
  "targetLufs": -16,
  "maxSeconds": 180
}
```

## PDF to Markdown in one command

```sh
export SOLANA_KEYPAIR_PATH=/absolute/path/to/agent-wallet.json
npx -y utilia-solana-agent pdf-to-markdown https://example.com/document.pdf
```

The `$0.0025` response includes page-delimited Markdown, page count, metadata, and a
source SHA-256 digest. Install the dedicated agent skill with:

```sh
npx skills add mohamedkuch/utilia-solana-agent \
  --skill utilia-pdf-to-markdown -g -y
```

The same skill is 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).

## Live Solana priority fees

For the shortest wallet-managed flow, AgentCash can inspect the live quote, pay
the x402 challenge, and retry the request:

```sh
npx -y agentcash@latest check https://api.utilia.ink/base/v1/fees/priority
npx -y agentcash@latest fetch https://api.utilia.ink/base/v1/fees/priority --yes
```

Run a JSONL fee watcher at five calls per hour, capped at 25 calls and $0.05:

```sh
export SOLANA_KEYPAIR_PATH=/absolute/path/to/low-balance-agent-wallet.json
npx -y utilia-solana-agent watch-fees --every 12m --max-calls 25
```

## Product

| Endpoint                         |   Price | Result                                                                   |
| -------------------------------- | ------: | ------------------------------------------------------------------------ |
| `GET /v1/transaction/:signature` |  $0.004 | Transaction outcome, deltas, logs, compute use, and error classification |
| `POST /v1/transaction/simulate`  |  $0.008 | Pre-broadcast simulation and failure explanation                         |
| `GET /v1/fees/priority`          |  $0.002 | Recent priority-fee quantiles                                            |
| `POST /v1/token/risk`            |  $0.006 | Workflow-friendly mint safety check with a JSON `{ "mint": "..." }` body |
| `GET /v1/token/:mint`            |  $0.006 | Mint controls, Token-2022 features, and concentration signals            |
| `POST /v1/pdf/to-markdown`       | $0.0025 | PDF text, page-delimited Markdown, metadata, and source digest           |
| `POST /v1/audio/normalize`       |   $0.01 | Bounded normalized MP3, loudness measurements, and content digests       |

All six products are also available as paid tools from the remote Streamable HTTP
MCP server at `https://api.utilia.ink/mcp`. Its public server metadata is available
at `https://api.utilia.ink/server.json`.

The server is published in the official MCP Registry as
[`ink.utilia/solana-preflight`](https://registry.modelcontextprotocol.io/?q=ink.utilia%2Fsolana-preflight).
The public API contract is available at
[`https://api.utilia.ink/openapi.json`](https://api.utilia.ink/openapi.json), and
live availability is reported by
[`https://api.utilia.ink/healthz`](https://api.utilia.ink/healthz).

The priority-fee, PDF-to-Markdown, token-safety, and transaction-simulation products
are ownership-verified and immediately runnable through x402.jobs. The live fee feed
is listed on both
[Solana](https://x402.jobs/resources/api-utilia-ink/utilia-solana-priority-fee-feed)
and
[Base](https://x402.jobs/resources/api-utilia-ink/utilia-solana-priority-fee-feed-on-base);
the PDF converter is likewise listed on
[Solana](https://x402.jobs/resources/api-utilia-ink/utilia-pdf-to-markdown-solana)
and
[Base](https://x402.jobs/resources/api-utilia-ink/utilia-pdf-to-markdown-base).
The workflow-friendly
[Base token-safety resource](https://www.x402.jobs/resources/api-utilia-ink/solana-token-safety-check-base)
accepts a Solana mint as JSON. Agents can also call the public
[audio-normalization resources on Solana](https://www.x402.jobs/resources/api-utilia-ink/utilia-audio-loudness-normalization-solana)
or
[Base](https://www.x402.jobs/resources/api-utilia-ink/utilia-audio-loudness-normalization-base),
the
[Solana Priority Fee Oracle workflow](https://www.x402.jobs/@utilia/solana-priority-fee-oracle-u0y57t),
or the
[Solana Token Safety Check workflow](https://www.x402.jobs/jobs/cdc9fa61-5a1a-4650-995b-d2f411d9cf14).
The public
[Normalize Audio to MP3 workflow](https://www.x402.jobs/jobs/7fdd196a-ee87-44ee-b9c4-0eb238e8af05)
accepts a public audio URL and passes the normalized MP3 result through to the buyer.
Agents can call its paid webhook directly at
`https://api.x402.jobs/@utilia/normalize-audio-to-mp3-dnx1du`.

Each HTTP product also has a `/base/v1/...` alias for Base USDC buyers and Coinbase
Agentic Market discovery. The canonical `/v1/...` routes and MCP tools continue to
settle on Solana.

For agents that prefer a marketplace purchase flow, Utilia also has native
[PayanAgent offers](https://payanagent.com/api/v1/discover?q=utilia), including
[audio normalization](https://payanagent.com/marketplace/offers/kh7e4z3jrcq2adhxym94v9kedh8b469d),
and four
healthy, instant-delivery services in
[the402 catalog](https://api.the402.ai/v1/services/catalog?q=utilia): priority
fees, Solana token safety, PDF-to-Markdown, and
[FFmpeg audio normalization](https://api.the402.ai/v1/services/svc_264e8bba8b504ca0).

Installable agent instructions are publicly available through
[ClawHub](https://clawhub.ai/mohamedkuch/skills/utilia-solana-preflight), including
the dedicated
[audio-normalization skill](https://clawhub.ai/mohamedkuch/skills/utilia-audio-normalization),
and through
[skills.sh](https://skills.sh/mohamedkuch/utilia-solana-agent/utilia-audio-normalization)
and
[Smithery](https://smithery.ai/skills/medksbuss/utilia-audio-normalization).
The direct MCP record is also indexed by
[Agent Tools Cloud](https://agent-tools.cloud/api/v1/mcp/servers/utilia-solana-priority-fee-feed-api-utilia-ink).

The PDF and audio transforms accept either a public HTTPS URL or a base64 payload,
reject private-network fetches, and cap input at 8 MiB. Audio output is additionally
capped at 5 MiB and 180 seconds; PDF input is capped at 100 pages and explicitly
reports that scanned image-only documents require OCR. The public homepage, health
check, and OpenAPI document are free. A paid request that ends in a 4xx or 5xx
response is canceled before x402 settlement.

For a guarded audio conversion that verifies the returned digest and writes the MP3
without overwriting an existing file:

```sh
npx -y utilia-solana-agent@0.4.2 audio-normalize <public-https-audio-url> \
  --output normalized.mp3
```

## Agent quick start

An x402-capable MCP agent connects to `https://api.utilia.ink/mcp`, lists the six
tools, and pays automatically only when it calls one. A runnable client with a strict
maximum-payment policy is included in [`examples/mcp-client.mjs`](examples/mcp-client.mjs).

Remote MCP configuration:

```json
{
  "mcpServers": {
    "utilia": {
      "type": "streamable-http",
      "url": "https://api.utilia.ink/mcp"
    }
  }
}
```

```sh
SOLANA_PRIVATE_KEY='base58-wallet-private-key' \
  node examples/mcp-client.mjs solana_priority_fees '{"accounts":[]}'
```

## Local development

Requirements: Node.js 22 and npm.

```sh
npm ci
HELIUS_API_KEY=your-key PAYMENTS_ENABLED=false npm run dev
```

Then open `http://localhost:4021`. Payments are deliberately disabled for local tests.

Run the complete verification suite:

```sh
npm test
npm run build
npm run lint
npm run format:check
npm audit
```

## Production model

- Solana RPC is supplied by Helius.
- Exact USDC payment verification and settlement initially uses the PayAI x402
  facilitator. `FACILITATOR_MODE` controls the primary Solana/multi-network routes,
  while `EVM_FACILITATOR_MODE` independently lets the `/base/...` aliases use CDP
  without changing the Solana path.
- Bazaar discovery metadata is attached to every Solana and Base paid route.
- The remote MCP server is published through the official MCP Registry.
- Caddy terminates TLS and proxies only to a loopback-bound Docker port.
- The container runs as an unprivileged user with a read-only filesystem, no Linux
  capabilities, bounded memory/CPU/PIDs, and rotated logs.
- The server stores no wallet private keys. `SVM_PAY_TO` and `EVM_PAY_TO` are only
  public receiving addresses.

See [Architecture](docs/ARCHITECTURE.md) and [Operations](docs/OPERATIONS.md).

## Economics

Revenue is usage multiplied by endpoint price, less facilitator fees, infrastructure,
RPC costs, taxes, refunds, and payment conversion costs. This software creates a
sellable service; it does not guarantee demand or profit. The initial prices remain
above PayAI's published post-free-tier per-settlement fee and should be revisited using
real conversion, retention, and endpoint-cost data.

## License

Source available for inspection. Copyright © 2026 Mohamed Kechaou. All rights
reserved; no license is granted to copy, modify, or redistribute the server source.