# AgentRef

> Affiliate marketing software for SaaS. Agent-first. Usage-based pricing ($0 to start).

AgentRef lets merchants run affiliate programs and lets affiliates (humans or AI agents) earn commissions by referring customers. It integrates with Stripe for payments and provides a production-ready MCP server, REST API, Node SDK, and Python SDK.

## Quick Links

- [Documentation](https://www.agentref.co/docs)
- [API Reference](https://www.agentref.co/docs/api-reference/authentication)
- [OpenAPI Spec](https://www.agentref.co/api/v1/openapi.json)
- [Full Documentation for LLMs](https://www.agentref.co/docs/llms-full.txt)

## API

Base URL: `https://www.agentref.co/api/v1`

Authentication: Bearer token via `Authorization: Bearer ak_live_*` (merchant), `ak_onb_*` (onboarding), or `ak_aff_*` (affiliate).

Rate limits: 60 requests/minute (authenticated), 10/minute (unauthenticated).

### Key REST Surfaces

- **Programs:** `GET /programs`, `POST /programs`, `GET /programs/{id}`, `PATCH /programs/{id}`, `GET /programs/{id}/stats`
- **Program setup:** `POST /programs/{id}/connect-stripe`, `GET /programs/{id}/tracking/status`, `PATCH /programs/{id}/marketplace`
- **Affiliates, applications, and invites:** `GET /affiliates`, `POST /affiliates/{id}/block`, `POST /affiliates/{id}/unblock`, `GET /applications`, `POST /applications/{id}/approve`, `POST /applications/{id}/decline`, `POST /applications/{id}/block`, `GET /programs/{id}/invites`
- **Conversions and payouts:** `GET /conversions`, `GET /payouts`, `GET /payouts/pending`, `GET /flags`, `POST /flags/{id}/resolve`
- **Affiliate self-serve (`ak_aff_*`):** `GET /me`, `GET /me/overview`, `GET /me/programs`, `GET /me/earnings`, `GET /me/clicks`, `GET /me/payouts`, `GET /me/links`, `POST /me/links`, `PATCH /me/links/{id}`, `DELETE /me/links/{id}`, `PATCH /me/payout-info`
- **Marketplace:** `GET /marketplace/programs`, `POST /marketplace/apply/{programId}`
- **Marketing Resources:** `GET /programs/{id}/marketing-resources`, `POST /programs/{id}/marketing-resources/social-posts`, `PATCH /marketing-resources/social-posts/{resourceId}`, social-post media upload/update/reorder/replace/delete endpoints, `POST /marketing-resources/{resourceId}/publish`, `POST /marketing-resources/{resourceId}/unpublish`, `POST /marketing-resources/{resourceId}/archive`, `POST /marketing-resources/{resourceId}/notify`, `GET /me/programs/{programId}/marketing-resources`, `POST /me/marketing-resources/social-posts/{resourceId}/render`

## MCP Server

Merchant endpoint: `https://www.agentref.co/api/mcp/merchant`

Affiliate endpoint: `https://www.agentref.co/api/mcp/affiliate`

Preferred auth: OAuth 2.1 + dynamic client registration

Fallback auth for manual/custom clients: `Authorization: Bearer ak_live_*`, `ak_onb_*`, or `ak_aff_*`

Verified onboarding flows:
- **Claude Code:** `claude mcp add --scope user --transport http agentref-merchant https://www.agentref.co/api/mcp/merchant`
- **Claude App:** add a custom connector with the MCP endpoint, then trigger a test call and click `Reconnect`
- **Codex:** ask Codex to run `codex mcp add agentref-merchant --url https://www.agentref.co/api/mcp/merchant`
- **Cursor:** add `{"mcpServers":{"agentref-merchant":{"url":"https://www.agentref.co/api/mcp/merchant"}}}` to `.cursor/mcp.json`, restart once, then click `Connect`
- **OpenClaw (`mcporter`):** add the persona endpoint with OAuth and run `mcporter ... auth --reset agentref-merchant`

Inputs and outputs use snake_case. Mutation tools accept `idempotency_key`. MCP is broader than REST/SDK for some workflows, including merchant onboarding status, tracking snippet/verify, invite revoke, payout status/export/upcoming payouts, and advanced Marketing Resources operations.

Workflow groups:

**merchant_setup:** get_onboarding_status, update_merchant_profile, create_program, list_programs, update_program, get_stripe_connect_url, complete_onboarding, get_tracking_snippet, verify_tracking

**merchant_growth:** list_affiliates, list_applications, review_application, set_affiliate_status, list_invites, create_invite, revoke_invite, get_program_overview, list_conversions, list_flags, review_flag

**merchant_payouts:** list_pending_payouts, list_payouts, list_upcoming_payouts, create_payout, update_payout_status, export_payouts_csv

**merchant_marketing_resources:** list_marketing_resources, get_marketing_resource, create_marketing_collection, update_marketing_collection, publish_marketing_resource, unpublish_marketing_resource, archive_marketing_resource, create_marketing_social_post, update_marketing_social_post, create_marketing_social_post_media_upload_session, complete_marketing_social_post_media_upload, remove_marketing_social_post_media, update_marketing_social_post_media, reorder_marketing_social_post_media, replace_marketing_social_post_media, create_marketing_resource_download_url, create_marketing_external_link, create_marketing_upload_session, complete_marketing_upload_session, import_marketing_resource_from_url, notify_marketing_resource_affiliates

**affiliate_workspace:** discover_programs, apply_to_program, get_affiliate_overview, list_my_programs, list_links, create_link, get_earnings, get_click_stats, list_my_payouts, update_my_payout_profile

**affiliate_marketing_resources:** list_marketing_resources, get_marketing_resource, render_marketing_social_post, create_marketing_resource_download_url

Resources:
- `merchant://me`
- `program://{id}`
- `stats://{programId}`
- `marketing-resources://program/{program_id}`
- `marketing-resource-collection://{collection_id}`
- `marketing-resource://{resource_id}`
- `affiliate://me/programs`
- `marketplace://catalog`

Prompts:
- `onboard_program`
- `review_payout_run`
- `debug_tracking_installation`
- `triage_fraud_flags`

## SDKs

Examples below use merchant keys. Affiliate self-serve flows are exposed via REST `/me/*` endpoints and MCP tools.

### Node.js (`agentref` on npm, v5.1.2)

```javascript
import { AgentRef } from 'agentref'
const client = new AgentRef({ apiKey: 'ak_live_YOUR_KEY' })

const programs = await client.programs.list()
const conversions = await client.conversions.list({ programId: 'prg_abc' })
const stats = await client.conversions.stats({ programId: 'prg_abc' })
const pendingApplications = await client.applications.list({ programId: 'prg_abc', status: 'pending' })
const resources = await client.marketingResources.list('prg_abc')
```

### Python (`agentref` on PyPI, v5.1.2)

```python
from agentref import AgentRef
client = AgentRef(api_key="ak_live_YOUR_KEY")

programs = client.programs.list()
conversions = client.conversions.list(program_id="prg_abc")
stats = client.conversions.stats(program_id="prg_abc")
pending_applications = client.applications.list(program_id="prg_abc", status="pending")
resources = client.marketing_resources.list("prg_abc")
```

## Tracking

Install the tracking script on the merchant's website:

```html
<script defer src="https://www.agentref.co/api/tracking/script.js?pid=PROGRAM_ID"></script>
```

Cookies: `agentref_cid`, `agentref_pid`, `agentref_src` (first-party, SameSite=Lax).
URL parameter: generated links default to `?via=AFFILIATE_CODE`. Inbound attribution always accepts `via`, `ref`, `r`, and `a`; programs can add tracking parameter aliases on top of those defaults.
Stripe integration: `window.AgentRef.getCheckoutMetadata()` returns `{ agentref_cid, agentref_pid, agentref_source }` for custom Stripe checkout metadata.

## Webhooks

13 event types: `program.created`, `program.updated`, `affiliate.joined`, `affiliate.approved`, `affiliate.blocked`, `affiliate.unblocked`, `conversion.created`, `conversion.refunded`, `payout.created`, `payout.processing`, `payout.completed`, `payout.failed`, `flag.resolved`.

Signature: HMAC-SHA256 via `svix-signature` header. Retry: 8 attempts with exponential backoff (1min → 24h).

## Docs Sections

- [Getting Started](https://www.agentref.co/docs/getting-started/welcome): Overview, quickstart, agent setup
- [Merchant Guide](https://www.agentref.co/docs/merchant-guide/connect-stripe): Stripe, programs, tracking, affiliates, applications, marketing resources, conversions, payouts, fraud
- [Agent Integration](https://www.agentref.co/docs/agent-integration/mcp-server): MCP Server, Node SDK, Python SDK, CLI, agent patterns
- [Tracking](https://www.agentref.co/docs/tracking/how-tracking-works): JS snippet, Stripe Checkout, consent, debug, server-side
- [Webhooks](https://www.agentref.co/docs/webhooks/overview): Setup, signatures, events, retries, testing
- [For Affiliates](https://www.agentref.co/docs/affiliates/getting-started): Joining, links, marketing resources, commissions, payouts, FAQ
- [API Reference](https://www.agentref.co/docs/api-reference/authentication): Auth, errors, idempotency, all endpoints