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 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 ($0.05, one-time)

Provision via the x402-gateway tool raas_project_provision — unpaid calls get a 402 challenge; after the USDC settlement the gateway creates the project and returns your API key — it is shown only once:

POST https://x402.freeq.one/tools/raas_project_provision
{
  "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://freeq.one/XSEUCT"
}

3. Track clicks

When someone clicks https://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 — payer's cumulative spend is past min_payer_total_spend_usd:
{
  "credited": true,
  "credits": 40,
  "payer": "0x...",
  "txHash": "0x...",
  "refCode": "XSEUCT",
  "payerTotalSpend": 12.0
}

# Response — same payer, still below the floor (recorded, not yet paid):
{
  "credited": false,
  "credits": 0,
  "payerTotalSpend": 4.0,
  "pendingPayerCap": true,
  "minRequired": 10.0
}

# Response — this settlement was already reported (replay guard):
{ "duplicate": true, "txHash": "0x..." }

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

5. Redeem

A ref code is public — it is in every shared link — so redeeming requires proof of the referrer wallet. The referrer signs a canonical one-line message with personal_sign (EIP-191):

raas:redeem:XSEUCT:0x1a2b...9f0e:1760000000

# ref code upper-cased, wallet lower-cased; issued_at in unix seconds.
# Then, within 5 minutes of issued_at:
POST /v1/raas/redeem
{
  "refCode": "XSEUCT",
  "wallet": "0x1a2b...9f0e",
  "signature": "0x...",
  "issuedAt": 1760000000
}

# Response — a 5-minute JWT, and the balance is consumed (oldest credit first):
{
  "token": "eyJ...",
  "sku": "fetch:dc:bundle",
  "requestsRemaining": 40,
  "expiresAt": "2026-10-10T07:55:00+00:00"
}

RaaS recovers the signer from the signature and compares it to the ref code's referrer wallet: a signature that does not belong to that wallet is rejected, and a captured signature can only ever re-mint a JWT for the same referrer, never for someone else.

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, signed by the referrer wallet and consumed oldest-credit-first. 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's spend accrues on every verified settlement and commission starts on the payment whose cumulative total clears min_payer_total_spend_usd — never before. max_outstanding caps total unredeemed credits per project, duplicate tx_hash values are rejected as replays, a payer who is also the referrer is blocked as self-referral, and credit that goes unredeemed for credit_expiry_days is written off.

How we make money

Provisioning is the only charge: a one-time $0.05 (paid in USDC on Base via x402 — the raas_project_provision tool). No listing fee, no subscription, no per-conversion rake, and no cut of the credits a merchant issues afterward.

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:

freeq.one/{code}  (Cloudflare edge worker → KV)
       │
       ▼
  https://api.freeq.one/r/{code}  (api-gateway)
       │
       ▼
  raas service (FastAPI) — logs click, 302 ?ref={code}
       │
       ▼
  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
• Referrer — an EIP-191 signature from the referrer wallet, for redemption only

Public

Project self-service (x-api-key)

Referrer (EIP-191 signature)

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 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.