API Integration Guide

Connect to KicksDB in 5 minutes. Step-by-step setup for accessing 1000+ endpoints.

Step 1: Get Your API Key

1. Visit dashboard.kicks.dev

2. Sign up or log in with your wallet

3. Navigate to "API Keys" section

4. Click "Create New Key"

5. Copy your key: sk_live_xxx...

Store your API key in environment variables. Never commit it to git.

Step 2: Install SDK

Using npm or pnpm

npm install @revault/kicksdb
# or
pnpm add @revault/kicksdb

Create .env.local

KICKSDB_API_KEY=sk_live_your_api_key_here
KICKSDB_API_URL=https://api.kicks.dev

Step 3: Initialize KicksDB Client

TypeScript / Node.js

import { KicksDB } from '@revault/kicksdb'

// Initialize client with API key
const client = new KicksDB({
  apiKey: process.env.KICKSDB_API_KEY,
  baseUrl: process.env.KICKSDB_API_URL,
  timeout: 10000
})

// Test connection
const status = await client.health()
console.log('KicksDB Status:', status.operational)

Python

from kicksdb import KicksDBClient
import os

# Initialize client
client = KicksDBClient(
    api_key=os.environ.get('KICKSDB_API_KEY'),
    base_url=os.environ.get('KICKSDB_API_URL')
)

# Test connection
status = client.health()
print(f"KicksDB Status: {status['operational']}")

Step 4: Fetch Prices & Data

Fetch StockX Prices

// Get current StockX prices
const prices = await client.stockx.prices({
  models: ['Nike Dunk Low', 'Jordan 4 Retro'],
  sizes: ['US 8', 'US 9', 'US 10'],
  limit: 100
})

prices.data.forEach(item => {
  console.log(`${item.model}`)
  console.log(`  Last Sale: $${item.lastSale}`)
  console.log(`  Ask: $${item.lowestAsk}`)
  console.log(`  Bid: $${item.highestBid}`)
  console.log(`  Spread: ${((item.lowestAsk - item.highestBid) / item.highestBid * 100).toFixed(2)}%`)
})

Fetch GOAT Marketplace Data

// Get GOAT marketplace data
const goatData = await client.goat.prices({
  models: ['Yeezy 350 V2 Zebra'],
  includeHistory: true,
  timeframe: '24h'
})

goatData.data.forEach(item => {
  console.log(`${item.model}`)
  console.log(`  Demand Trend: ${item.demandTrend}`)
  console.log(`  Active Sellers: ${item.sellerCount}`)
  console.log(`  Size US8: $${item.priceRanges.US8.avg}`)
})

Monitor Real-Time Inventory

// Get real-time inventory status
const inventory = await client.inventory.status({
  models: ['Nike Dunk Low'],
  includeHistory: true
})

inventory.data.forEach(item => {
  console.log(`${item.model} @ ${item.retail}`)
  console.log(`  Available: ${item.inventory.available}`)
  console.log(`  Sold Out: ${item.inventory.soldOut}`)
  console.log(`  Sell-out Speed: ${item.selloutSpeed}`)
  console.log(`  Predicted Sellout: ${item.predictedSoldout}`)
})

Fetch Retail Prices Across Partners

// Get prices from all retail partners
const retail = await client.retail.prices({
  models: ['Nike Dunk Low'],
  retailers: ['nike', 'adidas', 'footpatrol', 'jdsports'],
  region: 'US'
})

retail.data.forEach(item => {
  console.log(`${item.model}`)
  item.retailers.forEach(r => {
    console.log(`  ${r.name}: $${r.price} (${r.inStock ? 'IN STOCK' : 'SOLD OUT'})`)
  })
})

Step 5: Error Handling & Retry Logic

Production-Ready Error Handling

