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.
NoteImage-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:
catena policy showWhen the policy requires evidence, the output has evidenceRequirements, with
the following two parts:
{
"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:
catena send --rail cpr_... --amount 125.00 --method ach \
--evidence invoice_number=4471 \
--evidence-file invoice_photo=./invoice-4471.jpg \
--idempotency-key 7c4f2a8e-invoice-4471With 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:
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.