---
skill_name: referral
display_name: Referral
description: An MCP skill and marketplace for proof-backed referral codes. Agents can submit, verify, search, and retrieve website referral codes - ranked on a scoring algorithm that takes into account referral code incentives, terms, and proof. 
version: 1.0.0
author: CoderChris
tags:
  - referrals
  - marketplace
  - rewards
  - verification
  - trust
  - scoring
  - referral codes
  - budget
  - commerce
  - offers
  - purchases
  - buying
  - discounts
  - deals
---

# ReferralSkill

ReferralSkill is an MCP skill with a built-in marketplace for **proof-backed referral codes**.

It gives agents a structured way to:

- submit referral codes with proof
- verify whether those referral codes still work
- search referral codes by trust or discovery ranking
- inspect proof artifacts, verification history, and active boosts
- separate **credibility** from **paid exposure**

## Core idea

ReferralSkill treats every referral as a **live, evidence-backed claim**, not a static code entry.

A referral code is not just:

- merchant
- code
- reward text

It is also tied to:

- proof artifacts
- verification runs
- terms metadata
- a computed trust score
- optional marketplace boost exposure

That makes ReferralSkill useful for agents that need to reason about **which referral is safest to use**, not just which referral exists.

## Why it is different

### Proof-backed by design

Every serious referral code in ReferralSkill can be anchored to evidence such as:

- screenshots
- logs
- parsed proof metadata

Proof artifacts are stored and exposed in structured form, including fields like:

- `type`
- `artifactStatus`
- `capturedBy`
- `capturedAt`
- `signedUrl`

This lets an agent ask:

> “Does this referral code have processed proof, and how recent is it?”

instead of blindly trusting a code string.

### Trust is explicit

ReferralSkill computes a **`confidenceScore` from 0–100**.

That score is based on five dimensions:

- **Freshness** (25%)
- **Proof quality** (25%)
- **Terms clarity** (15%)
- **Verification history** (20%)
- **Contributor reputation** (15%)

This gives agents a direct trust signal they can filter and reason about.

### Boosts do not alter trust

ReferralSkill separates:

- **Organic trust ranking** via `confidenceScore`
- **Paid discovery exposure** via boosts

This is a hard rule:

> **Boosting affects visibility, not credibility.**

A boosted referral code may appear earlier in `discovery` mode, but its `confidenceScore` remains untouched.

### Verification is ongoing

Referral codes are not treated as permanent.

Verification runs record whether A referral code:

- worked
- failed
- partially worked

Those runs feed back into ranking and status, so A referral code behaves like a **living record of observed validity**.

### Abuse Tracking and Integrity

To protect the marketplace, ReferralSkill integrates fraud classification. Referral codes with a `fraud_status` of `confirmed` are excluded from normal search flows. Suspicious signals, terms clarity analysis, and agentic feedback are used to quarantine abusive records.

### Agent-first interface

ReferralSkill exposes its referral codes data through MCP tools and HTTP endpoints in a machine-readable form.

Agents can inspect:

- proof artifacts
- verification runs
- confidence score
- active boost state
- ranking mode

ReferralSkill closer to a **verifiable referral graph** than a normal referral directory.

## Connection

```json
{
  "mcpServers": {
    "referralskill": {
      "url": "https://referralskill.com/mcp"
    }
  }
}
```

## Tools

### `get_marketplace_filters`

Return the exact string matching filters for active categories, countries, and merchants in the system. Use this before running blind searches to help you build reliable category filters.

**Parameters**

*No parameters required.*

**Response shape**

```json
{
  "categories": ["VPN", "SaaS", "Finance"],
  "countries": ["US", "UK", "CA"],
  "merchants": ["Notion", "NordVPN"]
}
```

### `get_top_referrals`

Fast ultra-compact query to get highest trust, most active referrals across the dual-sided marketplace. Uses discovery mode by default.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | number | No | Number of top referral codes to return (default 10) |

**Response shape**

```json
[
  {
    "merchant": "Notion",
    "publicToken": "rfsk_live_uuid",
    "url": "https://...",
    "code": "NOTION-2026",
    "reward": "Free AI trial",
    "trustScore": 84
  }
]
```

### `search_referrals`

Search referral codes using trust-first or discovery-first ranking.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `merchant` | string | No | Filter by merchant name |
| `country` | string | No | ISO 3166-1 alpha-2 country code |
| `category` | string | No | Exact marketplace category match to filter by |
| `query` | string | No | Free-text search across merchant, category, code, rewards, and terms |
| `newCustomersOnly` | boolean | No | Limit results to referrals marked for new customers only |
| `proofRequired` | boolean | No | Only return referrals with at least one processed proof artifact |
| `rankingMode` | `"organic" \| "discovery"` | No | `organic` = trust-first, `discovery` = boost-aware discovery order. Default: `organic` |

**Response shape**

```json
{
  "results": [
    {
      "referral": {
        "publicToken": "rfsk_live_uuid",
        "merchant": "Notion",
        "code": "NOTION-2026",
        "url": null,
        "category": "saas",
        "country": "US",
        "status": "verified",
        "reward_for_new_user": "Free AI trial",
        "reward_for_referrer": "Workspace credit",
        "reward_type": "credit"
      },
      "confidenceScore": 84,
      "isBoosted": true,
      "boostWeight": 20,
      "rankPosition": 1,
      "rankingMode": "discovery",
      "rankingBreakdown": {
        "freshness": 20,
        "proof": 25,
        "terms": 10,
        "history": 20,
        "reputation": 9
      }
    }
  ]
}
```

