/simulate

Validate a write request — shape plus, where applicable, owner permissions and spend caps — without broadcasting

Requires API-key authentication (agentAuth, agentId).

Purpose: validate a target write request and body shape without broadcasting.

Auth and scope: header-key auth or OAuth agent:simulate.

Idempotency: not required.

Request:

{
  "method": "POST",
  "path": "/v1/agent/conversions/quote",
  "body": {
    "from_asset": "USDC",
    "to_asset": "ETH",
    "amount": "1",
    "slippage_percent": 1
  }
}

method may be POST, PATCH, or DELETE. path must start with /v1/agent/.

The simulate wrapper accepts body as an object and then validates it against the target route. An optional top-level depth field ("static" | "policy" | "onchain", default "policy") selects how far to simulate. At the default "policy" depth it validates request shape and, where applicable, evaluates the owner-configured permissions and USD spend-cap headroom off-chain — returning permission_not_granted or limit_exceeded. The static stages include validate_route, validate_request_body, and route-specific validate_static_contract checks when applicable. The policy stages are conditional: evaluate_policy_permission runs only for a target route with an operation type, and evaluate_policy_limits runs only when the request's USD spend is deterministic (it covers USD spend headroom only). A stage only appears in execution_path when it actually ran, so an absent stage means that layer was not evaluated — not that it passed. amount_usd is deterministic; a native USDC amount is treated as its USD value and cap-checked, while a non-USDC native amount is not price-converted. If policy-layer reads fail transiently, simulation returns would_succeed: true with policy_read_failed in execution_path; retry rather than treating that as a policy pass. "static" is shape-only; "onchain" runs the policy layers and appends simulate_onchain_not_run to execution_path (the on-chain dry-run is not implemented yet). Simulation still does not check actual balances, max transaction count, cooldowns, recipient or asset allowlists, LTV, recipient resolution, quote freshness, fees, or broadcast viability.

Response:

{
  "ok": true,
  "would_succeed": true,
  "execution_path": ["validation"],
  "blocks": []
}

Common errors: validation_failed, insufficient_scope.

Related recipe: Quickstart.