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:

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

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:

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.

Important

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:

Use x402 and MPP lists every field.