---
title: "Evaluate EVM Transaction"
method: POST
path: "/v0/platform/cosigners/{id}/evm/evaluate"
tags: ["cosigner"]
---

# Evaluate EVM Transaction

`POST /v0/platform/cosigners/{id}/evm/evaluate`

Run policy evaluation against an EVM transaction for the given cosigner. Returns the policy decision and per-policy trace.

## Path parameters

- `id` string, required — Cosigner ID

## Request body

- union — Request body for evaluating an EVM transaction against cosigner policies.
  - object — Simulate mode: evaluate a hypothetical EVM transaction against cosigner policies.
    - `account_address` string, required — Address of the account initiating the transaction.
    - `chain` 'arbitrum' | 'base' | 'bsc' | 'gnosis' | 'ethereum' | 'optimism' | 'polygon' | 'sepolia' | 'monad' | 'katana', required — Chain name, e.g. "ethereum", "polygon".
    - `data` union, required — EVM transaction payload.
      - object — Standard EVM transaction payload.
        - `data` string, required — Calldata as a hex string, for example "0xa22cb465...".
        - `from` string, required — Sender address.
        - `to` string, required — Recipient or contract address.
        - `type` 'transaction' — Transaction type discriminator. Defaults to "transaction".
        - `value` string, required — Wei value as a hex string, for example "0x0".
      - object — EIP-712 typed-data signing payload.
        - `eip712_executor` string, nullable — Executor contract address, for example a Safe executor.
        - `type` 'eip712', required — Must be "eip712".
        - `typed_data` string, required — EIP-712 typed-data structure as a JSON string.
    - `evaluation_type` 'simulate', required — Evaluation mode. Use "simulate" for dry-run evaluation of calldata.
    - `inline_policies` object[], nullable — Optional list of inline policy definitions to evaluate against instead of persisted policies. When provided, the cosigner's stored policies are ignored and these are used instead. Priority is derived from list order (index 0 = highest).
      - `action` string, required — Policy action: "approve", "reject", or "pending".
      - `name` string, required — Policy name.
      - `policy` object, required — Policy definition with policy_type_id, conditions, targets, etc.
    - `metadata` object — Additional context. Accepts a "domain" key for the dapp origin domain.
    - `options` string[] — Evaluation options to apply. Defaults to ["validation"].
  - object
    - `chain` 'arbitrum' | 'base' | 'bsc' | 'gnosis' | 'ethereum' | 'optimism' | 'polygon' | 'sepolia' | 'monad' | 'katana', required — Chain identifier.
    - `evaluation_type` 'tx_hash', required — Evaluation mode.
    - `inline_policies` object[], nullable — Optional list of inline policy definitions to evaluate against instead of persisted policies. When provided, the cosigner's stored policies are ignored and these are used instead. Priority is derived from list order (index 0 = highest).
      - `action` string, required — Policy action: "approve", "reject", or "pending".
      - `name` string, required — Policy name.
      - `policy` object, required — Policy definition with policy_type_id, conditions, targets, etc.
    - `show_transaction_detail_for` string[], nullable — Transaction hash lists for asked verdicts.
    - `tx_hash` string, required — Transaction hash to evaluate.
  - object
    - `chain` 'arbitrum' | 'base' | 'bsc' | 'gnosis' | 'ethereum' | 'optimism' | 'polygon' | 'sepolia' | 'monad' | 'katana', required — Chain identifier.
    - `evaluation_type` 'time_period', required — Evaluation mode.
    - `show_transaction_detail_for` string[], nullable — Transaction hash lists for asked verdicts.
    - `time_period` object, required — Time window for query.
      - `from` string, date-time, required — Start of window (inclusive, ISO 8601).
      - `to` string, date-time, required — End of window (inclusive, ISO 8601).

## Response `200`

Successful Response

- union
  - EvaluateTransactionResponse — Response containing the policy evaluation result for the submitted EVM transaction.
    - `policies` PoliciesExternal, required
      - `decision` 'approve' | 'reject' | 'error' | 'pending', required — Policy decision outcome: "approve", "reject", "error", or "pending".
      - `reason` string, nullable — Human-readable reason for the decision. Present when a policy matched.
      - `matched_policy` MatchedPolicyInfoExternal
        - `name` string, required — Policy name.
        - `action` string, required — Action defined by the policy.
        - `type` string, required — Policy type.
      - `trace` PolicyTraceEntryExternal[], required — Per-policy evaluation log.
        - `name` string, required — Policy name.
        - `action` string, required — Action defined by the policy.
        - `type` string, required — Policy type.
        - `result` 'matched' | 'not_matched' | 'skipped', required — Evaluation result for this policy entry: "matched", "not_matched", or "skipped".
      - `should_handle_pending_tx` boolean, nullable — True when this dry-run pending result means a real scan would create a manual pending transaction.
    - `scan_id` string, nullable
  - EvaluateHistoricalDataResponse — Response containing the policy evaluation result for historical data.
    - `cosigner_id` string, required — The cosigner that was evaluated.
    - `chain` string, required — Chain used for evaluation.
    - `summary` EvaluationSummary, required — Aggregated counts across all transactions. Note: ``rejected`` includes transactions blocked before policy evaluation (non-benign scans). Per-policy counts only reflect transactions that reached policy evaluation, so ``sum(p.rejected for p in policies)`` may be less than ``summary.rejected``.
      - `total_transactions` integer, required — Total number of transactions scanned for this evaluation.
      - `approved` integer, required — Transactions approved by all policies under this mode.
      - `rejected` integer, required — Transactions rejected by at least one policy or blocked before policy evaluation (non-benign scans). Per-policy counts only reflect transactions that reached policy evaluation, so the sum of per-policy rejected counts may be less than this value.
      - `manual_approved` integer, required — Transactions that required manual approval (pending decision).
    - `policies` PolicyEvaluationSummary[], required — Per-policy aggregates and optional transaction hash lists.
      - `policy_id` string, required — Policy identifier.
      - `policy_name` string, required — Human-readable policy name.
      - `total_evaluated` integer, required — Transactions evaluated against this policy (excludes non-benign scans where policy eval was skipped).
      - `approved` integer, required — Count approved for this policy.
      - `rejected` integer, required — Count rejected for this policy.
      - `manual_approved` integer, required — Count manually approved for this policy.
      - `approved_transactions` string[], nullable — Tx hashes when "approved" was requested in show_transaction_detail_for.
      - `rejected_transactions` string[], nullable — Tx hashes when "rejected" was requested in show_transaction_detail_for.
      - `manual_approved_transactions` string[], nullable — Tx hashes when "manual_approved" was requested in show_transaction_detail_for.
      - `policy_type` string, nullable — Policy type identifier.
    - `scan` object, nullable — Full scan payload of the first scanned transaction. Used for publishing to platform-api.
    - `scan_id` string, nullable — Scan ID of the first scanned transaction. Present for single-tx evaluations.
    - `scan_result` string, nullable — Result type of the first scanned transaction. Present for single-tx evaluations.
    - `scan_timestamp` string, nullable — ISO timestamp of the first scanned transaction. Present for single-tx evaluations.
    - `transaction_timestamp` string, nullable — ISO timestamp for the on-chain transaction when available from the scan (for example block or transaction time). Distinct from scan_timestamp when both are present.

## Other responses

- `404` — Cosigner not found
- `422` — Validation Error

---

[API](https://skmtc.net/blockaid-official/apis/blockaid-api.md) · [All operations](https://skmtc.net/blockaid-official/apis/blockaid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/blockaid-official/blockaid-api/versions/17c41f337b2e/schema)