@agentpayments/edge 0.1.0 → 0.1.1

package/README.md

@@ -82,6 +82,12 @@ export default { fetch: (req, env, ctx) => gate(req, env, ctx) };
 | `SOLANA_RPC_URL` | No | Custom Solana RPC endpoint. Defaults by debug flag. |
 | `USDC_MINT` | No | Custom USDC mint address. Defaults by debug flag. |
 | `DEBUG` | No | `"true"` = devnet. `"false"` = mainnet (default varies by adapter). |
+| `AGENTPAYMENTS_API_KEY` | No | AgentPayments hosted-platform API key (`ap_live_...`). When set, agent keys are issued and metered via the platform instead of self-signed locally. See **Hosted Platform Mode** below. |
+| `AGENTPAYMENTS_PLATFORM_URL` | No | Override for a self-hosted platform API. |
+
+## Hosted Platform Mode
+
+Setting `AGENTPAYMENTS_API_KEY` switches agent-key issuance from local (`ag_...`) to platform-issued (`agp_...`), and — when the platform account has an on-chain fee configured — every 402 response's custom `payment` object gains a `platform_fee` field describing a second required USDC transfer, to be sent in the **same Solana transaction** as the vendor payment. Missing that second transfer is treated as an unpaid request, same as any other invalid payment. This is opt-in per vendor account and has no effect on self-hosted deployments (no `AGENTPAYMENTS_API_KEY`). The standards-compliant `accepts[]`/`X-PAYMENT-REQUIRED` x402 fields are untouched — they still describe only the vendor leg.
 
 ## Security Features
 

package/index.js

@@ -27,7 +27,7 @@ const USDC_DECIMALS = 6;
 const X402_VERSION = 1;
 const SOLANA_CHAIN_ID_MAINNET = 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp';
 const SOLANA_CHAIN_ID_DEVNET = 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1';
-const PLATFORM_API_URL = 'https://api.agentpayments.dev';
+const PLATFORM_API_URL = 'https://api.agentpayments.cloud';
 const HOSTED_KEY_PREFIX = 'agp_';
 
 // ---------------------------------------------------------------------------
@@ -251,30 +251,50 @@ class EdgePlatformClient {
     this.apiKey = apiKey;
     this.platformUrl = platformUrl.replace(/\/$/, '');
     this._verificationSecret = null;
-    this._secretFetch = null;
+    this._platformFeeInfo = undefined; // undefined = not fetched yet; null = fetched, no fee configured
+    this._accountFetch = null;
   }
 
   _authHeaders() {
     return { Authorization: `Bearer ${this.apiKey}`, 'Content-Type': 'application/json' };
   }
 