async function fetchPricesWithRetry(models, maxRetries = 3) {
  let lastError
  
  for (let i = 0; i < maxRetries; i++) {
    try {
      const prices = await client.stockx.prices({ models })
      return prices.data
    } catch (error) {
      lastError = error
      
      if (error.status === 429) {
        // Rate limited - exponential backoff
        const delay = Math.pow(2, i) * 1000
        console.log(`Rate limited. Retrying in ${delay}ms`)
        await new Promise(resolve => setTimeout(resolve, delay))
      } else if (error.status >= 500) {
        // Server error - retry
        console.log(`Server error: ${error.status}. Retrying...`)
        await new Promise(resolve => setTimeout(resolve, 1000))
      } else {
        // Client error - don't retry
        throw error
      }
    }
  }
  
  throw new Error(`Failed after ${maxRetries} retries: ${lastError.message}`)
}

// Usage
try {
  const prices = await fetchPricesWithRetry(['Nike Dunk Low'])
  console.log('Prices:', prices)
} catch (error) {
  console.error('Failed to fetch prices:', error.message)
}

Implement exponential backoff for rate limits (429) and server errors (5xx). Don't retry 4xx client errors.

Advanced: Real-Time Monitoring Loop

24/7 Price Monitoring Agent

// Real-time market monitoring
const monitored = ['Nike Dunk Low', 'Jordan 4 Retro', 'Yeezy 350 V2']
const prices = {}

async function monitorMarket() {
  while (true) {
    try {
      // Fetch current prices
      const current = await client.stockx.prices({ models: monitored })
      
      // Check for changes
      current.data.forEach(item => {
        const key = item.model
        const prev = prices[key]
        
        if (prev) {
          const change = item.lastSale - prev.lastSale
          const pct = (change / prev.lastSale * 100).toFixed(2)
          
          if (Math.abs(change) > 5) {
            console.log(`[ALERT] ${key}: $${prev.lastSale} → $${item.lastSale} (${pct}%)`)
            
            // Calculate spread opportunity
            const spread = item.lowestAsk - item.highestBid
            const spreadPct = (spread / item.highestBid * 100).toFixed(2)
            console.log(`  Spread: $${spread} (${spreadPct}%)`)
          }
        }
        
        prices[key] = item
      })
      
      // Wait before next check (50ms = sub-second monitoring)
      await new Promise(resolve => setTimeout(resolve, 50))
    } catch (error) {
      console.error('Monitor error:', error.message)
      // Backoff on error
      await new Promise(resolve => setTimeout(resolve, 5000))
    }
  }
}

// Start monitoring
monitorMarket()

Testing Your Integration

Quick Test Script

// test-kicksdb.js
import { KicksDB } from '@revault/kicksdb'

const client = new KicksDB({
  apiKey: process.env.KICKSDB_API_KEY
})

async function runTests() {
  console.log('Testing KicksDB Integration...')
  
  // Test 1: Connection
  console.log('\n1. Testing connection...')
  const health = await client.health()
  console.log(`   Status: ${health.operational ? '✓ OK' : '✗ ERROR'}`)
  
  // Test 2: StockX
  console.log('\n2. Testing StockX prices...')
  const sx = await client.stockx.prices({ models: ['Nike Dunk Low'], limit: 1 })
  console.log(`   Retrieved: ${sx.data.length} items`)
  
  // Test 3: GOAT
  console.log('\n3. Testing GOAT prices...')
  const goat = await client.goat.prices({ models: ['Yeezy 350 V2'], limit: 1 })
  console.log(`   Retrieved: ${goat.data.length} items`)
  
  // Test 4: Retail
  console.log('\n4. Testing retail prices...')
  const retail = await client.retail.prices({ models: ['Nike Dunk Low'], limit: 1 })
  console.log(`   Retrieved: ${retail.data.length} items`)
  
  console.log('\n✓ All tests passed!')
}

runTests().catch(console.error)

Run with: node test-kicksdb.js

Production Deployment Checklist

API key stored in environment variables (never hardcoded)

Error handling with exponential backoff implemented

Rate limit handling (HTTP 429)

Monitoring and alerting configured

Logging to capture all errors and API issues

API key rotation policy established

Load testing completed (capacity planning)

Fallback data sources identified

Need Help?

Check the full API docs at api.kicks.dev/docs or email support@revault.ai