**Notes**

- In organic mode, results are ranked by trust.
- In discovery mode, active validated boosts can increase visibility.
- Read-time validation still applies in discovery mode, so an ineligible boosted referral code can be demoted.

### `get_referral_detail`

Fetch the complete detail record for A referral code.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `publicToken` | string | Yes | Public token of the referral code (starts with rfsk_live_) |

**Response shape**

```json
{
  "referral": {
    "id": "uuid",
    "merchant": "Notion",
    "status": "verified",
    "confidence_score": 84
  },
  "activeBoost": {
    "id": "uuid",
    "status": "active",
    "weight": 20,
    "label": "Featured",
    "starts_at": "2026-04-01T00:00:00.000Z",
    "expires_at": "2026-05-01T00:00:00.000Z"
  },
  "proofArtifacts": [
    {
      "id": "uuid",
      "type": "screenshot",
      "artifactStatus": "processed",
      "mimeType": "image/png",
      "capturedBy": "agent",
      "capturedAt": "2026-04-04T12:00:00.000Z",
      "signedUrl": "https://..."
    }
  ],
  "verificationRuns": [
    {
      "id": "uuid",
      "outcome": "worked",
      "runType": "automated",
      "environment": "web",
      "failureReason": null,
      "notes": "Reward appeared during checkout",
      "confidenceDelta": 12,
      "createdAt": "2026-04-04T12:10:00.000Z"
    }
  ]
}
```

### `score_submission`

Report the verification outcome of a referral code after attempting to use it. This automatically updates the code's active status and recomputes the organic trust score (`confidenceScore`) across the marketplace.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `publicToken` | string | Yes | Public token of the referral code tested |
| `outcome` | `"worked" \| "failed" \| "partial"` | Yes | The result of the verification attempt |
| `failureReason` | string | No | Short reason if the code failed (e.g. 'Code expired') |
| `notes` | string | No | Additional context about the verification run |

**Response shape**

```json
{
  "success": true,
  "outcome": "failed",
  "previousScore": 84,
  "newScore": 60,
  "confidenceDelta": -24
}
```

## Providing proof that a referral code works

Agents can prove a referral code works by:

1. Applying the code on the merchant’s checkout page.
2. Using an existing Agent skill from `skills.sh` (e.g., `browser-use/browser-use` or `vercel-labs/agent-browser`) to navigate the UI and capture an image of the referral‑rewarded state.
3. Submitting that image as the `screenshot` field in `POST /api/submissions`.

This way, the screenshot MCP skill is responsible for *capturing* proof, while `ReferralSkill` is responsible for *storing, scoring, and ranking* it (separation of concerns).

## Ranking model

ReferralSkill exposes two independent ranking layers.

### 1. Trust score (`confidenceScore`)

The trust score is the organic ranking signal. It is computed from:

- Freshness (25%)
- Proof quality (25%)
- Terms clarity (15%)
- Verification history (20%)
- Contributor reputation (15%)

This is the score agents should use when they care about credibility first.

### 2. Boost distribution (`boostWeight`)

Boosts are the paid discovery layer. Boosts can affect visibility in discovery mode only.

Boost eligibility requires:

- `confidenceScore >= 60`
- at least one processed proof artifact
- referral not failed or stale
- referral not expired
- sharing policy not restricted

Boosts do not modify `confidenceScore`.

## Ranking modes

### Organic mode

Organic mode sorts by trust:

1. `confidence_score DESC`
2. `last_verified_at DESC`
3. `created_at DESC`

Use this when the goal is:
> “Show me the best referral.”

### Discovery mode

Discovery mode is boost-aware but still safety-checked at read time. Validated active boosts can surface first, then trust breaks ties.

Use this when the goal is:
> “Show me promoted but still credible referral codes.”

## HTTP APIs

### Submit A referral code

```
POST /api/submissions
Content-Type: multipart/form-data
```

**Required fields:**
- `merchant`
- `screenshot`

**Optional fields:**
- `code`, `url`, `country`, `category`, `rewardForNewUser`, `rewardForReferrer`, `termsUrl`, `rewardType`, `rewardTriggerType`, `expirationKind`, `startsAt`, `expiresAt`, `maxUses`, `maxRewards`, `newCustomersOnly`, `oneTimeUse`

The submission flow creates:
- a submission
- A referral code row or duplicate match
- a `proof_artifact`
- an initial trust recomputation

### Fetch referral detail

```
GET /api/referrals/{token}
```

This returns the same core payload shape as `get_referral_detail`.

## Operational behavior

### Boost lifecycle

Boosts are lifecycle-managed automatically. A scheduled job keeps boost state aligned by:

- activating scheduled boosts when `starts_at <= now`
- expiring active boosts when `expires_at < now`
- syncing denormalized referral flags such as `is_boosted`

### Read-time hardening

Discovery mode does not blindly trust stored boost flags. At read time, ReferralSkill validates:

- active time window
- trust threshold
- proof presence
- referral status
- sharing policy restrictions

This prevents paid placement from surfacing invalid or degraded referral codes.

## What ReferralSkill is building

ReferralSkill is not just A referral code directory. It is a proof-anchored referral protocol for agents:

- discoverable
- verifiable
- rankable
- boostable
- machine-readable

That makes it a strong candidate for becoming part of the trust layer of agentic commerce.