SDK Reference

npm install @specify-sh/sdk

import Specify, { ImageFormat } from '@specify-sh/sdk';
 
// Initialize the SDK
const specify = new Specify({
  publisherKey: 'spk_your_publisher_key_here',
  // Enable for more efficient client-side serves
  cacheMostRecentAddress: true
});
 
// Serve an ad to a wallet address
try {
  const ad = await specify.serve('0x742d35Cc6634C0532925a3b8D57C11E4a3e1A510', {
    imageFormat: ImageFormat.LANDSCAPE
  });
 
  if (ad) {
    console.log('Headline:', ad.headline);
    console.log('Content:', ad.content);
    console.log('Image URL:', ad.imageUrl);
    console.log('CTA:', ad.ctaLabel, '->', ad.ctaUrl);
  } else {
    console.log('No ad found for this wallet');
  }
} catch (error) {
  console.error('Error serving ad:', error);
}

const specify = new Specify(config: SpecifyInitConfig);

const specify = new Specify({
  publisherKey: 'spk_1234567890abcdef1234567890abcdef',
  cacheMostRecentAddress: true
});

serve(
  addressOrAddresses: Address | Address[] | undefined,
  options: ServeOptions
): Promise<SpecifyAd | null>

import { ImageFormat } from '@specify-sh/sdk';
 
const ad = await specify.serve(
  '0x742d35Cc6634C0532925a3b8D57C11E4a3e1A510',
  {
    imageFormat: ImageFormat.LANDSCAPE
  }
);

const ad = await specify.serve(
  '0x742d35Cc6634C0532925a3b8D57C11E4a3e1A510',
  {
    imageFormat: ImageFormat.LANDSCAPE,
    adUnitId: 'homepage-hero-banner'
  }
);

const ad = await specify.serve(
  [
    '0x742d35Cc6634C0532925a3b8D57C11E4a3e1A510',
    '0x8ba1f109551bD432803012645Hac136c0532925a',
    '0x1234567890123456789012345678901234567890'
  ],
  {
    imageFormat: ImageFormat.LONG_BANNER,
    adUnitId: 'multi-wallet-banner'
  }
);

const ad = await specify.serve(null, {
  imageFormat: ImageFormat.LONG_BANNER,
  adUnitId: 'header-banner'
});
 
// Or with an empty array
const ad = await specify.serve([], {
  imageFormat: ImageFormat.LONG_BANNER,
  adUnitId: 'header-banner'
});

import {
  AuthenticationError,
  ValidationError,
  NotFoundError,
  APIError,
  ImageFormat
} from '@specify-sh/sdk';
 
try {
  const ad = await specify.serve(walletAddress, {
    imageFormat: ImageFormat.LANDSCAPE,
    adUnitId: 'main-content-ad'
  });
 
  if (ad) {
    displayAd(ad);
  } else {
    showFallbackContent();
  }
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Invalid input:', error.message);
  } else if (error instanceof NotFoundError) {
    showFallbackContent();
  } else if (error instanceof AuthenticationError) {
    console.error('Authentication failed. Check your publisher key.');
  } else if (error instanceof APIError) {
    console.error('API error:', error.message);
    showErrorMessage();
  } else {
    console.error('Unexpected error:', error);
  }
}

import React, { useState, useEffect } from 'react';
import Specify, {
  SpecifyAd,
  ValidationError,
  NotFoundError,
  ImageFormat
} from '@specify-sh/sdk';
 
const specify = new Specify({
  publisherKey: process.env.REACT_APP_SPECIFY_PUBLISHER_KEY!,
  cacheMostRecentAddress: true
});
 
interface AdComponentProps {
  walletAddress: string;
  imageFormat?: ImageFormat;
  adUnitId?: string;
}
 
const AdComponent: React.FC<AdComponentProps> = ({
  walletAddress,
  imageFormat = ImageFormat.LANDSCAPE,
  adUnitId
}) => {
  const [ad, setAd] = useState<SpecifyAd | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);
 
  useEffect(() => {
    const fetchAd = async () => {
      try {
        setLoading(true);
        setError(null);
 
        const adData = await specify.serve(walletAddress, {
          imageFormat,
          adUnitId
        });
        setAd(adData);
      } catch (err) {
        if (err instanceof ValidationError) {
          setError('Invalid wallet address');
        } else if (err instanceof NotFoundError) {
          setAd(null);
        } else {
          setError('Failed to load ad');
        }
      } finally {
        setLoading(false);
      }
    };
 
    if (walletAddress) fetchAd();
  }, [walletAddress, imageFormat, adUnitId]);
 
  if (loading) return <div>Loading ad...</div>;
  if (error) return <div>Error: {error}</div>;
  if (!ad) return null; // No ad — render nothing (or your own fallback)
 
  return (
    <div className="ad-container">
      <div className="ad-header">
        <img src={ad.communityLogo} alt={ad.communityName} className="community-logo" />
        <span className="community-name">{ad.communityName}</span>
      </div>
      <h3 className="ad-headline">{ad.headline}</h3>
      <img src={ad.imageUrl} alt={ad.headline} className="ad-image" />
      <p className="ad-content">{ad.content}</p>
      <a href={ad.ctaUrl} className="ad-cta" target="_blank" rel="noopener noreferrer">
        {ad.ctaLabel}
      </a>
    </div>
  );
};
 
export default AdComponent;

import express from 'express';
import Specify, { ValidationError, NotFoundError, ImageFormat } from '@specify-sh/sdk';
 
const app = express();
const specify = new Specify({
  publisherKey: process.env.SPECIFY_PUBLISHER_KEY!
  // Note: cacheMostRecentAddress has no effect server-side
});
 
app.get('/api/ads/:walletAddress', async (req, res) => {
  try {
    const { walletAddress } = req.params;
    const { format = 'LANDSCAPE', adUnitId } = req.query;
 
    const ad = await specify.serve(walletAddress, {
      imageFormat: format as ImageFormat,
      adUnitId: adUnitId as string | undefined
    });
 
    if (ad) {
      res.json({
        success: true,
        ad: {
          ...ad,
          timestamp: new Date().toISOString()
        }
      });
    } else {
      res.status(404).json({ success: false, message: 'No ad found' });
    }
  } catch (error) {
    if (error instanceof ValidationError) {
      res.status(400).json({
        success: false,
        message: error.message,
        details: (error as ValidationError & { details?: unknown }).details
      });
    } else if (error instanceof NotFoundError) {
      res.status(404).json({ success: false, message: 'No ad found' });
    } else {
      console.error('Server error:', error);
      res.status(500).json({ success: false, message: 'Internal server error' });
    }
  }
});
 
app.listen(3000, () => {
  console.log('Server running on port 3000');
});