Flashy Gold API

Authentication

All API requests must include your partner API key in the X-Api-Key header. Keys are available in your partner portal.

curl -H "X-Api-Key: YOUR_KEY" \
  https://claimyour.gold/api/v1/public/events

Events Feed

Retrieve a paginated list of platform events for your campaign. User IDs are one-way hashed — no PII is ever returned.

GET /api/v1/public/events?limit=20&cursor=<id>

// Response
{
  "success": true,
  "data": {
    "events": [
      {
        "id": "clx...",
        "type": "reward.claimed",
        "occurredAt": "2026-07-06T12:00:00Z",
        "data": {
          "userId": "a3f9b12c...",   // 16-char one-way hash
          "goldAmount": 5000
        }
      }
    ],
    "nextCursor": "clx..."           // null when no more pages
  }
}

Available Events

Webhooks

Register an HTTPS endpoint and we will POST events to you in real time. All requests include an X-Flashy-Signature header for verification.

Register an endpoint

POST /api/v1/partner/webhooks
X-Api-Key: YOUR_KEY
Content-Type: application/json

{
  "url": "https://yourapp.com/webhooks/flashy",
  "events": ["reward.claimed", "referral.completed"]
}

// Response — save the secret! It is shown only once.
{
  "success": true,
  "data": {
    "endpoint": {
      "id": "abc123",
      "url": "https://yourapp.com/webhooks/flashy",
      "secret": "d4e5f6...",   // use this to verify signatures
      "events": ["reward.claimed", "referral.completed"],
      "active": true,
      "createdAt": "2026-07-06T12:00:00Z"
    }
  }
}

Verify the signature

Every webhook POST includes a X-Flashy-Signature: sha256=<hmac> header. Compute the HMAC on the raw request body using your endpoint secret and compare:

import crypto from 'crypto';

function verifyFlashySignature(
  rawBody: string,
  secret: string,
  signature: string,   // from X-Flashy-Signature header
): boolean {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature),
  );
}

Webhook payload shape

{
  "id": "e1f2a3b4",
  "type": "reward.claimed",
  "occurredAt": "2026-07-06T12:00:00Z",
  "data": {
    "userId": "a3f9b12c...",
    "goldAmount": 5000
  }
}

Manage webhooks

Rate limits

Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included on applicable responses. Contact us if your integration requires higher throughput.