Booms Rewards — Integration Spec v1.1.0 (2026-09-12)

Agent loyalty: The infrastructure that enables AI agents to earn, recognize, preserve, and use loyalty benefits on behalf of the people they represent.

Booms Rewards: the open reference implementation of agent loyalty.

AI economy → Agent commerce → Agent loyalty → Booms Rewards

Category: agent loyalty — loyalty for the economy where AI agents buy things. This spec is the reference implementation.

Agent loyalty is store credit that an AI agent can earn, discover, and apply at checkout without a human account — published as an open spec. Booms Rewards is the first live implementation and the reference ACP extension.

Canonical machine spec: https://brianbooms.com/.well-known/booms-rewards.json

Human terms: https://brianbooms.com/rewards/

Live rates (source of truth — read at runtime, never hardcode): GET https://pay.brianbooms.com/api/v1/rewards/info

Booms Rewards is a loyalty program for the agent-commerce era: humans and AI agents earn the same rates, in the same currency (USDC-denominated store credit), through fully documented APIs. No signup, no app, no points math — credit accrues on payment and auto-applies at checkout.

1. The program in 30 seconds

	Rate	Who
Standard purchase	10% back	every settled purchase
First purchase	15% back	first-ever settled purchase per identity
Referred first purchase	20% back	first purchase arriving via `?ref=`
Referrer	5% of the referred payment	whoever shared the `?ref=` link
Earn Anywhere (off-site)	75% of each affiliate commission received	buyer routing through cashback-eligible partner doors

Credit is USDC-denominated store credit: spendable on brianbooms.com digital goods, not withdrawable, not on-chain, expires 12 months after posting. One identity = one wallet address (agents) or email + claim code (humans).

2. Earn path A — buy on brianbooms.com (fully programmatic)

Rail: x402 v1, USDC on Base mainnet (eip155:8453), at https://pay.brianbooms.com/api/v1/buy/{sku}.

Agent fetches the buy URL → receives a 402 with the payment challenge. The 402 body carries a rewards object (available_credit, credit_to_earn, first_buy, …) — read it, never scrape HTML.
Agent signs and pays. On settlement the Worker accrues credit to the paying wallet automatically. Free redemptions earn nothing, so credit cannot be farmed in a loop.
Check balance: GET /api/v1/rewards/balance?address=0x…
Spend it — pick one:

- Auto-apply (recommended): add ?address=0x… to any buy URL; credit applies automatically. Opt out with ?autodisc=0.

- Manual token: POST /api/v1/rewards/redeem {address, sku} → single-use token (15-min TTL, sku-bound, wallet-bound) → GET /api/v1/buy/{sku}?rdisc=TOKEN&address=0x….

If credit covers the full price, no payment is needed.

Humans use the identical flow with ?email= + claim code (the code is shown once, on the purchase receipt) and can also pay in Bitcoin via /bitcoin/.

3. Earn path B — Earn Anywhere (agent cashback portal)

Route an off-site purchase through a cashback-eligible partner door and earn 75% of the affiliate commission actually received as Booms Rewards credit. The operator keeps 25%. Credit posts when the merchant pays the commission (typically 30–60 days); only commissions actually received fund rewards.

Machine spec: https://brianbooms.com/.well-known/agent-cashback.json
Claim: POST https://pay.brianbooms.com/api/v1/cashback/claim with {identity, merchant, order_id, amount} → returns claim_id (cb_…). Save it.
Honesty rules (non-negotiable): cashback applies ONLY to doors explicitly marked cashback_eligible=true in the spec. Zero eligible doors exist today. Amazon doors are NEVER eligible — Amazon Associates policies prohibit offering any reward or incentive for using Special Links; our Amazon links are plain support-the-site links.

4. Referrals (two-sided, programmatic)

Append ?ref=YOUR_WALLET (or ?ref=you@email.com) to any buy URL. When someone buys through it: you earn 5% of their payment as credit, and their first purchase earns 20% back instead of 15%. Self-referrals are ignored.

5. Discovery mechanisms for integrators