-  async getVerificationSecret() {
-    if (this._verificationSecret) return this._verificationSecret;
-    if (this._secretFetch) return this._secretFetch;
-    this._secretFetch = fetch(`${this.platformUrl}/v1/account`, { headers: this._authHeaders() })
+  _fetchAccount() {
+    if (this._accountFetch) return this._accountFetch;
+    this._accountFetch = fetch(`${this.platformUrl}/v1/account`, { headers: this._authHeaders() })
       .then((r) => {
         if (!r.ok) throw new Error(`Platform /v1/account returned ${r.status}`);
         return r.json();
       })
       .then((data) => {
         this._verificationSecret = data.verificationSecret;
-        return data.verificationSecret;
+        this._platformFeeInfo = data.platformFeeWallet
+          ? { wallet: data.platformFeeWallet, ratePct: data.platformFeeRatePct }
+          : null;
+        return data;
       })
       .catch((err) => {
-        this._secretFetch = null;
+        this._accountFetch = null;
         throw err;
       });
-    return this._secretFetch;
+    return this._accountFetch;
+  }
+
+  async getVerificationSecret() {
+    if (this._verificationSecret) return this._verificationSecret;
+    await this._fetchAccount();
+    return this._verificationSecret;
+  }
+
+  /**
+   * Lazily fetch + cache the on-chain platform fee config (same request as
+   * getVerificationSecret — no extra round trip if already fetched).
+   * Returns { wallet, ratePct } or null if no fee is configured.
+   */
+  async getPlatformFeeInfo() {
+    if (this._platformFeeInfo !== undefined) return this._platformFeeInfo;
+    await this._fetchAccount();
+    return this._platformFeeInfo;
   }
 
   async issueKey() {
@@ -332,7 +352,15 @@ async function rpcCallWithFallback(rpcUrls, method, params, opts) {
   throw lastError;
 }
 
-async function verifyPaymentOnChain(agentKey, walletAddress, rpcUrls, usdcMint) {
+/**
+ * Verify payment on-chain.
+ *
+ * feeInfo, when set (hosted-platform mode with an on-chain fee configured), is
+ * { wallet, ratePct }. When set, the SAME transaction that carries the vendor
+ * payment must also carry a USDC transfer to feeInfo.wallet of at least
+ * minPayment * ratePct / 100, or the payment is treated as unverified.
+ */
+export async function verifyPaymentOnChain(agentKey, walletAddress, rpcUrls, usdcMint, minPayment = MIN_PAYMENT, feeInfo = null) {
   try {
     // commitment: 'finalized' — confirmed blocks can be rolled back (rare but possible).
     const ataData = await rpcCallWithFallback(rpcUrls, 'getTokenAccountsByOwner', [walletAddress, { mint: usdcMint }, { encoding: 'jsonParsed', commitment: 'finalized' }]);
@@ -343,6 +371,15 @@ async function verifyPaymentOnChain(agentKey, walletAddress, rpcUrls, usdcMint)
     const vendorUsdcAccounts = new Set(tokenAccounts);
     if (vendorUsdcAccounts.size === 0) return false; // vendor has no USDC account yet — no payment possible
 
+    let feeUsdcAccounts = null;
+    let feeAmountMicro = 0;
+    if (feeInfo) {
+      const feeAtaData = await rpcCallWithFallback(rpcUrls, 'getTokenAccountsByOwner', [feeInfo.wallet, { mint: usdcMint }, { encoding: 'jsonParsed', commitment: 'finalized' }]);
+      feeUsdcAccounts = new Set((feeAtaData.result?.value || []).map((entry) => entry.pubkey));
+      feeAmountMicro = Math.round(Math.round(minPayment * 1e6) * feeInfo.ratePct / 100);
+      if (feeUsdcAccounts.size === 0) return false; // fee wallet has no USDC account — fee can never be satisfied
+    }
+
     const addressesToScan = [walletAddress, ...tokenAccounts];
     const seen = new Set();
     const allSignatures = [];
@@ -376,6 +413,7 @@ async function verifyPaymentOnChain(agentKey, walletAddress, rpcUrls, usdcMint)
 
       let hasMemo = false;
       let hasPayment = false;
+      let hasFeePayment = !feeInfo; // vacuously satisfied when no fee is required
 
       for (const ix of allInstructions) {
         if (ix.program === 'spl-memo' || ix.programId === MEMO_PROGRAM) {
@@ -387,19 +425,24 @@ async function verifyPaymentOnChain(agentKey, walletAddress, rpcUrls, usdcMint)
           const parsed = ix.parsed || {};
           if (parsed.type === 'transfer' || parsed.type === 'transferChecked') {
             const info = parsed.info || {};
-            // Payment must be delivered to one of the vendor's USDC token accounts.
-            if (!vendorUsdcAccounts.has(info.destination)) continue;
+            // Payment must be delivered to one of the vendor's or fee wallet's USDC
+            // token accounts — anything else is irrelevant.
+            const isVendorDest = vendorUsdcAccounts.has(info.destination);
+            const isFeeDest = feeUsdcAccounts !== null && feeUsdcAccounts.has(info.destination);
+            if (!isVendorDest && !isFeeDest) continue;
             if (parsed.type === 'transferChecked' && info.mint !== usdcMint) continue;
             // Integer base-unit comparison — avoids float precision issues at threshold.
             const amountStr = info.tokenAmount?.amount ?? info.amount ?? '0';
             const amountMicro = parseInt(amountStr, 10);
-            const minPaymentMicro = Math.round(MIN_PAYMENT * 1e6);
-            if (!Number.isNaN(amountMicro) && amountMicro >= minPaymentMicro) hasPayment = true;
+            if (Number.isNaN(amountMicro)) continue;
+            const minPaymentMicro = Math.round(minPayment * 1e6);
+            if (isVendorDest && amountMicro >= minPaymentMicro) hasPayment = true;
+            else if (isFeeDest && amountMicro >= feeAmountMicro) hasFeePayment = true;
           }
         }
       }
 
-      if (hasMemo && hasPayment) return true;
+      if (hasMemo && hasPayment && hasFeePayment) return true;
     }
   } catch (error) {
     gateLog('error', 'Solana RPC error', { error: error.message });
@@ -473,6 +516,30 @@ function buildX402PaymentRequirements({ walletAddress, mint, minPayment, debug,
   return req;
 }
 
+/**
+ * Builds the custom `payment` object (NOT part of the x402 spec — that's
+ * buildX402PaymentRequirements above, which stays vendor-leg-only). When feeInfo
+ * is set (hosted-platform mode with an on-chain fee configured), adds a
+ * platform_fee field describing the second required transfer. Deliberately not
+ * added as a second x402 accepts[] entry — that would read to a spec-compliant
+ * client as an alternative payment method, not an additional requirement.
+ */
+function buildPaymentField({ network, minPayment, walletAddress, memo, feeInfo, instructions }) {
+  const payment = { chain: 'solana', network, token: 'USDC', amount: String(minPayment), wallet_address: walletAddress, memo };
+  if (feeInfo) {
+    const feeAmountMicro = Math.round(Math.round(minPayment * 1e6) * feeInfo.ratePct / 100);
+    payment.platform_fee = {
+      wallet_address: feeInfo.wallet,
+      amount: String(feeAmountMicro / 1e6),
+      token: 'USDC',
+      rate_pct: feeInfo.ratePct,
+      note: 'Must be a second USDC transfer inside the SAME Solana transaction as the payment above, or access will be denied.',
+    };
+  }
+  if (instructions) payment.instructions = instructions;
+  return payment;
+}
+
 /**
  * Like jsonResponse(body, 402) but adds x402Version, accepts[], and
  * the X-PAYMENT-REQUIRED header (base64-encoded PaymentRequirements).
@@ -633,6 +700,18 @@ export function createEdgeGate(options = {}) {
 
     if (!isBrowser(request)) {
       const agentKey = request.headers.get('X-Agent-Key');
+      const network = debug ? 'devnet' : 'mainnet-beta';
+
+      // Resolve the on-chain platform fee requirement once (hosted-platform mode
+      // only — always null for self-hosted vendors with no platformClient).
+      let feeInfo = null;
+      if (platformClient) {
+        try {
+          feeInfo = await platformClient.getPlatformFeeInfo();
+        } catch (err) {
+          gateLog('warn', 'Failed to fetch platform fee info, proceeding without fee enforcement', { error: err.message });
+        }
+      }
 
       if (!agentKey) {
         // Hosted mode: issue a metered platform key (agp_...).
@@ -649,19 +728,14 @@ export function createEdgeGate(options = {}) {
         } else {
           newKey = await generateAgentKey(secret);
         }
+        const noKeyInstructions = feeInfo
+          ? `Send ${minPayment} USDC on Solana ${debug ? 'devnet' : 'mainnet'} to ${walletAddress} with memo "${newKey}", AND in the SAME transaction send the platform fee (see platform_fee below) to ${feeInfo.wallet}. Then include the header X-Agent-Key: ${newKey} on all subsequent requests.`
+          : `Send ${minPayment} USDC on Solana ${debug ? 'devnet' : 'mainnet'} to ${walletAddress} with memo "${newKey}". Then include the header X-Agent-Key: ${newKey} on all subsequent requests.`;
         return paymentRequiredResponse({
           error: 'payment_required',
           message: 'Access requires a paid API key. A key has been generated for you below. Send a USDC payment on Solana with this key as the memo to activate it, then retry your request with the X-Agent-Key header.',
           your_key: newKey,
-          payment: {
-            chain: 'solana',
-            network: debug ? 'devnet' : 'mainnet-beta',
-            token: 'USDC',
-            amount: String(minPayment),
-            wallet_address: walletAddress,
-            memo: newKey,
-            instructions: `Send ${minPayment} USDC on Solana ${debug ? 'devnet' : 'mainnet'} to ${walletAddress} with memo "${newKey}". Then include the header X-Agent-Key: ${newKey} on all subsequent requests.`,
-          },
+          payment: buildPaymentField({ network, minPayment, walletAddress, memo: newKey, feeInfo, instructions: noKeyInstructions }),
         }, { walletAddress, mint: usdcMint, minPayment, debug, agentKey: newKey, resource: url.pathname });
       }
 
@@ -708,24 +782,17 @@ export function createEdgeGate(options = {}) {
           error: 'payment_required',
           message: 'Key is valid but payment has not been verified on-chain yet. Please send the USDC payment and allow a few moments for confirmation.',
           your_key: agentKey,
-          payment: { chain: 'solana', network: debug ? 'devnet' : 'mainnet-beta', token: 'USDC', amount: String(minPayment), wallet_address: walletAddress, memo: agentKey },
+          payment: buildPaymentField({ network, minPayment, walletAddress, memo: agentKey, feeInfo }),
         }, { walletAddress, mint: usdcMint, minPayment, debug, agentKey, resource: url.pathname });
       }
-      const paid = await verifyPaymentOnChain(agentKey, walletAddress, rpcUrls, usdcMint);
+      const paid = await verifyPaymentOnChain(agentKey, walletAddress, rpcUrls, usdcMint, minPayment, feeInfo);
       await store.setCachedPayment(agentKey, paid, paid ? PAYMENT_CACHE_TTL : NEGATIVE_CACHE_TTL_MS);
       if (!paid) {
         return paymentRequiredResponse({
           error: 'payment_required',
           message: 'Key is valid but payment has not been verified on-chain yet. Please send the USDC payment and allow a few moments for confirmation.',
           your_key: agentKey,
-          payment: {
-            chain: 'solana',
-            network: debug ? 'devnet' : 'mainnet-beta',
-            token: 'USDC',
-            amount: String(minPayment),
-            wallet_address: walletAddress,
-            memo: agentKey,
-          },
+          payment: buildPaymentField({ network, minPayment, walletAddress, memo: agentKey, feeInfo }),
         }, { walletAddress, mint: usdcMint, minPayment, debug, agentKey, resource: url.pathname });
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentpayments/edge",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "AgentPayments gate for Cloudflare Workers, Netlify Edge, and Vercel Edge Functions — charge AI agents USDC on Solana",
   "license": "MIT",
   "type": "module",