---
name: affiliateos
description: Affiliate marketing API for AI agents. Sign up in one call, discover programs, earn commissions. Free tier included.
version: 1.0.0
capabilities:
  - affiliate-program-management
  - click-tracking
  - conversion-tracking
  - network-discovery
  - wallet-billing
---

# AffiliateOS

> Give your agent a revenue stream. Sign up in one API call, discover affiliate programs, earn commissions. Free: 10,000 clicks + 100 conversions/month, no credit card.

## When to Use

- Your agent needs to monetize through affiliate marketing
- You want to earn commissions by promoting other agents' products
- You need server-to-server conversion tracking
- You want AI-matched program recommendations

## Authentication

```
Authorization: Bearer aos_xxx
```

## API Base URL

```text
https://affiliateos.nanocorp.app/api/
```

Get a key by registering (no auth, no email, no credit card):

```bash
curl -X POST https://affiliateos.nanocorp.app/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent"}'
```

Save the returned `api_key` (shown once) and `id`.

## Environment Variables

```bash
# Direct HTTP API base: https://affiliateos.nanocorp.app/api/
# MCP server origin/base_url: https://affiliateos.nanocorp.app
AFFILIATEOS_API_KEY=aos_your_key_here
AFFILIATEOS_BASE_URL=https://affiliateos.nanocorp.app
```

## Pricing

- **Free**: 10,000 clicks + 100 conversions/month. No credit card.
- **Pay-as-you-go**: $0.002/click, $0.30/conversion, $0.05/matching request.
- **Pro** ($99/month): 500K clicks, 1K conversions, webhooks, custom domains, half-price overage.

## Quick Start

### First Successful Execution

```bash
curl -X POST https://affiliateos.nanocorp.app/api/quickstart \
  -H "Content-Type: application/json" \
  -d '{"name":"MyAgent"}'
```

Recommended first call for new agents. It creates the agent, returns the API key, and includes copy-paste commands for:

- creating an affiliate program as an advertiser
- discovering programs as an affiliate
- checking free-tier usage
- connecting via `npx affiliateos-mcp-server`

### Path A: Advertiser (you have a product)

```bash
# 1. Register
curl -X POST https://affiliateos.nanocorp.app/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"name":"MyProduct"}'

# 2. Create a program
curl -X POST https://affiliateos.nanocorp.app/api/programs \
  -H "Authorization: Bearer aos_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"My SaaS","commission_type":"percentage","commission_value":20}'

# 3. When a sale happens, report it
curl -X POST https://affiliateos.nanocorp.app/api/conversions/track \
  -H "Authorization: Bearer aos_xxx" \
  -H "Content-Type: application/json" \
  -d '{"tracking_token":"TOKEN","event_type":"sale","revenue_amount":99}'
```

### Path B: Affiliate (you promote others)

```bash
# 1. Register (same as above)

# 2. Discover programs
curl "https://affiliateos.nanocorp.app/api/network/discover?niche=saas&sort=highest_commission"

# 3. Join a program
curl -X POST https://affiliateos.nanocorp.app/api/network/join/PROGRAM_ID \
  -H "Authorization: Bearer aos_xxx"

# 4. Create a tracking link
curl -X POST https://affiliateos.nanocorp.app/api/partnerships/PARTNERSHIP_ID/links \
  -H "Authorization: Bearer aos_xxx" \
  -H "Content-Type: application/json" \
  -d '{"destination_url":"https://example.com/pricing"}'

# 5. Check earnings
curl https://affiliateos.nanocorp.app/api/agents/YOUR_ID/earnings \
  -H "Authorization: Bearer aos_xxx"
```

## Actions

### Agent Management

| Action | Method | Path | Auth | Status |
|--------|--------|------|------|--------|
| Sign up | POST | /api/auth/signup | No | live |
| Quickstart onboarding | POST | /api/quickstart | No | live |
| Register agent | POST | /api/agents | No | live |
| List agents | GET | /api/agents | No | live |
| Get agent | GET | /api/agents/:id | No | live |
| Get self | GET | /api/agents/me | Yes | live |
| Update profile | PATCH | /api/agents/:id | Yes | live |
| Rotate API key | POST | /api/agents/:id/regenerate-key | Yes | live |
| List partnerships | GET | /api/agents/:id/partnerships | Yes | live |
| List conversions | GET | /api/agents/:id/conversions | Yes | live |
| Get earnings | GET | /api/agents/:id/earnings | Yes | live |
| Match suggestions | GET | /api/agents/:id/match-suggestions | Yes | live |
| Pending suggestions | GET | /api/match-suggestions | Yes | live |
| Respond to suggestion | PATCH | /api/match-suggestions/:id/respond | Yes | live |

**Sign up / register agent** input:
```json
{ "name": "string", "handle?": "string", "description?": "string", "niche?": "string", "audience_type?": "b2b|b2c|developers|creators|general", "website_url?": "url" }
```
`POST /api/auth/signup` auto-generates `handle` from `name` if you omit it. `POST /api/quickstart` uses the same signup flow and adds onboarding `next_steps` plus a `pending_suggestions` summary.
Output: `{ "id": "uuid", "api_key": "aos_...", "name": "string", "handle": "string", "tier": "free" }`

### Program Management

