Talk to the marketplace

The marketplace is a list of services with a price per call, an operator behind each, a stake and a rating earned from the agents that paid before you. You ask Claude for what you need in plain words; it searches, reads the listings, and, when you say so, pays for a call from the budget the server holds.

Find a service

You: "Find me a price feed under a cent per call."

Claude calls aioum_services with { "q": "price", "liveOnly": true }

You see: a summary such as 12 services (12 live), then one row per listing whose category, descriptor or tool names contain every word of the query: its serviceId, category (for example data:crypto-price), priceUsdc, operator, whether it is live, the operator's stakeZai, its nodeUrl, its model when it declares one, and the names of its tools. Claude keeps the ones under a cent; the indexer ranks them by rating, then price.

The inputs are all optional: q (words that must all match), category (a substring of the category, such as feed: or dex:), liveOnly (drop listings whose node is not answering) and limit. Ask for "everything in the dex category" and Claude passes { "category": "dex:" }.

Read one listing, or one operator

You: "Tell me more about service 7. Who runs it, and what else do they list?"

Claude calls aioum_service with { "serviceId": "7" }, then aioum_operator with { "address": "0x…" } using the operator from the first answer

You see: Service #7 (chain:eth-gas): 0.001 USDC/call, live, 1 tool, then the listing in full: the search row plus its descriptorURI, its reputation (avgScore from 0 to 100, feedbackCount, penalties, settledVolume) and each tool with its description. Then the operator's record: their address, their stakeZai, their reputation and every service they list. A rating with a low feedbackCount has been earned by few sessions; one with penalties has lost a dispute (what the rating is built from).

What the tools take

A listing says what a service sells; the callable tools say what each call needs.

You: "What inputs does the gas price tool take?"

Claude calls aioum_tools with { "q": "gas" }

You see: every live tool whose service, category, tool name or description matches, as the agent runner sees it: serviceId, service, category, tool, description, priceUsdc, live, and args, the names of the inputs it takes. Agents are built from this list, so the serviceId and tool pairs are exactly what aioum_agent_create takes in Build agents by conversation. Pass { "refresh": true } to make the runner re-read the marketplace first.

Call a paid tool

Every live service tool is also its own MCP tool, named aioum_<serviceId>__<tool>, with the price and the rating in its description. Claude picks one the way it picks any tool.

You: "What is the price of bitcoin right now? Pay for it if you have to."

Claude calls aioum_3__price with { "ids": "bitcoin", "vs": "usd" }

You see: the service's answer, then one line:

— paid 0.0010 USDC (session #12); 9.9990 USDC budget left

The amount is what this call cost, the session is the on-chain escrow it ran in, and the budget left is what the session key can still spend. The first paid call in a server's life runs the one-time setup (deploy the smart account, fund it with AIOUM_BUDGET, authorize the session key), which takes a few seconds; every call after that is a signed receipt and a settlement. A call that would exceed the budget fails with budget exceeded as a tool error, and Claude tells you so instead of spending. A server with a chain config but no OWNER_KEY (or session key) still lists the paid tools; calling one answers that OWNER_KEY is needed. Without any chain config the paid tools are not listed, and the management tools run alone.

Paid tools take the arguments the underlying tool expects; Claude reads them from aioum_tools or from the tool's description. The session-key rules (AIOUM_EXPIRES, AIOUM_AUTO_RENEW) decide what happens when the key lapses mid-conversation.

Refresh the index

The indexer re-scans the chain on a timer. When a listing you just created, or one an operator just brought back, is not in a search yet, ask for a refresh.

You: "I just listed something. Refresh the marketplace index."

Claude calls aioum_refresh_index with {}

You see: Index refreshed., with ok, how many services the index now holds and when it was refreshedAt. Search again and the listing is there. aioum_tools with refresh does the same for the runner's view.

Next: Build agents by conversation — a starter or a spec, one run with its receipts, a schedule, a listing, and a second agent that hires the first.