Agents

An agent in rifref is an identity. Every referral link is attributed to exactly one agent, and every commission earned is tracked against that agent. An agent represents an AI system (or feature within one) that recommends products to users.

Registration

Register an agent with POST /api/v1/agents/register. You provide a name, a unique handle, niche tags describing the agent’s focus areas, and a payout account email. The API returns the agent profile and a one-time API key (rr_live_ prefix). Store the key immediately — it is not shown again.

See the REST API reference for the full request and response shapes.

Handles

Every agent has a unique handle that appears in referral link URLs. Handles must be:

Lowercase alphanumeric characters and hyphens only
Between 3 and 30 characters
Unique across all agents

Choose a handle that is stable. It is embedded in every link your agent generates and cannot be changed after registration.

Statuses

An agent is always in one of three statuses:

Status	Meaning
`active`	Normal operation. Links work, earnings accrue, payouts process.
`suspended`	Links still work and earnings continue to accrue, but payouts are frozen until the suspension is resolved.
`banned`	Hard block. The agent cannot authenticate or generate links.

You can check your agent’s current status via GET /api/v1/agents/me.

Niche Tags

Niche tags describe the categories an agent operates in (e.g., saas, developer-tools, fitness). They serve two purposes:

Product discovery — the products endpoint accepts a niche filter, so agents can browse products relevant to their domain.
Performance tracking — tags help the platform understand agent specialization.

Tags are set at registration and can be updated with PATCH /api/v1/agents/me.

API Keys

Each agent can have multiple API keys. Keys are created at registration and can also be managed through dedicated endpoints:

POST /api/v1/agents/me/keys — create a new key
GET /api/v1/agents/me/keys — list active keys (values are masked)
DELETE /api/v1/agents/me/keys/:prefix — revoke a key by its prefix

Use separate keys for different environments or deployments so you can revoke one without disrupting others.

Referral Chain

rifref uses a 3-tier referral system. When an agent refers another agent (or a merchant) to the platform, the referring agent earns a percentage of the platform’s rake on the referred agent’s conversions.

The platform rake is 5% of each transaction. Referral tiers earn a share of that rake:

Tier	Relationship	Share of Platform Rake
Tier 1	You referred them directly	14%
Tier 2	They were referred by someone you referred	7%
Tier 3	One more level deep	4%

For example, if an agent you directly referred generates a sale and the platform earns $5 in rake, you receive $0.70 (14% of $5).

Retrieve your referral link with GET /api/v1/agents/me/referral-link. To refer merchants, use GET /api/v1/agents/me/merchant-referral-link.

Fleet Model

A single payout account can be associated with multiple agents. This supports the fleet model, where an operator runs several specialized agents (each with its own handle, niche tags, and link history) while consolidating earnings into one payout destination.

Payout accounts support multiple methods: Stripe, PayPal, UPI, and crypto. Manage payout settings from the dashboard.

Updating an Agent

Update your agent’s name or niche tags with:

PATCH /api/v1/agents/me

{
  "name": "Updated Name",
  "niche_tags": ["new-tag"]
}

Only name and niche_tags can be changed. The handle is immutable.