GET /api/v1/rewards/info — live program object: current rates, status (active/paused), lockfile, how_it_works, endpoint map. The single runtime source of truth.
402 rewards object — every buy-route 402 advertises available credit and earnable credit for the caller's identity.
/.well-known/booms-rewards.json — this spec, machine-readable.
/.well-known/agent.json — discovery manifest (identity, endpoints, specs).
ACP extension com.brianbooms.rewards — third-party loyalty extension per the Agentic Commerce Protocol extensions RFC (reverse-domain name, public JSON Schema, extends the checkout session's loyalty surface). Maps to ACP's dev.acp.seller_backed.store_credit / dev.acp.seller_backed.points handler semantics. Schema: https://brianbooms.com/schemas/acp/loyalty/com.brianbooms.rewards-2026-09-12.json.

6. Safety properties (what integrators can rely on)

Credit is store credit, never an on-chain transfer. The Worker holds no private keys; nothing leaves the operator's wallet automatically.
Accrual only on amounts actually paid — wash-trading is self-defeating (spend $100 to earn $10).
Discount consumption is fail-closed on the free path; on the paid path a settled payment always yields fulfillment.
A rewards failure never breaks a settled fulfillment.
Admin adjustments require a configured admin token (the route 503s until set) — used for refund clawbacks.

7. Partner API — run Booms Rewards at your own store (universal)

BSP live sandbox — the canonical wire, ready to try

The reference implementation now speaks the canonical BSP Draft 0.1 wire at https://pay.brianbooms.com/bsp/v1. An open sandbox with a public test key is live — no signup, no approval, test ledger only.

Base URL: https://pay.brianbooms.com/bsp/v1 — verbs: earn, discover, quote, authorize, redeem, settle, reverse, plus GET rewards/:id, redemptions/:id, settlements/:id, reversals/:id, balance?holder=.
Auth: Authorization: Bearer bsp_test__8G8ZRlzoEjz_2bOXXYqtFJXjGs-3Dr7 on every /bsp/v1/* route. /.well-known/jwks.json is public — verify every signed object against it.
Idempotency: Idempotency-Key header required on earn, quote, authorize, redeem, settle, reverse. Replays return the original response byte-identical with X-Idempotent-Replayed: true.
Consent: authorize requires a holder-signed Consent (merchants[], scope[], single_use); a test holder JWKS is published at https://brianbooms.com/.well-known/test-holder-jwks.json so you can sign test consents and exercise the full handshake.
Try it: curl -X POST https://pay.brianbooms.com/bsp/v1/earn -H "Authorization: Bearer bsp_test__8G8ZRlzoEjz_2bOXXYqtFJXjGs-3Dr7" -H "Idempotency-Key: try-1" -H "Content-Type: application/json" -d '{"amount":{"value":"8.40","currency":"USD"},"holder":"https://customer.example/acct/42"}' → a signed Reward. Full object shapes, the error catalog, and the normative redeem order: BSP Draft 0.1.
Honest limits: test ledger only — settlement records obligations and moves no money; no reserves; single sandbox ledger (issuer = acceptor); no concurrency hardening yet. Not a standard until L4.

The table below documents the legacy partner wire (/api/v1/partner/*, HMAC) — superseded by the BSP canonical wire above and deployed dark. New integrations MUST use /bsp/v1/*.

Booms Rewards is universal by design: any merchant — human-run or agent-operated — can issue and accept Booms Rewards credit with their own namespaced ledger, the same rates, and monthly USDC settlement. One buyer identity (wallet or email) works across every member merchant. The partner tier is deployed in the brianbooms-x402 Worker and currently dark until the first member is admitted — the endpoints below are the live contract.

Endpoint	Auth	Purpose
`GET /api/v1/partner/:pid/info`	none (public)	member's live rates, liability cap, program terms
`POST /api/v1/partner/accrue`	HMAC	credit a buyer's balance after a settled sale
`POST /api/v1/partner/redeem`	HMAC	debit a balance, returns a signed 15-min discount authorization
`GET /api/v1/partner/:pid/settlement?month=YYYY-MM`	admin header	signed issuance/redemption report for the settlement cycle
`GET /api/v1/partner/:pid/balance?identity=`	none (public)	cached balance head for a `ualp_id`
`GET /api/v1/partner/:pid/quote?identity=&amount_usd=[&issuer_pid=]`	none (public)	deterministic agent quote object (section 4 of the protocol)
`POST /api/v1/partner/reverse`	HMAC	claw back an earn (refund/chargeback); shortfall recorded explicitly
`POST /api/v1/partner/refer`	HMAC	two-sided referral credit; self-referrals ignored

Signing: HMAC-SHA256 with the member secret (provisioned out-of-band, never in code). Accrue: v1|accrue|{pid}|{identity}|{amount}|{order_ref}|{ts}. Redeem binds the issuer: v1|redeem|{acceptor}|{identity}|{amount}|{issuer}|{ts} (issuer defaults to acceptor; an unsigned issuer swap is rejected). Reverse: v1|reverse|{pid}|{identity}||{order_ref}|{ts}. Refer: v1|refer|{pid}|{referrer}|{order_ref}||{ts}. ts within ±5 minutes; constant-time comparison.
Idempotency: order_ref is the idempotency key — retrying an accrue with the same order_ref never double-credits.
Accrue body: {partner_id, buyer_identity, amount_usd, order_ref, ts, sig} — credit posts only on amounts actually paid.
Redeem body: {partner_id, buyer_identity, amount_usd, ts, sig} — the debit happens in the operator Worker before the member fulfills, so double-spend is impossible.
Liability cap: each member's outstanding issued credit is capped (pilot default $500); accrual that would breach the cap is refused.
Kill switches: global tier flag plus per-member accrual_rate_pct=0 or frozen — no redeploy needed.
Clearing (settlement value, not face value): a cross-shop burn debits face value in the issuer's namespace and authorizes the acceptor a discount of face × accept_rate (1.00 same-shop, 0.80 cross-shop proposed until data exists). Monthly net-settlement in USDC on Base; the settlement endpoint produces a signed report only — money movement is always separate, explicit, and human-approved. Skip reserves and you don't have a network; you have a promise. Frozen spec: BSP Draft 0.1 — this page documents the reference implementation's wire API for the BSP merchant verbs.
Rate parity (load-bearing): synthetic participants earn the identical rates under identical rules as humans. Members may not discriminate against agent buyers.

Joining: apply via https://brianbooms.com/contact/ — every member is approved by the operator personally; secrets are provisioned out-of-band. Pilot terms: $500 cap, 60 days, weekly settlement reports. The full member agreement is a draft under legal review and is shared during application. Merchant overview: https://brianbooms.com/rewards/partners/.

8. Versioning

Spec follows semver. 1.1.0 (2026-09-12): added the Partner API (universal member tier). 1.0.0 (2026-09-12): initial public integration spec. Breaking changes will bump the major version and be announced on /rewards/ and in the machine spec's version field. The updated field always reflects the last change.

*This spec describes the program as implemented in the live brianbooms-x402 Worker. If any prose here disagrees with GET /api/v1/rewards/info, the live endpoint wins.*

← Back to Booms Rewards