add x402-payments SKILL

Adds SKILL for x402 Payments

Author: AyushBherwani1998

domains/web3-tools/skills/x402-payments/skill.md

@@ -0,0 +1,68 @@
+---
+name: x402-payments
+description: Build x402 payment flows using MetaMask Smart Accounts Kit, machine to machine payments over HTTP with ERC-7710 delegations and ERC-7715 Advanced Permissions
+---
+
+# x402 Payments
+
+x402 is an open payment protocol that uses the HTTP 402 status code to enable programmatic, machine-to-machine payments over HTTP. It lets servers charge for API access without requiring traditional payment infrastructure, buyer accounts, or API keys.
+
+## When to use
+
+- You want to charge for API access using onchain payments.
+- You want to build AI agents that pay per request for API resources.
+- You want to enable micro payments for premium data or services.
+- You want to set up recurring payments with periodic budgets.
+- You want to use MetaMask smart account delegations for x402 settlement.
+
+## Installation
+
+```bash
+npm install @x402/core @x402/fetch @metamask/x402 @metamask/smart-accounts-kit
+```
+
+For seller endpoints:
+
+```bash
+npm install @x402/core @x402/express @metamask/x402
+```
+
+## How x402 works
+
+1. The buyer sends a request to a protected endpoint.
+2. The server responds with HTTP 402 and a `PAYMENT-REQUIRED` header containing payment terms.
+3. The buyer creates a payment payload (delegation or permission) matching the terms.
+4. The buyer resends the request with the payment in the `PAYMENT-SIGNATURE` header.
+5. The server validates the payment through a facilitator and returns the resource.
+
+## x402 ERC-7710 payments
+
+The standard x402 protocol supports direct token transfers (using ERC-20 Permit2 or EIP-3009). ERC-7710 extends this by enabling delegation-based payments from MetaMask smart accounts.
+
+With ERC-7710, a buyer's smart account creates a delegation that authorizes the facilitator to transfer tokens on their behalf. The buyer doesn't sign a direct token approval. Instead, they sign a delegation that the facilitator redeems during settlement.
+
+This approach enables buyers to pay from MetaMask wallet. Buyers can restrict delegations to specific facilitator addresses, amounts, and time windows using delegation scopes. They can also create long-lived delegations that allow recurring payments without re-signing for each request.
+
+## Workflows
+
+| Workflow | Use case |
+|----------|----------|
+| [Seller endpoint setup](./workflows/seller-endpoint-setup.md) | You want to protect API endpoints with x402 payment requirements. |
+| [Delegation payments](./workflows/delegation-payments.md) | You control the buyer smart account and want to automate payments programmatically. |
+| [Advanced Permissions (recurring)](./workflows/recurring-payments.md) | You want to request a periodic budget from a MetaMask user for ongoing API access. Best for subscriptions and recurring usage. |
+
+If the user hasn't specified which payment method they need, present the options.
+
+## Supported networks
+
+| Network | Chain ID | Facilitator URL |
+|---------|----------|-----------------|
+| Base | eip155:8453 | `https://tx-sentinel-base-mainnet.dev-api.cx.metamask.io/platform/v2/x402` |
+| Base Sepolia | eip155:84532 | `https://tx-sentinel-base-sepolia.dev-api.cx.metamask.io/platform/v2/x402` |
+| Monad | eip155:143 | `https://tx-sentinel-monad-mainnet.dev-api.cx.metamask.io/platform/v2/x402` |
+
+## Resources
+
+- x402 protocol: https://www.x402.org/
+- Smart Accounts Kit docs: https://docs.metamask.io/smart-accounts-kit
+- [x402 overview](https://docs.metamask.io/smart-accounts-kit/guides/x402/overview.md)

domains/web3-tools/skills/x402-payments/workflows/delegation-payments.md

@@ -0,0 +1,79 @@
+---
+name: Delegation payments
+description: Pay for x402-protected APIs using ERC-7710 delegations from a smart account
+---
+
+# Delegation payments
+
+Use this workflow when you control the buyer smart account and want to automate payments programmatically. Best for AI agents and backend services.
+
+## Install dependencies
+
+```bash
+npm install @x402/core @x402/fetch @metamask/x402 @metamask/smart-accounts-kit
+```
+
+## Create the buyer smart account
+
+Create a public client for your target network, then create a MetaMask smart account. Ensure the smart account is funded with the required token (typically USDC):
+
+```typescript
+import { createPublicClient, http } from 'viem'
+import { baseSepolia } from 'viem/chains'
+import { Implementation, toMetaMaskSmartAccount } from '@metamask/smart-accounts-kit'
+import { privateKeyToAccount } from 'viem/accounts'
+
+const chain = baseSepolia
+const publicClient = createPublicClient({ chain, transport: http() })
+
+const account = privateKeyToAccount('<BUYER_PRIVATE_KEY>')
+
+const buyerSmartAccount = await toMetaMaskSmartAccount({
+  client: publicClient,
+  implementation: Implementation.Hybrid,
+  deployParams: [account.address, [], [], []],
+  deploySalt: '0x',
+  signer: { account },
+})
+```
+
+## Create the x402 delegation provider
+
+Use `createx402DelegationProvider` to create an ERC-7710 client that automatically creates, signs, and encodes open root delegations with the required caveats:
+
+```typescript
+import { createx402DelegationProvider } from '@metamask/smart-accounts-kit/experimental'
+import { x402Erc7710Client } from '@metamask/x402'
+
+const erc7710Client = new x402Erc7710Client({
+  delegationProvider: createx402DelegationProvider({
+    account: buyerSmartAccount,
+  }),
+})
+```
+
+For API reference, see [`createx402DelegationProvider`](https://docs.metamask.io/smart-accounts-kit/reference/x402.md).
+
+## Register the client and wrap fetch
+
+Register the ERC-7710 client for all EVM networks, then create an HTTP client and wrap `fetch` with automatic payment handling:
+
+```typescript
+import { x402Client, x402HTTPClient } from '@x402/core/client'
+import { wrapFetchWithPayment } from '@x402/fetch'
+
+const coreClient = new x402Client().register('eip155:*', erc7710Client)
+const httpClient = new x402HTTPClient(coreClient)
+const fetchWithPayment = wrapFetchWithPayment(fetch, httpClient)
+```
+
+## Make paid requests
+
+Call protected endpoints using the wrapped fetch. It automatically handles 402 responses, creates the delegation payment, and retries the request:
+
+```typescript
+const response = await fetchWithPayment('https://api.example.com/paid-endpoint')
+const data = await response.json()
+```
+
+For more details, see the [delegation payments guide](https://docs.metamask.io/smart-accounts-kit/development/guides/x402/buyer/delegations.md).

domains/web3-tools/skills/x402-payments/workflows/recurring-payments.md

@@ -0,0 +1,116 @@
+---
+name: Recurring payments
+description: Set up recurring x402 payments using ERC-7715 Advanced Permissions with periodic budgets
+---
+
+# Recurring payments
+
+Use this workflow when you want to request a periodic budget from a MetaMask user for ongoing API access. The permission resets each period, enabling subscription-style payment flows.
+
+## Install dependencies
+
+```bash
+npm install @x402/core @x402/fetch @metamask/x402 @metamask/smart-accounts-kit
+```
+
+## Set up the wallet client
+
+Create a viem wallet client connected to MetaMask and extend it with ERC-7715 actions. This enables the `requestExecutionPermissions` method needed to request periodic spending budgets from the user:
+
+```typescript
+import { createWalletClient, custom } from 'viem'
+import { baseSepolia } from 'viem/chains'
+import { erc7715ProviderActions } from '@metamask/smart-accounts-kit/actions'
+
+const chain = baseSepolia
+
+const walletClient = createWalletClient({
+  chain,
+  transport: custom(window.ethereum),
+}).extend(erc7715ProviderActions())
+```
+
+## Create a session account
+
+Generate a session key that will act on behalf of the user within the granted permission. This account signs x402 payment delegations without requiring the user's approval for each individual payment:
+
+```typescript
+import { privateKeyToAccount } from 'viem/accounts'
+
+const sessionAccount = privateKeyToAccount('<SESSION_PRIVATE_KEY>')
+```
+
+## Request periodic permissions
+
+Request a periodic ERC-20 permission that resets each period. This example requests 10 USDC per week for 30 days:
+
+```typescript
+import { parseUnits } from 'viem'
+
+const currentTime = Math.floor(Date.now() / 1000)
+
+const grantedPermissions = await walletClient.requestExecutionPermissions([
+  {
+    chainId: chain.id,
+    expiry: currentTime + 30 * 86400,
+    to: sessionAccount.address,
+    permission: {
+      type: 'erc20-token-periodic',
+      data: {
+        tokenAddress: '<TOKEN_ADDRESS>',
+        periodAmount: parseUnits('10', 6),
+        periodDuration: 604800,
+        justification: 'Weekly budget for API access',
+      },
+      isAdjustmentAllowed: true,
+    },
+  },
+])
+```
+
+## Create the x402 delegation provider
+
+Use `createx402DelegationProvider` with the granted permission context. This sets up open redelegation so facilitators can redeem payments within the granted budget:
+
+```typescript
+import { createx402DelegationProvider } from '@metamask/smart-accounts-kit/experimental'
+import { x402Erc7710Client } from '@metamask/x402'
+
+const permission = grantedPermissions[0]
+
+const erc7710Client = new x402Erc7710Client({
+  delegationProvider: createx402DelegationProvider({
+    account: sessionAccount,
+    parentPermissionContext: permission.context,
+    from: permission.from,
+  }),
+})
+```
+
+For API reference, see [`createx402DelegationProvider`](https://docs.metamask.io/smart-accounts-kit/reference/x402.md).
+
+## Register and wrap fetch
+
+Register the ERC-7710 client for all EVM networks, then create an HTTP client and wrap `fetch` with automatic payment handling. When a server responds with HTTP 402, the wrapped fetch creates a payment within the granted budget and retries the request:
+
+```typescript
+import { x402Client, x402HTTPClient } from '@x402/core/client'
+import { wrapFetchWithPayment } from '@x402/fetch'
+
+const coreClient = new x402Client().register('eip155:*', erc7710Client)
+const httpClient = new x402HTTPClient(coreClient)
+const fetchWithPayment = wrapFetchWithPayment(fetch, httpClient)
+```
+
+## Make recurring paid requests
+
+Each call automatically handles x402 payment within the granted periodic budget:
+
+```typescript
+const response = await fetchWithPayment('https://api.example.com/paid-endpoint')
+const data = await response.json()
+```
+
+The periodic budget resets at the start of each new period. The user doesn't need to approve each individual payment.
+
+For more details, see the [recurring payments guide](https://docs.metamask.io/smart-accounts-kit/development/guides/x402/buyer/recurring-payments.md).

domains/web3-tools/skills/x402-payments/workflows/seller-endpoint-setup.md

@@ -0,0 +1,90 @@
+---
+name: Seller endpoint setup
+description: Set up an Express server with x402 payment middleware for ERC-7710 payments
+---
+
+# Seller endpoint setup
+
+## Install dependencies
+
+```bash
+npm install @metamask/x402 @x402/core @x402/express cors express
+```
+
+## Create the Express server
+
+Set up an Express app with CORS configured to expose the x402 payment headers:
+
+```typescript
+import express from 'express'
+import cors from 'cors'
+
+const app = express()
+
+app.use(cors({
+  exposedHeaders: ['PAYMENT-REQUIRED', 'PAYMENT-RESPONSE'],
+}))
+```
+
+## Configure the facilitator client and resource server
+
+Initialize an `HTTPFacilitatorClient` pointing to the MetaMask facilitator for your network, then create an `x402ResourceServer` and register the ERC-7710 server scheme so the middleware can parse and validate delegation-based payment payloads:
+
+```typescript
+import { HTTPFacilitatorClient } from '@x402/core/server'
+import { paymentMiddleware, x402ResourceServer } from '@x402/express'
+import { x402ExactEvmErc7710ServerScheme } from '@metamask/x402'
+
+const facilitatorClient = new HTTPFacilitatorClient({
+  url: '<FACILITATOR_URL>',
+})
+
+const resourceServer = new x402ResourceServer(facilitatorClient).register(
+  'eip155:84532',
+  new x402ExactEvmErc7710ServerScheme(),
+)
+```
+
+MetaMask facilitator URLs by network:
+- Base Sepolia: `https://tx-sentinel-base-sepolia.dev-api.cx.metamask.io/platform/v2/x402`
+- Base: `https://tx-sentinel-base-mainnet.dev-api.cx.metamask.io/platform/v2/x402`
+- Monad: `https://tx-sentinel-monad-mainnet.dev-api.cx.metamask.io/platform/v2/x402`
+
+## Add payment middleware to protected routes
+
+Define the payment requirements for each route and apply the middleware with the resource server:
+
+```typescript
+app.use(
+  paymentMiddleware(
+    {
+      'GET /api/hello': {
+        accepts: [{
+          scheme: 'exact',
+          price: '$0.01',
+          network: 'eip155:84532',
+          payTo: '<SELLER_ADDRESS>',
+          extra: { assetTransferMethod: 'erc7710' },
+        }],
+        description: 'A paid hello endpoint',
+        mimeType: 'application/json',
+      },
+    },
+    resourceServer,
+  ),
+)
+```
+
+## Add the protected route handler
+
+Define the route handler as usual. The payment middleware runs before your handler — by the time your handler executes, the payment has already been verified and settled through the facilitator:
+
+```typescript
+app.get('/api/hello', (req, res) => {
+  res.json({ message: 'Hello, paid user!' })
+})
+
+app.listen(3000)
+```
+
+For more details, see the [seller endpoint guide](https://docs.metamask.io/smart-accounts-kit/development/guides/x402/seller.md).