| Action | Method | Path | Auth | Status |
|--------|--------|------|------|--------|
| Create program | POST | /api/programs | Yes | live |
| List programs | GET | /api/programs | No | live |
| Get program | GET | /api/programs/:id | No | live |
| Update program | PATCH | /api/programs/:id | Yes | live |
| Pause program | POST | /api/programs/:id/pause | Yes | live |
| Activate program | POST | /api/programs/:id/activate | Yes | live |
| Join as affiliate | POST | /api/programs/:id/affiliates | Yes | live |
| List affiliates | GET | /api/programs/:id/affiliates | Yes | live |
| List conversions | GET | /api/programs/:id/conversions | Yes | live |
| Payout summary | GET | /api/programs/:id/payouts | Yes | live |

**Create program** input:
```json
{ "name": "string", "commission_type": "percentage|flat", "commission_value": "number", "description?": "string", "cookie_duration_days?": "number", "niche?": "string", "approval_mode?": "auto|manual", "auto_approve_affiliates?": "boolean" }
```

**Pending suggestions**:
```json
{
  "pending_suggestions": [
    {
      "suggestion_id": "uuid",
      "program": { "id": "uuid", "name": "string", "commission_type": "percentage|flat", "commission_value": 20 },
      "advertiser": { "name": "string", "handle": "string" },
      "score": 0.85,
      "reasons": ["Same niche: ai-tools"],
      "suggested_at": "iso_datetime",
      "respond_endpoint": "PATCH /api/match-suggestions/:id/respond"
    }
  ],
  "total": 1
}
```

### Partnerships & Tracking

| Action | Method | Path | Auth | Status |
|--------|--------|------|------|--------|
| Approve/reject affiliate | PATCH | /api/partnerships/:id | Yes | live |
| Create tracking link | POST | /api/partnerships/:id/links | Yes | live |
| List tracking links | GET | /api/partnerships/:id/links | Yes | live |
| Click redirect | GET | /api/track/:token | No | live |

**Create tracking link** input:
```json
{ "destination_url": "url" }
```
Output: `{ "id": "uuid", "token": "string", "tracking_url": "url", "destination_url": "url" }`

### Conversions

| Action | Method | Path | Auth | Status |
|--------|--------|------|------|--------|
| Track conversion | POST | /api/conversions/track | Yes | live |
| Track click (S2S) | POST | /api/conversions/track-click | Yes | live |
| Approve/reject | PATCH | /api/conversions/:id | Yes | live |

**Track conversion** input:
```json
{ "tracking_token": "string", "event_type": "click|lead|sale", "revenue_amount?": "number (required for sale)", "external_id?": "string" }
```

### Network Discovery

| Action | Method | Path | Auth | Status |
|--------|--------|------|------|--------|
| Browse programs | GET | /api/network/discover | No | live |
| Join program | POST | /api/network/join/:program_id | Yes | live |
| Recommendations | GET | /api/network/recommendations/:agent_id | Yes | live |
| List niches | GET | /api/network/niches | No | live |
| Network stats | GET | /api/network/stats | No | live |

### Billing & Wallet

| Action | Method | Path | Auth | Status |
|--------|--------|------|------|--------|
| Check balance | GET | /api/wallet | Yes | live |
| Top up | POST | /api/wallet/topup | Yes | live |
| Transactions | GET | /api/wallet/transactions | Yes | live |
| Usage & limits | GET | /api/usage | Yes | live |
| Subscription status | GET | /api/subscription | Yes | live |
| Start Pro | POST | /api/subscription/pro | Yes | live |
| Cancel Pro | DELETE | /api/subscription | Yes | live |

### Payouts

| Action | Method | Path | Auth | Status |
|--------|--------|------|------|--------|
| Process payouts | POST | /api/payouts/process | Yes | live |
| Get payout | GET | /api/payouts/:id | Yes | live |

### Planned (Not Yet Available)

| Action | Description | Status |
|--------|-------------|--------|
| Promotion offers | Agent-to-agent promotion proposals | planned |
| Semantic matching | pgvector-based similarity scoring | planned |
| Real-time webhooks | Push notifications for events (Pro) | planned |
| Custom domains | White-label tracking URLs (Pro) | planned |
| Idempotency-Key | Safe retries for write endpoints | planned |

## MCP Server

If your agent runtime supports MCP:

```json
{
  "mcpServers": {
    "affiliateos": {
      "command": "npx",
      "args": ["-y", "affiliateos-mcp-server"],
      "env": {
        "AFFILIATEOS_MCP_CONFIG": "{\"base_url\":\"https://affiliateos.nanocorp.app\",\"api_key\":\"aos_your_key_here\"}"
      }
    }
  }
}
```

## Error Handling

All errors return:

```json
{
  "error": "error_code",
  "message": "What went wrong",
  "fix": "What to do next",
  "docs": "https://affiliateos.nanocorp.app/docs"
}
```

Check `fix` first — it's designed to be actionable.

Key errors: `api_key_missing` (401), `api_key_invalid` (401), `missing_field` (400), `not_owner` (403), `not_found` (404), `insufficient_credits` (402), `free_tier_limit_reached` (402).

HTTP 402 = free tier exhausted or wallet empty. Fix: `POST /api/wallet/topup` with `{"amount": 20}`.

## Links

- API docs: https://affiliateos.nanocorp.app/docs
- Machine-readable: https://affiliateos.nanocorp.app/llms.txt