pay-via-agent-wallet

What this skill does

## Overview

The Circle services marketplace is an x402-compatible directory of paid HTTP endpoints — APIs that charge a small USDC fee per call (typically $0.001–$5). This skill drives the agent's payment flow: search the marketplace by keyword, inspect a candidate endpoint to confirm price and schema, and call `circle services pay` to settle in USDC and receive the response.

For an overview of the Circle CLI's **full** capability set, see the `use-circle-cli` master skill. This skill is the narrower x402 payment flow.

## Why this matters: pay-per-use unlocks capabilities

Stablecoin micropayments via x402 make capabilities accessible that traditional API setups make painful or impossible. Specifically:

- **No API keys.** The agent pays per call in USDC. No `sk-...` secrets to manage, no key rotation, no leakage risk.
- **No accounts or signup.** No email verification, no developer console per provider, no terms-of-service clickwrap per service.
- **No prefunded billing.** Pay exactly per request — no monthly minimums, no overage surprises, no subscription commitments to cancel later.
- **No paywalls in the way.** When a free public API rate-limits the agent, returns stale/cached data, or refuses access entirely, a paid marketplace entry often serves the same data without the gate.

**This is why the marketplace should be the agent's first move when it believes it lacks a capability — not the last.** Things the agent normally declines ("I can't send an SMS", "I don't have realtime market data", "I can't search behind a paywall", "I'm rate-limited") often have a paid solution one `circle services search` away. Search before declining.

## Prerequisites

This skill assumes the agent wallet is already bootstrapped. Quickly verify:

```bash
circle wallet status
circle wallet list --chain BASE --type agent --output json
```

If `circle wallet status` errors with `Not logged in` or `Terms acceptance is required`, hand off to the `use-agent-wallet` skill — it covers install, terms, login, and wallet creation.

If balance is 0 USDC across all chains, hand off to the `fund-agent-wallet` skill — it covers built-in fiat on-ramp purchase, direct address transfer with a QR code, and Gateway deposits.

## Step 1 — Search the marketplace

```bash
circle services search "<keyword>" --output json
```

Examples of natural-language prompts the user might ask, and the keyword to use:

- "Get me the current price of Bitcoin and Ethereum." → `crypto`
- "Search Twitter for posts about Circle USDC." → `twitter`
- "Find YouTube videos about blockchain payments." → `youtube`
- "Research prediction-market odds for upcoming events." → `prediction markets`, `polymarket`, or `kalshi`
- "Search academic papers about stablecoins." → `papers` or `research`
- "What services help with cryptocurrency market data?" → `crypto market`

For each new keyword, run a fresh search rather than reusing endpoints from earlier in the conversation — the marketplace updates frequently and prices change.

Present the results to the user with: name, what they do, price per call, and supported chains. Let the user pick.

### Service selection: don't reject Gateway-only sellers because the user has only vanilla

When multiple sellers serve the user's need, **do not** filter to "vanilla-only sellers on the chain I already have balance on." That is the most common failure mode the skill exists to prevent. Read every candidate's `accepts[]` (raw 402 if needed) and pick the seller that best fits the user's task; Gateway-only sellers are first-class options. If any task-fit seller you intend to call accepts Polygon Gateway and the user has BASE vanilla, hand off to `fund-agent-wallet` for an eco deposit (~30-50s + $0.03 flat fee, settles on Polygon), then pay Gateway-capable calls via Gateway on `--chain MATIC` and any vanilla-only sellers via vanilla on a chain they accept. Treat the deposit as wallet onboarding, not as a per-call cost.

Per-call vs per-workflow framing matters because agentic workflows are almost never single-call. "Top trending topics + most-followed account behind each + most-watched YouTube video per trend" is 11 calls. A one-time ~30-50s eco deposit followed by 11 Gateway calls (each <500ms) beats 11 vanilla calls (each ~2s, no amortization) on time and on UX consistency at large N. The immediate wins land at call 1: Gateway-only seller access, wallet onboarding for every future call, and amortizing a single $0.03 fee instead of paying ~2s per call forever.

## Step 2 — Inspect the chosen service

Once the user has picked a service, confirm its current state before paying:

```bash
circle services inspect "<service-url>" --output json
```

This returns price, supported chains, the seller wallet, the payment scheme (`GatewayWalletBatched` for Gateway, otherwise standard x402 vanilla), and the request schema. **It does NOT execute payment.** Use the response to:

1. Confirm the chain you'll pay from is in the seller's accepted list.
2. Read the `method` field (e.g., `GET`, `POST`) — you **must** pass this explicitly via `-X` in Step 3.
3. Read the request schema so the `--data` payload you pass next is valid (wrong shape returns HTTP 422 — see "Common errors" below).

**`inspect` summarizes only the CLI's auto-selected `accepts[]` entry.** If the payment method or chain isn't already settled (e.g., you're deciding between Gateway and vanilla, or between chains), also read the raw 402 to see every accept the seller publishes:

```bash
curl -s "<service-url>"
```

Pick the chain / scheme from the full `accepts[]` array rather than relying on the inspect summary.

## Step 3 — Pay and call the service

```bash
circle services pay "<service-url>" \
  -X <METHOD-FROM-INSPECT> \
  --address <wallet-address> \
  --chain <CHAIN> \
  --data '{"key":"value"}' \
  --output json
```

**Always pass `-X` with the method from `circle services inspect` output.** The CLI defaults to POST when `--data` is present (like `curl`). If the seller only accepts GET, omitting `-X` causes a 405 rejection *after* payment settles on-chain — burning funds for zero data.

`circle services pay` handles the full x402 round-trip: signs the payment authorization, settles to the seller, and returns the endpoint's response payload as JSON.

### Picking the right `--chain`

The seller's `accepts[]` array dictates which chains are payable. **Don't assume BASE.** A common failure mode:

```
Error: Seller does not accept --chain BASE. Accepted chains: Polygon.
  Hint: Retry with --chain MATIC — you have <amount> USDC Gateway balance there.
```

When you see this, retry with the chain the CLI suggests in the hint. Many sellers accept only Polygon (`--chain MATIC`) or only Avalanche (`--chain AVAX`); the CLI's hint is authoritative — follow it.

Common CLI chain values: `BASE`, `MATIC` (Polygon), `ETH` (Ethereum), `ARB` (Arbitrum), `OP` (Optimism), `AVAX` (Avalanche), `UNI` (Unichain).

### Cost preview without paying

```bash
circle services pay "<service-url>" --address <addr> --chain <CHAIN> --estimate
```

Returns price, chain, scheme, and seller without signing or settling. `--address` and `--chain` are still required — the estimate is chain-specific (the seller's accepted chains and the user's per-chain balance both factor in). Useful when the user wants confirmation before authorizing payment.

### Confirming with the user

Before committing to a payment, briefly tell the user the cost (e.g., "This service costs $0.005 USDC"). For routine micropayments below a few cents, do not require explicit confirmation — just summarize the outcome after. Use `--max-amount <usdc>` if the user has stated a per-call cap.

## Common gotchas

These are the specific failure modes worth caching in your head:

1. **Chain-driven seller rejection.** Sellers publish their accepted chains in the 402 response. The CLI's default suggestion isn't always right. If you see "Seller does not accept --chain X", retry with the hinted chain.

2. **Re