@elizaos/plugin-x402 2.0.0-beta.1 → 2.0.3-beta.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# @elizaos/plugin-x402
+
+x402 micropayment middleware for elizaOS plugin HTTP routes.
+
+This package lets Eliza agent plugins gate their HTTP routes behind the [x402 protocol](https://x402.org), requiring on-chain micropayments before serving responses. It handles HTTP 402 negotiation, payment verification (on-chain and facilitator-backed), and replay protection in one integration point.
+
+## What it does
+
+- **Declares payment requirements** via HTTP 402 responses with `accepts` arrays describing payment networks, token addresses, amounts, and resource URLs — compatible with x402scan indexing.
+- **Verifies payments** using three strategies, tried in priority order:
+  1. Standard `X-Payment` / `PAYMENT-SIGNATURE` payloads (x402-fetch / CDP-style) verified and settled via a facilitator.
+  2. Direct on-chain proofs: Solana SPL token transfers (via `@solana/web3.js`), EVM ERC-20 transfers and EIP-712 authorizations (via `viem`).
+  3. Facilitator payment IDs via `X-Payment-Id` header.
+- **Prevents replay attacks** using an atomic in-process guard plus a durable store backed by `runtime.setCache`/`getCache` (shared across processes when using the same DB).
+- **Emits runtime events** on payment required (`PAYMENT_REQUIRED`) and verified (`PAYMENT_VERIFIED`).
+
+## Supported networks and tokens
+
+| Config name | Network | Token |
+|-------------|---------|-------|
+| `base_usdc` | Base (chain 8453) | USDC |
+| `solana_usdc` | Solana | USDC |
+| `polygon_usdc` | Polygon (chain 137) | USDC |
+| `bsc_usdc` | BSC (chain 56) | USDC |
+| `base_elizaos` | Base | elizaOS token |
+| `solana_elizaos` | Solana | elizaOS token |
+| `solana_degenai` | Solana | degenai |
+
+## Enabling in a plugin
+
+Install (it declares `@elizaos/core` as a peer dependency; in this monorepo that resolves via `workspace:*`):
+
+```bash
+bun add @elizaos/plugin-x402
+```
+
+Wrap your route array before returning them from your plugin:
+
+```typescript
+import { applyPaymentProtection } from '@elizaos/plugin-x402';
+import type { Plugin, Route } from '@elizaos/core';
+
+const routes: Route[] = applyPaymentProtection([
+  {
+    type: 'GET',
+    path: '/api/premium-data',
+    public: true,
+    x402: {
+      priceInCents: 10,                             // $0.10
+      paymentConfigs: ['base_usdc', 'solana_usdc'],
+    },
+    handler: async (req, res, runtime) => {
+      res.json({ result: 'premium content' });
+    },
+  },
+]);
+
+export const myPlugin: Plugin = { name: 'my-plugin', routes };
+```
+
+`applyPaymentProtection` validates config at call time and throws on misconfiguration so the agent fails fast at startup.
+
+## Shorthand with character defaults
+
+Set `x402: true` on a route to inherit price and payment configs from the agent character:
+
+```typescript
+// In character config:
+character.settings.x402 = {
+  defaultPriceInCents: 10,
+  defaultPaymentConfigs: ['base_usdc', 'solana_usdc'],
+};
+
+// In route:
+{ type: 'GET', path: '/api/resource', x402: true, handler: ... }
+```
+
+## Required environment variables
+
+Set your payout wallet addresses. If unset, bundled example addresses are used (startup warns in dev, errors in production).
+
+```
+# Payout wallets (set the networks you want to accept)
+SOLANA_PUBLIC_KEY=<your-solana-wallet>
+BASE_PUBLIC_KEY=<your-base-evm-wallet>
+POLYGON_PUBLIC_KEY=<your-polygon-evm-wallet>
+BSC_PUBLIC_KEY=<your-bsc-evm-wallet>
+```
+
+## Optional environment variables
+
+```
+# Facilitator service (recommended for standard x402-fetch clients)
+X402_FACILITATOR_URL=https://your-facilitator.example.com
+
+# Override individual facilitator endpoints
+X402_FACILITATOR_VERIFY_URL=https://your-facilitator.example.com/api/v1/x402/verify
+X402_FACILITATOR_SETTLE_URL=https://your-facilitator.example.com/api/v1/x402/settle
+
+# Public base URL for this server (used in resource URLs)
+X402_BASE_URL=https://your-agent.example.com
+
+# Development: skip all payment verification
+X402_TEST_MODE=true
+
+# Replay protection: use in-memory only (no DB persistence)
+X402_REPLAY_DURABLE=0
+
+# Custom RPC endpoints
+SOLANA_RPC_URL=https://your-rpc.solana.com
+BASE_RPC_URL=https://your-rpc.base.org
+
+# Token prices for non-stablecoin configs (exact decimal string, dollars)
+ELIZAOS_PRICE_USD=0.05
+AI16Z_PRICE_USD=0.50
+DEGENAI_PRICE_USD=0.01
+
+# Debug logging
+DEBUG_X402_PAYMENTS=true
+```
+
+## Custom payment configs
+
+Register additional token/network combinations at plugin init time:
+
+```typescript
+import { registerX402Config } from '@elizaos/plugin-x402';
+
+registerX402Config('mytoken_base', {
+  network: 'BASE',
+  assetNamespace: 'erc20',
+  assetReference: '0x<token-contract-address>',
+  paymentAddress: process.env.BASE_PUBLIC_KEY!,
+  symbol: 'MYTOKEN',
+  chainId: '8453',
+});
+```
+
+Then reference `'mytoken_base'` in your route's `paymentConfigs` array.
+
+## Payment headers
+
+Clients send payment credentials in HTTP headers:
+
+| Header | Purpose |
+|--------|---------|
+| `X-Payment` or `PAYMENT-SIGNATURE` | Standard x402 payload (base64 JSON with `x402Version`, `accepted`, `payload`) |
+| `X-Payment-Proof` | Legacy proof: Solana tx sig, EVM tx hash, or colon-delimited format |
+| `X-Payment-Id` | Facilitator-issued payment ID |
+
+On success the response includes a `PAYMENT-RESPONSE` header from the facilitator and emits a `PAYMENT_VERIFIED` event on the agent runtime.

package/dist/index.d.ts

@@ -38,8 +38,8 @@ export type { BuiltInPaymentConfig, CharacterX402Settings, PaymentEnabledRoute,
 export type { Network } from "./payment-config.js";
 export { atomicAmountForPriceInCents, BUILT_IN_NETWORKS, getBaseUrl, getPaymentAddress, getPaymentConfig, getX402Health, listX402Configs, PAYMENT_ADDRESSES, PAYMENT_CONFIGS, type PaymentConfigDefinition, registerX402Config, toResourceUrl, toX402Network, } from "./payment-config.js";
 export { applyPaymentProtection, createPaymentAwareHandler, isRoutePaymentWrapped, X402_ROUTE_PAYMENT_WRAPPED, } from "./payment-wrapper.js";
-export { resolveEffectiveX402, X402_EVENT_PAYMENT_REQUIRED, X402_EVENT_PAYMENT_VERIFIED, } from "./x402-resolve.js";
 export { type StartupValidationResult, validateAndThrowIfInvalid, validateX402Startup, } from "./startup-validator.js";
+export { resolveEffectiveX402, X402_EVENT_PAYMENT_REQUIRED, X402_EVENT_PAYMENT_VERIFIED, } from "./x402-resolve.js";
 export { type Accepts, createAccepts, createX402Response, type OutputSchema, validateAccepts, validateX402Response, type X402Response, type X402ScanNetwork, } from "./x402-types.js";
 import type { Plugin } from "@elizaos/core";
 /**

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,YAAY,EACV,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,UAAU,EACV,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EACL,2BAA2B,EAC3B,iBAAiB,EACjB,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,KAAK,uBAAuB,EAC5B,kBAAkB,EAClB,aAAa,EACb,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,uBAAuB,EAC5B,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,KAAK,OAAO,EACZ,aAAa,EACb,kBAAkB,EAClB,KAAK,YAAY,EACjB,eAAe,EACf,oBAAoB,EACpB,KAAK,YAAY,EACjB,KAAK,eAAe,GACrB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;GAQG;AACH,QAAA,MAAM,UAAU,EAAE,MAQjB,CAAC;AAEF,eAAe,UAAU,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,YAAY,EACV,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,UAAU,EACV,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EACL,2BAA2B,EAC3B,iBAAiB,EACjB,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,KAAK,uBAAuB,EAC5B,kBAAkB,EAClB,aAAa,EACb,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,uBAAuB,EAC5B,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,KAAK,OAAO,EACZ,aAAa,EACb,kBAAkB,EAClB,KAAK,YAAY,EACjB,eAAe,EACf,oBAAoB,EACpB,KAAK,YAAY,EACjB,KAAK,eAAe,GACrB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;GAQG;AACH,QAAA,MAAM,UAAU,EAAE,MAUjB,CAAC;AAEF,eAAe,UAAU,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,CAAC"}