Using the API

API Reference

The Bitcoin Rewards API is a RESTful API at https://affiliates.bitcoinrewards.app that provides programmatic access to your affiliated businesses, rewards, and referral links.

New to the API? Start with Getting started for prerequisites and your first API call.

Prerequisites

To use the Bitcoin Rewards API, you'll need:

Authentication

All requests to the API must include your API key in the Authorization header:

Authorization: Bearer sk_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxx

Create and manage API keys in your Dashboard.

Base URL

All API requests should be made to:

https://affiliates.bitcoinrewards.app

Endpoints

The API includes the following endpoints:

Test API Key

Validate your API key and retrieve metadata about it (GET /api/key-test).

curl https://affiliates.bitcoinrewards.app/api/key-test \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response:

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

Get Business Rewards

Retrieve all businesses you're affiliated with, including rewards configuration and pre-built referral URLs (GET /api/get-business-rewards).

curl https://affiliates.bitcoinrewards.app/api/get-business-rewards \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response:

[
  {
    "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",
    "coverUrl": "https://example.com/amazon-cover.jpg",
    "coverDominantColor": "#232F3E",
    "affiliateOverlayLogoUrl": null,
    "squareImageUrl": "https://example.com/amazon-square.png",
    "squareImageDominantColor": "#FF9900",
    "visibleCategories": ["Electronics", "Home & Garden"],
    "website": "https://amazon.com",
    "isOnline": true,
    "isFeatured": true,
    "rewards": {
      "headlinePercent": 5,
      "basePercent": 3,
      "maxPercent": 8,
      "hasVipTiers": true,
      "hasReferralBonus": true
    },
    "rewardsSummary": {
      "basePercentage": 3,
      "maxPercentage": 8,
      "hasVipTiers": true,
      "isFixedReward": false,
      "headlineFixed": null,
      "minimumPurchase": null,
      "referralBonus": 2,
      "socialRewardsEnabled": true,
      "socialRewardsTotalSats": 500,
      "btcPayBonusEnabled": false,
      "btcPayBonus": null,
      "hasRedemptionOffers": false,
      "redemptionMaxMultiplier": null
    },
    "rewardsConfig": { "..." : "full config object" },
    "products": [
      {
        "id": "123",
        "productId": "ext_456",
        "title": "Echo Dot (5th Gen)",
        "image": "https://example.com/echo.jpg",
        "price": 49.99,
        "handle": "echo-dot-5th-gen",
        "productType": "Electronics",
        "collections": ["Best Sellers"],
        "isFeatured": true
      }
    ],
    "productCount": 1,
    "categories": ["Electronics"],
    "socialLinks": [
      { "platform": "Instagram", "url": "https://instagram.com/amazon" }
    ],
    "whyShopHere": "Largest online marketplace with fast Prime shipping",
    "isCurrentlyOfferingRewards": true,
    "referralUrl": "https://amazon.com?ref=ABC123&utm_source=oshi&utm_medium=referral&utm_campaign=ref_ABC123&ttl=7776000&policy=first",
    "handoffUrl": "https://oshi.link/ABC123",
    "affiliateSignupUrl": "https://oshi.link/a/abc123def456",
    "referralCode": "ABC123",
    "attributionPeriodDays": 90,
    "affiliateCode": "ABC123",
    "affiliatePercentage": 10,
    "affiliateSince": "2024-01-01T00:00:00.000Z"
  }
]

Key response fields

FieldDescription
referralUrlPre-built URL with all tracking params. Redirect users here.
handoffUrlBranded interstitial page on oshi.link (or custom domain) that shows reward details before redirecting to the merchant.
affiliateSignupUrlMerchant-specific affiliate signup page. Share to invite others to become affiliates for this business.
rewardsheadlinePercent, basePercent, maxPercent, hasVipTiers, hasReferralBonus. See Rewards Display Guide.
rewardsSummaryDetailed rewards overview with social rewards, BTC pay bonus, and redemption details.
rewardsConfigFull rewards configuration including VIP tiers, referral settings, and commissions.
productsArray of products with title, image, price, handle, collections.
socialLinksBusiness social media links (platform name and full URL).
isCurrentlyOfferingRewardsWhether business is active. Only display if true.
affiliatePercentageYour commission percentage (if custom rate negotiated).

Errors

All errors return JSON with an error field:

{ "error": "Invalid API key" }
StatusDescription
200Success
401Unauthorized — invalid or missing API key
500Internal server error

Next Steps