TXRISK

Buyer-safe explainer

What the action authorization response actually means.

This page explains the shipped response fields on POST /v1/action/authorize so a buyer can read one paid decision quickly without a live walkthrough. The contract today is centered on four fields: decision, policy.reasons, operator.step, and billing.

Run the live evaluator Open paid-success proof

Field Map

The four fields buyers actually care about

decision

The top-line policy result for the action being evaluated.

  • allow: the request can proceed to submit.
  • review: a human operator needs to approve the action first.
  • deny: the action should be rewritten before retry.

policy.reasons

A concise explanation of why TXRISK returned that decision.

  • Shows the current counterparty risk band and score.
  • Lists the watch flags that pushed the decision.
  • Safe to surface in buyer-facing proofs and operator tooling.

operator.step

The next action the caller should take after reading the decision.

  • proceed_to_submit for allow.
  • require_operator_review for review.
  • deny_and_rewrite_action for deny.

billing

The payment proof attached to the admitted decision.

  • charged_usdc shows the amount charged for this decision.
  • remaining_balance_usdc shows post-call balance state.
  • settlement_mode stays aligned with the shipped x402 flow.

Decision Reading

How to interpret one paid response

  1. Read decision first to know whether the action passed, needs review, or must stop.
  2. Read policy.reasons next to understand what drove that result.
  3. Use operator.step as the handoff instruction for your caller or operator queue.
  4. Use billing to confirm the response came through the paid TXRISK proof path.

Live Contract Examples

One allow example and one review example

Allow example: low-risk vendor payout

This is the shipped allow path for the built-in vendor payout template. The operator can submit the action immediately because operator.step resolves to proceed_to_submit. 

{
  "mode": "action_authorize",
  "authorizationId": "auth_882c6beff8fd",
  "decision": "allow",
  "action": {
    "version": "bankr-preflight-v1",
    "kind": "transfer",
    "chain": "base",
    "actor": "0x1111111111111111111111111111111111111111",
    "targetAddress": "0x1111111111111111111111111111111111111112",
    "amountUsd": 2800,
    "metadata": {"tokenSymbol": "USDC"}
  },
  "policy": {
    "profile": "operator_guard_v1",
    "decisionSource": "txrisk_action_policy",
    "reasons": [
      "counterparty risk band=low score=7",
      "watch flags: mixer_interaction, velocity_spike"
    ],
    "chargedOnDecision": true
  },
  "operator": {
    "step": "proceed_to_submit"
  },
  "billing": {
    "charged_usdc": "0.0020",
    "remaining_balance_usdc": "0.9980",
    "settlement_mode": "direct_transfer",
    "settlement_reference": null
  }
}

Review example: approval-backed subscription purchase

This is the shipped review path for the built-in subscription purchase template. The policy did not deny the action, but it requires explicit operator approval before submit. 

{
  "mode": "action_authorize",
  "authorizationId": "auth_844e3de6d819",
  "decision": "review",
  "action": {
    "version": "bankr-preflight-v1",
    "kind": "approval",
    "chain": "base",
    "actor": "0x1111111111111111111111111111111111111111",
    "targetAddress": "0x2222222222222222222222222222222222222222",
    "amountUsd": 299,
    "metadata": {
      "tokenAddress": "0x3333333333333333333333333333333333333333",
      "allowanceUsd": 299,
      "approvalScope": "exact"
    }
  },
  "policy": {
    "profile": "operator_guard_v1",
    "decisionSource": "txrisk_action_policy",
    "reasons": [
      "counterparty risk band=medium score=36",
      "watch flags: sanctions_proximity, contract_exploit_cluster"
    ],
    "chargedOnDecision": true
  },
  "operator": {
    "step": "require_operator_review"
  },
  "billing": {
    "charged_usdc": "0.0020",
    "remaining_balance_usdc": "0.9960",
    "settlement_mode": "direct_transfer",
    "settlement_reference": null
  }
}

Proof Path

How to open the same live lane

Browser path

  • Open /playground.html.
  • Select POST /v1/action/authorize.
  • Leave API key blank and run a built-in template.
  • Inspect the final paid response with the same fields explained here.

Raw docs path

  • Open /docs.html for the full x402 request flow.
  • Use the copy/paste curl example for a direct HTTP proof.
  • Keep x-chain aligned to the request body.
  • Expect the final paid response to include the same decision, reasons, operator step, and billing block.