seeklepay

The official SDK for agent developers. Add purchasing capability to any AI agent in minutes.

npm install seeklepay
# or
pip install seeklepay

What it does

Seeklepay is the protocol that lets AI agents purchase from any brand that has implemented the standard. This SDK handles discovery, search, and purchase — your agent just needs to ask.

Without Seeklepay your agent scrapes HTML, guesses at checkout flows, and breaks every time a brand redesigns their site.

With Seeklepay:

const order = await sp.purchase({ variantId: 'summit-lite-uk9', userToken: 'usr_...' })
// Done. Payment handled. Order confirmed. Commission attributed.

Quickstart — Node.js

import { Seeklepay } from 'seeklepay'

const sp = new Seeklepay({
  apiKey: 'sk_live_...',  // from seeklepay.com/dashboard
})

// Search across all Seeklepay brands
const results = await sp.search('trail running shoes', {
  maxPrice: 100,
  size: 'UK9',
  currency: 'GBP'
})

// results is a ranked array of products from all brands
console.log(results[0].name)       // "Summit Lite"
console.log(results[0].price)      // { amount: 74.99, currency: "GBP" }
console.log(results[0].brand)      // "TrailCo"
console.log(results[0].variantId)  // "summit-lite-uk9"
console.log(results[0].agentNotes) // "True to size. Not for deep mud."

// Purchase — user_token authorises the transaction
const order = await sp.purchase({
  variantId: results[0].variantId,
  userToken: 'usr_...',
  delivery: 'standard'
})

console.log(order.id)                // "ORD-1234567890"
console.log(order.estimatedDelivery) // "3-5 business days"
console.log(order.total)             // { amount: 74.99, currency: "GBP" }

Quickstart — Python

from seeklepay import Seeklepay

sp = Seeklepay(api_key="sk_live_...")

# Search
results = sp.search("trail running shoes", max_price=100, size="UK9", currency="GBP")

print(results[0].name)        # "Summit Lite"
print(results[0].agent_notes) # "True to size. Not for deep mud."

# Purchase
order = sp.purchase(
    variant_id=results[0].variant_id,
    user_token="usr_...",
    delivery="standard"
)

print(order.id)                 # "ORD-1234567890"
print(order.estimated_delivery) # "3-5 business days"

Core Concepts

API Key

Your agent's API key. Get one at seeklepay.com/dashboard. Identifies your agent in every transaction — used for analytics, rate limiting, and commission attribution.

const sp = new Seeklepay({ apiKey: process.env.SEEKLEPAY_API_KEY })

User Token

A token representing a specific user's payment details and preferences. Users generate this by registering at seeklepay.com. Your agent stores it and presents it at purchase time.

// Your agent stores this per user
const userToken = 'usr_abc123...'

// Present at purchase
await sp.purchase({ variantId: '...', userToken })

Seeklepay resolves the token to a real payment method. Your agent never handles card numbers.

Search

Search across all Seeklepay-enabled brands simultaneously. Returns a ranked array of products.

const results = await sp.search(query, options)

Options:

| Option | Type | Description | |---|---|---| | maxPrice | number | Maximum price in the specified currency | | minPrice | number | Minimum price | | currency | string | ISO 4217 currency code. Default: GBP | | size | string | Size string e.g. UK9, M, 32x32 | | brand | string | Filter to a specific brand ID | | category | string[] | Filter by category e.g. ["footwear", "trail"] | | inStockOnly | boolean | Exclude out of stock variants. Default: true | | limit | number | Max results to return. Default: 10 |

Product object:

{
  id: string
  variantId: string
  name: string
  brand: string
  brandId: string
  description: string
  price: { amount: number, currency: string, taxIncluded: boolean }
  availability: 'in_stock' | 'low_stock' | 'out_of_stock'
  quantity: number
  size: string
  attributes: Record<string, string>
  media: { role: string, url: string, alt: string }[]
  policies: { returns: object, delivery: object }
  agentNotes: string  // brand-specific notes for AI agents
}

Purchase

Execute a purchase on behalf of a user.

const order = await sp.purchase({
  variantId: 'summit-lite-uk9',
  userToken: 'usr_...',
  delivery: 'standard' | 'express',
  quantity: 1  // optional, default 1
})

Order object:

{
  id: string
  status: 'confirmed' | 'pending' | 'failed'
  product: { name: string, variantId: string, size: string }
  price: { subtotal: number, delivery: number, total: number, currency: string }
  estimatedDelivery: string
  trackingUrl: string
  createdAt: string
}

