# Bitcoin Rewards Affiliate API
Version: 1.3.0

## Base URLs
- https://www.bitcoinrewards.app (Production)
- http://localhost:3000 (Local development)

## Authentication

All requests require an API key in the Authorization header:

```
Authorization: Bearer sk_live_{lookupId}_{secret}
```

API keys are created in the Affiliate Dashboard at /developers.

## Error Format

All errors return JSON with an `error` field:

```json
{ "error": "Human-readable error message" }
```

Common status codes:
- 200: Success
- 401: Unauthorized (invalid or missing API key)
- 500: Internal server error

## Endpoints

### GET /api/key-test

**Test API Key**

Validates your API key and returns metadata about the key.
Use this endpoint to verify your API key is working correctly.

**Example Request:**

```bash
curl -X GET "https://www.bitcoinrewards.app/api/key-test" \
  -H "Authorization: Bearer sk_live_xxx_yyy"
```

**Example Response (200):**

```json
{
  "success": true,
  "message": "API key is valid",
  "key": {
    "id": 42,
    "name": "My Production Key",
    "affiliateId": "123456",
    "readOnly": true
  }
}
```

### GET /api/get-business-rewards

**Get Business Rewards**

Returns all businesses you're affiliated with, including:
- Business details (name, description, images, branding)
- Simplified rewards info (headline %, base %, VIP tiers)
- Products with categories
- Pre-built referral URLs ready for immediate use
- Ready-to-use display text for your UI

The response is optimized for display—percentages are calculated,
URLs are fully constructed, and copy text is ready to use.

**Example Request:**

```bash
curl -X GET "https://www.bitcoinrewards.app/api/get-business-rewards" \
  -H "Authorization: Bearer sk_live_xxx_yyy"
```

### GET /api/public/businesses

**List All Businesses**

Returns a paginated list of all active businesses with Bitcoin rewards.
This is a public endpoint—no authentication required.

Used for SEO pages, discovery, and building business directories.

**Note:** The `referralCode`, `referralUrl`, and `handoffUrl` fields return
Oshi's affiliate tracking links. Purchases through these links attribute
to Oshi's affiliate account. For your own affiliate tracking, use the
authenticated `/api/get-business-rewards` endpoint.

**Example Request:**

```bash
curl -X GET "https://www.bitcoinrewards.app/api/public/businesses" \
  -H "Authorization: Bearer sk_live_xxx_yyy"
```

**Example Response (200):**

```json
{
  "businesses": [
    {
      "slug": "amazon",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "name": "Amazon",
      "shortDescription": "Shop millions of products",
      "logoUrl": "https://example.com/amazon-logo.png",
      "transparentLogoUrl": "https://example.com/amazon-logo-transparent.png",
      "affiliateOverlayLogoUrl": null,
      "coverUrl": "https://example.com/amazon-cover.jpg",
      "squareImageUrl": "https://example.com/amazon-square.png",
      "coverDominantColor": "#232F3E",
      "squareImageDominantColor": "#FF9900",
      "website": "https://amazon.com",
      "isOnline": true,
      "isFeatured": true,
      "referralCode": "OSHI123",
      "attributionPeriodDays": 90,
      "referralUrl": "https://amazon.com?ref=OSHI123&utm_source=oshi&utm_medium=referral&utm_campaign=ref_OSHI123&ttl=7776000&policy=first",
      "handoffUrl": "https://oshi.link/OSHI123",
      "affiliateSignupUrl": "https://oshi.link/a/abc123def456",
      "rewardsSummary": {
        "basePercentage": 3,
        "maxPercentage": 8,
        "hasVipTiers": true
      },
      "productCount": 25
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 100,
    "offset": 0,
    "hasMore": true
  }
}
```

### GET /api/public/businesses/{slug}

**Get Business Details**

Returns detailed information about a specific business including
full rewards configuration, products, and social links.
This is a public endpoint—no authentication required.

Used for SEO business detail pages.

**Note:** The `referralCode`, `referralUrl`, and `handoffUrl` fields return
Oshi's affiliate tracking links. For your own affiliate tracking, use the
authenticated API.

**Example Request:**

```bash
curl -X GET "https://www.bitcoinrewards.app/api/public/businesses/{slug}" \
  -H "Authorization: Bearer sk_live_xxx_yyy"
```

## Key Response Fields for GET /api/get-business-rewards

Each business object includes:

| Field | Description |
|-------|-------------|
| `referralUrl` | Pre-built URL with all tracking params. Redirect users here. |
| `handoffUrl` | Branded interstitial page on oshi.link (or custom domain). Format: https://oshi.link/{code} |
| `affiliateSignupUrl` | Merchant-specific affiliate signup page. Format: https://oshi.link/a/{hashedId} (or custom domain). |
| `rewards.headlinePercent` | Main percentage to display (includes bonuses). |
| `rewards.basePercent` | Ongoing rate after first purchase. |
| `rewards.maxPercent` | Maximum with VIP tiers. |
| `rewards.hasVipTiers` | Whether VIP progression is available. |
| `rewards.hasReferralBonus` | Whether first purchase gets a bonus. |
| `rewardsSummary` | Detailed rewards overview (social rewards, BTC pay bonus, redemption). |
| `rewardsConfig` | Full rewards config (VIP tiers, referrals, commissions). |
| `products` | Array of products with title, image, price, handle, productType, collections, isFeatured. |
| `socialLinks` | Business social media links (platform + URL). |
| `isCurrentlyOfferingRewards` | Whether the business is currently active. |
| `affiliatePercentage` | Your commission percentage (if custom rate negotiated). |

## Referral URL Parameters

The `referralUrl` includes these tracking parameters:

| Parameter | Description |
|-----------|-------------|
| `ref` | Your unique referral code |
| `utm_source` | Always 'oshi' |
| `utm_medium` | Always 'referral' |
| `utm_campaign` | Format: 'ref_{code}' |
| `ttl` | Cookie lifetime in seconds |
| `policy` | Attribution policy (usually 'first') |

---

Full OpenAPI spec available at: /api/openapi
Interactive documentation at: /docs/api