JavaScript Examples

Code examples for JavaScript/Node.js integration with the SNS Auctions API

Setup

Use native fetch (Node 18+ or browser):

npm

# no SDK required

Configure API key:

Node.js

const API_BASE = 'https://api.snsauctions.xyz/api/v1';
const API_KEY = process.env.SNS_API_KEY;

async function apiCall(endpoint, options = {}) {
  const response = await fetch(`${API_BASE}${endpoint}`, {
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json',
      ...options.headers
    },
    ...options
  });

  if (!response.ok) {
    throw new Error(`API Error: ${response.statusText}`);
  }

  return response.json();
}

List Auctions

Fetch active auctions:

JavaScript

async function listAuctions() {
  const data = await apiCall('/auctions', {
    method: 'GET'
  });

  console.log(`Found ${data.data.auctions.length} auctions`);

  data.data.auctions.forEach(auction => {
    console.log(`- ${auction.domains[0]} at ${auction.currentPrice} SOL`);
  });

  return data.data.auctions;
}

// With filters
async function listActiveAuctions() {
  const params = new URLSearchParams({
    status: 'active',
    sortBy: 'endTime',
    sortOrder: 'asc',
    pageSize: 50
  });

  return apiCall(`/auctions?${params}`);
}

Create Auction

Create a new auction:

JavaScript

async function createAuction(domain, options = {}) {
  const payload = {
    domainNames: [domain],
    type: options.type || 'standard',
    startingPrice: options.startingPrice || 1,
    minBidIncrement: options.minBidIncrement || 0.1,
    durationHours: options.durationHours || 24,
    snipeProtectionEnabled: options.snipeProtection !== false,
    title: options.title || `Auction for ${domain}`,
    description: options.description || ''
  };

  // For Dutch auctions
  if (options.type === 'dutch') {
    payload.dutchStartPrice = options.dutchStartPrice;
    payload.dutchEndPrice = options.dutchEndPrice;
    payload.dutchDecrementInterval = options.decrementInterval || 300;
  }

  const response = await apiCall('/auctions/create', {
    method: 'POST',
    body: JSON.stringify(payload)
  });

  if (response.success) {
    console.log(`Created auction ${response.data.auctionId}`);
    return response.data;
  } else {
    throw new Error(response.error);
  }
}

// Usage
await createAuction('premium.sol', {
  startingPrice: 5,
  minBidIncrement: 0.5,
  durationHours: 48,
  type: 'standard'
});

Place Bid

Place a bid on an auction:

JavaScript

async function placeBid(auctionId, bidAmount) {
  const response = await apiCall(`/auctions/${auctionId}/bid`, {
    method: 'POST',
    body: JSON.stringify({
      bidAmount: bidAmount,
      autoSettle: true // Automatically settle if you win
    })
  });

  if (response.success) {
    console.log(
      `Bid placed! New top bidder: ${response.data.newTopBidder}`
    );
    console.log(
      `Next minimum bid: ${response.data.nextMinimumBid} SOL`
    );
    return response.data;
  } else {
    console.error(`Bid failed: ${response.error}`);
    throw new Error(response.error);
  }
}

// Usage
await placeBid('auction_123', 2.5);

Get User Profile

Fetch user statistics:

JavaScript

async function getUserProfile(walletAddress) {
  const response = await apiCall(`/users/${walletAddress}`);

  if (response.success) {
    const profile = response.data;
    console.log(`User: ${profile.snsName || walletAddress}`);
    console.log(`Auctions created: ${profile.stats.totalAuctionsCreated}`);
    console.log(`Auctions won: ${profile.stats.totalAuctionsWon}`);
    console.log(`Volume traded: ${profile.stats.totalVolumeTraded} SOL`);
    console.log(`Win rate: ${profile.stats.winRate}%`);
    return profile;
  } else {
    throw new Error(response.error);
  }
}

// Usage
await getUserProfile('9B5X5wUohEzB8UZjfAvaxS1huNY6q5p5XqvCH7r6T1Hj');

Settle Auction

Finalize a completed auction:

JavaScript

async function settleAuction(auctionId) {
  const response = await apiCall(`/auctions/${auctionId}/settle`, {
    method: 'POST',
    body: JSON.stringify({})
  });

  if (response.success) {
    console.log(`Auction settled: ${response.data.status}`);
    if (response.data.winner) {
      console.log(
        `Winner: ${response.data.winner} won for ${response.data.winnerAmount} SOL`
      );
    }
    return response.data;
  } else {
    throw new Error(response.error);
  }
}

// Usage
await settleAuction('auction_123');

Webhooks (Real-time Events)

Subscribe to webhooks to receive real-time events instead of polling. First, create a webhook subscription:

Create Webhook Subscription

const apiKey = 'sk_live_your_key';

// Create a webhook subscription
const response = await fetch('https://api.snsauctions.xyz/api/v1/webhooks/create', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://your-server.com/webhooks/sns-auctions',
    events: ['auction.bid', 'auction.settled', 'auction.created'],
  }),
});

const { data } = await response.json();
console.log('Webhook created:', data.subscriptionId);

Then handle webhook events on your server:

Express Server

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json());

// Verify webhook signature
function verifyWebhookSignature(payload, signature, secret) {
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return computedSignature === signature;
}

app.post('/webhooks/sns-auctions', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = req.body;

  // In production, verify signature with your webhook secret
  // if (!verifyWebhookSignature(payload, signature, webhookSecret)) {
  //   return res.status(401).json({ error: 'Invalid signature' });
  // }

  const eventType = req.headers['x-webhook-event'];
  console.log(`Received event: ${eventType}`);

  switch (eventType) {
    case 'auction.bid':
      console.log(`New bid on ${payload.domain}: ${payload.data.bidAmount} SOL`);
      // Handle bid event
      break;

    case 'auction.settled':
      console.log(`Auction settled: ${payload.auctionId}`);
      // Handle settlement
      break;

    case 'auction.created':
      console.log(`New auction: ${payload.domain}`);
      // Handle creation
      break;
  }

  // Acknowledge receipt (important for webhook retry logic)
  res.json({ received: true });
});

app.listen(3000);

List your webhooks:

List Webhooks

const response = await fetch('https://api.snsauctions.xyz/api/v1/webhooks', {
  headers: { 'X-API-Key': apiKey },
});

const { data } = await response.json();
console.log('Your webhooks:', data.webhooks);

Error Handling

Robust error handling:

JavaScript

async function apiCallWithRetry(endpoint, options = {}, maxRetries = 3) {
  let lastError;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await apiCall(endpoint, options);
      return response;
    } catch (error) {
      lastError = error;

      if (attempt < maxRetries) {
        // Exponential backoff
        const delay = Math.pow(2, attempt - 1) * 1000;
        console.log(`Retry attempt ${attempt}/${maxRetries} in ${delay}ms`);
        await new Promise(resolve => setTimeout(resolve, delay));
      }
    }
  }

  throw lastError;
}

// Usage
try {
  await placeBid('auction_123', 2.5);
} catch (error) {
  if (error.message.includes('Rate limit')) {
    console.error('Rate limited - waiting before retry');
  } else if (error.message.includes('ALREADY_TOP_BIDDER')) {
    console.error('You already have the top bid');
  } else {
    console.error('Unexpected error:', error.message);
  }
}

Error Handling

Python

Follow Notify Join Discord