# Pay for an API call

Some APIs charge for each call. When an agent calls one, the API answers with
HTTP 402 (Payment Required), the agent pays in USDC from a wallet account, and
the agent then gets the response. We support both x402 and MPP (Machine Payments
Protocol) endpoints, and this recipe uses x402. The agent will pay no more than
the ceiling you set with `--max-amount`.

## Example use case

Wren's Weather sells forecasts from a paid endpoint that answers HTTP 402.
Cora's Coffee wants its agent to fetch a forecast, but does not want to spend
more than $0.25 on the call. The agent calls the endpoint with
`--max-amount 0.25`. The first time, Wren's Weather is not a saved counterparty
yet, so the agent shows you the seller's name and address and adds it before
paying.

The steps below follow that agent from start to finish:

```text
Call the endpoint → Add the seller → Approve the payment → Read the response
```

## Requirements

Before you start, you'll need:

- **A linked agent:** The agent must use the CLI.
- **A wallet account on the API's network:** The agent pays from this account.
- **A [policy](https://docs.catena.com/policies.md) that allows the send:** The agent's policy must allow
  sends from that account.

In addition, each seller's address must be saved as a
[counterparty](https://docs.catena.com/counterparties.md) before the agent can pay it. We recommend that
the policy also let the agent request new counterparties.

## Prompt

You can hand the task to your agent with a prompt like this one:

```prompt
Fetch https://api.example.com/forecast with Catena x402 from our wallet account. Do not pay more than $0.25. If the seller is not a saved counterparty, show me its name and address before you add it.
```

## Steps

### 1. Call the endpoint

First, the agent calls the endpoint with the account to pay from and the most
it's allowed to pay:

```sh
catena x402 --url https://api.example.com/forecast \
  --account acct_... --max-amount 0.25
```

### 2. Add the seller

On the first call, the seller usually is not a counterparty yet. In that case,
the command will charge nothing, exit non-zero, and return
`.counterpartyNotFound` with a `.createCommand` to run. What the agent does next
depends on the seller's name. If `.nameIsPlaceholder` is `false`, the name is
what the seller calls itself (no one has verified it), so the agent shows it to
you before it creates the counterparty. If `.nameIsPlaceholder` is `true`, the
agent replaces the placeholder with a name you choose.

The agent then runs the create command, which may need approval of its own. Once
the counterparty exists, the agent runs the same `catena x402` command again.

### 3. Approve the payment

If the price is at or above your approval threshold, the result will include
`.approvalPending` with the intent ID. You can approve it in the console, and
the agent will then run the same command again. That run uses the approval and
pays once.

### 4. Read the response

On success, `.paid` is true, `.payment` holds the intent ID and amount, and
`.body` holds the response. If `.bodyTruncated` is true, the full body is in the
file at `.bodyPath`.

> [!WARNING] **Each run can pay again**
>
> The agent must not run the command again to see more of the response. Each run
> can pay again, so the agent should read `.bodyPath` instead.

## Variations

You can adapt this recipe in a few ways:

| Variation     | Change                                                |
| ------------- | ----------------------------------------------------- |
| POST a body   | Add `--data '{"q":"..."}'` or `--data @request.json`. |
| MPP endpoints | Use `catena mpp` with the same options.               |
| Sandbox       | Use a wallet account on Base Sepolia.                 |

[Use x402 and MPP](https://docs.catena.com/x402-and-mpp.md) lists every field.

## Related

- [Use x402 and MPP](https://docs.catena.com/x402-and-mpp.md): Let your agent pay HTTP 402 endpoints in USDC with x402 or the Machine Payments Protocol, under the same policy as any other payment.
- [Manage counterparties and vendors](https://docs.catena.com/counterparties.md): Add the people and businesses you pay, request their payment details, and find the rail ID your agent sends to.
- [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.