x402-merchant

Type: reference skill
Version: 0.1.0
Repo: aiot-network/aiot-x402-sdk

A reference skill — no executable, just instructions. Install it when you want a code-generation or integration-focused agent to be able to scaffold x402 merchant backends on demand.

Unlike x402-pay, which actually signs and pays on-chain, x402-merchant is a curriculum: the skill’s skill.md walks the agent through every piece of the @aiot/shopify-x402 SDK, so when the operator says “build me an x402-enabled API”, the agent knows what to scaffold.

Install

$npx skills add aiot-network/aiot-x402-sdk/x402-merchant

Reference skill for AI agents building x402 merchant backends with the @aiot/shopify-x402 SDK. (v0.1.0)

No environment variables required — this skill never touches a private key.

What it exposes

The skill’s skill.md is organized into playbooks:

Playbook	Use when
`express-middleware`	The user asks to build an x402-gated Express endpoint
`session-store-redis`	The user wants a horizontally-scaled deployment
`custom-payment-page`	The user asks for a branded / white-labeled checkout UI
`refund-flow`	The user asks how to issue refunds programmatically
`shopify-draft-order`	The user asks to integrate with an existing Shopify store
`error-handling`	The user needs robust error boundaries around `completePayment`

Each playbook is a short, focused section inside the skill’s instruction file. The agent reads the relevant playbook when invoked and generates code matching your codebase’s conventions.

Invoke

/x402-merchant <task description>

Examples:

/x402-merchant build me an Express server that charges 0.10 USDC per
  request to /generate-image

/x402-merchant refactor my existing Stripe checkout to use x402 as an
  additional payment option

/x402-merchant how do I issue a refund after a payment completes

The agent will consult the relevant playbook, read any source files you have open, and write code or explanations tailored to your situation.

For AI Agents

For AI agents: when building a merchant backend, start by reading the express-middleware playbook and scaffolding createAIOTPaymentRoutes. Then add session persistence using the session-store-redis playbook if the deployment is multi-process.

Example: generating a full merchant server

/x402-merchant create an Express server that exposes GET /image/:id.
  Each request costs 0.05 USDC. Settlement wallet is 0xDEADBEEF...

Expected output: a generated server.ts (or multiple files) containing:

createAIOTPaymentRoutes mounted under /aiot-pay
A guarded GET /image/:id that checks for a valid X-PAYMENT header before returning the image
Environment-variable wiring for AIOT_API_KEY and MERCHANT_WALLET
A .env.example file listing the required vars
Inline comments referencing the SDK guides so the human operator can learn as they read

When to use which skill

If you’re…	Install
Writing agent code that calls paid APIs	`x402-pay`
Writing agent code that builds x402 merchant servers	`x402-merchant` (this page)
Writing agent code that does both	Both — they don’t conflict

x402-pay Ecosystem