API Reference

ProductClank Arena provides RESTful API endpoints for interacting with products, campaigns, auctions, and more.

Base URL

Production: https://productclank.com/api
Development: http://localhost:3000/api

Authentication

Most endpoints require authentication via:

• Farcaster authentication (for frame users)
• Privy authentication (for web users)
• Session cookies

Products

Search Products

GET /api/products/search?q={query}&category={category}&tags={tags}

Response:
{
  "products": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "imageUrl": "string",
      "believerCount": number,
      "createdAt": "timestamp"
    }
  ]
}

Get Product Votes

GET /api/product/[id]/votes

Response:
{
  "believerCount": number,
  "userHasBelieved": boolean
}

Campaigns

List Campaigns

GET /api/campaigns/list?status={active|completed}&productId={id}

Response:
{
  "campaigns": [
    {
      "id": "string",
      "productId": "string",
      "rewardAmount": number,
      "startDate": "timestamp",
      "endDate": "timestamp",
      "participantCount": number
    }
  ]
}

Create Campaign

POST /api/campaigns/create

Body:
{
  "productId": "string",
  "rewardAmount": number,
  "startDate": "timestamp",
  "endDate": "timestamp",
  "actionItems": [...]
}

Response:
{
  "campaignId": "string",
  "status": "created"
}

Get User Campaigns

GET /api/campaigns/mine

Response:
{
  "campaigns": [...]
}

Auctions

Get Auction

GET /api/auction

Response:
{
  "tokenId": number,
  "startTime": "timestamp",
  "endTime": "timestamp",
  "highestBid": number,
  "highestBidder": "address",
  "isSettled": boolean,
  "campaignId": "string"
}

Get Auction History

GET /api/auction/history?limit={number}

Response:
{
  "auctions": [
    {
      "tokenId": number,
      "winner": "address",
      "winningBid": number,
      "settledAt": "timestamp"
    }
  ]
}

Bids

Create Bid

POST /api/bids/create

Body:
{
  "auctionId": number,
  "amount": number,
  "campaignId": "string",
  "txHash": "string"
}

Response:
{
  "bidId": "string",
  "status": "created"
}

Get Bids by Auction

GET /api/bids/by-auction?auctionId={id}

Response:
{
  "bids": [
    {
      "id": "string",
      "bidder": "address",
      "amount": number,
      "timestamp": "timestamp",
      "txHash": "string"
    }
  ]
}

Validate Bid

POST /api/bids/validate

Body:
{
  "auctionId": number,
  "amount": number,
  "bidder": "address"
}

Response:
{
  "isValid": boolean,
  "reason": "string"
}

Error Responses

All endpoints may return error responses:

{
  "error": "string",
  "message": "string",
  "statusCode": number
}

Rate Limiting

API endpoints are rate-limited to prevent abuse:

• Standard endpoints: 100 requests per minute
• Write endpoints: 10 requests per minute
• Rate limit headers included in responses