synthra-x402 1.0.0

package/dist/client/index.d.ts

@@ -0,0 +1,12 @@
+import { x402Client } from "@x402-avm/core/client";
+import type { ClientAvmSigner } from "@x402-avm/avm";
+export interface SynthraClientConfig {
+    signer: ClientAvmSigner;
+    network?: "testnet" | "mainnet";
+}
+/**
+ * Creates a wrapped fetch client that automatically handles x402 payments
+ * using prepaid USDC on Algorand.
+ */
+export declare function createSynthraClient(config: SynthraClientConfig): x402Client;
+export type { ClientAvmSigner };

package/dist/client/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSynthraClient = void 0;
+const client_1 = require("@x402-avm/core/client");
+const client_2 = require("@x402-avm/avm/exact/client");
+const avm_1 = require("@x402-avm/avm");
+/**
+ * Creates a wrapped fetch client that automatically handles x402 payments
+ * using prepaid USDC on Algorand.
+ */
+function createSynthraClient(config) {
+    const isMainnet = config.network === "mainnet";
+    const caip2 = isMainnet ? avm_1.ALGORAND_MAINNET_CAIP2 : avm_1.ALGORAND_TESTNET_CAIP2;
+    const usdcId = isMainnet ? avm_1.USDC_MAINNET_ASA_ID : avm_1.USDC_TESTNET_ASA_ID;
+    // Initialize the base fetch client
+    const client = new client_1.x402Client();
+    // Register the AVM scheme
+    (0, client_2.registerExactAvmScheme)(client, { signer: config.signer });
+    // The x402Client has a .fetch() method that automatically handles the 402 flow
+    return client;
+}
+exports.createSynthraClient = createSynthraClient;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './client';
+export * from './server';

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./client"), exports);
+__exportStar(require("./server"), exports);

package/dist/server/index.d.ts

@@ -0,0 +1,16 @@
+export interface SynthraApiConfig {
+    payTo: string;
+    priceUsdc: number;
+    network?: "testnet" | "mainnet";
+    discovery?: {
+        description?: string;
+        tags?: string[];
+        inputSchema?: any;
+        outputSchema?: any;
+    };
+}
+/**
+ * Express middleware that protects an endpoint with x402 using USDC.
+ * Automatically declares discovery info to the Facilitator.
+ */
+export declare function synthraApiAuth(config: SynthraApiConfig): (req: Request, res: Response, next: NextFunction) => Promise<void>;

package/dist/server/index.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.synthraApiAuth = void 0;
+const express_1 = require("@x402-avm/express");
+const server_1 = require("@x402-avm/avm/exact/server");
+const extensions_1 = require("@x402-avm/extensions");
+const server_2 = require("@x402-avm/core/server");
+const avm_1 = require("@x402-avm/avm");
+// Create the shared resource server
+const server = new server_2.x402ResourceServer();
+(0, server_1.registerExactAvmScheme)(server);
+/**
+ * Express middleware that protects an endpoint with x402 using USDC.
+ * Automatically declares discovery info to the Facilitator.
+ */
+function synthraApiAuth(config) {
+    const isMainnet = config.network === "mainnet";
+    const caip2 = isMainnet ? avm_1.ALGORAND_MAINNET_CAIP2 : avm_1.ALGORAND_TESTNET_CAIP2;
+    const usdcId = isMainnet ? avm_1.USDC_MAINNET_ASA_ID : avm_1.USDC_TESTNET_ASA_ID;
+    // Convert friendly USDC amount (e.g. 0.50) to micro-USDC units (e.g. 500000)
+    // USDC has 6 decimals
+    const rawAmount = Math.floor(config.priceUsdc * 1_000_000);
+    // Prepare extensions
+    let extensions = {};
+    if (config.discovery) {
+        const discoveryConfig = {
+            ...config.discovery,
+            price: { amount: config.priceUsdc, currency: "USDC" }
+        };
+        Object.assign(extensions, (0, extensions_1.declareDiscoveryExtension)(discoveryConfig));
+    }
+    // Define a wildcard route configuration
+    const routes = {
+        "*": {
+            accepts: {
+                scheme: "exact",
+                network: caip2,
+                price: String(rawAmount),
+                asset: String(usdcId),
+                payTo: config.payTo,
+            },
+            extensions
+        }
+    };
+    return (0, express_1.paymentMiddleware)(routes, server);
+}
+exports.synthraApiAuth = synthraApiAuth;

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "synthra-x402",
+  "version": "1.0.0",
+  "description": "Synthra API SDK using x402 and Algorand USDC",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@x402-avm/avm": "^2.6.1",
+    "@x402-avm/core": "^2.6.1",
+    "@x402-avm/express": "^2.6.1",
+    "@x402-avm/extensions": "^2.6.1",
+    "@x402-avm/fetch": "^2.6.1",
+    "algosdk": "^3.5.2"
+  }
+}

package/scripts/test-agent.ts

