> ## Documentation Index
> Fetch the complete documentation index at: https://docs.utter.technology/llms.txt
> Use this file to discover all available pages before exploring further.

# Call endpoint

> The POST /call payment gate every deployed Utter resource exposes, its 402 quote, and its outcomes.

Every deployed resource serves a single paid entry point, `POST /call`, fronted by a trusted sidecar (the gate). An unpaid call returns HTTP 402 with a machine-readable quote; a paid call carries a signed authorization in the `X-PAYMENT` header. This page is the wire reference. The model behind it is [the escrow response gate](/concepts/escrow-response-gate).

## Free paths

These paths are un-gated and matched exactly. Everything else requires payment.

| Path                           | Purpose                                              |
| ------------------------------ | ---------------------------------------------------- |
| `/.well-known/agent-card.json` | The [A2A agent card](/reference/agent-card-schema).  |
| `/health`                      | Liveness.                                            |
| `/healthz`                     | Liveness.                                            |
| `/openapi.json`                | The OpenAPI request/response schema (may be served). |

## POST /call

<ParamField header="content-type" type="string" required>
  Must be `application/json`.
</ParamField>

<ParamField body="body" type="object" required>
  A JSON body matching the resource's OpenAPI request schema.
</ParamField>

<ParamField header="X-PAYMENT" type="string">
  A base64-encoded payment payload. Omit it to receive the 402 quote; include it to pay.
</ParamField>

## Unpaid call: HTTP 402

A `POST /call` with no `X-PAYMENT` header returns HTTP 402 and a quote describing how to pay.

<ResponseExample>
  ```json 402 Payment Required theme={null}
  {
    "x402Version": 2,
    "error": "X-PAYMENT header is required",
    "accepts": [
      {
        "scheme": "utter-escrow",
        "network": "eip155:5042002",
        "maxAmountRequired": "<cap base units>",
        "asset": "<USDC>",
        "escrow": "<PaymentEscrow>",
        "payTo": "<resourceId bytes32>",
        "maxTimeoutSeconds": 30,
        "pricing": {
          "model": "metered",
          "base": "<base units>",
          "perKB": "<base units>",
          "computeMultiplier": 1,
          "maxResponseBytes": 1048576,
          "errorPrice": "<base units>"
        },
        "extra": {
          "eip712": {
            "name": "UtterEscrow",
            "version": "1",
            "chainId": 5042002,
            "verifyingContract": "<escrow>"
          }
        }
      }
    ]
  }
  ```
</ResponseExample>

The `accepts` array may carry a second `exact` entry for the flat EIP-3009 path.

<ResponseField name="x402Version" type="number">
  Always `2`.
</ResponseField>

<ResponseField name="error" type="string">
  Why the call was refused.
</ResponseField>

<ResponseField name="accepts" type="array">
  One entry per acceptable scheme.
</ResponseField>

<ResponseField name="accepts[].scheme" type="string">
  `utter-escrow` for the gated metered path.
</ResponseField>

<ResponseField name="accepts[].network" type="string">
  `eip155:5042002` (Arc Testnet).
</ResponseField>

<ResponseField name="accepts[].maxAmountRequired" type="string">
  The cap, in USDC base units. This is the ceiling the buyer signs, not the price.
</ResponseField>

<ResponseField name="accepts[].asset" type="string">
  The USDC token address.
</ResponseField>

<ResponseField name="accepts[].escrow" type="string">
  The PaymentEscrow contract address.
</ResponseField>

<ResponseField name="accepts[].payTo" type="string">
  The `resourceId` (bytes32) the debit is bound to.
</ResponseField>

<ResponseField name="accepts[].maxTimeoutSeconds" type="number">
  How long the buyer's authorization must stay valid.
</ResponseField>

<ResponseField name="accepts[].pricing" type="object">
  The metered pricing terms: `model`, `base`, `perKB`, `computeMultiplier`, optional `maxResponseBytes`, optional `errorPrice`.
</ResponseField>

<ResponseField name="accepts[].extra.eip712" type="object">
  The EIP-712 domain to sign under: `name` `UtterEscrow`, `version` `1`, `chainId` `5042002`, `verifyingContract` the escrow address.
</ResponseField>

## Paid call

Re-POST the same request with an `X-PAYMENT` header carrying the base64 encoding of this payload:

```json X-PAYMENT payload (before base64) theme={null}
{
  "x402Version": 2,
  "scheme": "utter-escrow",
  "network": "eip155:5042002",
  "authorization": {
    "buyer": "<address>",
    "resourceId": "<bytes32>",
    "maxAmount": "<cap base units>",
    "nonce": "<bytes32>",
    "validBefore": "<unix seconds>"
  },
  "signature": "<0x…>"
}
```

The `authorization` is signed as an [EIP-712 `DebitAuthorization`](/reference/contracts#debitauthorization-type) under the `UtterEscrow` domain.

## Outcomes

| Outcome        | Status     | Charge                        | Strike | Notes                                                               |
| -------------- | ---------- | ----------------------------- | ------ | ------------------------------------------------------------------- |
| Success        | 200        | `min(computed, cap)`          | No     | Handler body returned, plus an `X-PAYMENT-RESPONSE` receipt header. |
| Declared error | error body | Free or a capped `errorPrice` | No     | A valid "your input was bad" response. Reservation released.        |
| Malfunction    | 502        | None                          | Yes    | Not a valid success or declared error, or the handler threw.        |
| Timeout        | 504        | None                          | Yes    | Handler exceeded the signed timeout.                                |
| Settle failure | 502        | None                          | No     | Fail-closed: the reservation is not debited.                        |

On success the `X-PAYMENT-RESPONSE` header carries a base64 receipt:

```json X-PAYMENT-RESPONSE receipt (before base64) theme={null}
{
  "tx": "<0x…>",
  "amount": "<base units>",
  "payer": "<address>",
  "idemKey": "<bytes32>",
  "scheme": "utter-escrow"
}
```

## Size caps

| Limit         | Value | On breach |
| ------------- | ----- | --------- |
| Request body  | 1 MiB | HTTP 413  |
| Response body | 1 MiB | HTTP 502  |

<Note>
  The gate never runs the handler against an unreserved authorization, and it never debits on anything but a validated success. See [the escrow response gate](/concepts/escrow-response-gate) and [metering and classification](/concepts/metering-and-classification).
</Note>