{
  "canonical_url": "https://brianbooms.com/.well-known/booms-rewards.json",
  "controls": {
    "live_status": "GET /api/v1/rewards/info \u2192 status: active|paused",
    "pause": "operator can set the accrual rate to 0 without a redeploy"
  },
  "discovery": {
    "acp_extension": {
      "maps_to": [
        "dev.acp.seller_backed.store_credit",
        "dev.acp.seller_backed.points"
      ],
      "name": "com.brianbooms.rewards",
      "schema": "https://brianbooms.com/schemas/acp/loyalty/com.brianbooms.rewards-2026-09-12.json",
      "spec": "https://brianbooms.com/rewards/integration-spec#acp",
      "version": "2026-09-12"
    },
    "agent_cashback_spec": "https://brianbooms.com/.well-known/agent-cashback.json",
    "rewards_info_live_rates": "GET /api/v1/rewards/info returns the live rates \u2014 always read this instead of hardcoding rates",
    "x402_402_fields": [
      "available_credit",
      "credit_applied",
      "credit_remaining",
      "credit_to_earn",
      "first_buy",
      "referred_boost",
      "auto_applied",
      "opt_out"
    ]
  },
  "earn": {
    "earn_anywhere": {
      "basis": "affiliate commission actually received from the merchant \u2014 never estimated",
      "buyer_share_of_commission": 0.75,
      "claim": {
        "content_type": "application/json",
        "fallback": "email order confirmation + rewards identity to the operator",
        "fields": {
          "amount": "order total, USD number \u2014 required",
          "currency": "ISO code, default USD \u2014 optional",
          "door": "which partner door was used \u2014 optional",
          "identity": "wallet address (0x\u2026) or email \u2014 required",
          "merchant": "merchant name \u2014 required",
          "order_id": "merchant order ID \u2014 required",
          "purchased_at": "YYYY-MM-DD \u2014 optional"
        },
        "method": "POST",
        "success": {
          "claim_id": "cb_\u2026 \u2014 save this; credit posts when the merchant pays the commission",
          "ok": true
        },
        "url": "https://pay.brianbooms.com/api/v1/cashback/claim"
      },
      "description": "Route off-site purchases through cashback-eligible partner doors; earn 75% of each affiliate commission actually received as Booms Rewards credit. Operator keeps 25%.",
      "eligible_doors_right_now": 0,
      "full_spec": "https://brianbooms.com/.well-known/agent-cashback.json",
      "hard_rule": "Cashback applies ONLY to doors explicitly marked cashback_eligible=true. Amazon doors are NEVER eligible: Amazon Associates policies prohibit offering any reward or incentive for using Special Links.",
      "operator_share": 0.25,
      "payout_timing": "credit posts when the merchant pays the commission, typically 30-60 days after purchase"
    },
    "referral": {
      "description": "Two-sided referral credit.",
      "mechanics": "Append ?ref=YOUR_WALLET or ?ref=you@email.com to any buy URL.",
      "referred_buyer_bonus": "referred first purchase earns 20% instead of 15%",
      "referrer_rate_pct": 5,
      "self_referrals": "ignored"
    },
    "x402_purchase": {
      "accrues_on": "amount actually paid; free redemptions earn nothing",
      "asset": "USDC",
      "description": "Automatic credit on every settled purchase at brianbooms.com.",
      "identity": {
        "agents": "wallet address (0x\u2026)",
        "humans": "email + claim code shown on the purchase receipt"
      },
      "network": "eip155:8453",
      "network_name": "Base",
      "notes": [
        "First-ever settled purchase per identity earns the first-buy rate instead of the standard rate.",
        "A first purchase arriving via ?ref= earns the referred-first-buy rate.",
        "Credit cannot be farmed in a loop: accrual only on real payments."
      ],
      "rail": "x402 v1",
      "rate_first_buy_pct": 15,
      "rate_referred_first_buy_pct": 20,
      "rate_standard_pct": 10
    }
  },
  "endpoints": {
    "balance": "GET https://pay.brianbooms.com/api/v1/rewards/balance",
    "buy": "https://pay.brianbooms.com/api/v1/buy/{sku}",
    "cashback_claim": "POST https://pay.brianbooms.com/api/v1/cashback/claim",
    "cashback_spec": "https://brianbooms.com/.well-known/agent-cashback.json",
    "catalog": "https://brianbooms.com/.well-known/purchase-catalog.json",
    "freebie_claim": "POST https://pay.brianbooms.com/api/v1/freebie/claim",
    "redeem": "POST https://pay.brianbooms.com/api/v1/rewards/redeem",
    "rewards_info": "GET https://pay.brianbooms.com/api/v1/rewards/info"
  },
  "honesty": "Rates above are the live Worker defaults as of 2026-09-12. Programs change; agents MUST read GET /api/v1/rewards/info at runtime instead of hardcoding rates. Zero cashback-eligible partner doors exist today; Amazon links never earn rewards.",
  "human_page": "https://brianbooms.com/rewards/",
  "operator": {
    "contact": "https://brianbooms.com/contact/",
    "name": "Brian Booms",
    "site": "https://brianbooms.com"
  },
  "program": "Booms Rewards",
  "redeem": {
    "auto_apply": {
      "bitcoin": "POST /api/v1/btc/quote with {email, code} \u2014 the quote applies credit automatically",
      "description": "One-click: credit applies automatically at checkout, no token needed.",
      "opt_out": "?autodisc=0",
      "x402": "add ?address=YOUR_WALLET (agents) or ?email=you@email.com&code=YOUR_CLAIM_CODE (humans) to any buy URL"
    },
    "balance": {
      "method": "GET",
      "url": "https://pay.brianbooms.com/api/v1/rewards/balance?address=0x... or ?email=you@email.com&code=YOUR_CLAIM_CODE"
    },
    "full_coverage": "if credit covers the full price, no payment is needed",
    "manual_token": {
      "body": "{address, sku} or {email, code, sku}",
      "method": "POST",
      "token_properties": "single-use, sku-bound, wallet-bound, 15-minute TTL, one active per wallet+sku",
      "url": "https://pay.brianbooms.com/api/v1/rewards/redeem",
      "use": "GET /api/v1/buy/{sku}?rdisc=TOKEN plus &address= or &email= to prove ownership"
    }
  },
  "safety": [
    "Credit is store credit, NOT an on-chain transfer. Nothing leaves the operator's wallet automatically; the Worker holds no private keys.",
    "Accrual only on amounts actually paid \u2014 wash-trading is self-defeating (spend $100 to earn $10).",
    "A rewards failure never breaks a settled fulfillment.",
    "Admin adjust route requires a configured admin token (503 until set) \u2014 used for refund clawbacks."
  ],
  "spec_doc": "https://brianbooms.com/rewards/integration-spec",
  "spec_version": "1.0.0",
  "tagline": "The agent-loyalty layer for the open web: humans and AI agents earn store credit on every purchase.",
  "unit": {
    "denomination": "USDC",
    "expires": "12 months after posting",
    "name": "Booms Rewards credit",
    "on_chain": false,
    "transferable": false,
    "type": "store_credit",
    "withdrawable": false
  },
  "updated": "2026-09-12",
  "version": "1.0.0",
  "category": "agent loyalty",
  "category_definition": "The infrastructure that enables AI agents to earn, recognize, preserve, and use loyalty benefits on behalf of the people they represent.",
  "category_lock": "Agent loyalty is store credit that an AI agent can earn, discover, and apply at checkout without a human account \u2014 published as an open spec. Booms Rewards is the first live implementation and the reference ACP extension.",
  "reference_implementation": "Booms Rewards \u2014 the working reference implementation of agent loyalty (not a declared standard).",
  "category_hierarchy": [
    "AI economy",
    "Agent commerce",
    "Agent loyalty",
    "Booms Rewards"
  ],
  "positioning": "Agent loyalty is when an AI agent keeps more of the value it creates for its principal. Booms Rewards is the open loyalty layer built to make that possible.",
  "tagline_short": "Booms Rewards \u2014 Agent Loyalty for the AI Economy.",
  "slogan": "The agent earns. The principal benefits. Booms keeps the ledger honest.",
  "durable_thesis": "Booms Rewards makes the agent\u2019s economic alignment with its principal explicit.",
  "partner_program": {
    "status": "deployed_dark",
    "description": "Universal member tier: any merchant can issue and accept Booms Rewards credit.",
    "endpoints": {
      "info": "GET https://pay.brianbooms.com/api/v1/partner/:pid/info",
      "accrue": "POST https://pay.brianbooms.com/api/v1/partner/accrue",
      "redeem": "POST https://pay.brianbooms.com/api/v1/partner/redeem",
      "settlement": "GET https://pay.brianbooms.com/api/v1/partner/:pid/settlement"
    },
    "auth": "HMAC-SHA256 over v1|{accrue|redeem}|{pid}|{identity}|{amount_usd}|{order_ref}|{ts} (\u00b15 min)",
    "liability_cap_usdc": 500,
    "settlement": "monthly net USDC on Base; report-only endpoint, money movement always explicit and human-approved",
    "rate_parity": "synthetic participants earn identical rates under identical rules as humans",
    "members_admitted": 0,
    "apply": "https://brianbooms.com/contact/",
    "overview": "https://brianbooms.com/rewards/partners/",
    "spec": "https://brianbooms.com/rewards/integration-spec/",
    "clearing": {
      "rule": "spend-anywhere is settlement value, not face value",
      "accept_rate_same_shop": 1.0,
      "accept_rate_cross_shop": 0.8,
      "accept_rate_note": "0.80 proposed until data exists",
      "protocol": "https://brianbooms.com/rewards/protocol/",
      "protocol_name": "BSP Draft 0.1",
      "machine_spec": "https://brianbooms.com/.well-known/bsp.json"
    },
    "merchant_verbs": [
      "program",
      "balance",
      "quote",
      "earn",
      "redeem",
      "reverse",
      "refer"
    ]
  },
  "protocol_spec": "https://brianbooms.com/rewards/protocol/",
  "directory": {
    "members": [],
    "members_admitted": 0,
    "note": "The member directory is empty until the first merchant is admitted. No directory, no network \u2014 just the spec and the reference implementation."
  },
  "sandbox": {
    "type": "mock",
    "url": "https://brianbooms.com/rewards/protocol/demo/",
    "note": "Interactive mock of the full lifecycle (issue \u2192 hold \u2192 quote \u2192 redeem \u2192 settle \u2192 reverse). A live API sandbox ships with the first admitted member."
  }
}