API Reference

POST https://app.specify.sh/api/ads

{
  "walletAddresses": ["0x742d35Cc6634C0532925a3b8D57C11E4a3e1A510"],
  "imageFormat": "LANDSCAPE",
  "adUnitId": "header-landscape-1"
}

{
  "walletAddress": "0x742d35Cc6634C0532925a3b8D57C11E4a3e1A510",
  "campaignId": "campaign_123",
  "adId": "ad_456",
  "headline": "Join the Future of DeFi",
  "content": "Experience next-generation decentralized finance with our platform.",
  "ctaUrl": "https://example.com/signup",
  "ctaLabel": "Get Started",
  "imageUrl": "https://cdn.specify.sh/ads/image_123.png",
  "communityName": "DeFi Protocol",
  "communityLogo": "https://cdn.specify.sh/logos/community_123.png",
  "imageFormat": "LANDSCAPE"
}

{
  "error": "Error message describing what went wrong",
  "details": [
    {
      "field": "walletAddresses",
      "message": "Invalid wallet address format"
    }
  ]
}

const response = await fetch('https://app.specify.sh/api/ads', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'spk_your_publisher_key_here'
  },
  body: JSON.stringify({
    walletAddresses: [
      '0x742d35Cc6634C0532925a3b8D57C11E4a3e1A510',
      '0x8ba1f109551bD432803012645Hac136c0532925a',
      '0x1234567890123456789012345678901234567890'
    ],
    imageFormat: 'LONG_BANNER'
  })
});

curl -X POST https://app.specify.sh/api/ads \
  -H "Content-Type: application/json" \
  -H "x-api-key: spk_your_publisher_key_here" \
  -d '{
    "walletAddresses": ["0x742d35Cc6634C0532925a3b8D57C11E4a3e1A510"],
    "imageFormat": "LANDSCAPE",
    "adUnitId": "homepage-banner"
  }'

async function getAd(walletAddress, imageFormat = 'LANDSCAPE', adUnitId = null) {
  const requestBody = {
    walletAddresses: [walletAddress],
    imageFormat
  };
 
  if (adUnitId) requestBody.adUnitId = adUnitId;
 
  const response = await fetch('https://app.specify.sh/api/ads', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'spk_your_publisher_key_here'
    },
    body: JSON.stringify(requestBody)
  });
 
  if (response.status === 404) return null; // No ad — expected, handle with fallback
 
  if (response.status === 401) throw new Error('Invalid API key');
 
  if (response.status === 400) {
    const errorData = await response.json();
    throw new Error(`Validation error: ${errorData.error}`);
  }
 
  if (!response.ok) {
    throw new Error(`HTTP error: ${response.status}`);
  }
 
  return response.json();
}
 
// Usage
const ad = await getAd(
  '0x742d35Cc6634C0532925a3b8D57C11E4a3e1A510',
  'LONG_BANNER',
  'sidebar-ad'
);
 
if (ad) {
  console.log('Headline:', ad.headline);
  console.log('CTA:', ad.ctaLabel, '->', ad.ctaUrl);
}

import requests
 
def get_ad(wallet_address, image_format='LANDSCAPE', api_key='spk_your_publisher_key_here', ad_unit_id=None):
    data = {
        'walletAddresses': [wallet_address],
        'imageFormat': image_format
    }
    if ad_unit_id:
        data['adUnitId'] = ad_unit_id
 
    response = requests.post(
        'https://app.specify.sh/api/ads',
        headers={
            'Content-Type': 'application/json',
            'x-api-key': api_key
        },
        json=data
    )
 
    if response.status_code == 404:
        return None  # No ad — expected, handle with fallback
    if response.status_code == 401:
        raise Exception('Invalid API key')
    if response.status_code == 400:
        error_data = response.json()
        raise Exception(f"Validation error: {error_data.get('error', 'Invalid request')}")
 
    response.raise_for_status()
    return response.json()
 
# Usage
ad = get_ad(
    '0x742d35Cc6634C0532925a3b8D57C11E4a3e1A510',
    image_format='SHORT_BANNER',
    ad_unit_id='header-banner'
)
 
if ad:
    print('Headline:', ad['headline'])
    print('CTA:', ad['ctaLabel'], '->', ad['ctaUrl'])

