Reference
Every tool the server offers, and every environment variable it reads. Each tool takes one JSON
object; inputs are name: type, required ones marked. Every tool answers with a summary line,
then a json block when the result is structured; a failure is one readable line marked as an
error. Tools that sign send a transaction from AIOUM_PRIVATE_KEY and return the hash; tools
that spend pay from the session key capped by AIOUM_BUDGET, from an agent's own budget, or from
the private node's wallet. Amounts are decimal strings ("12000" ZAI, "0.05" USDC) unless a
type says number.
Tools
| Tool | What it does | Inputs | Signs or spends |
|---|---|---|---|
aioum_<serviceId>__<tool> | Calls one live marketplace service tool, paying per call | the tool's own arguments | spends from the session key |
aioum_status | Probes every part of the stack and reports the available AI planners | – | no |
aioum_activity | The runner's totals and the latest runs | limit: integer (default 20) | no |
aioum_wallet | Balances of the runner's wallet and, with a key, yours | – | no |
aioum_services | Searches the marketplace index | q: string, category: string, liveOnly: boolean, limit: integer | no |
aioum_service | One listing in full | serviceId: string (required) | no |
aioum_operator | One operator: stake, reputation, listings | address: string (required) | no |
aioum_tools | The callable tools with their argument names and prices | q: string, refresh: boolean | no |
aioum_refresh_index | Makes the index re-read the chain and re-probe every node now | – | no |
aioum_planners | Who can plan an assistant: the planner listings on the marketplace, and whether the runner has a key or a local model of its own | – | no |
aioum_starters | The ready-made agents and pipelines (agent networks with a project), each with what it still needs | kind: string (agent, pipeline, all) | no |
aioum_skills | Searches the skills an agent can load: the open-source index (repo, commit, licence) and skills listed on nodes (per use or one-time) | q: string, category: string (crypto, media, writing, research, code, data, social, ai, ops, other), tag: string, limit: integer (default 50) | no |
aioum_pipeline_create | Creates a pipeline: its agents in hiring order, the hired ones published, its project on the lead, with the budgets you set; refused with the missing parts named (a GPU among them) | id: string (required), budgetUsdc: number (required, the project's cap), agentBudgetsUsdc: object (required, a cap per agent key), input: string, start: boolean (default false) | no (starting spends) |
aioum_super | Prompt first: builds a Super Agent from a prompt and the budget you are willing to spend (fully loose, pay in any token, the best live planner, the highest model tier live, said back with why) with a project whose stages that planner proposes, and starts it | prompt: string (required), budgetUsdc: number (required), planner: string (marketplace:<serviceId>, anthropic, openai), start: boolean (default true) | no (spends from the budget) |
aioum_agents | Lists agents | owner: string (default AIOUM_OWNER) | no |
aioum_agent_get | One agent in full | id: string (required) | no |
aioum_agent_create | Creates an agent from a spec, or from a starter with the spec's fields on top | spec: object (name, description, instructions, mode, planner, plannerService, tools, access, deny, skills, skillsAccess, data: {memory, files}, dataAccess, steps, outputTemplate, budget, schedule, payAcross), starter: string; one of spec.name or starter is required | no |
aioum_agent_update | Replaces the fields sent | id: string (required), spec: object (required) | no |
aioum_agent_delete | Deletes an agent that is not published | id: string (required) | no |
aioum_agent_run | Starts a run and waits for it, up to the timeout | id: string (required), input: string, timeoutSeconds: integer (default 300) | the agent spends from its own budget |
aioum_agent_schedule | Sets, changes or disables the schedule | id: string (required), enabled: boolean (required), everyMinutes: integer, input: string | scheduled runs spend from the agent's budget |
aioum_agent_publish | Lists the agent as a service | id: string (required), priceUsdc: number (required), stakeZai: number | no; the runner stakes ZAI and registers the listing with its own wallet |
aioum_agent_unpublish | Delists it | id: string (required) | no |
aioum_runs | Lists runs, newest first | agentId: string, limit: integer (default 30) | no |
aioum_run_get | One run: steps, paid calls, receipts, output | runId: string (required) | no |
aioum_run_stop | Stops a run in progress | runId: string (required) | no |
aioum_run_watch | Watches a run over its event stream until it ends: every step with its doing line, service, cost and media, then the spend per service | runId: string (required), timeoutSeconds: integer (default 300), from: integer | no |
aioum_spend | Spend per service: one run, or an agent or a project over a period, with a per-day line | one of runId, agentId, projectId: string; period: "24h" (default), "7d" or "all" | no |
aioum_project_list | Your projects, or one agent's | owner: string, agentId: string | no |
aioum_project_get | One project in full: its brief, every stage with its status, run, spend, output and links | id: string (required) | no |
aioum_project_create | Creates a project as a draft: one brief, one budget, stages (each {title?, instruction, after?}, after the positions of the stages it waits for; absent, every stage before it) or "auto" for the agent's planner to propose them with their after (a planner listing is paid one turn, a run of kind plan on the agent) | agentId: string (required), brief: string (required), stages: object[], string[] or "auto" (required), title: string, budgetUsdc: number | no |
aioum_project_start | Runs the stages not done yet, each as soon as the stages it waits for are done and the ready ones at the same time, and waits | id: string (required), wait: boolean (default true), timeoutSeconds: integer (default 600) | the project spends from its budget |
aioum_project_pause | Lets the running stages finish, then stops before the next | id: string (required) | no |
aioum_project_resume | Continues from the first stage not done; a failed stage runs again | id: string (required), wait: boolean, timeoutSeconds: integer | spends from the project's budget |
aioum_project_stages | Replaces the stages still to run and/or the budget; done stages stay | id: string (required), stages: string[], budgetUsdc: number | no |
aioum_project_delete | Deletes a project; a running stage is stopped, its runs stay | id: string (required) | no |
aioum_sell_templates | The template gallery | q: string | no |
aioum_sell_config | Assembles a services.json from templates | names: string[] (required) | no |
aioum_sell_preview | Runs one tool of a spec once, without listing | spec: object (required), tool: string (required), args: object, env: object | no |
aioum_sell_add | Lists a service on the catalogue node | spec: object or template: string (one required); price: string, pricingMax: string (let the price follow demand up to this), stake: string, env: object | no; the node stakes and registers with its own wallet |
aioum_sell_skill | Puts a folder with SKILL.md on the node and lists it, per use or one-time | mode: "per-use" or "one-time" (required), price: string (required), one of dir: string (a folder here, uploaded), files: object[], nodeDir: string (a folder on the node); name, description, category, key, stake: string | no; the node stakes and registers with its own wallet |
aioum_sell_list | What the node sells | – | no |
aioum_sell_remove | Delists one service | key: string (required) | no |
aioum_sell_verify_domain | The DNS TXT record or /.well-known/aioum.json to add for the node's operator, and what each check finds now | domain: string (required) | no |
aioum_stake_operators | Operators with their stake, liveness and listings | – | no |
aioum_stake_positions | Your delegations and claimable rewards | – | no |
aioum_stake_delegate | Approves and delegates ZAI to an operator | operator: string (required), amountZai: string (required) | signs |
aioum_stake_claim | Claims your USDC rewards from an operator | operator: string (required) | signs |
aioum_stake_unstake | Starts unbonding | operator: string (required), amountZai: string (required) | signs |
aioum_stake_withdraw | Withdraws after the unbonding period | operator: string (required) | signs |
aioum_stake_request | Asks the network's staking node to review a listing and back it so it goes live; follows the states to the end and returns the final one with the reasons | serviceId: string (required), wait: boolean (default true), timeoutSeconds: integer (default 600) | no; the staking node's pool delegates |
aioum_stake_requests | Backing requests on the staking node, newest first, with their state, reasons and stake | operator: string, serviceId: string, state: string (requested, reviewing, approved, rejected, backing, live, failed, withdrawn), limit: integer (default 100) | no |
aioum_jury_status | The jury's rules and your seat | – | no |
aioum_jury_join | Approves and stakes on the arbitrator | amountZai: string (required) | signs |
aioum_jury_cases | Disputes, newest first, with your state on each | limit: integer (default 50) | no |
aioum_jury_commit | Seals a vote; saves the salt to ~/.aioum/jury-salts.json | disputeId: integer (required), nodeAtFault: boolean (required) | signs |
aioum_jury_reveal | Reveals the vote sealed on this machine | disputeId: integer (required) | signs |
aioum_jury_finalize | Closes a case after the reveal period | disputeId: integer (required) | signs |
aioum_jury_escalate | Settles a case that reached no quorum | disputeId: integer (required), nodeAtFault: boolean (required) | signs |
aioum_jury_reward | Claims your reward for a case | disputeId: integer (required) | signs |
aioum_jury_leave | Starts unstaking from the jury | amountZai: string (required) | signs |
aioum_jury_withdraw | Withdraws once unlocked | – | signs |
aioum_node_status | The private node's health and connections | – | no |
aioum_node_connect | Connects a provider; OAuth ones return a link to open | provider: string (required), apiKey: string, baseUrl: string, header: string, prefix: string | no |
aioum_node_disconnect | Removes a connection and its stored credentials | provider: string (required) | no |
aioum_node_tools | The node's tools with their arguments | – | no |
aioum_node_call | Calls one of them, free | tool: string (required), args: object | no |
aioum_node_memory_add | Stores a memory item | text: string (required), kind: string, tags: string (comma-separated) | no |
aioum_node_memory_list | Lists memory | – | no |
aioum_node_memory_delete | Forgets one item | id: string (required) | no |
aioum_node_memory_forget_all | Wipes memory | – | no |
aioum_node_schedules | Lists scheduled jobs and their runs | – | no |
aioum_node_schedule_create | Creates a job | job: object (required): name (required), steps (required), intervalSeconds, budgetUsd | the node spends from its own wallet when the job runs |
aioum_node_schedule_run | Runs a job now and waits | id: string (required) | the node spends up to the job's budget |
aioum_node_schedule_toggle | Pauses or resumes a job | id: string (required) | no |
aioum_node_schedule_delete | Deletes a job | id: string (required) | no |
aioum_node_backup_export | Writes an encrypted backup to a file on the server's machine | path: string (required), passphrase: string (required, 12 characters at least) | no |
aioum_node_backup_restore | Restores a backup file | path: string (required), passphrase: string (required) | no |
aioum_deposit_address | The deposit address for an AI wallet, deployed or not, with the chain, the fee and the service's mode (route, or direct with the sentence to send USDC to the address) | wallet: string | no |
aioum_deposit_chains | The chains a deposit can route from; 501 with one sentence on a direct network, as for tokens and quote | – | no |
aioum_deposit_tokens | The assets on one of those chains | chain: integer (required), q: string, limit: integer | no |
aioum_deposit_quote | A route from an asset on a chain to USDC here: what arrives, the fee, the credit | chain: integer (required), token: string (required; an address, "native", or a symbol), amount: string (required, in units), wallet: string, fromAddress: string | no |
aioum_deposit_send | Quote, then send from your wallet on the source chain and record the deposit | same as the quote | signs and spends |
aioum_deposit_list | Every deposit of a wallet, with its status | wallet: string | no |
aioum_deposit_status | One deposit, status refreshed | id: string (required) | no |
aioum_deposit_sweep | Forward the USDC that has arrived at the deposit address to the wallet now, less the fee; the path that works on every network | wallet: string | no (the service signs the sweep) |
aioum_deposit_card_partners | Pay by card: the on-ramp partners with keys, how each reports delivery, its fee, and whether this network can take a card payment | none | no |
aioum_deposit_card | Pay by card: a partner's link that delivers USDC to the deposit address, tracked as a deposit | partner: string, wallet: string | no |
The CLI's aioum jury salts export and import, and aioum config, have no MCP counterpart.
Environment variables
| Variable | Default | What it does |
|---|---|---|
AIOUM_DEPLOYMENTS, DEPLOYMENTS | – | Path to the network's deployments.json: chain id and contract addresses. Either name works; with neither set, the management tools look for ./deployments.json, ./offchain/deployments.json and ../offchain/deployments.json. Without one there are no chain tools (staking, the jury, balances) and no paid tools, and the rest still works. |
AIOUM_CHAIN_ID, AIOUM_PAYMENT, AIOUM_USDC, AIOUM_ACCOUNT_FACTORY, AIOUM_ENTRYPOINT, AIOUM_PAYMASTER | – | Without a deployments file: the chain and the five addresses the paid tools need. |
AIOUM_RPC_URL | http://127.0.0.1:8545, or rpcUrl from the deployments file | Chain RPC. |
OWNER_KEY | – | Owner wallet for the paid tools: funds and authorizes the session key. |
SESSION_KEY, SMART_ACCOUNT | – | Session mode: a key authorized elsewhere; no owner key in the process; no renewal. |
AIOUM_BUDGET | 10 USDC | Cap on the session key, enforced on-chain. |
AIOUM_EXPIRES | 24h | Session-key lifetime. |
AIOUM_AUTO_RENEW | 1 | Re-authorize a lapsed key automatically; 0 fails paid calls instead. |
AIOUM_RENEW_SKEW_SECONDS | 60 | Renew this many seconds before expiry. |
AIOUM_MINT | – | Local development network: 1 mints mock USDC to the owner. |
NODE_TOKEN | – | Bearer token for a token-gated node the paid tools call. |
AIOUM_PRIVATE_KEY | falls back to OWNER_KEY | Wallet for staking, the jury, your balances and paid calls made by the management tools. |
AIOUM_OWNER | cli | The owner your agents are created under and listed by. |
AIOUM_INDEXER_URL | http://127.0.0.1:8549 | The marketplace index. |
AIOUM_AGENTS_URL | http://127.0.0.1:8770/runner | Your runner: your own inside your private node, or a shared one you signed in to. |
AIOUM_NODE_URL | http://127.0.0.1:8546 | The single demo node; where paid calls default to. |
AIOUM_MULTINODE_URL | http://127.0.0.1:8556 | The catalogue node whose admin API lists and delists. |
AIOUM_NODE_TOKEN | – | Bearer token for that admin API. |
AIOUM_FACILITATOR_URL | http://127.0.0.1:8547 | The facilitator (probed by aioum_status). |
AIOUM_BUNDLER_URL | http://127.0.0.1:8548 | The ERC-4337 bundler. |
AIOUM_PRIVATE_NODE_URL | http://127.0.0.1:8770 | Your private node. |
AIOUM_PRIVATE_NODE_TOKEN | the file $PRIVATE_NODE_DIR/token, default ~/.aioum-private/token | Its bearer token (PRIVATE_NODE_DIR names the node's data directory). |
AIOUM_DEPOSITS_URL | http://127.0.0.1:8551 | The deposit service: deposits from any chain, credited as USDC. |
AIOUM_BACKER_URL | http://127.0.0.1:8552 | The network's staking node (aioum_stake_request, aioum_stake_requests). |
AIOUM_DEBUG | – | 1 logs the resolved configuration, secrets masked, to stderr at start. |
Next: Why receipts beat API keys — the case for the receipt every one of these calls carried.