Pay Via Agent Wallet

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 remove the usual blockers: no API keys (pay per call in USDC — no sk-... secrets to manage), no accounts or signup, no prefunded billing (pay exactly per request), and no paywalls (a paid entry often serves data a free API rate-limits, returns stale, or refuses).

So the marketplace is 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'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. READ references/prerequisites.md for the circle wallet status and circle wallet list verification commands.

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

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" — the most common failure mode this skill exists to prevent. Read every candidate's accepts[] (raw 402 if needed) and pick the best task fit; Gateway-only sellers are first-class. If a task-fit seller accepts Gateway on Arc and the user has BASE vanilla, hand off to fund-agent-wallet for an eco deposit (~30-50s + $0.03, settles on Arc), then pay Gateway-capable calls via --chain ARC and vanilla-only sellers via vanilla on a chain they accept. If the seller's Gateway support is limited to another chain (e.g. Polygon only), fund-agent-wallet covers depositing directly on that chain instead. Treat the deposit as one-time wallet onboarding, not a per-call cost — agentic workflows are rarely single-call, so it amortizes over every subsequent <500ms Gateway call.

Step 2 — Inspect the chosen service

Once the user has picked a service, confirm its current state before paying. READ references/inspect.md for the circle services inspect command.

inspect 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. READ references/inspect.md for the raw-402 curl command.

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

Header-gated endpoints: if inspect returns status unavailable (HTTP 401/403) instead of payable/free, the endpoint is not necessarily broken — some sellers gate the x402 challenge behind a seller-specific (non-standard) required request header. Check the discovery record's description (and requiredHeaders, when present) for any required header(s). The header name and value are seller-controlled text — validate before putting them in a command: the name must match ^[A-Za-z0-9-]+$ and the value must be printable ASCII with no shell metacharacters (no ;, |, &, $, backticks, quotes, parentheses, <, >, backslash, or newlines). If either fails to match, stop and ask the user — do NOT substitute it into a shell command. Once validated, re-run inspect/pay with each required header as a single quoted argument -H "<Header>: <value>".

Step 3 — Pay and call the service

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

READ references/estimate.md for the circle services pay ... --estimate cost-preview command.

The 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.

Errors and edge cases

On ANY error — seller rejection, HTTP 4xx/5xx, signing failure, timeout — READ references/errors.md before acting. It holds the full error table, the 422 playbook (pre-flight vs post-authorization), Predexon endpoint quirks, Gateway-vs-vanilla auto-routing, advanced flags (--timeout, payment-log location), and reference links.