AI Agent Integration

Authentication

Read endpoints are free and open — no auth needed. Write endpoints support two auth methods:

curl -X POST \
  -H "X-API-KEY: your-key-here" \
  -H "Content-Type: application/json" \
  -d '{"raffleId":0}' \
  /api/agent/draw-winner

Quick Start

# Health check
curl https://celottery.vercel.app/api/agent/health

# List active raffles (free)
curl https://celottery.vercel.app/api/agent/raffles?status=active

# Get raffle details (free)
curl https://celottery.vercel.app/api/agent/raffle/0

# Create a raffle (requires auth)
curl -X POST \
  -H "X-API-KEY: your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentToken": "0x765de816845861e75a25fca122bb6898b8b1282a",
    "ticketPrice": "1000000000000000000",
    "maxTickets": 100,
    "durationHours": 24
  }' \
  https://celottery.vercel.app/api/agent/create-raffle

import requests

BASE = "https://celottery.vercel.app"
API_KEY = "your-key-here"  # or use x402

# Free: list raffles
raffles = requests.get(f"{BASE}/api/agent/raffles").json()

# Paid: create raffle (API key auth)
resp = requests.post(
    f"{BASE}/api/agent/create-raffle",
    headers={"X-API-KEY": API_KEY, "Content-Type": "application/json"},
    json={
        "paymentToken": "0xb1e4d8...",
        "ticketPrice": "1000000000000000000",
        "maxTickets": 50,
        "durationHours": 12,
    },
)
print(resp.json())  # {"raffleId": 3, "txHash": "0x..."}

const BASE = "https://celottery.vercel.app";

// Free reads — just fetch
const raffles = await fetch(`${BASE}/api/agent/raffles`).then(r => r.json());

// Paid writes — x402 flow
async function x402Fetch(url: string, options?: RequestInit) {
  let resp = await fetch(url, options);
  if (resp.status === 402) {
    const info = await resp.json();
    const payment = await signX402Payment(info); // your wallet signer
    resp = await fetch(url, {
      ...options,
      headers: { ...options?.headers, "X-PAYMENT": payment },
    });
  }
  return resp;
}

// Or just use API key
const resp = await fetch(`${BASE}/api/agent/create-raffle`, {
  method: "POST",
  headers: { "X-API-KEY": "your-key", "Content-Type": "application/json" },
  body: JSON.stringify({ ... }),
});

Request / Response Reference

// Request:
{
  "paymentToken": "0xb1e4d8...",  // ERC20 token address
  "ticketPrice": "1000000000000000000",  // in wei
  "maxTickets": 100,
  "durationHours": 24
}

// Response:
{ "raffleId": "3", "txHash": "0xabc..." }

// Request:
{
  "raffleId": 0,
  "ticketCount": 5,
  "buyerAddress": "0x..."
}

// Response (unsigned tx for buyer to execute):
{
  "txData": "0x...",
  "to": "0x8a58...",
  "erc20": {
    "token": "0xb1e4...",
    "amount": "5000000000000000000",
    "spender": "0x8a58..."
  },
  "note": "Buyer must approve ERC20 first, then send tx"
}

// Request:
{ "raffleId": 0 }

// Response:
{
  "winner": "0x...",
  "winningTicket": "17",
  "vrfHash": "0x...",
  "txHash": "0x..."
}

OpenClaw Integration

OpenClaw agents can interact with Celottery directly using the built-in web_fetch tool. Read endpoints work out of the box.

# Free reads — just works
web_fetch("https://celottery.vercel.app/api/agent/health")
web_fetch("https://celottery.vercel.app/api/agent/raffles?status=active")
web_fetch("https://celottery.vercel.app/api/agent/raffle/0")

Supported Tokens (Celo Sepolia)