Evaluate a transfer

Before creating a transfer, you can ask the Policy Engine "will this go through?" without creating anything or reserving funds. evaluate returns the same allow / queue / block verdict, along with the reason and the list of matched policies. It's useful for preflight checks in UIs and automation. For the engine itself, see Policy Engine.

How evaluate reaches a verdict (the same calculation as when creating a transfer, but with no side effects):

Prerequisites

• A Vault (vaultId) and the user (userId) on whose behalf the action is checked.
• An access token (see Authentication).
• The parameters of the intended action: asset, amount, toAddress.

Step 1. Send an evaluation request

POST /api/v1/evaluate is a top-level endpoint (not under /vaults/{code}). It doesn't create anything; it only calculates the verdict.

curl -X POST "[BASE_URL]/api/v1/evaluate" \
  -H "Authorization: Bearer $V3_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "transfer",
    "vaultId": "VAULT_ID",
    "userId": "USER_ID",
    "asset": "usdt",
    "amount": "1350.00",
    "toAddress": "TQ2m...p4rX"
  }'

const res = await fetch("[BASE_URL]/api/v1/evaluate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.V3_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    action: "transfer",
    vaultId: "VAULT_ID",
    userId: "USER_ID",
    asset: "usdt",
    amount: "1350.00",
    toAddress: "TQ2m...p4rX",
  }),
});
console.log(await res.json());

res = requests.post(
    "[BASE_URL]/api/v1/evaluate",
    headers={"Authorization": f"Bearer {os.environ['V3_TOKEN']}"},
    json={
        "action": "transfer",
        "vaultId": "VAULT_ID",
        "userId": "USER_ID",
        "asset": "usdt",
        "amount": "1350.00",
        "toAddress": "TQ2m...p4rX",
    },
)
print(res.json())

Step 2. Read the decision

The response contains the verdict and an explanation:

{
  "decision": "block",
  "reason": "AMOUNT_EXCEEDED",
  "policyId": "...",
  "policyCode": "otc-daily-limit",
  "trace": [
    { "policyCode": "otc-daily-limit", "policyName": "OTC daily limit", "effect": "block" }
  ]
}

How to use the verdict:

Step 3. How the engine makes a decision

evaluate follows the deny-overrides principle:

1. All of the user's policies in the Vault are collected (through group memberships).
2. Only enabled policies whose action type matches the requested one are kept.
3. Applicability is checked (a condition tree; an empty tree means "always applies").
4. If at least one policy blocks, the outcome is block.

The same calculation runs when a transfer is created, but there it comes with side effects (a reserve, an approval request). evaluate, on the other hand, is safe to call repeatedly. For details, see Policy Engine.

Common mistakes

You're done when

• POST /api/v1/evaluate returns a decision without creating anything;
• when a limit is expected, you get block with a clear reason;
• trace contains the matched policies;
• a repeated call with the same parameters returns the same verdict (no side effects).

Next steps