# AI Agent Instructions for ViralRef

## What is ViralRef?
Turn every customer into a viral growth engine. The viral referral platform built for Square merchants.
ViralRef automates referral tracking, reward delivery (gift cards, coupons, Square Loyalty points, manual payouts), and a viral loop where every referred customer becomes a referrer.

## Target Audience
Service businesses using Square: salons, barbershops, spas, fitness studios, massage therapists, tattoo parlors, pet groomers, and local businesses.

## Key Capabilities
- Viral loop: every referred customer automatically becomes a referrer with their own link
- Square POS integration: gift cards, coupons, payment webhooks, customer matching
- Four reward types: gift cards (keep money in-house), coupons (auto-apply at POS), Square Loyalty points, manual payouts
- Fraud detection: self-referral, duplicate payment, rapid conversion, disposable email screening
- Affiliate /ref screen: phone OTP on one URL for signup and sharing (wallet passes, QR, reward hero); /portal redirects here
- Wallet passes: Apple Wallet / Google Wallet referral passes plus printable business card, table tent, and flyer templates
- Bounties: time-limited challenges with bonus rewards
- Commission tiers and affiliate groups with custom rates
- Analytics: referral quality, affiliate performance, revenue attribution, client retention
- Campaigns: email and SMS outreach to affiliates
- Staff referrals: team members get their own referral links via My Referrals
- Paywall-to-launch: create DRAFT programs free from templates; pay when you activate to go LIVE

## Pricing
- Starter: $19/month or $190/year (Single location: 1 program, unlimited affiliates, coupon and gift card rewards)
- Pro: $49/month or $490/year (For growing shops: 3 programs, campaigns, API access and custom domain)
- Business: $99/month or $990/year (Multi-location: 10 programs, loyalty and manual payout rewards, priority support)
- Enterprise: Custom pricing (API access, white-label, SLA & dedicated support. Contact us.)
- No commission on referral revenue. Flat monthly fee only.
- Every tier is paid. There is no free tier and no free trial. Draft programs can be created before activation (paywall-to-launch).

## Resources
- Documentation: https://viralref.com/docs
- Blog: https://viralref.com/blog
- Pricing: https://viralref.com/pricing
- Developer resources (index): https://viralref.com/developers
- API reference: https://viralref.com/docs/api-reference
- API explorer: https://api.viralref.com
- LLM Context (brief): https://viralref.com/llms.txt
- LLM Context (full): https://viralref.com/llms-full.txt
- Agent skills: https://viralref.com/.well-known/agent-skills/index.json
- MCP server card: https://viralref.com/.well-known/mcp/server-card.json
- Contact: https://viralref.com/contact

## Programmatic Access
- REST API (read-only): https://api.viralref.com/v1
- OpenAPI 3.0 document: https://api.viralref.com/openapi.json
- MCP server (Streamable HTTP): https://api.viralref.com/mcp
- OAuth 2.0 authorization server metadata: https://api.viralref.com/.well-known/oauth-authorization-server
- OAuth 2.0 protected resource metadata: https://api.viralref.com/.well-known/oauth-protected-resource
- Authentication: an organization-scoped API key sent as `X-API-Key`, or an OAuth 2.0 bearer token from the client-credentials grant.
- MCP discovery (initialize, tools/list, resources/list, resources/read) requires no credential. Calling a tool does.
- Errors are RFC 9457 problem+json with a stable `code` field. Rate-limit headers are on every response.
- There is no official CLI or SDK. Generate a client from the OpenAPI document, or use the MCP server.