@velumx/sdk 2.1.0 → 2.3.0

package/README.md

@@ -23,238 +23,125 @@ VelumX SDK enables gasless transactions on Stacks blockchain. Users pay transact
 npm install @velumx/sdk
 ```
 
-## Quick Start
+## Quick Start (Production Pattern)
 
-### 1. Initialize Client
+### 1. Initialize Client via Proxy
+For production dApps, initialize the client pointing to your backend proxy to keep your API key secure.
 
 ```typescript
-import { getVelumXClient } from '@velumx/sdk';
-
-const velumx = getVelumXClient();
-```
-
-### 2. Estimate Fee
+import { VelumXClient } from '@velumx/sdk';
 
-```typescript
-const estimate = await velumx.estimateFee({
-  estimatedGas: 100000
+const velumx = new VelumXClient({
+  paymasterUrl: '/api/velumx/proxy', // Your secure backend proxy
+  network: 'mainnet'
 });
-
-console.log(`Fee: ${estimate.maxFeeUSDCx} micro-USDCx`);
-// Output: Fee: 540000 micro-USDCx (0.54 USDCx)
 ```
 
-### 3. Execute Gasless Transaction
+### 2. Request Sponsorship
+Use the **`.sponsor()`** method to request gas sponsorship while reporting your custom fee for the VelumX Dashboard.
 
 ```typescript
-import { openContractCall } from '@stacks/connect';
-import { Cl } from '@stacks/transactions';
-
-// Call paymaster contract with sponsored=true
-const result = await openContractCall({
-  contractAddress: 'STKYNF473GQ1V0WWCF24TV7ZR1WYAKTC79V25E3P',
-  contractName: 'simple-paymaster-v1',
-  functionName: 'bridge-gasless',
-  functionArgs: [
-    Cl.uint(10000000),  // 10 USDCx
-    Cl.buffer(recipientBytes),
-    Cl.uint(estimate.maxFeeUSDCx),
-    Cl.principal('STKYNF473GQ1V0WWCF24TV7ZR1WYAKTC79V25E3P'),
-    Cl.principal('ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.usdcx')
-  ],
-  sponsored: true,  // Enable gasless mode
-  network: 'testnet',
-  onFinish: async (data) => {
-    // Submit to relayer for sponsorship
-    const tx = await velumx.submitRawTransaction(data.txRaw);
-    console.log(`Transaction: ${tx.txid}`);
-  }
+// Report your dApp's specific fee and a unique user ID for tracking
+const result = await velumx.sponsor(txRaw, {
+  feeAmount: '250000', // 0.25 USDCx (6 decimals)
+  userId: 'user_12345'
 });
-```
-
-## How It Works
-
-### Architecture
-
-```
-┌──────────┐                                      ┌──────────┐
-│   User   │                                      │ Relayer  │
-└────┬─────┘                                      └────┬─────┘
-     │                                                  │
-     │ 1. Request fee estimate                         │
-     ├──────────────────────────────────────────────►  │
-     │                                                  │
-     │ 2. Return fee in USDCx                          │
-     │ ◄──────────────────────────────────────────────┤
-     │                                                  │
-     │ 3. Sign transaction (sponsored=true)            │
-     │                                                  │
-     │ 4. Submit signed transaction                    │
-     ├──────────────────────────────────────────────►  │
-     │                                                  │
-     │                                                  │ 5. Sponsor with STX
-     │                                                  │    & broadcast
-     │                                                  │
-     │ 6. Return transaction ID                        │
-     │ ◄──────────────────────────────────────────────┤
-     │                                                  │
-     ▼                                                  ▼
-
-┌─────────────────────────────────────────────────────┐
-│              Stacks Blockchain                       │
-│                                                      │
-│  simple-paymaster-v1::bridge-gasless                │
-│  • Transfer USDCx fee from user to relayer          │
-│  • Execute core logic (burn/swap)                   │
-│  • Transaction confirmed ✓                          │
-└─────────────────────────────────────────────────────┘
-```
-
-### Fee Calculation
 
-```
-Fee in any SIP-010 token = (Gas Cost in STX × STX/USD Rate × 1.08) / Token/USD Rate
-
-Example with USDCx:
-- Gas: 100,000 units = 1 STX
-- STX/USD: $0.50
-- USDC/USD: $1.00
-- Markup: 8%
-- Fee: 1 × $0.50 × 1.08 / $1.00 = 0.54 USDCx
-
-Example with sBTC:
-- Gas: 100,000 units = 1 STX
-- STX/USD: $0.50
-- BTC/USD: $45,000
-- Markup: 8%
-- Fee: 1 × $0.50 × 1.08 / $45,000 = 0.000012 BTC (1,200 sats)
-
-Example with ALEX:
-- Gas: 100,000 units = 1 STX
-- STX/USD: $0.50
-- ALEX/USD: $0.10
-- Markup: 8%
-- Fee: 1 × $0.50 × 1.08 / $0.10 = 5.4 ALEX
+console.log(`Transaction Sponsored: ${result.txid}`);
 ```
 
-## API Reference
+## Security Best Practice: The Proxy Pattern
 
-### VelumXClient
-
-#### Configuration
+**NEVER** expose your `VELUMX_API_KEY` in the browser. Instead, create a simple backend route that injects the key and forwards the request to the VelumX Relayer.
 
+### Example Next.js Proxy Route
 ```typescript
-interface NetworkConfig {
-  coreApiUrl: string;      // Stacks API URL
-  network: 'mainnet' | 'testnet' | 'devnet';
-  paymasterUrl?: string;   // Relayer URL (optional)
-}
-```
+// app/api/velumx/proxy/[...path]/route.ts
+export async function POST(req: Request, { params }) {
+  const { path } = params;
+  const apiKey = process.env.VELUMX_API_KEY; // Securely stored on server
+  const targetUrl = `https://relayer.velumx.com/api/v1/${path.join('/')}`;
+
+  const body = await req.json();
+  const response = await fetch(targetUrl, {
+    method: 'POST',
+    headers: { 
+      'Content-Type': 'application/json',
+      'x-api-key': apiKey 
+    },
+    body: JSON.stringify(body),
+  });
 
-**Default Configuration**:
-```typescript
-{
-  coreApiUrl: 'https://api.testnet.hiro.so',
-  network: 'testnet',
-  paymasterUrl: 'https://sgal-relayer.onrender.com/api/v1'
+  return Response.json(await response.json());
 }
 ```
 
-#### Methods
+## API Reference
 
-##### estimateFee()
+### VelumXClient
 
-Get fee estimate in USDCx for a transaction.
+#### Methods
 
-```typescript
-estimateFee(params: {
-  estimatedGas: number
-}): Promise<FeeEstimate>
-```
+##### `.sponsor(txHex, options)`
+The recommended method for Stacks-native sponsorship.
 
-**Parameters**:
-- `estimatedGas`: Estimated gas units (e.g., 100000)
+- `txHex`: The raw hex string of the signed transaction.
+- `options`:
+    - `feeAmount`: (Optional) The specific fee collected by your contract (e.g., "250000").
+    - `userId`: (Optional) A unique identifier for your user to enable multi-tenant wallet tracking.
 
-**Returns**:
-```typescript
-interface FeeEstimate {
-  maxFeeUSDCx: string;    // Fee in micro-USDCx
-  estimatedGas: number;    // Gas units
-  stxToUsd?: number;       // Exchange rate
-  markup?: number;         // Fee markup (0.08 = 8%)
-}
-```
+##### `.estimateFee(intent)`
+Get a real-time USDCx fee estimation for a transaction intent.
+- `intent`: The transaction details (target, function, args).
 
-**Example**:
-```typescript
-const estimate = await velumx.estimateFee({
-  estimatedGas: 100000
-});
+##### `.submitIntent(signedIntent)`
+Submit a SIP-018 signed intent for legacy smart-wallet sponsorship.
 
-console.log(`Fee: ${estimate.maxFeeUSDCx} micro-USDCx`);
-// Fee: 540000 micro-USDCx (0.54 USDCx)
-```
+## Use Cases
 
-##### submitRawTransaction()
+### 1. Gasless Token Transfer (New in v2.3.0)
 
-Submit a signed transaction for sponsorship.
+Transfer any SIP-010 token (like USDCx) between wallets without needing STX.
 
 ```typescript
-submitRawTransaction(txRaw: string): Promise<TransactionResult>
-```
-
-**Parameters**:
-- `txRaw`: Hex-encoded signed transaction from wallet
+import { getVelumXClient } from '@velumx/sdk';
 
-**Returns**:
-```typescript
-interface TransactionResult {
-  txid: string;           // Transaction ID
-  status: string;         // Status (pending/success/failed)
+async function sendTokens(token: string, amount: string, recipient: string) {
+  const velumx = getVelumXClient();
+  
+  // 1. Estimate fee
+  const estimate = await velumx.estimateFee({ estimatedGas: 100000 });
+  
+  // 2. Perform gasless transfer
+  await velumx.transferGasless({
+    token: 'SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx',
+    amount: '10000000', // 10 USDCx
+    recipient: 'SP123...', 
+    feeUsdcx: estimate.maxFeeUSDCx,
+    onFinish: (data) => console.log(`Transfer TX: ${data.txid}`)
+  });
 }
 ```
 
-**Example**:
-```typescript
-const result = await velumx.submitRawTransaction(data.txRaw);
-console.log(`Transaction ID: ${result.txid}`);
-```
-
-##### sponsorTransaction()
+### 2. Universal Gasless Action (New in v2.3.0)
 
-High-level helper to make any transaction gasless.
+Make any contract call gasless by using the Universal Executor trait.
 
 ```typescript
-sponsorTransaction(params: {
-  transaction: any;
-  network: 'mainnet' | 'testnet';
-}): Promise<any>
-```
-
-**Parameters**:
-- `transaction`: Unsigned Stacks transaction
-- `network`: Target network
-
-**Returns**: Transaction with `sponsored: true` flag
-
-**Example**:
-```typescript
-import { makeContractCall } from '@stacks/transactions';
-
-const unsignedTx = await makeContractCall({...});
-
-const sponsored = await velumx.sponsorTransaction({
-  transaction: unsignedTx,
-  network: 'testnet'
-});
-
-// User signs and broadcasts
-const result = await openContractCall(sponsored);
+async function callDeFiProtocol() {
+  const velumx = getVelumXClient();
+  
+  await velumx.executeGasless({
+    target: 'SP...YOUR_PROTOCOL_CONTRACT',
+    actionId: '0x...', // Hex hash of the intended action
+    param: '100', // Numeric parameter
+    feeUsdcx: '250000',
+    onFinish: (data) => console.log(`Action TX: ${data.txid}`)
+  });
+}
 ```
 
-## Use Cases
-
-### 1. Gasless Bridge
+### 3. Gasless Bridge
 
 Bridge USDC from Ethereum to Stacks without needing STX.
 
@@ -277,18 +164,18 @@ async function gaslessBridge(amount: string, recipient: string) {
   
   // 3. Execute gasless bridge
   const result = await openContractCall({
-    contractAddress: 'STKYNF473GQ1V0WWCF24TV7ZR1WYAKTC79V25E3P',
+    contractAddress: 'SPKYNF473GQ1V0WWCF24TV7ZR1WYAKTC7AM8QGBW',
     contractName: 'simple-paymaster-v1',
     functionName: 'bridge-gasless',
     functionArgs: [
       Cl.uint(parseUnits(amount, 6)),
       Cl.buffer(recipientBytes),
       Cl.uint(estimate.maxFeeUSDCx),
-      Cl.principal('STKYNF473GQ1V0WWCF24TV7ZR1WYAKTC79V25E3P'),
-      Cl.principal('ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.usdcx')
+      Cl.principal('SPKYNF473GQ1V0WWCF24TV7ZR1WYAKTC7AM8QGBW'),
+      Cl.principal('SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx')
     ],
     sponsored: true,
-    network: 'testnet',
+    network: 'mainnet',
     onFinish: async (data) => {
       const tx = await velumx.submitRawTransaction(data.txRaw);
       console.log(`Bridge transaction: ${tx.txid}`);
@@ -328,7 +215,7 @@ async function gaslessSwap(
   
   // 2. Execute gasless swap
   const result = await openContractCall({
-    contractAddress: 'STKYNF473GQ1V0WWCF24TV7ZR1WYAKTC79V25E3P',
+    contractAddress: 'SPKYNF473GQ1V0WWCF24TV7ZR1WYAKTC7AM8QGBW',
     contractName: 'simple-paymaster-v1',
     functionName: 'swap-gasless',
     functionArgs: [
@@ -337,11 +224,11 @@ async function gaslessSwap(
       Cl.uint(parseUnits(amountIn, 6)),
       Cl.uint(parseUnits(minOut, 6)),
       Cl.uint(estimate.maxFeeUSDCx),
-      Cl.principal('STKYNF473GQ1V0WWCF24TV7ZR1WYAKTC79V25E3P'),
-      Cl.principal('ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.usdcx')
+      Cl.principal('SPKYNF473GQ1V0WWCF24TV7ZR1WYAKTC7AM8QGBW'),
+      Cl.principal('SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx')
     ],
     sponsored: true,
-    network: 'testnet',
+    network: 'mainnet',
     onFinish: async (data) => {
       const tx = await velumx.submitRawTransaction(data.txRaw);
       console.log(`Swap transaction: ${tx.txid}`);
@@ -374,7 +261,7 @@ async function customGaslessTransaction() {
       // More args...
     ],
     sponsored: true,  // Enable gasless
-    network: 'testnet',
+    network: 'mainnet',
     onFinish: async (data) => {
       const tx = await velumx.submitRawTransaction(data.txRaw);
       console.log(`Transaction: ${tx.txid}`);
@@ -401,18 +288,18 @@ async function gaslessWithSBTC(amount: string) {
   
   // 3. Execute with sBTC as fee token
   const result = await openContractCall({
-    contractAddress: 'STKYNF473GQ1V0WWCF24TV7ZR1WYAKTC79V25E3P',
+    contractAddress: 'SPKYNF473GQ1V0WWCF24TV7ZR1WYAKTC7AM8QGBW',
     contractName: 'simple-paymaster-v1',
     functionName: 'bridge-gasless',
     functionArgs: [
       Cl.uint(parseUnits(amount, 6)),
       Cl.buffer(recipientBytes),
       Cl.uint(feeInSBTC),  // Fee in sBTC
-      Cl.principal('STKYNF473GQ1V0WWCF24TV7ZR1WYAKTC79V25E3P'),
+      Cl.principal('SPKYNF473GQ1V0WWCF24TV7ZR1WYAKTC7AM8QGBW'),
       Cl.principal('SM3KNVZS30WM7F89SXKVVFY4SN9RMPZZ9FX929N0V.sbtc')  // sBTC token
     ],
     sponsored: true,
-    network: 'testnet',
+    network: 'mainnet',
     onFinish: async (data) => {
       const tx = await velumx.submitRawTransaction(data.txRaw);
       console.log(`Transaction: ${tx.txid}`);
@@ -442,18 +329,18 @@ async function gaslessWithALEX(amount: string) {
   const feeInALEX = convertToALEX(estimate.maxFeeUSDCx);
   
   const result = await openContractCall({
-    contractAddress: 'STKYNF473GQ1V0WWCF24TV7ZR1WYAKTC79V25E3P',
+    contractAddress: 'SPKYNF473GQ1V0WWCF24TV7ZR1WYAKTC7AM8QGBW',
     contractName: 'simple-paymaster-v1',
     functionName: 'bridge-gasless',
     functionArgs: [
       Cl.uint(parseUnits(amount, 6)),
       Cl.buffer(recipientBytes),
       Cl.uint(feeInALEX),  // Fee in ALEX
-      Cl.principal('STKYNF473GQ1V0WWCF24TV7ZR1WYAKTC79V25E3P'),
+      Cl.principal('SPKYNF473GQ1V0WWCF24TV7ZR1WYAKTC7AM8QGBW'),
       Cl.principal('ALEX_TOKEN_ADDRESS')  // ALEX token
     ],
     sponsored: true,
-    network: 'testnet',
+    network: 'mainnet',
     onFinish: async (data) => {
       const tx = await velumx.submitRawTransaction(data.txRaw);
       console.log(`Transaction: ${tx.txid}`);
@@ -495,7 +382,7 @@ VelumX accepts ANY SIP-010 token for gas fees. The paymaster contract uses the `
 
 | Token | Contract Address | Decimals | Use Case |
 |-------|-----------------|----------|----------|
-| USDCx | `ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.usdcx` | 6 | Stablecoin fees |
+| USDCx | `SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx` | 6 | Stablecoin fees |
 | sBTC | `SM3KNVZS30WM7F89SXKVVFY4SN9RMPZZ9FX929N0V.sbtc` | 8 | Bitcoin fees |
 | ALEX | `ALEX_TOKEN_ADDRESS` | 6 | DeFi token fees |
 | STX | Native | 6 | Native token fees |
@@ -540,13 +427,13 @@ const feeInSBTC = await calculateFeeInToken(estimate.maxFeeUSDCx, 'sBTC');
 
 ```bash
 # Frontend (.env.local)
-NEXT_PUBLIC_STACKS_NETWORK=testnet
-NEXT_PUBLIC_STACKS_API_URL=https://api.testnet.hiro.so
-NEXT_PUBLIC_VELUMX_RELAYER_URL=https://sgal-relayer.onrender.com/api/v1
+NEXT_PUBLIC_STACKS_NETWORK=mainnet
+NEXT_PUBLIC_STACKS_API_URL=https://api.mainnet.hiro.so
+NEXT_PUBLIC_VELUMX_RELAYER_URL=https://your-relayer-proxy.com
 
 # Contracts
-NEXT_PUBLIC_STACKS_PAYMASTER_ADDRESS=STKYNF473GQ1V0WWCF24TV7ZR1WYAKTC79V25E3P.simple-paymaster-v1
-NEXT_PUBLIC_STACKS_USDCX_ADDRESS=ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.usdcx
+NEXT_PUBLIC_STACKS_PAYMASTER_ADDRESS=SP...YOUR_PAYMASTER_ADDRESS
+NEXT_PUBLIC_STACKS_USDCX_ADDRESS=SP...YOUR_USDCX_ADDRESS
 ```
 
 ### Network Configuration
@@ -635,14 +522,14 @@ describe('VelumX SDK', () => {
 
 **Simple Paymaster**
 ```
-Address: STKYNF473GQ1V0WWCF24TV7ZR1WYAKTC79V25E3P.simple-paymaster-v1
-Network: Stacks Testnet
-Explorer: https://explorer.hiro.so/txid/0x90c134205b04599405e3cccae6c86ed496ae2d81ef0392970e2c9a7acd3b2138?chain=testnet
+Address: SPKYNF473GQ1V0WWCF24TV7ZR1WYAKTC7AM8QGBW.simple-paymaster-v1
+Network: Stacks Mainnet
+Explorer: https://explorer.hiro.so/txid/[TRANSACTION_ID]?chain=mainnet
 ```
 
 **USDCx Token**
 ```
-Address: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.usdcx
+Address: SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx
 Standard: SIP-010
 Decimals: 6
 ```
@@ -671,7 +558,7 @@ Status: https://sgal-relayer.onrender.com/api/v1/health
 **A:** Any Stacks wallet (Xverse, Leather, Hiro) that supports sponsored transactions.
 
 ### Q: Can I use this in production?
-**A:** Currently on testnet. Mainnet launch pending security audit.
+**A:** Yes! VelumX is fully functional on Stacks Mainnet.
 
 ### Q: How do I get an API key?
 **A:** Visit [https://velum-x-ssum.vercel.app](https://velum-x-ssum.vercel.app) to sign up and generate API keys.

package/dist/SimplePaymaster.d.ts

@@ -24,6 +24,22 @@ export interface SwapParams {
     onFinish?: (data: any) => void;
     onCancel?: () => void;
 }
+export interface TransferParams {
+    token: string;
+    amount: string;
+    recipient: string;
+    feeUsdcx: string;
+    onFinish?: (data: any) => void;
+    onCancel?: () => void;
+}
+export interface ExecuteParams {
+    target: string;
+    actionId: string;
+    param: string;
+    feeUsdcx: string;
+    onFinish?: (data: any) => void;
+    onCancel?: () => void;
+}
 export declare class SimplePaymaster {
     private config;
     constructor(config: SimplePaymasterConfig);
@@ -35,6 +51,14 @@ export declare class SimplePaymaster {
      * Execute gasless swap
      */
     swapGasless(params: SwapParams): Promise<void>;
+    /**
+     * Execute gasless token transfer
+     */
+    transferGasless(params: TransferParams): Promise<void>;
+    /**
+     * Execute universal gasless action
+     */
+    executeGasless(params: ExecuteParams): Promise<void>;
     /**
      * Estimate fee for gasless transaction
      */

package/dist/SimplePaymaster.js

@@ -63,6 +63,58 @@ class SimplePaymaster {
             onCancel: params.onCancel || (() => { }),
         });
     }
+    /**
+     * Execute gasless token transfer
+     */
+    async transferGasless(params) {
+        const [contractAddress, contractName] = this.config.paymasterContract.split('.');
+        const [tokenAddress, tokenName] = params.token.split('.');
+        const functionArgs = [
+            (0, transactions_1.contractPrincipalCV)(tokenAddress, tokenName),
+            (0, transactions_1.uintCV)(params.amount),
+            (0, transactions_1.principalCV)(params.recipient),
+            (0, transactions_1.uintCV)(params.feeUsdcx),
+            (0, transactions_1.principalCV)(this.config.relayerAddress),
+            (0, transactions_1.contractPrincipalCV)(this.config.usdcxContract.split('.')[0], this.config.usdcxContract.split('.')[1])
+        ];
+        await (0, connect_1.openContractCall)({
+            contractAddress,
+            contractName,
+            functionName: 'transfer-gasless',
+            functionArgs,
+            network: this.config.network,
+            sponsored: true,
+            postConditionMode: transactions_1.PostConditionMode.Allow,
+            onFinish: params.onFinish || (() => { }),
+            onCancel: params.onCancel || (() => { }),
+        });
+    }
+    /**
+     * Execute universal gasless action
+     */
+    async executeGasless(params) {
+        const [contractAddress, contractName] = this.config.paymasterContract.split('.');
+        const [targetAddress, targetName] = params.target.split('.');
+        const functionArgs = [
+            (0, transactions_1.contractPrincipalCV)(targetAddress, targetName),
+            (0, transactions_1.bufferCV)(Buffer.from(params.actionId.replace(/^0x/, ''), 'hex')),
+            (0, transactions_1.uintCV)(params.param),
+            (0, transactions_1.uintCV)(params.feeUsdcx),
+            (0, transactions_1.principalCV)(this.config.relayerAddress),
+            (0, transactions_1.contractPrincipalCV)(this.config.usdcxContract.split('.')[0], this.config.usdcxContract.split('.')[1])
+        ];
+        await (0, connect_1.openContractCall)({
+            contractAddress,
+            contractName,
+            functionName: 'execute-gasless',
+            functionArgs,
+            network: this.config.network,
+            sponsored: true,
+            postConditionMode: transactions_1.PostConditionMode.Allow,
+            onFinish: params.onFinish || (() => { }),
+            onCancel: params.onCancel || (() => { }),
+        });
+    }
     /**
      * Estimate fee for gasless transaction
      */

package/dist/VelumXClient.d.ts

@@ -1,10 +1,10 @@
-import { SignedIntent, NetworkConfig } from './types';
+import { SignedIntent, NetworkConfig, SponsorshipOptions } from './types';
 export declare class VelumXClient {
     private config;
     private relayerUrl;
     constructor(config: NetworkConfig);
     /**
-     * Get a fee estimation from the SGAL relayer for a specific intent
+     * Get a fee estimation from the relayer for a specific intent
      */
     estimateFee(intent: any): Promise<{
         maxFeeUSDCx: string;
@@ -17,10 +17,19 @@ export declare class VelumXClient {
         txid: string;
         status: string;
     }>;
+    /**
+     * [New Recommended Method] Request sponsorship for a Stacks transaction
+     * @param txHex The raw transaction hex
+     * @param options Metadata like developer-reported fee and userId
+     */
+    sponsor(txHex: string, options?: SponsorshipOptions): Promise<{
+        txid: string;
+        status: string;
+    }>;
     /**
      * Submit a raw Stacks transaction hex for native sponsorship
      */
-    submitRawTransaction(txHex: string): Promise<{
+    submitRawTransaction(txHex: string, options?: SponsorshipOptions): Promise<{
         txid: string;
         status: string;
     }>;

package/dist/VelumXClient.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VelumXClient = void 0;
 class VelumXClient {
     constructor(config) {
-        if (!config.apiKey) {
+        if (!config.apiKey && !config.paymasterUrl?.includes('/api/velumx/proxy')) {
             throw new Error("VelumX Client Error: API Key is required. Please obtain your key from the VelumX Developer Dashboard.");
         }
         this.config = config;
@@ -11,12 +11,12 @@ class VelumXClient {
         this.relayerUrl = config.paymasterUrl || 'https://relayer.velumx.com/api/v1';
     }
     /**
-     * Get a fee estimation from the SGAL relayer for a specific intent
+     * Get a fee estimation from the relayer for a specific intent
      */
     async estimateFee(intent) {
         try {
             const headers = { 'Content-Type': 'application/json' };
-            if (this.config.apiKey) {
+            if (this.config.apiKey && this.config.apiKey !== 'proxied') {
                 headers['x-api-key'] = this.config.apiKey;
             }
             const response = await fetch(`${this.relayerUrl}/estimate`, {
@@ -41,7 +41,7 @@ class VelumXClient {
     async submitIntent(signedIntent) {
         try {
             const headers = { 'Content-Type': 'application/json' };
-            if (this.config.apiKey) {
+            if (this.config.apiKey && this.config.apiKey !== 'proxied') {
                 headers['x-api-key'] = this.config.apiKey;
             }
             const response = await fetch(`${this.relayerUrl}/sponsor`, {
@@ -60,19 +60,31 @@ class VelumXClient {
             throw error;
         }
     }
+    /**
+     * [New Recommended Method] Request sponsorship for a Stacks transaction
+     * @param txHex The raw transaction hex
+     * @param options Metadata like developer-reported fee and userId
+     */
+    async sponsor(txHex, options) {
+        return this.submitRawTransaction(txHex, options);
+    }
     /**
      * Submit a raw Stacks transaction hex for native sponsorship
      */
-    async submitRawTransaction(txHex) {
+    async submitRawTransaction(txHex, options) {
         try {
             const headers = { 'Content-Type': 'application/json' };
-            if (this.config.apiKey) {
+            if (this.config.apiKey && this.config.apiKey !== 'proxied') {
                 headers['x-api-key'] = this.config.apiKey;
             }
             const response = await fetch(`${this.relayerUrl}/broadcast`, {
                 method: 'POST',
                 headers,
-                body: JSON.stringify({ txHex })
+                body: JSON.stringify({
+                    txHex,
+                    userId: options?.userId,
+                    feeAmount: options?.feeAmount
+                })
             });
             if (!response.ok) {
                 const errData = await response.json().catch(() => ({ error: 'Unknown error' }));

package/dist/types.d.ts

@@ -14,3 +14,7 @@ export interface NetworkConfig {
     paymasterUrl?: string;
     apiKey?: string;
 }
+export interface SponsorshipOptions {
+    userId?: string;
+    feeAmount?: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velumx/sdk",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "VelumX Gas Abstraction Layer SDK for dApps",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/SimplePaymaster.ts

@@ -38,6 +38,24 @@ export interface SwapParams {
     onCancel?: () => void;
 }
 
+export interface TransferParams {
+    token: string; // Contract principal of token to transfer (e.g. 'SP...usdcx')
+    amount: string; // Amount in micro units
+    recipient: string; // Stacks address
+    feeUsdcx: string; // Fee in micro units
+    onFinish?: (data: any) => void;
+    onCancel?: () => void;
+}
+
+export interface ExecuteParams {
+    target: string; // Contract principal implementing executor-trait-v1
+    actionId: string; // 32-byte hex string (e.g., hash of action)
+    param: string; // Numeric parameter for the action
+    feeUsdcx: string; // Fee in micro units
+    onFinish?: (data: any) => void;
+    onCancel?: () => void;
+}
+
 export class SimplePaymaster {
     private config: SimplePaymasterConfig;
 
@@ -104,6 +122,64 @@ export class SimplePaymaster {
         });
     }
 
+    /**
+     * Execute gasless token transfer
+     */
+    async transferGasless(params: TransferParams): Promise<void> {
+        const [contractAddress, contractName] = this.config.paymasterContract.split('.');
+        const [tokenAddress, tokenName] = params.token.split('.');
+
+        const functionArgs: ClarityValue[] = [
+            contractPrincipalCV(tokenAddress, tokenName),
+            uintCV(params.amount),
+            principalCV(params.recipient),
+            uintCV(params.feeUsdcx),
+            principalCV(this.config.relayerAddress),
+            contractPrincipalCV(this.config.usdcxContract.split('.')[0], this.config.usdcxContract.split('.')[1])
+        ];
+
+        await openContractCall({
+            contractAddress,
+            contractName,
+            functionName: 'transfer-gasless',
+            functionArgs,
+            network: this.config.network,
+            sponsored: true,
+            postConditionMode: PostConditionMode.Allow,
+            onFinish: params.onFinish || (() => {}),
+            onCancel: params.onCancel || (() => {}),
+        });
+    }
+
+    /**
+     * Execute universal gasless action
+     */
+    async executeGasless(params: ExecuteParams): Promise<void> {
+        const [contractAddress, contractName] = this.config.paymasterContract.split('.');
+        const [targetAddress, targetName] = params.target.split('.');
+
+        const functionArgs: ClarityValue[] = [
+            contractPrincipalCV(targetAddress, targetName),
+            bufferCV(Buffer.from(params.actionId.replace(/^0x/, ''), 'hex')),
+            uintCV(params.param),
+            uintCV(params.feeUsdcx),
+            principalCV(this.config.relayerAddress),
+            contractPrincipalCV(this.config.usdcxContract.split('.')[0], this.config.usdcxContract.split('.')[1])
+        ];
+
+        await openContractCall({
+            contractAddress,
+            contractName,
+            functionName: 'execute-gasless',
+            functionArgs,
+            network: this.config.network,
+            sponsored: true,
+            postConditionMode: PostConditionMode.Allow,
+            onFinish: params.onFinish || (() => {}),
+            onCancel: params.onCancel || (() => {}),
+        });
+    }
+
     /**
      * Estimate fee for gasless transaction
      */

package/src/VelumXClient.ts

@@ -1,11 +1,11 @@
-import { SignedIntent, NetworkConfig } from './types';
+import { SignedIntent, NetworkConfig, SponsorshipOptions } from './types';
 
 export class VelumXClient {
     private config: NetworkConfig;
     private relayerUrl: string;
 
     constructor(config: NetworkConfig) {
-        if (!config.apiKey) {
+        if (!config.apiKey && !config.paymasterUrl?.includes('/api/velumx/proxy')) {
             throw new Error("VelumX Client Error: API Key is required. Please obtain your key from the VelumX Developer Dashboard.");
         }
         this.config = config;
@@ -14,12 +14,12 @@ export class VelumXClient {
     }
 
     /**
-     * Get a fee estimation from the SGAL relayer for a specific intent
+     * Get a fee estimation from the relayer for a specific intent
      */
     public async estimateFee(intent: any): Promise<{ maxFeeUSDCx: string, estimatedGas: number }> {
         try {
             const headers: Record<string, string> = { 'Content-Type': 'application/json' };
-            if (this.config.apiKey) {
+            if (this.config.apiKey && this.config.apiKey !== 'proxied') {
                 headers['x-api-key'] = this.config.apiKey;
             }
 
@@ -47,7 +47,7 @@ export class VelumXClient {
     public async submitIntent(signedIntent: SignedIntent): Promise<{ txid: string, status: string }> {
         try {
             const headers: Record<string, string> = { 'Content-Type': 'application/json' };
-            if (this.config.apiKey) {
+            if (this.config.apiKey && this.config.apiKey !== 'proxied') {
                 headers['x-api-key'] = this.config.apiKey;
             }
 
@@ -69,20 +69,33 @@ export class VelumXClient {
         }
     }
 
+    /**
+     * [New Recommended Method] Request sponsorship for a Stacks transaction
+     * @param txHex The raw transaction hex
+     * @param options Metadata like developer-reported fee and userId
+     */
+    public async sponsor(txHex: string, options?: SponsorshipOptions): Promise<{ txid: string, status: string }> {
+        return this.submitRawTransaction(txHex, options);
+    }
+
     /**
      * Submit a raw Stacks transaction hex for native sponsorship
      */
-    public async submitRawTransaction(txHex: string): Promise<{ txid: string, status: string }> {
+    public async submitRawTransaction(txHex: string, options?: SponsorshipOptions): Promise<{ txid: string, status: string }> {
         try {
             const headers: Record<string, string> = { 'Content-Type': 'application/json' };
-            if (this.config.apiKey) {
+            if (this.config.apiKey && this.config.apiKey !== 'proxied') {
                 headers['x-api-key'] = this.config.apiKey;
             }
 
             const response = await fetch(`${this.relayerUrl}/broadcast`, {
                 method: 'POST',
                 headers,
-                body: JSON.stringify({ txHex })
+                body: JSON.stringify({ 
+                    txHex,
+                    userId: options?.userId,
+                    feeAmount: options?.feeAmount
+                })
             });
 
             if (!response.ok) {

package/src/types.ts

@@ -15,6 +15,11 @@ export interface SignedIntent extends WalletIntent {
 export interface NetworkConfig {
     coreApiUrl: string;
     network: 'mainnet' | 'testnet' | 'devnet';
-    paymasterUrl?: string; // URL for the SGAL relayer service
-    apiKey?: string; // SGAL API Key
+    paymasterUrl?: string; // URL for the VelumX relayer service
+    apiKey?: string; // VelumX API Key
+}
+
+export interface SponsorshipOptions {
+    userId?: string;
+    feeAmount?: string;
 }