This page covers everything you need to install, configure, and run x402 Agent Checkout for WooCommerce: getting your Coinbase Developer Platform credentials, setting up the plugin, testing on testnet, going live, and a full reference for every setting and endpoint. It reflects the current release, v1.11.1.
On This Page
- Requirements
- Setup
- Enabling Products for Agent Checkout
- Testing Your Setup
- Going Live (Switching to Mainnet)
- Settings Reference
- Agent Endpoints Reference
- Currency Conversion
- Discovery: Storefront & Bazaar
- Reliability & Security
- Troubleshooting
- FAQ
Requirements
- WordPress 6.0 or higher
- WooCommerce 6.0 or higher
- PHP 7.4 or higher
- A free Coinbase Developer Platform (CDP) account
- A wallet address to receive USDC on the Base network
Setup
1. Install the plugin
Upload the plugin zip under Plugins → Add New → Upload Plugin, then activate it. A new x402 Agent Checkout menu appears under WooCommerce.
2. Get your CDP API credentials
Create a free account at the Coinbase Developer Platform and generate a CDP API Key. You’ll get a Key ID and Key Secret — both go into the plugin’s settings. The Key Secret can optionally be kept out of your database entirely and stored in wp-config.php instead (see Reliability & Security below).
3. Get a receiving wallet address
This is the wallet that receives USDC from every agent purchase. Any standard EVM-compatible address works — a Coinbase Wallet, MetaMask, or similar address you control.
4. Configure the plugin
Under WooCommerce → x402 Agent Checkout, enter your CDP Key ID, Key Secret, and receiving wallet address. Leave the network on Base Sepolia for now — that’s the testnet, and it’s the default for a reason (see Testing Your Setup).
Don’t switch to mainnet until you’ve completed a full test purchase on Sepolia. It costs nothing and it’s the only way to confirm your CDP credentials, wallet address, and product setup are all correct before real USDC is on the line.
Enabling Products for Agent Checkout
Agent checkout is opt-in per product by default. Open any product, find the x402 Agent Checkout panel, and toggle it on — new products default to enabled. If you’d rather skip per-product setup entirely, turn on Force-enable Agent Checkout for ALL products under the plugin’s settings, which exposes every purchasable, priced product to agents at once.
Each product also has an optional USDC Price Override — set one if you want to price a specific product in USD directly rather than relying on automatic currency conversion.
Testing Your Setup
- Fund a testnet wallet with free Base Sepolia USDC from a public faucet.
- Fetch your catalog feed and confirm the product you want to test shows up with the right price.
- Send a checkout request for that product, sign the returned payment challenge with your testnet wallet, and resubmit.
- Confirm a real WooCommerce order was created, with a populated x402 Payment Details panel showing the payer wallet, network, and transaction hash.
Going Live (Switching to Mainnet)
Once a full testnet purchase has gone through end to end, switch the Network setting to Base Mainnet. Real USDC will move from this point on. Do one small real test purchase yourself before announcing agent checkout is live, the same way you’d test any new payment method.
Settings Reference
All settings live under WooCommerce → x402 Agent Checkout.
Payment & Network
| Setting | What it does | Default |
|---|---|---|
| Network | Base Sepolia (testnet) or Base Mainnet. | Base Sepolia |
| CDP Key ID / Key Secret | Your Coinbase Developer Platform API credentials. | — |
| Receiving Wallet Address | Where agent payments settle. | — |
| Order Status | The WooCommerce order status assigned after a successful settlement. | Processing |
Order Totals
| Setting | What it does | Default |
|---|---|---|
| Calculate real tax on agent orders | Uses your actual configured WooCommerce tax rates instead of skipping tax. | Off |
| Calculate real shipping cost on agent orders | Uses the cheapest matching rate from your configured Shipping Zones for the destination address given. | Off |
Currency, Discovery & Rate Limiting
| Setting | What it does | Default |
|---|---|---|
| Currency Conversion | Converts a non-USD store’s prices to USD using a live exchange rate before an agent is ever charged. | On |
| Store Discovery | Publishes a link tag, HTTP header, and a /.well-known/x402 manifest so agents can find your catalog on their own. | On |
| Bazaar Marketplace Listing | Attaches Coinbase’s own discovery metadata to checkout, so the CDP Facilitator can auto-list this store in Bazaar / Agentic.Market after the first real sale. | On |
| Rate Limiting Enabled | Caps checkout requests per IP address. | On |
| Rate Limit (requests / minute) | How many checkout requests one IP may make per minute. | 20 |
Data Handling
| Setting | What it does | Default |
|---|---|---|
| On Uninstall — Delete all plugin settings | Orders created via agent checkout are never deleted either way, regardless of this setting — they remain normal WooCommerce orders. | Off |
Agent Endpoints Reference
These are the URLs agents actually call against your store — shown for reference; you don’t need to build anything to expose them.
| Endpoint | URL |
|---|---|
| Product Catalog (JSON feed) | https://yourstore.com/wp-json/store/v1/x402/products |
| Checkout (single item) | https://yourstore.com/wp-json/store/v1/x402/checkout?product_id=123&quantity=1 |
| Checkout (cart, multiple items) | Same URL, called as a POST with a JSON body listing an items array |
| Order Status Lookup | https://yourstore.com/wp-json/store/v1/x402/orders/{order_id}?payer=0x... |
| Store Manifest | https://yourstore.com/.well-known/x402 |
Example cart checkout body:
{
"items": [
{ "product_id": 123, "quantity": 2 },
{ "product_id": 456, "quantity": 1 }
]
}Currency Conversion
x402 payments always settle in USDC. If your store prices in anything other than USD, agent checkout converts to USD automatically using a live exchange rate before an agent is ever quoted or charged — a €50 product correctly charges roughly $54 worth of USDC (at typical rates), not 50 USDC. USD stores are unaffected either way, with no added latency.
This is on by default. Turning it off restores the plugin’s original behavior of charging the raw store-currency number as-is — only do this if you’re intentionally pricing in USD-equivalent numbers already. A per-product USDC Price Override is never converted, since setting one is already an explicit statement of the USD price.
If a live exchange rate genuinely can’t be reached and no recent cached rate is available either, checkout for affected products fails with a clear error rather than guessing at a rate.
Discovery: Storefront & Bazaar
Two independent, complementary discovery mechanisms are on by default once a receiving wallet address is set:
- Store Discovery — every page on your site gets a
<link>tag and a matching HTTP header pointing at your catalog and checkout endpoints, plus a manifest published at/.well-known/x402. An agent that simply visits your store can find everything on its own, with no URL handed to it out of band. - Bazaar Marketplace Listing — separately, Coinbase’s own CDP Facilitator runs a free, opt-in discovery index (Bazaar, surfaced publicly at Agentic.Market). This plugin attaches the metadata Coinbase looks for to every checkout request, so your store gets listed there automatically the first time a real payment settles — no signup, no extra cost.
Both can be turned off independently under Settings if you’d rather this store not be indexed anywhere beyond what you set up yourself.
Reliability & Security
- Idempotent replay protection — a retried request with the same signed payment returns the original order instead of creating a duplicate or charging twice.
- Atomic stock reservation — stock for a low-quantity item is locked at the moment of settlement, so two agents can never both walk away thinking they bought the last unit.
- Per-IP rate limiting on the checkout endpoint, on by default and configurable.
- No private keys stored on your WordPress site — settlement runs through Coinbase’s CDP Facilitator, and your CDP Key Secret itself can be kept out of the database entirely via a
wp-config.phpconstant. - License verification unlocks support and future updates, but never gates any checkout functionality — every feature works identically whether or not a license has been verified.
Troubleshooting
The catalog feed returns no products
Check that the product is published, has a price, and has “Enable Agent Checkout” turned on (or that store-wide Force-enable is on).
Checkout returns a 402 that never resolves
Confirm the signed payment header is being sent on the retry request, and that the wallet used has funds on the correct network (Sepolia vs. Mainnet must match your plugin setting exactly).
Checkout returns a currency-conversion error
This means a live USD exchange rate couldn’t be obtained for your store’s currency and no recent cached rate was available either. It’s a transient failure — retrying shortly usually resolves it.
An order wasn’t created after a real payment
Check the transaction on a Base block explorer using the transaction hash. If it settled on-chain but no order appears, contact support with the transaction hash and the approximate time of the request.
FAQ
Do I need to hold or manage USDC myself?
No. Payments settle directly to your receiving wallet address on-chain. The plugin never custodies funds and doesn’t need you to pre-fund anything.
Does this replace my existing payment gateways?
No — it runs alongside them. This is specifically for autonomous agent buyers calling your store’s API directly; it doesn’t change or interfere with your normal human checkout flow.
Can an agent buy more than one product in a single order?
Yes. An agent can POST a JSON body with an items array listing multiple products (or multiple variations of the same product) to check out and pay for all of them in a single order. The original single-product request still works too, for simple purchases.
What happens if my store doesn’t price in USD?
Agent checkout automatically converts your store’s currency to USD before quoting or charging an agent, using a live exchange rate. This is on by default — see Currency Conversion above to turn it off.
Do I have to verify a license to use the plugin?
No. License verification unlocks support and future updates, but every checkout feature works identically whether or not you’ve verified.
What if I don’t want a particular product available to agents?
Leave its “Enable Agent Checkout” toggle off (the default state is on for new products), or keep the store-wide Force-enable setting off and opt products in individually.
Ready to Sell to AI Agents?
Get x402 Agent Checkout for WooCommerce and start accepting agent-driven USDC payments on your store.