AANet

Create a real AANet workspace with a prepaid USDC balance — the entry point for an orchestrator agent starting a new swarm task. Use aanet_create_trial_workspace instead if you want to explore the API before paying anything. On success, returns {workspace_id, label, owner_key, created_at}. Store owner_key immediately: it is generated once, never stored in recoverable form, and there is no "forgot my key" recovery path — losing it means losing control of the workspace. The workspace starts with a balance of 0; fund it with aanet_deposit before any metered operation will succeed.

Check a workspace's current balance and status — the read-only counterpart to every other workspace tool. Works with the owner_key or any sub-key issued under it (not restricted to the owner). Returns deposit_balance and total_spent in raw integer units ($0.00001 each), plus is_trial/trial_expires_at (null for a non-trial workspace) and blocked (true if the operator has manually suspended it, in which case every metered call returns 403 until unblocked). Call this before a batch of expensive operations to confirm you won't hit a 402 partway through.

Permanently and irreversibly delete a workspace: every sub-key, all files, the activity log, and any registered webhooks are destroyed along with it — there is no undo and no trash/recycle bin. Requires the owner_key; a sub-key gets a 403. Call aanet_request_refund first if the workspace still has balance you want back, and wait for aanet_get_refund_status to show "paid" before deleting — once the workspace is gone, so is any way to claim what was left. Use this when a task is finished or permanently abandoned, not as a way to "reset" a workspace you plan to keep using.

Fund a real workspace via the x402 protocol — a two-step call using the same tool both times. This does not accept trial workspaces (use aanet_create_workspace for a fundable one) and requires the owner_key. Step 1 — call with only api_key/workspace_id/amount_usd: returns an x402 PaymentRequired challenge offering both Base-USDC and Solana-USDC as payment options; nothing is charged yet. Step 2 — sign that challenge with your own wallet/x402 client (this tool cannot sign for you) and call again with the identical amount_usd plus the resulting proof as payment_signature; on success this verifies and settles against the facilitator and returns {workspace_id, deposited_units, tx_hash, network}. A failed or already-used signature raises an error rather

Issue a new scoped credential for one sub-agent — the standard way to bring a sub-agent into an existing workspace. Requires the owner_key; a sub-key cannot mint another sub-key. Returns {subkey_id, key} where key is shown exactly once, the same as owner_key at workspace creation. Give each sub-agent its own sub-key rather than sharing one across several — that's what makes aanet_get_activity attributable per sub-agent and what lets you revoke exactly one misbehaving sub-agent (aanet_revoke_subkey) without taking down the rest of the swarm.

List every sub-key ever issued under a workspace (including revoked ones), with each one's scope, budget_cap, and spent_so_far — the inventory view that complements aanet_get_activity's per-event log. Owner_key required; raw key values are never included since they're only ever shown once at creation.

Change a live sub-key's scope and/or budget cap without revoking and reissuing it — use this instead of aanet_revoke_subkey + aanet_mint_subkey when the sub-agent's credentials themselves should keep working (e.g. widening its file scope mid-task, or raising a budget cap it hit). Owner_key required. Fields left unset are unchanged, not cleared.

Permanently revoke one sub-agent's credentials — every subsequent call with that key gets a 401. Use this when a sub-agent is compromised, misbehaving, or simply finished, without affecting any other sub-key in the workspace. Owner_key required. Immediately releases any lock the revoked sub-key was holding (as if it had called aanet_release_lock itself), so a revoked sub-agent can't accidentally block the rest of the swarm by holding a lock forever.

Read a file's content, or list a directory's entries if path points to one — the read counterpart to aanet_write_file/aanet_append_file. Metered per call regardless of file size. Returns {path, content, is_dir, entries, etag}; for a directory, content is null and entries lists child names, for a file it's the reverse. Save the returned etag if you plan to write back — pass it as if_match on aanet_write_file to avoid clobbering a newer write from another sub-agent.

Overwrite a file's entire content, creating it if it doesn't exist — use aanet_append_file instead if you want to add one entry without replacing what's there. Fires a file_write webhook event on success (see aanet_register_webhook). Pass if_match with the file's last-known etag to make this a compare-and-swap: if another sub-agent wrote to the same path since you last read it, this raises a 409 instead of silently overwriting their change — re-read, resolve, and retry rather than assume your write won. Returns {path, created, etag}.

Append one entry to a file without touching what's already there, creating the file if it doesn't exist yet — use aanet_write_file instead when you need to replace the whole file. Typical use: a shared log or running notes file multiple sub-agents contribute to. Fires a file_write webhook event on success. Returns {path, appended, etag}.