@clawpay-hedera/sdk 0.1.0

package/README.md

@@ -0,0 +1,294 @@
+# @clawpay-hedera/sdk
+
+SDK and CLI for ClawPay — autonomous MCP micropayments for AI agents on Hedera. Enables any MCP-compatible AI agent (Claude, Cursor, ChatGPT, OpenClaw, etc.) to autonomously pay for tool calls using the x402 HTTP payment protocol with USDC on Hedera.
+
+- 🔌 Connect to multiple MCP servers at once (stdio proxy)
+- 💳 Handle 402 Payment Required automatically (x402 on Hedera)
+- 📦 Programmatic APIs for both clients and servers
+- 🦞 Hedera-native: HTS USDC payments, HCS audit trails, Blocky402 settlement
+
+## Quick Start
+
+Connect to a paid MCP server with automatic Hedera x402 payments:
+
+```bash
+npx @clawpay-hedera/sdk connect \
+  --urls "https://your-server.com/mcp" \
+  --hedera-key 0xYOUR_ECDSA_PRIVATE_KEY \
+  --hedera-account 0.0.YOUR_ACCOUNT_ID
+```
+
+This starts an MCP stdio proxy that intercepts 402 responses, creates partially-signed HTS USDC transfers, and retries with payment — all automatically.
+
+## Installation
+
+```bash
+npm i @clawpay-hedera/sdk
+# or
+pnpm i @clawpay-hedera/sdk
+```
+
+## CLI
+
+### Commands
+
+- `clawpay connect` — start an MCP stdio proxy with Hedera x402 payments
+- `clawpay version` — show version information
+
+### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-u, --urls <urls>` | Comma-separated list of MCP server URLs | Required |
+| `-a, --api-key <key>` | API key for ClawPay proxy authentication | `API_KEY` env |
+| `--hedera-key <privateKey>` | Hedera ECDSA private key (0x-prefixed) | `HEDERA_PRIVATE_KEY` env |
+| `--hedera-account <accountId>` | Hedera account ID (e.g. 0.0.6514537) | `HEDERA_ACCOUNT_ID` env |
+| `--hedera-network <network>` | `hedera-testnet` or `hedera` (mainnet) | `hedera-testnet` |
+| `--max-atomic <value>` | Max payment in atomic units (e.g. 100000 = 0.1 USDC) | `X402_MAX_ATOMIC` env |
+
+### Examples
+
+```bash
+# Direct Hedera key (recommended for agents)
+npx @clawpay-hedera/sdk connect \
+  --urls "https://your-server.com/mcp" \
+  --hedera-key 0xYOUR_ECDSA_KEY \
+  --hedera-account 0.0.1234567
+
+# Multiple servers
+npx @clawpay-hedera/sdk connect \
+  --urls "https://server1.com/mcp,https://server2.com/mcp" \
+  --hedera-key $HEDERA_PRIVATE_KEY \
+  --hedera-account $HEDERA_ACCOUNT_ID
+
+# Using API key (via ClawPay proxy)
+npx @clawpay-hedera/sdk connect \
+  --urls "https://clawpay-proxy.com/mcp" \
+  --api-key clawpay_YOUR_API_KEY
+
+# Custom max payment (500000 = 0.5 USDC)
+npx @clawpay-hedera/sdk connect \
+  --urls "https://your-server.com/mcp" \
+  --hedera-key $HEDERA_PRIVATE_KEY \
+  --hedera-account $HEDERA_ACCOUNT_ID \
+  --max-atomic 500000
+```
+
+### Behavior
+
+- With `--hedera-key`: the proxy uses x402 Payment transport — creates partially-signed HTS USDC transfers and settles via Blocky402 facilitator on Hedera.
+- With `--api-key`: the proxy forwards the key to the ClawPay proxy service, which signs payments on your behalf using your stored encrypted Hedera key.
+- Default max payment: 0.1 USDC (100000 atomic units). Override with `--max-atomic`.
+
+## MCP Client Configuration
+
+### Claude Desktop / Cursor / Windsurf
+
+Add to your MCP client config (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "hedera-tools": {
+      "command": "npx",
+      "args": [
+        "@clawpay-hedera/sdk",
+        "connect",
+        "--urls",
+        "https://your-server.com/mcp",
+        "--hedera-key",
+        "0xYOUR_ECDSA_PRIVATE_KEY",
+        "--hedera-account",
+        "0.0.YOUR_ACCOUNT_ID"
+      ]
+    }
+  }
+}
+```
+
+### Using API Key (Alternative)
+
+If you've linked your wallet on the ClawPay dashboard and created an API key:
+
+```json
+{
+  "mcpServers": {
+    "hedera-tools": {
+      "command": "npx",
+      "args": [
+        "@clawpay-hedera/sdk",
+        "connect",
+        "--urls",
+        "https://your-server.com/mcp",
+        "--api-key",
+        "clawpay_YOUR_API_KEY"
+      ]
+    }
+  }
+}
+```
+
+## SDK Usage
+
+### Client: x402 Payment Wrapper
+
+Wrap any MCP client with automatic Hedera x402 payment handling:
+
+```ts
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+import { withX402Client } from '@clawpay-hedera/sdk/client'
+
+const client = new Client(
+  { name: 'my-agent', version: '1.0.0' },
+  { capabilities: {} }
+)
+
+const transport = new StreamableHTTPClientTransport(
+  new URL('https://your-server.com/mcp')
+)
+await client.connect(transport)
+
+// Wrap with Hedera x402 payment capabilities
+const paymentClient = withX402Client(client, {
+  hederaConfig: {
+    privateKey: '0xYOUR_ECDSA_KEY',
+    network: 'testnet',
+    payerAccountId: '0.0.YOUR_ACCOUNT_ID',
+    facilitatorFeePayer: '0.0.7162784', // Blocky402
+  },
+  maxPaymentValue: BigInt(0.1 * 10 ** 6), // 0.1 USDC max
+  confirmationCallback: async () => true,  // Auto-approve payments
+})
+
+// Use tools — payments happen automatically on 402
+const tools = await paymentClient.listTools()
+const result = await paymentClient.callTool({
+  name: 'hbar_account_balance',
+  arguments: { accountId: '0.0.1234567' }
+})
+```
+
+### Server: Protecting Tools with Payments
+
+Use `createMcpPaidHandler` to add x402 paywalls to your MCP tools:
+
+```ts
+import { createMcpPaidHandler } from '@clawpay-hedera/sdk/handler'
+import { z } from 'zod'
+
+const handler = createMcpPaidHandler(
+  (server) => {
+    server.paidTool(
+      'my_tool',
+      'Description of what this tool does',
+      '$0.05',  // Price in USD (charged in USDC on Hedera)
+      { input: z.string().describe('Input parameter') },
+      { readOnlyHint: true },
+      async ({ input }) => ({
+        content: [{ type: 'text', text: `Result: ${input}` }]
+      })
+    )
+  },
+  {
+    name: 'My Paid Server',
+    version: '1.0.0',
+  },
+  {
+    recipient: '0xYOUR_EVM_ADDRESS',  // Where you receive USDC payments
+    facilitator: {
+      url: 'https://api.testnet.blocky402.com',
+    },
+  }
+)
+
+// Use with Hono, Express, or any framework
+import { Hono } from 'hono'
+const app = new Hono()
+app.all('/mcp', (c) => handler(c.req.raw))
+```
+
+### Programmatic Stdio Proxy
+
+```ts
+import { startStdioServer, ServerType } from '@clawpay-hedera/sdk'
+
+const serverConnections = [{
+  url: 'https://your-server.com/mcp',
+  serverType: ServerType.HTTPStream,
+}]
+
+await startStdioServer({
+  serverConnections,
+  x402ClientConfig: {
+    hederaConfig: {
+      privateKey: '0xYOUR_ECDSA_KEY',
+      network: 'testnet',
+      payerAccountId: '0.0.YOUR_ACCOUNT_ID',
+      facilitatorFeePayer: '0.0.7162784',
+    },
+    maxPaymentValue: BigInt(0.1 * 10 ** 6),
+    confirmationCallback: async () => true,
+  },
+})
+```
+
+## How Payment Works
+
+When an agent calls a paid tool:
+
+1. Agent sends `tools/call` request to the MCP server
+2. Server returns a 402 response with payment requirements (network, asset, amount, recipient)
+3. The SDK creates a partially-signed HTS USDC transfer on Hedera with Blocky402 as fee payer
+4. SDK retries the request with the `X-PAYMENT` header containing the signed transaction
+5. Server forwards payment to Blocky402 facilitator for verification
+6. Blocky402 co-signs, submits to Hedera, and settles the USDC transfer
+7. Agent receives the tool result
+
+The entire flow is autonomous — no human intervention needed.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `HEDERA_PRIVATE_KEY` | Hedera ECDSA private key (0x-prefixed) |
+| `HEDERA_ACCOUNT_ID` | Hedera account ID (e.g. 0.0.6514537) |
+| `HEDERA_NETWORK` | `hedera-testnet` (default) or `hedera` |
+| `API_KEY` | ClawPay API key for proxy authentication |
+| `X402_MAX_ATOMIC` | Max payment in atomic units |
+
+## Supported Network
+
+- **Hedera Testnet** (`hedera-testnet`) — USDC token `0.0.5449`
+- **Hedera Mainnet** (`hedera`) — USDC token `0.0.456858`
+
+Settlement via [Blocky402](https://blocky402.com) facilitator (account `0.0.7162784` on testnet).
+
+## Dependencies
+
+- `@modelcontextprotocol/sdk` — MCP protocol implementation
+- `@hashgraph/sdk` — Hedera SDK for HTS transfers
+- `x402` — x402 payment protocol types
+- `viem` — EVM utilities (used for Hedera EVM relay compatibility)
+- `commander` — CLI framework
+- `zod` — Schema validation
+- `mcp-handler` — MCP server handler utilities
+
+## Security
+
+- Never commit private keys. Use environment variables.
+- Use `maxPaymentValue` to cap per-transaction spend.
+- The Blocky402 facilitator only co-signs valid, pre-authorized transfers.
+- For production, consider using the ClawPay proxy with encrypted key storage instead of passing keys directly.
+
+## Development
+
+```bash
+pnpm i
+pnpm run build
+pnpm run dev  # watch mode
+```
+
+## License
+
+MIT

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}

package/dist/cli/index.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { config } from "dotenv";
+import { createWalletClient, http, defineChain } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { publicActions } from "viem";
+import packageJson from '../../package.json' with { type: 'json' };
+import { ServerType, startStdioServer } from '../server/stdio/start-stdio-server.js';
+config();
+const SUPPORTED_HEDERA_NETWORKS = ['hedera-testnet', 'hedera'];
+// Custom Hedera chain definitions for viem
+const hederaTestnet = defineChain({
+    id: 296,
+    name: 'Hedera Testnet',
+    nativeCurrency: { name: 'HBAR', symbol: 'HBAR', decimals: 18 },
+    rpcUrls: { default: { http: ['https://testnet.hashio.io/api'] } },
+    blockExplorers: { default: { name: 'HashScan', url: 'https://hashscan.io/testnet' } },
+    testnet: true,
+});
+const hederaMainnet = defineChain({
+    id: 295,
+    name: 'Hedera Mainnet',
+    nativeCurrency: { name: 'HBAR', symbol: 'HBAR', decimals: 18 },
+    rpcUrls: { default: { http: ['https://mainnet.hashio.io/api'] } },
+    blockExplorers: { default: { name: 'HashScan', url: 'https://hashscan.io/mainnet' } },
+    testnet: false,
+});
+function createHederaSigner(network, privateKey) {
+    const chain = network === 'hedera-testnet' ? hederaTestnet : hederaMainnet;
+    const account = privateKeyToAccount(privateKey);
+    return createWalletClient({ chain, transport: http(), account }).extend(publicActions);
+}
+const program = new Command();
+program
+    .name('clawpay')
+    .description('ClawPay CLI — autonomous MCP micropayments for AI agents on Hedera')
+    .version(packageJson.version);
+program
+    .command('connect')
+    .description('Start an MCP stdio proxy to remote servers with Hedera x402 payments')
+    .requiredOption('-u, --urls <urls>', 'Comma-separated list of MCP server URLs')
+    .option('-a, --api-key <key>', 'API key for authentication (env: API_KEY)')
+    .option('--max-atomic <value>', 'Max payment in atomic units (e.g. 100000 for 0.1 USDC). Env: X402_MAX_ATOMIC')
+    .option('--hedera-key <privateKey>', 'Hedera ECDSA private key (0x...) (env: HEDERA_PRIVATE_KEY)')
+    .option('--hedera-account <accountId>', 'Hedera account ID (e.g. 0.0.6514537) (env: HEDERA_ACCOUNT_ID)')
+    .option('--hedera-network <network>', 'Hedera network: hedera-testnet (default) or hedera (env: HEDERA_NETWORK)')
+    .action(async (options) => {
+    try {
+        const apiKey = options.apiKey || process.env.API_KEY;
+        const maxAtomicArg = options.maxAtomic || process.env.X402_MAX_ATOMIC;
+        const hederaKeyArg = options.hederaKey || process.env.HEDERA_PRIVATE_KEY;
+        const hederaAccountArg = options.hederaAccount || process.env.HEDERA_ACCOUNT_ID;
+        const hederaNetwork = (options.hederaNetwork || process.env.HEDERA_NETWORK || 'hedera-testnet');
+        if (!apiKey && !hederaKeyArg) {
+            console.error('Error: Provide either --api-key or --hedera-key (env: HEDERA_PRIVATE_KEY).');
+            process.exit(1);
+        }
+        if (hederaKeyArg && !SUPPORTED_HEDERA_NETWORKS.includes(hederaNetwork)) {
+            console.error(`Error: Invalid network '${hederaNetwork}'. Supported: ${SUPPORTED_HEDERA_NETWORKS.join(', ')}`);
+            process.exit(1);
+        }
+        const serverType = ServerType.HTTPStream;
+        const serverUrls = options.urls.split(',').map((url) => url.trim());
+        if (serverUrls.length === 0) {
+            console.error('Error: At least one server URL is required.');
+            process.exit(1);
+        }
+        // Determine proxy mode (API key with proxy URLs)
+        const isProxyMode = apiKey && serverUrls.some(url => url.includes('/v1/mcp') || url.includes('clawpay') || url.includes('clawpay-hedera') || url.includes('proxy'));
+        if (apiKey && !isProxyMode) {
+            console.error('Error: API key can only be used with proxy URLs. Use --hedera-key for direct x402 payments.');
+            process.exit(1);
+        }
+        const serverConnections = serverUrls.map(url => {
+            const isProxyUrl = url.includes('/v1/mcp') || url.includes('clawpay') || url.includes('clawpay-hedera') || url.includes('proxy');
+            let transportOptions = undefined;
+            if (apiKey && isProxyUrl) {
+                transportOptions = {
+                    requestInit: {
+                        credentials: 'include',
+                        headers: new Headers({ 'x-api-key': apiKey })
+                    }
+                };
+            }
+            return { url, serverType, transportOptions };
+        });
+        // X402 client config (when using Hedera key directly)
+        let x402ClientConfig = undefined;
+        if (!apiKey && hederaKeyArg) {
+            const pk = hederaKeyArg.trim();
+            if (!pk.startsWith('0x') || pk.length !== 66) {
+                console.error('Error: Invalid --hedera-key. Must be 0x-prefixed 64-hex ECDSA key.');
+                process.exit(1);
+            }
+            try {
+                const signer = createHederaSigner(hederaNetwork, pk);
+                const maybeMax = maxAtomicArg ? (() => { try {
+                    return BigInt(maxAtomicArg);
+                }
+                catch {
+                    return undefined;
+                } })() : undefined;
+                x402ClientConfig = {
+                    wallet: { evm: signer },
+                    hederaConfig: {
+                        privateKey: pk,
+                        network: hederaNetwork === 'hedera' ? 'mainnet' : 'testnet',
+                        payerAccountId: hederaAccountArg,
+                        facilitatorFeePayer: '0.0.7162784', // Blocky402 fee payer
+                    },
+                    ...(maybeMax !== undefined ? { maxPaymentValue: maybeMax } : {}),
+                    confirmationCallback: async () => true,
+                };
+            }
+            catch (error) {
+                console.error(`Error: Failed to create Hedera signer:`, error instanceof Error ? error.message : String(error));
+                process.exit(1);
+            }
+        }
+        await startStdioServer({ serverConnections, x402ClientConfig });
+    }
+    catch (error) {
+        console.error('Failed to start server:', error);
+        process.exit(1);
+    }
+});
+program
+    .command('version')
+    .description('Show version information')
+    .action(() => {
+    console.log('clawpay version ' + packageJson.version);
+});
+program.parse();
+if (!process.argv.slice(2).length) {
+    program.outputHelp();
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/client/hedera-payment.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Hedera-specific x402 payment header creation.
+ *
+ * Hedera x402 uses partially-signed HTS TokenTransfer transactions.
+ * The facilitator (Blocky402) is set as fee payer via TransactionId,
+ * then the payer partially signs. Blocky402 co-signs and submits.
+ *
+ * Key: outer payload must be { x402Version, payload: { transaction } }
+ * WITHOUT scheme/network in the outer object.
+ */
+import type { PaymentRequirements } from "x402/types";
+export interface HederaPaymentConfig {
+    privateKey: string;
+    network: 'testnet' | 'mainnet';
+    payerAccountId?: string;
+    facilitatorFeePayer?: string;
+}
+/**
+ * Create a Hedera x402 payment header (partially-signed HTS transfer).
+ *
+ * TransactionId is generated with the facilitator's account so Blocky402
+ * pays the HBAR gas fee. The payer only partially signs the token transfer.
+ */
+export declare function createHederaPaymentHeader(config: HederaPaymentConfig, paymentRequirements: PaymentRequirements): Promise<string>;
+//# sourceMappingURL=hedera-payment.d.ts.map

package/dist/client/hedera-payment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hedera-payment.d.ts","sourceRoot":"","sources":["../../src/client/hedera-payment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAQtD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,SAAS,GAAG,SAAS,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,mBAAmB,EAC3B,mBAAmB,EAAE,mBAAmB,GACvC,OAAO,CAAC,MAAM,CAAC,CAqDjB"}

package/dist/client/hedera-payment.js

@@ -0,0 +1,68 @@
+/**
+ * Hedera-specific x402 payment header creation.
+ *
+ * Hedera x402 uses partially-signed HTS TokenTransfer transactions.
+ * The facilitator (Blocky402) is set as fee payer via TransactionId,
+ * then the payer partially signs. Blocky402 co-signs and submits.
+ *
+ * Key: outer payload must be { x402Version, payload: { transaction } }
+ * WITHOUT scheme/network in the outer object.
+ */
+import { Client, TransferTransaction, AccountId, TokenId, PrivateKey, TransactionId, Timestamp, } from "@hashgraph/sdk";
+/** Convert EVM payTo address to Hedera AccountId */
+function resolvePayTo(payTo) {
+    if (payTo.startsWith("0.0."))
+        return AccountId.fromString(payTo);
+    return AccountId.fromEvmAddress(0, 0, payTo);
+}
+/**
+ * Create a Hedera x402 payment header (partially-signed HTS transfer).
+ *
+ * TransactionId is generated with the facilitator's account so Blocky402
+ * pays the HBAR gas fee. The payer only partially signs the token transfer.
+ */
+export async function createHederaPaymentHeader(config, paymentRequirements) {
+    const { privateKey: pkHex, network, payerAccountId: payerStr, facilitatorFeePayer } = config;
+    const pk = PrivateKey.fromStringECDSA(pkHex.replace(/^0x/, ''));
+    // Resolve payer account ID
+    let payerId;
+    if (payerStr) {
+        payerId = AccountId.fromString(payerStr);
+    }
+    else {
+        const evmAddress = pk.publicKey.toEvmAddress();
+        payerId = AccountId.fromEvmAddress(0, 0, evmAddress);
+    }
+    const recipientId = resolvePayTo(paymentRequirements.payTo);
+    // Convert EVM asset address to Hedera token ID
+    const tokenEntityNum = parseInt(paymentRequirements.asset.replace(/^0x/, ''), 16);
+    const tokenId = TokenId.fromString(`0.0.${tokenEntityNum}`);
+    const amount = Number(paymentRequirements.maxAmountRequired);
+    // Facilitator fee payer generates the TX ID (pays HBAR gas)
+    const feePayerAccountId = facilitatorFeePayer
+        ? AccountId.fromString(facilitatorFeePayer)
+        : payerId;
+    const client = network === 'testnet' ? Client.forTestnet() : Client.forMainnet();
+    const txId = TransactionId.withValidStart(feePayerAccountId, Timestamp.generate());
+    const tx = new TransferTransaction()
+        .addTokenTransfer(tokenId, payerId, -amount)
+        .addTokenTransfer(tokenId, recipientId, amount)
+        .setTransactionId(txId)
+        .setMaxTransactionFee(2_000_000)
+        .setTransactionValidDuration(180);
+    // Freeze and partially sign with payer's key only
+    const frozenTx = tx.freezeWith(client);
+    const signedTx = await frozenTx.sign(pk);
+    const txBytes = signedTx.toBytes();
+    // Blocky402 expects: { x402Version, payload: { transaction } }
+    // Do NOT include scheme/network in the outer object
+    const payload = {
+        x402Version: 1,
+        payload: {
+            transaction: Buffer.from(txBytes).toString('base64'),
+        },
+    };
+    client.close();
+    return Buffer.from(JSON.stringify(payload)).toString('base64');
+}
+//# sourceMappingURL=hedera-payment.js.map

package/dist/client/hedera-payment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hedera-payment.js","sourceRoot":"","sources":["../../src/client/hedera-payment.ts"],"names":[],"mappings":"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"}

package/dist/client/with-x402-client.d.ts

@@ -0,0 +1,27 @@
+import type { Client as MCPClient } from '@modelcontextprotocol/sdk/client/index.js';
+import type { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import type { CallToolRequest, CallToolResult, CallToolResultSchema, CompatibilityCallToolResultSchema } from '@modelcontextprotocol/sdk/types.js';
+import type { MultiNetworkSigner, PaymentRequirements, Network } from 'x402/types';
+import { type HederaPaymentConfig } from './hedera-payment.js';
+export interface X402AugmentedClient {
+    callTool(params: CallToolRequest["params"], resultSchema?: typeof CallToolResultSchema | typeof CompatibilityCallToolResultSchema, options?: RequestOptions): Promise<CallToolResult>;
+}
+export type X402ClientConfig = {
+    wallet: Partial<MultiNetworkSigner>;
+    maxPaymentValue?: bigint;
+    version?: number;
+    /** Hedera-specific config for native HTS payment signing */
+    hederaConfig?: HederaPaymentConfig;
+    confirmationCallback?: (payment: PaymentRequirements[]) => Promise<boolean | number | {
+        index: number;
+    } | {
+        network: Network;
+    } | {
+        requirement: PaymentRequirements;
+    }>;
+};
+/**
+ * Wraps an MCP client with X402 payment capabilities (Hedera-only)
+ */
+export declare function withX402Client<T extends MCPClient>(client: T, x402Config: X402ClientConfig): X402AugmentedClient & T;
+//# sourceMappingURL=with-x402-client.d.ts.map

package/dist/client/with-x402-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-x402-client.d.ts","sourceRoot":"","sources":["../../src/client/with-x402-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,2CAA2C,CAAC;AACrF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8CAA8C,CAAC;AACnF,OAAO,KAAK,EACR,eAAe,EACf,cAAc,EACd,oBAAoB,EACpB,iCAAiC,EACpC,MAAM,oCAAoC,CAAC;AAE5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACnF,OAAO,EAA6B,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAI1F,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CACN,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,EACjC,YAAY,CAAC,EACT,OAAO,oBAAoB,GAC3B,OAAO,iCAAiC,EAC5C,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,cAAc,CAAC,CAAC;CAC5B;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACpC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,mBAAmB,CAAC;IACnC,oBAAoB,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,EAAE,KAAK,OAAO,CAC9D,OAAO,GACP,MAAM,GACN;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GACjB;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,GACpB;QAAE,WAAW,EAAE,mBAAmB,CAAA;KAAE,CACvC,CAAC;CACH,CAAC;AAKF;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,SAAS,EAChD,MAAM,EAAE,CAAC,EACT,UAAU,EAAE,gBAAgB,GAC3B,mBAAmB,GAAG,CAAC,CA2KzB"}