@@ -0,0 +1,47 @@
+import algosdk from "algosdk";
+import { createSynthraClient } from "../src/client";
+import type { ClientAvmSigner } from "../src/client";
+
+async function main() {
+  console.log("Initializing Agent...");
+
+  // Normally the agent has a funded private key. For simulation, we generate one.
+  const account = algosdk.generateAccount();
+  const secretKey = account.sk;
+  const address = account.addr;
+
+  console.log("Agent Address:", address);
+
+  // Implement the ClientAvmSigner interface for the Agent
+  const agentSigner: ClientAvmSigner = {
+    address,
+    signTransactions: async (txns, indexesToSign) => {
+      return txns.map((txnBytes, i) => {
+        if (indexesToSign && !indexesToSign.includes(i)) return null;
+        const decoded = algosdk.decodeUnsignedTransaction(txnBytes);
+        return algosdk.signTransaction(decoded, secretKey).blob;
+      });
+    },
+  };
+
+  // Create the API SDK Client
+  const fetchClient = createSynthraClient({
+    signer: agentSigner,
+    network: "testnet"
+  });
+
+  console.log("Fetching paid API endpoint...");
+  try {
+    // This will intercept the 402, sign the transaction using agentSigner,
+    // get the x402 Macaroon prepaid token, and replay the request.
+    const res = await fetchClient("http://localhost:8080/api/weather-demo");
+    const data = await res.json();
+    console.log("API Response:", data);
+  } catch (error) {
+    // Note: We expect this to fail with "insufficient funds" since the generated account is empty,
+    // but the SDK flow will be fully tested.
+    console.error("Test Output:", (error as Error).message);
+  }
+}
+
+main().catch(console.error);

package/src/client/index.ts

@@ -0,0 +1,30 @@
+import { x402Client } from "@x402-avm/core/client";
+import { registerExactAvmScheme } from "@x402-avm/avm/exact/client";
+import { ALGORAND_TESTNET_CAIP2, ALGORAND_MAINNET_CAIP2, USDC_TESTNET_ASA_ID, USDC_MAINNET_ASA_ID } from "@x402-avm/avm";
+import type { ClientAvmSigner } from "@x402-avm/avm";
+
+export interface SynthraClientConfig {
+  signer: ClientAvmSigner;
+  network?: "testnet" | "mainnet";
+}
+
+/**
+ * Creates a wrapped fetch client that automatically handles x402 payments
+ * using prepaid USDC on Algorand.
+ */
+export function createSynthraClient(config: SynthraClientConfig) {
+  const isMainnet = config.network === "mainnet";
+  const caip2 = isMainnet ? ALGORAND_MAINNET_CAIP2 : ALGORAND_TESTNET_CAIP2;
+  const usdcId = isMainnet ? USDC_MAINNET_ASA_ID : USDC_TESTNET_ASA_ID;
+
+  // Initialize the base fetch client
+  const client = new x402Client();
+
+  // Register the AVM scheme
+  registerExactAvmScheme(client, { signer: config.signer });
+
+  // The x402Client has a .fetch() method that automatically handles the 402 flow
+  return client;
+}
+
+export type { ClientAvmSigner };

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './client';
+export * from './server';

package/src/server/index.ts

@@ -0,0 +1,62 @@
+import { paymentMiddleware } from "@x402-avm/express";
+import { registerExactAvmScheme } from "@x402-avm/avm/exact/server";
+import { declareDiscoveryExtension } from "@x402-avm/extensions";
+import { x402ResourceServer } from "@x402-avm/core/server";
+import { ALGORAND_TESTNET_CAIP2, ALGORAND_MAINNET_CAIP2, USDC_TESTNET_ASA_ID, USDC_MAINNET_ASA_ID } from "@x402-avm/avm";
+import type { Network } from "@x402-avm/core/types";
+
+// Create the shared resource server
+const server = new x402ResourceServer();
+registerExactAvmScheme(server);
+
+export interface SynthraApiConfig {
+  payTo: string;
+  priceUsdc: number;
+  network?: "testnet" | "mainnet";
+  discovery?: {
+    description?: string;
+    tags?: string[];
+    inputSchema?: any;
+    outputSchema?: any;
+  };
+}
+
+/**
+ * Express middleware that protects an endpoint with x402 using USDC.
+ * Automatically declares discovery info to the Facilitator.
+ */
+export function synthraApiAuth(config: SynthraApiConfig) {
+  const isMainnet = config.network === "mainnet";
+  const caip2 = isMainnet ? ALGORAND_MAINNET_CAIP2 : ALGORAND_TESTNET_CAIP2;
+  const usdcId = isMainnet ? USDC_MAINNET_ASA_ID : USDC_TESTNET_ASA_ID;
+  
+  // Convert friendly USDC amount (e.g. 0.50) to micro-USDC units (e.g. 500000)
+  // USDC has 6 decimals
+  const rawAmount = Math.floor(config.priceUsdc * 1_000_000);
+  
+  // Prepare extensions
+  let extensions: Record<string, unknown> = {};
+  if (config.discovery) {
+    const discoveryConfig = {
+      ...config.discovery,
+      price: { amount: config.priceUsdc, currency: "USDC" }
+    };
+    Object.assign(extensions, declareDiscoveryExtension(discoveryConfig));
+  }
+
+  // Define a wildcard route configuration
+  const routes = {
+    "*": {
+      accepts: {
+        scheme: "exact",
+        network: caip2 as Network,
+        price: String(rawAmount),
+        asset: String(usdcId),
+        payTo: config.payTo,
+      },
+      extensions
+    }
+  };
+
+  return paymentMiddleware(routes, server);
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"]
+}