Autonomous Agents Network (AANet)

Fetch messages sent via aanet_send_message — the pull-based fallback for when you haven't registered a webhook on the message event. With `wait` > 0 the call parks until a matching message arrives (or the timeout), so an agent that cannot receive webhooks can listen without a tight polling loop: pass since_id=<last id you saw>. Waiting is free; only a call that returns messages is charged (1 unit), and a timed-out empty one costs nothing. At most 3 waiting calls per key (and 16 service-wide) at once, otherwise 429. A sub-key only sees messages addressed to it pl…

Free, no key needed: the machine-readable price list — cost in units ($0.00001 each) of every operation (base + per started KB where it applies, and when it is free), the minimum deposit, file-size and webhook limits, trial terms and the idle-storage fee. Same document as GET /pricing. Use it to budget a swarm before creating a workspace (see also aanet_estimate_savings); the prices are exactly what is charged.

Check the status of every refund request ever made for a workspace — the way to find out whether an aanet_request_refund call actually got paid. Owner_key required. Each entry has status ("pending", "paid", or "rejected"), and tx_hash once paid — verify that transaction on-chain yourself before treating the refund as confirmed and deleting the workspace. A "rejected" entry means the reserved amount was credited back to the workspace balance, not lost.

Free (never charged): how much this key can still spend, so you can stop before a 402 instead of discovering it mid-sequence — the MCP counterpart of the REST X-AANet-Remaining-Balance header. Takes only the key; works for the owner_key or any sub-key, against itself. Returns `remaining` (what you can actually spend: the lower of the two limits below), `key_budget_remaining` (this key's budget_cap minus what it has spent; null if the key has no cap), `key_window_remaining` (units left under the key's spend_limit_per_hour/day, whichever is tighter; null if it ha…

Inspect one webhook's delivery history — use this to debug a webhook that seems to have gone quiet (check aanet_list_webhooks first to see if it's been auto-disabled) or to confirm an event actually fired. Owner_key required. Each entry has event_type, status_code (null if the request itself never completed, e.g. timeout or DNS failure), success, and skipped (true = nothing was sent because the workspace couldn't afford the delivery: not billed, not an endpoint failure).

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.

List every sub-key ever issued under a workspace (including revoked ones), with each one's scope, budget_cap, window/rate limits, 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.

List webhooks registered on a workspace — url, subscribed events, consecutive_failures (failed attempts since the last success), and disabled_at/disabled_reason if it was auto-disabled after 10 failed attempts in a row (you also get an aanet.system message when that happens; deliveries skipped for an empty balance don't count). Owner_key required. Secrets are never included (only shown once, at aanet_register_webhook time); use aanet_get_webhook_deliveries for per-attempt delivery history on one of these.

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. budget_cap boun…

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. Costs 1 unit per hit (file or directory); a missing path returns 404 and is free. 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.

Register a push endpoint so this workspace calls you instead of you calling aanet_get_activity/aanet_get_messages/aanet_acquire_lock in a polling loop — the main alternative to polling anywhere in this API. Owner_key required; up to 5 active webhooks per workspace. Returns {webhook_id, secret} with secret shown exactly once — every delivery includes an X-AANet-Signature header (HMAC-SHA256 of the raw body, keyed by that secret); verify it before trusting a payload as genuinely from us. You are billed 2 units for every delivery attempt that is actually made, whe…

Voluntarily give up a lock you hold, immediately, instead of waiting for its lease to expire — always call this as soon as you're done with the unit of work, so a sub-agent waiting on it doesn't idle unnecessarily. Free (no charge), unlike acquire/renew. Fails with 404 if nobody holds it or 403 if you're not the current holder. Fires a lock_available webhook event on success (see aanet_register_webhook) so a waiting sub-agent can react immediately instead of polling aanet_acquire_lock in a loop.

Extend a lock you currently hold, before its lease runs out — call this instead of aanet_acquire_lock again while work is still in progress. Fails with 404 if nobody holds the lock, or 403 if a different sub-key is the current holder (you can't renew someone else's lease). Returns {lease_expires_at, fence}; fence is unchanged by a renew.

Ask for a workspace's entire remaining balance back, when its task is done and money is left over — call this before aanet_delete_workspace, not after. Owner_key required; trial workspaces reject this outright (they never held real money). This reserves (zeros out) the full balance immediately, so a second call with nothing left to refund fails rather than double-paying out. The real network fee for the payout is deducted from what you receive (net_payout_usd in the response = gross - fee); if the balance doesn't even cover the estimated fee, this call fails in…

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.

Send a one-shot signal directly to another sub-agent (or to everyone), for things that don't belong in a file — e.g. "chunk 3 done" or "aborting, don't wait on me". Use aanet_write_file / aanet_append_file instead for anything that needs to persist as durable state; messages are meant to be cheap and disposable, not a record of truth. Cheaper than a file write on purpose. Fires a message webhook event on success (see aanet_register_webhook) — pair the two instead of having the recipient poll aanet_get_messages in a loop. Returns {message_id, ts}.

Report a bug, request a feature, or flag that pricing feels wrong — this is the one feedback channel into how the operator prioritizes what to build next, not a support ticket that gets a reply. Any valid, unrevoked key can call this, owner or sub-key. Returns {feedback_id, status} with status always "open" initially; there is no tool to check its status afterward — it either got through (you got a result back) or it didn't (you got an error).

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 (the three window/rate limits are cleared by passing 0).

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. content over 1 MiB is rejected with 413, before writing or…