Agent API
The platform API surface built for AI agents and automated callers, including machine identities and dry-run simulation.
The Agent API is the same REST API described in REST API, viewed from the perspective of an automated caller — an AI agent, a bot, a backend service — rather than a human using the dashboard. There is no separate, less-secure "agent mode": agents authenticate as machine identities, are bound to the same tenancy rules as the human wallet that created them, and go through the exact same deterministic pipeline as any other caller.
The authority model, concretely
AI MAY REQUEST. POLICYVAULT DETERMINISTICALLY DECIDES. THE COVENANT ENFORCES. SIGNERS RETAIN CUSTODY.
An AI agent calling this API can build requests, simulate them, and (if it holds a signer of its own) sign and submit them — but it can never expand its own authority, never bypass a policy check, and never make a decision PolicyVault's deterministic core disagrees with. Every consequential decision — is this spend within policy, does it need approvals, what does it actually do — is a server round trip into the same pipeline every client uses; nothing about calling the API from code changes what the covenant will accept.
Dry-run first, always
Before building anything real, call simulate. It runs the identical pipeline a real call would — policy checks, fee computation, successor derivation — while persisting nothing and consuming no approval or governance gate. A well-formed simulate request always answers with an explicit verdict (ok: true or ok: false with a structured refusal reason) — this is the recommended way for an agent to check "would this work?" before committing to a real request. See the JavaScript SDK's client.simulate() in JavaScript SDK, or the equivalent simulate() method in Python SDK.
Idempotency
Every mutating call should carry an idempotency key. This makes an agent's retries safe: a genuine retry with the same key and body replays the original result rather than double-spending; a different body under the same key is refused outright rather than silently reinterpreted. This matters especially for autonomous agents that may retry after a timeout without a human present to notice a duplicate action.
Where to go next
- Machine identities and capabilities — how an agent authenticates and what scopes narrow its access to.
- REST API — the underlying HTTP surface.
- MCP server — a Model Context Protocol adapter over this same API, for MCP-speaking agent runtimes.
- JavaScript SDK / Python SDK — typed clients over this API.
- x402 / AP2 — payment-protocol adapters for agent-initiated commerce, built on top of this same pipeline.