Configure

Require evidence

A policy can require an agent to send evidence with an action, such as an invoice number or a photo of the receipt with each payment. Catena will refuse an action whose evidence is missing or in the wrong form before it creates anything, and it keeps the evidence with the intent, so the person who approves the action can see why the agent asked.

For example, Cora's Coffee can require its purchasing agent to send the invoice number and a photo of the invoice with every payment. When the agent pays Pete's Packaging $125.00 by ACH for invoice 4471, it sends 4471 and the photo, and if the payment needs approval, the admin will see both on the review page.

This is separate from the offers and receipts that some x402 sellers sign (see Evidence from sellers).

Add evidence fields

An admin adds evidence fields to a policy on the Policies page. Open the policy, choose Edit, click Add evidence field under Evidence, fill in the field, and choose Save policy. Each field has the following:

  • Label: The name people and agents see, such as "Invoice number", up to 80 characters.
  • Instructions: Optional guidance for the agent, such as "Paste the link to the order page.", up to 500 characters.
  • Accepts: Text, an image, or both. When a field accepts both, either one meets it.

Catena derives the field's key, which agents send the evidence under, from the label (e.g., invoice_number). Renaming a saved field keeps its key, so agents that already send it keep working.

The fields you add in the console apply to payments: sends, and payments to x402 and MPP endpoints. A policy can hold up to 20 fields for payments and 50 fields in all. When a policy also requires evidence with other actions, the Evidence section lists those fields too, but you cannot change them there.

Note

Image-only fields and remote MCP

An agent connected only through the remote MCP can send text but not images, so it cannot take an action that requires a field that accepts only an image. The console warns you when a field accepts only an image. If such an agent needs to meet the field, let it accept text as well.

Find the requirements

Before an action, the agent should read its policy:

Shell
catena policy show

When the policy requires evidence, the output has evidenceRequirements, with the following two parts:

JSON
{
  "evidenceRequirements": {
    "fields": {
      "invoice_number": { "label": "Invoice number", "accepts": ["text"] },
      "invoice_photo": {
        "label": "Invoice photo",
        "instructions": "A photo of the whole invoice.",
        "accepts": ["image"]
      }
    },
    "requiredByCapability": {
      "send": ["invoice_number", "invoice_photo"]
    }
  }
}

fields describes each field by its key, and requiredByCapability lists the keys that each kind of action needs. When evidenceRequirements is absent, or the action's capability is not listed, the agent sends no evidence. Below is the capability of each action:

Capability CLI Remote MCP tool
send catena send, catena x402, and catena mpp send
transfer catena transfer transfer
create_counterparty catena counterparties create create_counterparty
request_counterparty_details catena counterparties request-details request_counterparty_details
policy_override catena policy request-override request_policy_override

In the SDK, getPolicy() returns the same evidenceRequirements.

Send evidence

Sending evidence needs CLI 0.22.0 or later, or SDK 0.14.0 or later. Images with x402 and MPP payments need CLI 0.23.0 or later, or SDK 0.15.0 or later.

With the CLI, the agent passes --evidence key=value for each text field and --evidence-file key=path for each image:

Shell
catena send --rail cpr_... --amount 125.00 --method ach \
  --evidence invoice_number=4471 \
  --evidence-file invoice_photo=./invoice-4471.jpg \
  --idempotency-key 7c4f2a8e-invoice-4471

With the SDK, submitIntent takes evidence beside the action. A text field takes a string, and an image takes its bytes, media type, and an optional file name to show the people who review it:

TypeScript
const intent = await client.submitIntent({
  action: {
    type: "send",
    counterpartyRailId: "cpr_...",
    amount: "125.00",
    method: "ach",
  },
  evidence: {
    invoice_number: "4471",
    invoice_photo: {
      bytes,
      contentType: "image/jpeg",
      filename: "invoice.jpg",
    },
  },
  idempotencyKey,
})

The agent should send only the fields that the action's capability lists. A text value can be up to 4,096 characters.

Images

An image must be a still PNG, JPEG, or WebP file. Below are the limits that apply to images:

  • File size: Up to 15 MiB for one image, and 50 MiB for all the images on one intent.
  • Dimensions: Up to 16,384 pixels on each side, and 50 megapixels in all.

The CLI and SDK upload each image before they submit the action, and Catena scans it for malware and checks its format and size. The action is submitted only once every image has passed. The CLI gives a command's images 45 seconds in all, and the SDK waits up to two minutes (its evidenceWait option). If an image is rejected or still being checked when that time runs out, nothing is submitted, and the error names the field. When you send images with send, transfer, counterparties, or policy request-override, pass --idempotency-key, so that you can run the command again with the same key to keep waiting. Replace a rejected image before you run it again. x402 and MPP payments retry differently, as described below.

Images go to Catena's storage host, not to api.catena.com. If your network allows only some hosts, allow bank-intent-evidence-landing-prod.s3.us-east-1.amazonaws.com for uploads, and bank-intent-evidence-prod.s3.us-east-1.amazonaws.com if your agent downloads evidence with the SDK. A blocked host fails within about 10 seconds, and the error names the host to allow.

x402 and MPP

catena x402 and catena mpp take the same --evidence and --evidence-file options, and the SDK's payment helpers take evidence when you set them up. Each payment is first tried without evidence, and the CLI or SDK sends the evidence, uploading any images, only when Catena asks for it. A payment that resumes an earlier approval needs no evidence, since the approval already has it. To retry after an image error, make the same payment again, and it will reuse the images it already uploaded.

Remote MCP

The remote MCP tools listed above take an evidence argument with text values only. A connector cannot send an image, so an action that requires an image-only field will fail as described below. For those actions, use the CLI or the SDK.

When evidence does not meet the policy

When the evidence is missing or in the wrong form, Catena will refuse the action with evidence_requirements_not_met (HTTP 422) and create nothing. The CLI exits 1, and the SDK throws EvidenceRequirementsNotMetError. The error lists every problem in details.issues, each with the field and one of the following reasons:

reason Meaning
missing The policy requires the field, and the agent did not send it.
unexpected The agent sent a field that the action does not need.
wrong_representation The agent sent the field in a form it does not accept (e.g., text for an image-only field). accepts lists the forms it does.
attachment_unavailable The image cannot be used: it expired, was rejected, failed its checks, or another intent already used it. Upload it again.

Since nothing was created, the agent can fix the evidence and send the request again with the same idempotency key.

Review evidence

When an action needs approval, its review page in the console shows the evidence under Evidence provided, in the order the policy lists the fields. Text is shown as sent, and an image has a thumbnail and a View full image link. See Handle approvals for the rest of the review.

When you approve, Catena checks the evidence again against the agent's current policy. If the policy's requirements changed while the request waited and the evidence no longer meets them, the review page says so, and approving will block the request instead of starting it. The agent must then send a new request with the evidence the policy now asks for.

The intent keeps its evidence after it is decided. catena intents get and catena intents list, and the SDK's getIntent() and listIntents(), show the text values under evidence and each image under evidenceFiles, with its media type, size, SHA-256 digest, and file name if it was given one. Listing images needs CLI 0.27.1 or later, or SDK 0.20.0 or later. The SDK's downloadIntentEvidence(intentId, field) downloads an image. Read from the API or the remote MCP, evidence holds both the text values and each image's details; see Get an intent.

Updated November 20, 2026 View as Markdown