RaaS: Referral-as-a-Service

Today we're releasing Referral-as-a-Service (RaaS) — a short-link referral system that turns verified on-chain x402 payments into referral credits. Create trackable referral links in one API call. Conversions are proven against Base settlement, not self-reported clicks.

Why RaaS?

Existing referral platforms take 15-30% cuts, pay out on 30-day cycles, and lock you into their ecosystem. RaaS is different:

• One API call — create a referral link, get a 6-char short code at go.freeq.one/{code}
• Cryptographically verified conversions — every credit is backed by an x402 settlement the platform independently re-verifies against Base via the Coinbase CDP facilitator. No trust-me-bro postbacks
• Instant crediting — the ledger entry lands the moment settlement verifies, not on a 30-day cycle
• Self-serve — no sales calls, no onboarding queue. Register a project, get an API key, start generating links
• Privacy-preserving — click logging uses truncated IP prefixes, not full addresses

How it works

1. Create a project

Projects can be self-provisioned. Call the create endpoint with your desired config and store your API key — it is shown only once:

POST /v1/raas/admin/project
{
  "name": "My App",
  "landing_url": "https://myapp.com",
  "referral_rate": 0.20,
  "credit_per_dollar": 200,
  "max_outstanding": 10000
}

# Response (apiKey shown once — it cannot be retrieved again):
{
  "projectId": "d0256586-...",
  "apiKey": "raas_...",
  "warning": "Store apiKey now — it cannot be retrieved again."
}

On creation, the platform sets defaults you can later tune: referral_rate, credit_per_dollar, max_outstanding, and your landing_url. Your API key is shown once — store it securely.

2. Generate referral links

Your backend calls RaaS to create a unique short link for each referrer:

POST /v1/raas/link
x-api-key: your-api-key
{
  "projectId": "your-project-id",
  "referrerWallet": "0x..."
}

# Response:
{
  "refCode": "XSEUCT",
  "shortLink": "https://go.freeq.one/XSEUCT"
}

3. Track clicks

When someone clicks https://go.freeq.one/XSEUCT, RaaS:

1. Logs the click (truncated IP, user-agent, referrer)
2. Returns a 302 redirect to your landing URL with ?ref=XSEUCT
3. Sets cache-control: no-store — every click is counted

4. Report the conversion

When a referred user pays, your backend forwards the x402 settlement to RaaS. RaaS re-verifies it against Base through the CDP facilitator, extracts the payer wallet, transaction hash, and USD amount, and writes a credit ledger entry against the referrer's ref code:

POST /v1/raas/credit
x-api-key: ***
{
  "refCode": "XSEUCT",
  "paymentPayload": { ... },
  "paymentRequirements": { ... }
}

# Response:
{
  "credited": true,
  "credits": 40,
  "payer": "0x...",
  "txHash": "0x...",
  "refCode": "XSEUCT"
}

Credits are computed straight from the verified on-chain amount:

credits = amount_usd × credit_per_dollar × referral_rate

# $1.00 settlement, credit_per_dollar=200, referral_rate=0.20
#   -> 1.00 × 200 × 0.20 = 40 credits

Who pays whom

This is the part most referral platforms are vague about, so here it is explicitly. There are three parties and exactly one movement of money:

  Referred user ──── USDC on Base (x402) ────▶ Merchant
                             │
                             │  merchant forwards settlement proof
                             ▼
                       RaaS verifies via CDP
                             │
                             │  credits = amount_usd × credit_per_dollar × referral_rate
                             ▼
                  Referrer's credit ledger (+40)
                             │
                             │  POST /v1/raas/redeem
                             ▼
                  Short-lived JWT ──▶ API access

• The referred user pays the merchant. That is the only USDC transfer in the system, and it goes wallet-to-wallet on Base. RaaS is not in the path.
• The merchant funds the reward by choosing credit_per_dollar and referral_rate. The cost of a referral is denominated in the merchant's own service credits, not in cash out of a balance RaaS holds.
• The referrer is paid in credits, not USDC. A credit balance redeems via /v1/raas/redeem for a 5-minute JWT granting API requests. There is no withdraw endpoint, and none is planned.
• RaaS never custodies funds. It holds no float, signs no transfers, and cannot move a referrer's balance off-platform. It reads settlement proofs and writes ledger rows.

Guardrails protect the merchant, not the platform: a payer must clear min_payer_total_spend_usd before counting, max_outstanding caps total unredeemed credits per project, duplicate tx_hash values are rejected as replays, and a payer who is also the referrer is blocked as self-referral.

How we make money

Directly: we don't. RaaS charges no listing fee, no subscription, no per-conversion rake, and takes no cut of the credits a merchant issues. Project creation is open and free. There is no billing code in the service, and that is deliberate rather than unfinished.

The business model is the redemption side. Credits are only ever worth API calls against the x402-gateway, so every referral a merchant funds ends as demand for metered gateway capacity — priced per call, paid in USDC, on the same rail. RaaS is distribution for that gateway: merchants get a conversion-tracking layer they'd otherwise build themselves, referrers get usable credit instead of a $5 payout waiting on a 30-day cycle, and we get the traffic. If you never redeem a credit, we never earn on it.

The honest caveat: because rewards are credits, RaaS suits businesses whose referrers actually want API access. If your referrers want cash, this is the wrong tool and we'd rather say so than sell you a payout feature that doesn't exist.

Architecture

RaaS runs as a Python FastAPI service on Railway, backed by Postgres. It sits behind the same api-gateway that serves our x402 paywall tools:

go.freeq.one/{code}
       │
       ▼
  api-gateway (Caddy)
       │
       ▼
  raas service (FastAPI)
       │
       ▼
  Postgres (projects, links, clicks)

API reference

Three tiers, three auth schemes:

• Public — short-link redirect, project creation, no auth
• Project self-service — x-api-key header, read/update own project and read own ledger

Public

Project self-service (x-api-key)

Platform admin (remaining endpoints)

Project creation is open. The remaining admin endpoints (list all projects, update another project, rotate another's key) require the platform bearer token and are reached over the internal Railway hostname only.

Hosted service

RaaS is a managed service — there is nothing to deploy or operate. The API is live behind the same api-gateway that fronts our x402 paywall tools, and short links resolve at go.freeq.one with no setup on your side.

You keep control of the parts that matter: your own landing_url, referral rate, credit conversion, and outstanding-credit ceiling are all per-project settings you define at registration and can change at any time. Referrer balances live in the RaaS ledger keyed to the ref code and redeem for API access — RaaS never custodies referrer funds and never moves USDC on anyone's behalf.

Short links. Verified conversions. Credit-only rewards, no middlemen.