Get product

Fetch full details for a specific product.

const product = await sp.getProduct('trail-x-pro')

Get order

Check order status.

const order = await sp.getOrder('ORD-1234567890')

Spending Limits

Users set spending limits when they register. Your agent should respect them — but Seeklepay also enforces them server-side.

// Check limits before purchasing
const user = await sp.getUser(userToken)
console.log(user.limits.autoApproveUnder)    // 30.00
console.log(user.limits.confirmRequiredOver)  // 30.00
console.log(user.limits.monthlyCap)           // 500.00

// If purchase is over the auto-approve limit, your agent
// should confirm with the user before calling sp.purchase()

Error Handling

import { Seeklepay, SeeklepayError, StockError, PaymentError, AuthError } from 'seeklepay'

try {
  const order = await sp.purchase({ variantId, userToken })
} catch (err) {
  if (err instanceof StockError) {
    // Item went out of stock between search and purchase
    const alternatives = await sp.search(err.productName, { size: err.size })
    // offer alternatives to user
  }

  if (err instanceof PaymentError) {
    // Payment failed — user needs to update payment details
    console.log(err.message) // "Card declined"
  }

  if (err instanceof AuthError) {
    // API key or user token invalid
  }
}

Error types:

| Error | When | |---|---| | AuthError | Invalid API key or user token | | StockError | Item out of stock at purchase time | | PaymentError | Payment declined or user token invalid | | BrandError | Brand's purchase endpoint returned an error | | RateLimitError | Too many requests | | SeeklepayError | Base class for all errors |

Using with an LLM agent

Seeklepay works naturally as a tool in any LLM framework.

With Anthropic tool use:

const tools = [
  {
    name: "search_products",
    description: "Search for products across all Seeklepay brands. Use when the user wants to find or buy something.",
    input_schema: {
      type: "object",
      properties: {
        query: { type: "string", description: "What to search for" },
        max_price: { type: "number", description: "Maximum price in GBP" },
        size: { type: "string", description: "Size if applicable e.g. UK9" }
      },
      required: ["query"]
    }
  },
  {
    name: "purchase_product",
    description: "Purchase a product. Only call this after confirming with the user.",
    input_schema: {
      type: "object",
      properties: {
        variant_id: { type: "string", description: "The variant ID from search results" },
        delivery: { type: "string", enum: ["standard", "express"] }
      },
      required: ["variant_id"]
    }
  }
]

// Handle tool calls
if (toolName === 'search_products') {
  const results = await sp.search(input.query, {
    maxPrice: input.max_price,
    size: input.size
  })
  return JSON.stringify(results)
}

if (toolName === 'purchase_product') {
  const order = await sp.purchase({
    variantId: input.variant_id,
    userToken: currentUserToken,
    delivery: input.delivery || 'standard'
  })
  return JSON.stringify(order)
}

Configuration

const sp = new Seeklepay({
  apiKey: 'sk_live_...',
  baseUrl: 'https://api.seeklepay.com',  // default
  timeout: 10000,                          // ms, default 10000
  retries: 3,                              // default 3
  currency: 'GBP',                         // default currency for searches
})

Webhooks

Receive events when orders are updated.

// In your Express/Fastify server
app.post('/seeklepay/webhooks', (req, res) => {
  const event = sp.webhooks.verify(req.body, req.headers['seeklepay-signature'])

  switch (event.type) {
    case 'order.confirmed':
      console.log('Order confirmed:', event.data.orderId)
      break
    case 'order.shipped':
      console.log('Order shipped:', event.data.trackingUrl)
      break
    case 'order.failed':
      console.log('Order failed:', event.data.reason)
      break
  }

  res.json({ received: true })
})

Environment variables

SEEKLEPAY_API_KEY=sk_live_...
SEEKLEPAY_USER_TOKEN=usr_...   # optional, set per-user at runtime
SEEKLEPAY_ENV=production       # production | sandbox

Sandbox

Test without real purchases using the sandbox environment.

const sp = new Seeklepay({
  apiKey: 'sk_test_...',  // test key from dashboard
  env: 'sandbox'
})

// All purchases return mock orders, no real payments
const order = await sp.purchase({ variantId: 'summit-lite-uk9', userToken: 'usr_test_...' })
console.log(order.id) // "ORD-TEST-1234"

Support

• Docs: seeklepay.com/docs
• Discord: seeklepay.com/discord
• Email: [email protected]
• Issues: github.com/seeklepay/seeklepay-node

Licence

MIT