Package Exports

@3mate/gas-station-sdk
@3mate/gas-station-sdk/dist/index.js
@3mate/gas-station-sdk/dist/index.mjs

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@3mate/gas-station-sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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