spur-client - v0.5.1

Client to access the Spur API.

Start with fetching a quote using SpurClient.quote and execute a swap using SpurClient.swapInteractive in the browser using a Solana Wallet Adapter or SpurClient.swapNonInteractive in a server or cli application using a Keypair.

Installation

npm install spur-client
Copy

Quick Start

Browser with Wallet Adapter

import { SpurClient } from 'spur-client';
import { Connection } from '@solana/web3.js';
import { useWallet } from '@solana/wallet-adapter-react';

const client = new SpurClient('your-wallet-public-key');
const connection = new Connection('https://api.mainnet-beta.solana.com');
const { wallet } = useWallet();

// Get a quote
const quote = await client.quote(
  BigInt(1000000), // 1 USDC (6 decimals)
  'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC mint
  'So11111111111111111111111111111111111111112'  // SOL mint
);

// Execute swap
const signature = await client.swapInteractive(
  connection,
  quote,
  wallet.adapter,
  0.01 // 1% slippage
);

console.log('Swap completed:', signature);
Copy

Server/CLI with Keypair

import { SpurClient } from 'spur-client';
import { Connection, Keypair } from '@solana/web3.js';
import fs from 'fs';

// Load keypair
const secretKey = JSON.parse(fs.readFileSync('keypair.json', 'utf8'));
const keypair = Keypair.fromSecretKey(Uint8Array.from(secretKey));

const client = new SpurClient(keypair.publicKey.toString());
const connection = new Connection('https://api.mainnet-beta.solana.com');

// Get quote and execute swap
const quote = await client.quote(
  BigInt(1000000000), // 1 SOL (9 decimals)
  'So11111111111111111111111111111111111111112', // SOL
  'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'  // USDC
);

const signature = await client.swapNonInteractive(
  connection,
  quote,
  keypair,
  0.005 // 0.5% slippage
);

console.log('Swap completed:', signature);
Copy

API Overview

SpurClient

// Initialize client
const client = new SpurClient(payerPublicKey?: string);

// Get swap quote
const quote = await client.quote(inputAmount, inputMint, outputMint, limits?);

// Get priority fees
const priorityLamports = await client.getPriorityLamports("medium"); // "high" | "medium" | "low"

// Execute swap with wallet adapter
const signature = await client.swapInteractive(connection, quote, wallet, slippage, priorityLamports?);

// Execute swap with keypair
const signature = await client.swapNonInteractive(connection, quote, signer, slippage, priorityLamports?);

// Advanced: compile transaction without executing
const compiledSwap = await client.compileSwap(connection, quote, slippage, priorityLamports?, blockhash?);

Copy

Common Token Mints

const USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
const SOL = 'So11111111111111111111111111111111111111112';
const USDT = 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB';
Copy

Advanced Usage

Custom Transaction Handling

// Compile swap for custom handling
const swap = await client.compileSwap(connection, quote, 0.01);

// Sign transaction
await swap.signInteractive(wallet); // or swap.signNonInteractive(keypair)

// Send and confirm
const signature = await swap.sendTransaction(connection);
const error = await swap.confirmTransaction(connection);

if (error) {
  console.error('Transaction failed:', error);
} else {
  console.log('Transaction confirmed:', signature);
}
Copy

Setting Resource Limits

const quote = await client.quote(
  inputAmount,
  inputMint,
  outputMint,
  {
    compute_units: 800_000,  // Compute budget (default: 1,000,000)
    encoded_bytes: 1000      // Transaction size limit (default: 1,100)
  }
);
Copy

Priority Fee Management

// Get current priority fees
const highFee = await client.getPriorityLamports("high");
const mediumFee = await client.getPriorityLamports("medium");
const lowFee = await client.getPriorityLamports("low");

// Use custom priority fee
const signature = await client.swapInteractive(
  connection,
  quote,
  wallet,
  0.01,
  BigInt(50000) // 50k lamports
);
Copy

Error Handling

try {
  const quote = await client.quote(inputAmount, inputMint, outputMint);
  const signature = await client.swapInteractive(connection, quote, wallet, 0.01);
  console.log('Swap successful:', signature);
} catch (error) {
  if (error.message.includes('could not find route')) {
    console.error('No trading route available');
  } else if (error.message.includes('could not quote')) {
    console.error('Quote failed:', error.message);
  } else {
    console.error('Swap failed:', error);
  }
}
Copy

Notes

• All amounts are in native token atoms (smallest unit)
• Slippage is expressed as a decimal (0.01 = 1%)
• Priority fees help with transaction inclusion during network congestion
• The client automatically handles Address Lookup Tables (ALTs) for transaction compression
• Failed transactions are automatically reported to Spur for debugging
• Use the demo website to make some test transactions