<?php
function getAd($walletAddress, $imageFormat = 'LANDSCAPE', $apiKey = 'spk_your_publisher_key_here', $adUnitId = null) {
    $data = [
        'walletAddresses' => [$walletAddress],
        'imageFormat' => $imageFormat
    ];
 
    if ($adUnitId !== null) {
        $data['adUnitId'] = $adUnitId;
    }
 
    $options = [
        'http' => [
            'header' => [
                'Content-Type: application/json',
                'x-api-key: ' . $apiKey
            ],
            'method' => 'POST',
            'content' => json_encode($data),
            'ignore_errors' => true // Allow reading 4xx response bodies
        ]
    ];
 
    $response = file_get_contents('https://app.specify.sh/api/ads', false, stream_context_create($options));
    $httpCode = intval(substr($http_response_header[0], 9, 3));
 
    switch ($httpCode) {
        case 200:
            return json_decode($response, true);
        case 404:
            return null; // No ad — expected, handle with fallback
        case 401:
            throw new Exception('Invalid API key');
        case 400:
            $errorData = json_decode($response, true);
            throw new Exception('Validation error: ' . ($errorData['error'] ?? 'Invalid request'));
        default:
            throw new Exception('HTTP error: ' . $httpCode);
    }
}
 
// Usage
$ad = getAd('0x742d35Cc6634C0532925a3b8D57C11E4a3e1A510', 'LANDSCAPE', 'spk_your_publisher_key_here', 'footer-banner');
 
if ($ad) {
    echo 'Headline: ' . $ad['headline'] . PHP_EOL;
    echo 'CTA: ' . $ad['ctaLabel'] . ' -> ' . $ad['ctaUrl'] . PHP_EOL;
}
?>

package main
 
import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)
 
type AdRequest struct {
    WalletAddresses []string `json:"walletAddresses"`
    ImageFormat     string   `json:"imageFormat"`
    AdUnitId        string   `json:"adUnitId,omitempty"`
}
 
type AdResponse struct {
    WalletAddress string `json:"walletAddress"`
    CampaignID    string `json:"campaignId"`
    AdID          string `json:"adId"`
    Headline      string `json:"headline"`
    Content       string `json:"content"`
    CTAUrl        string `json:"ctaUrl"`
    CTALabel      string `json:"ctaLabel"`
    ImageUrl      string `json:"imageUrl"`
    CommunityName string `json:"communityName"`
    CommunityLogo string `json:"communityLogo"`
    ImageFormat   string `json:"imageFormat"`
}
 
func getAd(walletAddress, imageFormat, apiKey, adUnitId string) (*AdResponse, error) {
    body, err := json.Marshal(AdRequest{
        WalletAddresses: []string{walletAddress},
        ImageFormat:     imageFormat,
        AdUnitId:        adUnitId,
    })
    if err != nil {
        return nil, err
    }
 
    req, err := http.NewRequest("POST", "https://app.specify.sh/api/ads", bytes.NewBuffer(body))
    if err != nil {
        return nil, err
    }
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("x-api-key", apiKey)
 
    resp, err := (&http.Client{}).Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
 
    respBody, err := io.ReadAll(resp.Body)
    if err != nil {
        return nil, err
    }
 
    switch resp.StatusCode {
    case 200:
        var ad AdResponse
        if err := json.Unmarshal(respBody, &ad); err != nil {
            return nil, err
        }
        return &ad, nil
    case 404:
        return nil, nil // No ad — expected, handle with fallback
    case 401:
        return nil, fmt.Errorf("invalid API key")
    case 400:
        return nil, fmt.Errorf("validation error: %s", string(respBody))
    default:
        return nil, fmt.Errorf("HTTP error: %d", resp.StatusCode)
    }
}
 
func main() {
    ad, err := getAd(
        "0x742d35Cc6634C0532925a3b8D57C11E4a3e1A510",
        "LANDSCAPE",
        "spk_your_publisher_key_here",
        "main-content",
    )
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
 
    if ad != nil {
        fmt.Printf("Headline: %s\n", ad.Headline)
        fmt.Printf("CTA: %s -> %s\n", ad.CTALabel, ad.CTAUrl)
    }
}