Skip to main content
x402-pay calls an x402-protected URL on behalf of the smart wallet. When the server returns 402 Payment Required, the CLI signs the payment using the wallet’s session, retries the request, and returns the response body. There is no --broadcast flag, payment and the request are one operation, so settlement happens as part of the call. Use this command to test that a seller’s x402 integration is live, to consume paid APIs from scripts, or to demonstrate agent-buyer flows interactively.

​
How it works

x402-pay flow
1Operator→CLIpolygon-agent x402-pay —url …
2CLI→APIInitial request (no payment header)
3API→CLI402 Payment Required with accepts block
4CLISigns payment with wallet session, retries with PAYMENT-SIGNATURE
5API→FacilitatorVerifies and settles USDC on Polygon
6API→CLI200 OK with body + PAYMENT-RESPONSE receipt
There is no separate verify-then-execute step. The CLI receives the 402, signs against the wallet’s session, retries, and prints the response body plus the settlement receipt in one call.

​
Prerequisites

Before calling x402-pay, confirm three things:
  1. Wallet exists. polygon-agent wallet list. If missing, run polygon-agent wallet create.
  2. USDC balance. polygon-agent balances --chain polygon. The wallet needs enough USDC to cover the price plus gas (keep ~0.1 USDC reserve).
  3. The endpoint actually requires x402. Curl the URL once; if it returns 200 without a payment header, x402 isn’t gating it.
For known endpoints, the x402 directory lists active sellers.

​
Command

polygon-agent x402-pay --url https://api.example.com/v1/lookups/company
polygon-agent x402-pay \
  --url https://api.example.com/v1/inference \
  --method POST \
  --body '{"prompt":"hi"}' \
  --header "X-Trace-Id:abc"
FlagDefaultPurpose
--walletmainWallet name
--chainnoneChain to pay on (defaults to wallet’s chain)
--urlrequiredEndpoint URL
--methodGETHTTP method
--bodynoneRequest body (JSON string)
--headernoneAdditional header Key:Value, repeatable
There is no --broadcast flag. x402-pay always settles as part of the call; running the command transfers USDC.

​
Worked example

polygon-agent x402-pay --url https://api.example.com/v1/weather/current

# 402 Payment Required → signing payment (0.0005 USDC)
# 200 OK
# Response body:
# { "city": "Tokyo", "temperature_c": 24.5, ... }
# Settlement: 0xabc... → https://polygonscan.com/tx/0xabc...
For a seller-side integration that returns 402 in front of the route, see the x402 Quickstart for Sellers.

​
Implementation

x402 Introduction

Protocol overview and facilitator list.

x402 Quickstart for Buyers

Programmatic buyer integration without the CLI.

x402 How It Works

Protocol mechanics, accepts block, receipts.

Balances and funding

Confirm USDC balance before calling.