# 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](https://docs.catena.com/intents.md), 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](https://docs.catena.com/x402-and-mpp.md#evidence-from-sellers)).

## Add evidence fields

An admin adds evidence fields to a policy on the
[**Policies**](https://app.catena.com/~/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](https://docs.catena.com/connect/mcp.md) 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:

```sh
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:

```sh
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:

```ts
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](https://docs.catena.com/connect/mcp.md) 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](https://docs.catena.com/connect/cli.md) or the [SDK](https://docs.catena.com/sdk.md).

## 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](https://docs.catena.com/approvals.md) 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](https://docs.catena.com/api/get-intent.md).

## Related

- [Set policies](https://docs.catena.com/policies.md): Decide what each agent can do with its policy, from the accounts it can read and the counterparties it can pay to its spending rules, temporary overrides, and the policies agents propose.
- [Handle approvals](https://docs.catena.com/approvals.md): Learn what goes to the approvals queue, who can approve, when requests expire, and what happens between an approval and a completed payment.
- [Intents and retries](https://docs.catena.com/intents.md): Learn how an intent moves through its statuses and resolutions, which fields explain its result, and how to retry safely with idempotency keys.
- [Link with the MCP](https://docs.catena.com/connect/mcp.md): Apps with custom connectors, such as Claude and ChatGPT, can act as a Catena agent through our remote MCP server.
