@3mate/gas-station-sdk

Official SDK for 3mate Gas Station - Seamless blockchain transaction sponsorship for SUI and IOTA networks.

Installation

npm install @3mate/gas-station-sdk
# or
yarn add @3mate/gas-station-sdk
# or
pnpm add @3mate/gas-station-sdk

Quick Start

SUI Transaction Sponsorship

import { suiSponsorship } from '@3mate/gas-station-sdk';
import { Transaction } from '@mysten/sui/transactions';
import { toHex, fromHex, toBase64 } from '@mysten/sui/utils';

// Build your transaction
const tx = new Transaction();
tx.setSender(userAddress);
// ... add your transaction logic

// Get transaction bytes
const transactionBytes = await tx.build({ 
  client, 
  onlyTransactionKind: true 
});

// Sponsor the transaction
try {
  const { txBytesHex, sponsorSignature } = await suiSponsorship({
    apiKey: 'your-sui-api-key',
    rawTxBytesHex: toHex(transactionBytes),
    sender: userAddress,
    network: 'testnet' // or 'mainnet'
  });
  
  // Convert for wallet signing
  const sponsoredBytes = fromHex(txBytesHex);
  
  // Sign with user wallet
  const userSignature = await wallet.signTransaction({
    transaction: toBase64(sponsoredBytes)
  });
  
  // Execute with both signatures
  await client.executeTransactionBlock({
    transactionBlock: sponsoredBytes,
    signature: [userSignature.signature, sponsorSignature]
  });
} catch (error) {
  console.error('Sponsorship failed:', error.message);
}

IOTA Transaction Sponsorship

import { iotaSponsorship } from '@3mate/gas-station-sdk';
import { toHEX, fromHEX, toB64 } from '@iota/iota-sdk/utils';

// Build your transaction
const tx = new Transaction();
tx.setSender(userAddress);
// ... add your transaction logic

const transactionBytes = await tx.build({ 
  client, 
  onlyTransactionKind: true 
});

// Sponsor the transaction
const { txBytesHex, sponsorSignature } = await iotaSponsorship({
  apiKey: 'your-iota-api-key',
  rawTxBytesHex: toHEX(transactionBytes),
  sender: userAddress,
  network: 'mainnet' // or 'testnet'
});

// Convert for wallet signing
const sponsoredBytes = fromHEX(txBytesHex);

// Sign with user wallet
const userSignature = await wallet.signTransaction({
  transaction: toB64(new Uint8Array(sponsoredBytes))
});

// Execute with both signatures
await client.executeTransactionBlock({
  transactionBlock: sponsoredBytes,
  signature: [userSignature.signature, sponsorSignature]
});

CORS Configuration

The Gas Station API requires server-side requests. For browser applications, you'll need to set up a proxy:

Development Setup

Vite

// vite.config.js
export default {
  server: {
    proxy: {
      '/api/gas-station': {
        target: 'https://gas.movevm.tools',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api\/gas-station/, '/api')
      }
    }
  }
}

Next.js

// pages/api/gas-station/[...path].js
export default async function handler(req, res) {
  const response = await fetch(
    `https://gas.movevm.tools/api/${req.query.path.join('/')}`,
    {
      method: req.method,
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': req.headers['x-api-key']
      },
      body: req.method !== 'GET' ? JSON.stringify(req.body) : undefined
    }
  );
  
  const data = await response.json();
  res.status(response.status).json(data);
}

Production Setup

For production, use server-side API routes or serverless functions to proxy requests to the Gas Station API.

Error Handling

The SDK provides detailed error messages with guidance:

import { suiSponsorship, GasStationError } from '@3mate/gas-station-sdk';

try {
  const result = await suiSponsorship({...});
} catch (error) {
  if (error instanceof GasStationError) {
    console.error('Status:', error.statusCode);
    console.error('Message:', error.message);
    console.error('Details:', error.details);
    
    // Handle specific errors
    switch (error.statusCode) {
      case 403:
        // Invalid API key or security violation
        break;
      case 400:
        // Bad request - check transaction format
        break;
      case 500:
        // Server error
        break;
    }
  }
}

API Reference

Functions

suiSponsorship(params: SponsorshipParams): Promise<SponsorshipResponse>

Sponsor a SUI transaction.

iotaSponsorship(params: SponsorshipParams): Promise<SponsorshipResponse>

Sponsor an IOTA transaction.

Types

interface SponsorshipParams {
  apiKey: string;         // Your Gas Station API key
  rawTxBytesHex: string;  // Hex encoded transaction bytes (without 0x prefix)
  sender: string;         // The sender's address
  network: 'mainnet' | 'testnet'; // Network environment
}

interface SponsorshipResponse {
  txBytesHex: string;     // Hex encoded sponsored transaction bytes
  sponsorSignature: string; // Sponsor signature
}

Requirements

• Node.js 16+ or modern browser
• Valid Gas Station API key from gas.movevm.tools

Support

• Documentation: gas.movevm.tools/docs
• Issues: GitHub Issues

License

MIT