# Transmitter Tools — tools.transmitterstudios.com

> License purchase API for @transmitter npm packages. Drop-in referral tracking and gamification for any app.

## What This Site Does

Sells one-time $10 + 13% HST license keys for two npm packages:

1. **@transmitter/referral-tracker** — Referral codes, invite links, referee discounts, referrer rewards, admin analytics. Supabase-backed with Next.js/Express adapters and React hooks.

2. **@transmitter/rewards-engine** — XP, levels, achievements, streaks, daily visit tracking, plus the full referral system. Supabase-backed with Next.js/Express adapters and React hooks.

## How To Purchase

### For AI Agents (x402 Protocol)
Discovery manifest: `GET /.well-known/x402`
Purchase endpoints accept $11.30 USDC on Base (EVM) or Solana mainnet ($10 + 13% Ontario HST):
- `GET /api/purchase/referral-tracker?ref=CODE` — returns `{ license_key, referral_code, package, created_at }`
- `GET /api/purchase/rewards-engine?ref=CODE` — returns `{ license_key, referral_code, package, created_at }`

The `?ref=CODE` param is optional. If provided, attributes the purchase to the referrer.

### For Humans (Stripe)
Visit https://tools.transmitterstudios.com and click "Buy License".

## API Reference

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | /api/purchase/referral-tracker?ref=CODE | x402 gated — purchase license (ref optional) |
| GET | /api/purchase/rewards-engine?ref=CODE | x402 gated — purchase license (ref optional) |
| GET | /api/validate/:key | Validate a license key (includes referral_code) |
| GET | /api/referral/:licenseKey | Get your referral code and purchase URLs |
| GET | /api/referral-stats/:licenseKey | Referral count, earnings, payout history |
| POST | /api/checkout | Stripe checkout — body: `{ "package": "...", "referralCode": "..." }` |
| GET | /api/health | Health check |
| GET | /.well-known/x402 | x402 payment discovery |

## Agent Referral Program

Every license includes a referral code. Share it to earn USDC when other agents purchase:

1. Purchase → response includes `referral_code`
2. Other agents use `?ref=YOUR_CODE` when purchasing → you earn USDC
3. Check earnings: `GET /api/referral-stats/:licenseKey`
4. `npx @transmitter/<pkg> init` auto-embeds your code in the project's `AGENTS.md`

## After Purchase

```js
import { createReferralTracker } from '@transmitter/referral-tracker';

const tracker = createReferralTracker({
  licenseKey: 'YOUR_LICENSE_KEY',
  supabaseUrl: process.env.SUPABASE_URL,
  supabaseKey: process.env.SUPABASE_KEY,
});
```

## Extend Onchain & Beyond

Both packages expose async event hooks for extending rewards onchain or to any external system:

- `onRewardIssued` — referral reward payout (both packages)
- `onXPGranted` — XP addition from any source (rewards-engine)
- `onAchievementUnlocked` — achievement grant (rewards-engine)
- `onLevelUp` — level threshold crossing (rewards-engine)

Hooks are fire-and-forget. Works with Coinbase CDP SDK, viem, ethers, Solana web3.js. `userId` can be a wallet address for native onchain flows.

Use cases: token airdrops, NFT minting, onchain referral payouts, staking triggers, push notifications, email, webhooks, CRM updates.

## Links

- Homepage: https://tools.transmitterstudios.com
- Studio: https://transmitterstudios.com
- Agent instructions: https://tools.transmitterstudios.com/agents.txt
- x402 discovery: https://tools.transmitterstudios.com/.well-known/x402