Example integrations

Representative patterns for wiring an AI agent or service into PolicyVault, using safe/demo values only.

These are illustrative patterns, not copy-paste production code — see JavaScript SDK, Python SDK, and REST API for the real, complete surfaces. All values below are placeholders.

#Pattern 1: an autonomous agent that pays recurring invoices

1. The owner creates a vault and grants the agent's key spending authority with a per-transaction limit around the largest expected invoice, a monthly periodic budget, and a destination allowlist containing only the known vendor addresses.
2. The agent's service holds its own key (never given to PolicyVault) and authenticates to the hosted API with a scoped machine identity — typically read:vaults, read:requests, and request:build (plus request:sign/ request:submit if the service signs autonomously, or narrower if a human approves each signature).
3. Before each payment, the agent calls simulate with the invoice amount and recipient. If simulation.ok is false, the agent logs the refusal reason and does not proceed — it never retries around a policy refusal.
4. If the simulation succeeds, the agent builds the real request, and either signs it with its own key (if it holds one directly) or hands the built request to a human/approval flow.

const { simulation } = await client.simulate({
  vaultId,
  action: "agentSpend",
  params: { payAmountSompi: invoiceAmountSompi, agentPk, recipient: vendorXOnly },
  signerAddress: agentAddress
});
if (!simulation.ok) {
  logRefusal(simulation.refusalReason.code, simulation.refusalReason.message);
} else {
  const built = await client.createRequest({ vaultId, action: "agentSpend", params, signerAddress });
  // ... sign and submit, or hand off for approval, per your deployment
}

#Pattern 2: an AI agent runtime speaking MCP

An MCP-native agent runtime (see MCP) configures the policyvault-mcp server with POLICYVAULT_MCP_SERVER_URL and POLICYVAULT_MCP_TOKEN (a scoped machine credential), then discovers available tools via the standard MCP tools/list call — the tool catalog is derived from the server's own capability document, so it always reflects what this specific deployment actually supports.

#Pattern 3: a human-in-the-loop approval workflow

1. An agent (bot or human) requests a spend above the vault's approval threshold.
2. The request enters a pending-approval state.
3. One or more external approvers — separate people with their own wallets — see the pending request (via the dashboard or their own API polling of read:requests) and sign their approval over the exact frozen transaction.
4. Once enough approvals exist, the request can be submitted.

#What every pattern shares

Every pattern above goes through the identical deterministic core: build, policy-check, and (before any signature) independent verification. No integration pattern — however it's wired up — gains authority beyond what the vault owner explicitly configured on-chain.

See also: Agent API, Give an AI agent spending authority.